agentic-orchestrator 0.1.0

package/apps/control-plane/src/supervisor/planning-wave-executor.ts

@@ -0,0 +1,316 @@
+import { STATUS, TOOLS } from '../core/constants.js';
+import type {
+  FeatureContextPayload,
+  InitialPlanGenerator,
+  SupervisorToolCaller
+} from './types.js';
+import { NOOP_WORKER_DECISION_RUNNER, type WorkerDecisionRunner } from './worker-decision-loop.js';
+
+type AnyRecord = Record<string, unknown>;
+
+interface PlanningWaveExecutorDependencies {
+  toolCaller: SupervisorToolCaller;
+  planGenerator: InitialPlanGenerator;
+  workerDecisionRunner?: WorkerDecisionRunner;
+}
+
+interface ReconciliationDecision {
+  action: 'update' | 'no_update';
+  reasons: string[];
+  acceptanceCriteriaAdditions: string[];
+  edgeCaseChecklist: string[];
+  qaSummary: {
+    pending: number;
+    failed: number;
+    running: number;
+  };
+  latestGateOverall: string | null;
+}
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const normalized: string[] = [];
+  for (const item of value) {
+    if (typeof item !== 'string') {
+      continue;
+    }
+    const trimmed = item.trim();
+    if (trimmed.length > 0) {
+      normalized.push(trimmed);
+    }
+  }
+  return normalized;
+}
+
+function normalizeList(values: string[]): string[] {
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    normalized.push(trimmed);
+  }
+  return normalized;
+}
+
+function readCount(summary: AnyRecord, key: string): number {
+  const raw = summary[key];
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) {
+    return 0;
+  }
+  return Math.floor(raw);
+}
+
+function readStatus(value: unknown): string {
+  return typeof value === 'string' ? value : 'unknown';
+}
+
+function deriveEdgeCaseChecklist(specText: string): string[] {
+  const checklist = [
+    'Edge-case: boundary values and size limits are covered.',
+    'Edge-case: negative-path input validation and error handling are covered.',
+    'Edge-case: dependency failure and retry behavior are covered.'
+  ];
+
+  const normalizedSpec = specText.toLowerCase();
+  if (/(empty|null|missing|required)/.test(normalizedSpec)) {
+    checklist.push('Edge-case: empty/null/missing input handling is covered.');
+  }
+  if (/(timeout|retry|backoff|latency)/.test(normalizedSpec)) {
+    checklist.push('Edge-case: timeout, retry, and latency behavior is covered.');
+  }
+  if (/(concurrent|race|parallel|lock)/.test(normalizedSpec)) {
+    checklist.push('Edge-case: concurrent access and race-condition behavior are covered.');
+  }
+  if (/(permission|auth|unauthori|forbidden|denied)/.test(normalizedSpec)) {
+    checklist.push('Edge-case: authorization and permission-denied behavior is covered.');
+  }
+
+  return normalizeList(checklist);
+}
+
+function readPlanVersion(plan: AnyRecord): number | null {
+  const raw = plan.plan_version;
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1) {
+    return null;
+  }
+  return Math.floor(raw);
+}
+
+function isPostQaStatus(status: string): boolean {
+  return status === STATUS.QA || status === STATUS.READY_TO_MERGE || status === STATUS.BLOCKED;
+}
+
+export class PlanningWaveExecutor {
+  private readonly toolCaller: SupervisorToolCaller;
+  private readonly planGenerator: InitialPlanGenerator;
+  private readonly workerDecisionRunner: WorkerDecisionRunner;
+
+  constructor(dependencies: PlanningWaveExecutorDependencies) {
+    this.toolCaller = dependencies.toolCaller;
+    this.planGenerator = dependencies.planGenerator;
+    this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
+  }
+
+  async run(featureIds: string[]): Promise<void> {
+    for (const featureId of featureIds) {
+      const context = await this.toolCaller.callTool<FeatureContextPayload>('planner', TOOLS.FEATURE_GET_CONTEXT, {
+        feature_id: featureId
+      });
+
+      const state = context.data.state.front_matter;
+      if (state.status !== STATUS.PLANNING && state.status !== STATUS.BLOCKED) {
+        continue;
+      }
+
+      const existingPlan = context.data.plan;
+      const decision = await this.workerDecisionRunner.execute({
+        role: 'planner',
+        featureId,
+        contextBundle: asRecord(context.data),
+        instructions:
+          'Review feature context and emit PLAN_SUBMISSION/REQUEST/NOTE outputs to advance planning deterministically.'
+      });
+
+      if (decision.planSubmission || existingPlan) {
+        continue;
+      }
+
+      const plan = await this.planGenerator.generateInitialPlan(featureId);
+      await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
+        feature_id: featureId,
+        plan_json: plan
+      });
+    }
+  }
+
+  async runPostQaReconciliation(featureIds: string[], iteration: number): Promise<void> {
+    for (const featureId of featureIds) {
+      const context = await this.toolCaller.callTool<FeatureContextPayload>('planner', TOOLS.FEATURE_GET_CONTEXT, {
+        feature_id: featureId
+      });
+
+      const frontMatter = asRecord(asRecord(context.data.state).front_matter);
+      const status = readStatus(frontMatter.status);
+      if (!isPostQaStatus(status)) {
+        continue;
+      }
+
+      const existingPlan = asRecord(context.data.plan);
+      if (Object.keys(existingPlan).length === 0) {
+        await this.appendDecisionLog(featureId, {
+          phase: 'post_qa_reconciliation',
+          iteration,
+          decision: 'no_update',
+          reasons: ['missing_plan'],
+          status
+        });
+        continue;
+      }
+
+      const planVersion = readPlanVersion(existingPlan);
+      if (planVersion == null) {
+        await this.appendDecisionLog(featureId, {
+          phase: 'post_qa_reconciliation',
+          iteration,
+          decision: 'no_update',
+          reasons: ['existing_plan_version_invalid'],
+          status
+        });
+        continue;
+      }
+
+      const decision = this.evaluateReconciliationDecision(context.data, existingPlan, status);
+      if (decision.action === 'no_update') {
+        await this.appendDecisionLog(featureId, {
+          phase: 'post_qa_reconciliation',
+          iteration,
+          decision: 'no_update',
+          status,
+          reasons: decision.reasons,
+          qa_summary: decision.qaSummary,
+          latest_gate_overall: decision.latestGateOverall,
+          edge_case_checklist: decision.edgeCaseChecklist
+        });
+        continue;
+      }
+
+      const nextPlan = this.buildUpdatedPlan(existingPlan, planVersion, decision);
+      await this.toolCaller.callTool('planner', TOOLS.PLAN_UPDATE, {
+        feature_id: featureId,
+        expected_plan_version: planVersion,
+        plan_json: nextPlan
+      });
+
+      await this.appendDecisionLog(featureId, {
+        phase: 'post_qa_reconciliation',
+        iteration,
+        decision: 'plan_update',
+        status,
+        expected_plan_version: planVersion,
+        next_plan_version: nextPlan.plan_version,
+        revision_reason: nextPlan.revision_reason,
+        reasons: decision.reasons,
+        qa_summary: decision.qaSummary,
+        latest_gate_overall: decision.latestGateOverall,
+        edge_case_checklist: decision.edgeCaseChecklist
+      });
+    }
+  }
+
+  private evaluateReconciliationDecision(
+    context: FeatureContextPayload,
+    plan: AnyRecord,
+    status: string
+  ): ReconciliationDecision {
+    const acceptanceCriteria = asStringArray(plan.acceptance_criteria);
+    const riskItems = asStringArray(plan.risk);
+    const specText = typeof context.spec === 'string' ? context.spec : '';
+    const edgeCaseChecklist = deriveEdgeCaseChecklist(specText);
+    const qaSummary = asRecord(asRecord(context.qa_test_index).summary);
+    const pending = readCount(qaSummary, 'pending');
+    const failed = readCount(qaSummary, 'failed');
+    const running = readCount(qaSummary, 'running');
+    const latestGateOverall = typeof asRecord(context.latest_evidence).overall === 'string'
+      ? String(asRecord(context.latest_evidence).overall)
+      : null;
+
+    const reasons: string[] = [];
+    const acceptanceCriteriaAdditions: string[] = [];
+
+    const missingEdgeCases = edgeCaseChecklist.filter((item) => !riskItems.includes(item));
+    if (missingEdgeCases.length > 0) {
+      reasons.push(`edge_case_checklist_missing:${missingEdgeCases.length}`);
+      acceptanceCriteriaAdditions.push(
+        'Planner edge-case checklist has been reviewed and incorporated into the execution plan.'
+      );
+    }
+
+    const hasQaSignals = status === STATUS.BLOCKED || failed > 0 || pending > 0 || latestGateOverall === 'fail';
+    const qaCheckpoint = `Planner reconciliation checkpoint [status=${status};failed=${failed};pending=${pending};latest=${latestGateOverall ?? 'unknown'}]`;
+    if (hasQaSignals && !acceptanceCriteria.includes(qaCheckpoint)) {
+      reasons.push(`qa_signals_detected:${status}:failed=${failed}:pending=${pending}`);
+      acceptanceCriteriaAdditions.push(
+        'Reconcile QA/gate findings against plan scope and apply corrective updates before merge.'
+      );
+      acceptanceCriteriaAdditions.push(qaCheckpoint);
+    }
+
+    if (reasons.length === 0) {
+      return {
+        action: 'no_update',
+        reasons: ['reconciled_no_gaps'],
+        acceptanceCriteriaAdditions: [],
+        edgeCaseChecklist,
+        qaSummary: {
+          pending,
+          failed,
+          running
+        },
+        latestGateOverall
+      };
+    }
+
+    return {
+      action: 'update',
+      reasons,
+      acceptanceCriteriaAdditions: normalizeList(acceptanceCriteriaAdditions),
+      edgeCaseChecklist,
+      qaSummary: {
+        pending,
+        failed,
+        running
+      },
+      latestGateOverall
+    };
+  }
+
+  private buildUpdatedPlan(plan: AnyRecord, planVersion: number, decision: ReconciliationDecision): AnyRecord {
+    const nextPlan = structuredClone(plan);
+    const acceptanceCriteria = asStringArray(nextPlan.acceptance_criteria);
+    const riskItems = asStringArray(nextPlan.risk);
+
+    nextPlan.plan_version = planVersion + 1;
+    nextPlan.revision_of = planVersion;
+    nextPlan.revision_reason = decision.reasons.join('; ');
+    nextPlan.acceptance_criteria = normalizeList([...acceptanceCriteria, ...decision.acceptanceCriteriaAdditions]);
+    nextPlan.risk = normalizeList([...riskItems, ...decision.edgeCaseChecklist]);
+    return nextPlan;
+  }
+
+  private async appendDecisionLog(featureId: string, note: AnyRecord): Promise<void> {
+    await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+      feature_id: featureId,
+      note: JSON.stringify(note)
+    });
+  }
+}

package/apps/control-plane/src/supervisor/prompt-bundle-loader.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { AgentPromptProvider, AppError, PromptBundle, RuntimeStateReader } from './types.js';
+
+export class PromptBundleLoader implements AgentPromptProvider {
+  private readonly runtimeStateReader: RuntimeStateReader;
+  private promptsCache: PromptBundle | null;
+
+  constructor(runtimeStateReader: RuntimeStateReader) {
+    this.runtimeStateReader = runtimeStateReader;
+    this.promptsCache = null;
+  }
+
+  async loadRolePrompts(): Promise<PromptBundle> {
+    if (this.promptsCache) {
+      return this.promptsCache;
+    }
+
+    const agentsConfig = this.runtimeStateReader.getAgentsConfig();
+    const roles = agentsConfig.roles ?? {};
+    const behavior = agentsConfig.missing_prompt_behavior ?? 'ignore';
+    const prompts: PromptBundle = {
+      planner: null,
+      builder: null,
+      qa: null
+    };
+
+    for (const role of ['planner', 'builder', 'qa'] as const) {
+      const configuredPath = roles[role]?.system_prompt_path;
+      if (!configuredPath) {
+        prompts[role] = null;
+        continue;
+      }
+
+      const absolute = path.join(this.runtimeStateReader.getRepoRoot(), configuredPath);
+      try {
+        prompts[role] = await fs.readFile(absolute, 'utf8');
+      } catch {
+        if (behavior === 'error') {
+          const error = new Error(ERROR_CODES.MISSING_ROLE_PROMPT) as AppError;
+          error.code = ERROR_CODES.MISSING_ROLE_PROMPT;
+          error.details = { role, configured_path: configuredPath };
+          throw error;
+        }
+
+        prompts[role] = null;
+      }
+    }
+
+    this.promptsCache = prompts;
+    return prompts;
+  }
+
+  peekCache(): PromptBundle | null {
+    return this.promptsCache;
+  }
+
+  setCache(prompts: PromptBundle | null): void {
+    this.promptsCache = prompts;
+  }
+}

package/apps/control-plane/src/supervisor/qa-wave-executor.ts

@@ -0,0 +1,99 @@
+import { STATUS, TOOLS } from '../core/constants.js';
+import type { WorkerProvider } from '../providers/providers.js';
+import type {
+  AgentPromptProvider,
+  FeatureClusterPatcher,
+  FeatureOrchestrationPort,
+  FeatureStatePayload,
+  SupervisorRuntimeState,
+  SupervisorToolCaller
+} from './types.js';
+import { UNASSIGNED_SESSION_ID } from './types.js';
+import { NOOP_WORKER_DECISION_RUNNER, type WorkerDecisionRunner } from './worker-decision-loop.js';
+
+interface QaWaveExecutorDependencies {
+  kernel: FeatureOrchestrationPort;
+  provider: WorkerProvider;
+  toolCaller: SupervisorToolCaller;
+  promptProvider: AgentPromptProvider;
+  featureClusterPatcher: FeatureClusterPatcher;
+  state: SupervisorRuntimeState;
+  workerDecisionRunner?: WorkerDecisionRunner;
+}
+
+export class QaWaveExecutor {
+  private readonly kernel: FeatureOrchestrationPort;
+  private readonly provider: WorkerProvider;
+  private readonly toolCaller: SupervisorToolCaller;
+  private readonly promptProvider: AgentPromptProvider;
+  private readonly featureClusterPatcher: FeatureClusterPatcher;
+  private readonly state: SupervisorRuntimeState;
+  private readonly workerDecisionRunner: WorkerDecisionRunner;
+
+  constructor(dependencies: QaWaveExecutorDependencies) {
+    this.kernel = dependencies.kernel;
+    this.provider = dependencies.provider;
+    this.toolCaller = dependencies.toolCaller;
+    this.promptProvider = dependencies.promptProvider;
+    this.featureClusterPatcher = dependencies.featureClusterPatcher;
+    this.state = dependencies.state;
+    this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
+  }
+
+  async run(featureIds: string[], maxParallelGateRuns: number): Promise<void> {
+    const batch: string[] = [];
+    for (const featureId of featureIds) {
+      const state = await this.toolCaller.callTool<FeatureStatePayload>('qa', TOOLS.FEATURE_STATE_GET, {
+        feature_id: featureId
+      });
+
+      if (state.data.front_matter.status === STATUS.QA) {
+        batch.push(featureId);
+      }
+    }
+
+    for (const featureId of batch.slice(0, maxParallelGateRuns)) {
+      const context = await this.toolCaller.callTool('qa', TOOLS.FEATURE_GET_CONTEXT, {
+        feature_id: featureId
+      });
+      await this.workerDecisionRunner.execute({
+        role: 'qa',
+        featureId,
+        contextBundle: context.data,
+        instructions:
+          'Emit PATCH outputs for deterministic QA remediations, NOTE outputs for findings, and REQUEST outputs for lock/context needs.'
+      });
+
+      await this.toolCaller.callTool('qa', TOOLS.GATES_RUN, {
+        feature_id: featureId,
+        profile: null,
+        mode: 'full'
+      });
+
+      const sessions = this.state.sessionsByFeature.get(featureId);
+      if (sessions?.qa) {
+        await this.provider.closeSession(sessions.qa);
+      }
+
+      const prompts = await this.promptProvider.loadRolePrompts();
+      const newQa = await this.provider.createSession('qa', featureId, prompts.qa);
+      if (sessions) {
+        sessions.qa = newQa.session_id;
+      }
+
+      await this.kernel.updateFeatureSessionAssignment({
+        run_id: this.state.runId,
+        owner_instance_id: this.state.ownerInstanceId,
+        feature_id: featureId,
+        planner_session_id: sessions?.planner ?? UNASSIGNED_SESSION_ID,
+        builder_session_id: sessions?.builder ?? UNASSIGNED_SESSION_ID,
+        qa_session_id: newQa.session_id
+      });
+
+      await this.featureClusterPatcher.patchFeatureCluster(featureId, {
+        orchestrator_session_id: this.state.orchestratorSessionId ?? 'unknown',
+        qa_session_id: newQa.session_id
+      });
+    }
+  }
+}

package/apps/control-plane/src/supervisor/run-coordinator.ts

@@ -0,0 +1,224 @@
+import { STATUS, TOOLS } from '../core/constants.js';
+import type { WorkerProvider } from '../providers/providers.js';
+import type {
+  FeatureInput,
+  FeatureStatePayload,
+  FeatureOrchestrationPort,
+  RuntimeStateReader,
+  SupervisorRuntimeState,
+  SupervisorToolCaller
+} from './types.js';
+import { type SessionOrchestrator } from './session-orchestrator.js';
+import { type PlanningWaveExecutor } from './planning-wave-executor.js';
+import { type BuildWaveExecutor } from './build-wave-executor.js';
+import { type QaWaveExecutor } from './qa-wave-executor.js';
+import { type LeaseHeartbeatService } from './lease-heartbeat-service.js';
+import { NOOP_WORKER_DECISION_RUNNER, type WorkerDecisionRunner } from './worker-decision-loop.js';
+
+interface RunCoordinatorDependencies {
+  kernel: FeatureOrchestrationPort & RuntimeStateReader;
+  provider: WorkerProvider;
+  toolCaller: SupervisorToolCaller;
+  state: SupervisorRuntimeState;
+  sessionOrchestrator: SessionOrchestrator;
+  planningWaveExecutor: PlanningWaveExecutor;
+  buildWaveExecutor: BuildWaveExecutor;
+  qaWaveExecutor: QaWaveExecutor;
+  leaseHeartbeatService: LeaseHeartbeatService;
+  maxActiveFeatures: number;
+  maxParallelGateRuns: number;
+  maxIterationsPerPhase: number;
+  takeoverStaleRun: boolean;
+  providerConfigRefHash: () => string;
+  workerDecisionRunner?: WorkerDecisionRunner;
+}
+
+export class RunCoordinator {
+  private readonly kernel: FeatureOrchestrationPort & RuntimeStateReader;
+  private readonly provider: WorkerProvider;
+  private readonly toolCaller: SupervisorToolCaller;
+  private readonly state: SupervisorRuntimeState;
+  private readonly sessionOrchestrator: SessionOrchestrator;
+  private readonly planningWaveExecutor: PlanningWaveExecutor;
+  private readonly buildWaveExecutor: BuildWaveExecutor;
+  private readonly qaWaveExecutor: QaWaveExecutor;
+  private readonly leaseHeartbeatService: LeaseHeartbeatService;
+  private readonly maxActiveFeatures: number;
+  private readonly maxParallelGateRuns: number;
+  private readonly maxIterationsPerPhase: number;
+  private readonly takeoverStaleRun: boolean;
+  private readonly providerConfigRefHash: () => string;
+  private readonly workerDecisionRunner: WorkerDecisionRunner;
+  private static readonly TERMINAL_STATUSES = new Set<string>([STATUS.MERGED, STATUS.FAILED]);
+
+  constructor(dependencies: RunCoordinatorDependencies) {
+    this.kernel = dependencies.kernel;
+    this.provider = dependencies.provider;
+    this.toolCaller = dependencies.toolCaller;
+    this.state = dependencies.state;
+    this.sessionOrchestrator = dependencies.sessionOrchestrator;
+    this.planningWaveExecutor = dependencies.planningWaveExecutor;
+    this.buildWaveExecutor = dependencies.buildWaveExecutor;
+    this.qaWaveExecutor = dependencies.qaWaveExecutor;
+    this.leaseHeartbeatService = dependencies.leaseHeartbeatService;
+    this.maxActiveFeatures = dependencies.maxActiveFeatures;
+    this.maxParallelGateRuns = dependencies.maxParallelGateRuns;
+    this.maxIterationsPerPhase = dependencies.maxIterationsPerPhase;
+    this.takeoverStaleRun = dependencies.takeoverStaleRun;
+    this.providerConfigRefHash = dependencies.providerConfigRefHash;
+    this.workerDecisionRunner = dependencies.workerDecisionRunner ?? NOOP_WORKER_DECISION_RUNNER;
+  }
+
+  async start(features: FeatureInput[]): Promise<Record<string, unknown>> {
+    await this.kernel.ensureLoaded();
+    await this.kernel.recoverFromState();
+
+    const leaseResult = await this.kernel.acquireRunLease({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      provider: this.provider.selection.provider,
+      model: this.provider.selection.model,
+      provider_config_ref_hash: this.providerConfigRefHash(),
+      takeover_stale_run: this.takeoverStaleRun
+    });
+
+    this.state.runMetadata.took_over_stale = Boolean(leaseResult.data.took_over_stale);
+
+    await this.sessionOrchestrator.ensureGlobalOrchestratorSession();
+
+    const sorted = [...features].sort((a, b) => a.feature_id.localeCompare(b.feature_id));
+    const scopedFeatureIds = sorted.map((item) => item.feature_id);
+    this.state.queue = sorted;
+    let activeFeatureIds: string[] = [];
+
+    await this.sessionOrchestrator.cleanupOrphanWorkerSessions(scopedFeatureIds);
+    await this.kernel.pruneFeatureSessionAssignments({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      active_feature_ids: scopedFeatureIds
+    });
+
+    activeFeatureIds = await this.rebalanceActiveFeatures(activeFeatureIds);
+
+    for (let iteration = 0; iteration < this.maxIterationsPerPhase; iteration += 1) {
+      if (activeFeatureIds.length === 0 && this.state.queue.length === 0) {
+        break;
+      }
+      await this.leaseHeartbeatService.renew();
+      activeFeatureIds = await this.applyOrchestratorPrioritization(activeFeatureIds, iteration + 1);
+      await this.planningWaveExecutor.run(activeFeatureIds);
+      await this.buildWaveExecutor.run(activeFeatureIds, this.maxParallelGateRuns);
+      await this.qaWaveExecutor.run(activeFeatureIds, this.maxParallelGateRuns);
+      await this.planningWaveExecutor.runPostQaReconciliation(activeFeatureIds, iteration + 1);
+      activeFeatureIds = await this.rebalanceActiveFeatures(activeFeatureIds);
+    }
+
+    const dashboard = await this.toolCaller.callTool('orchestrator', TOOLS.REPORT_DASHBOARD, {});
+    const runtimeSessions = await this.kernel.getRuntimeSessions();
+
+    return {
+      status: 'running',
+      dashboard: dashboard.data,
+      queue_depth: this.state.queue.length,
+      run_metadata: {
+        ...this.state.runMetadata,
+        runtime_sessions: runtimeSessions
+      }
+    };
+  }
+
+  private async rebalanceActiveFeatures(currentActiveFeatureIds: string[]): Promise<string[]> {
+    const survivingActiveFeatureIds: string[] = [];
+    const sortedCurrent = [...currentActiveFeatureIds].sort((a, b) => a.localeCompare(b));
+
+    for (const featureId of sortedCurrent) {
+      const status = await this.readFeatureStatus(featureId);
+      if (status && RunCoordinator.TERMINAL_STATUSES.has(status)) {
+        await this.sessionOrchestrator.closeFeatureCluster(featureId);
+        continue;
+      }
+      survivingActiveFeatureIds.push(featureId);
+    }
+
+    while (survivingActiveFeatureIds.length < this.maxActiveFeatures && this.state.queue.length > 0) {
+      const nextFeature = this.state.queue.shift();
+      if (!nextFeature) {
+        break;
+      }
+
+      const status = await this.readFeatureStatus(nextFeature.feature_id);
+      if (status && RunCoordinator.TERMINAL_STATUSES.has(status)) {
+        await this.sessionOrchestrator.closeFeatureCluster(nextFeature.feature_id);
+        continue;
+      }
+
+      await this.sessionOrchestrator.initializeFeatureCluster(nextFeature.feature_id);
+      survivingActiveFeatureIds.push(nextFeature.feature_id);
+    }
+
+    const activeFeatureIds = [...new Set(survivingActiveFeatureIds)].sort((a, b) => a.localeCompare(b));
+    const scopedFeatureIds = [...activeFeatureIds, ...this.state.queue.map((item) => item.feature_id)].sort((a, b) =>
+      a.localeCompare(b)
+    );
+
+    await this.sessionOrchestrator.reconcileQueuedFeatures(this.state.queue);
+    await this.sessionOrchestrator.enforceActiveFeatureInvariant(activeFeatureIds);
+    await this.kernel.pruneFeatureSessionAssignments({
+      run_id: this.state.runId,
+      owner_instance_id: this.state.ownerInstanceId,
+      active_feature_ids: scopedFeatureIds
+    });
+
+    return activeFeatureIds;
+  }
+
+  private async readFeatureStatus(featureId: string): Promise<string | null> {
+    try {
+      const state = await this.toolCaller.callTool<FeatureStatePayload>('orchestrator', TOOLS.FEATURE_STATE_GET, {
+        feature_id: featureId
+      });
+      const status = state.data.front_matter.status;
+      return typeof status === 'string' ? status : null;
+    } catch (_error) {
+      return null;
+    }
+  }
+
+  private async applyOrchestratorPrioritization(
+    activeFeatureIds: string[],
+    iteration: number
+  ): Promise<string[]> {
+    if (activeFeatureIds.length < 2) {
+      return activeFeatureIds;
+    }
+
+    const decision = await this.workerDecisionRunner.execute({
+      role: 'orchestrator',
+      featureId: 'global',
+      contextBundle: {
+        iteration,
+        active_feature_ids: activeFeatureIds,
+        queued_feature_ids: this.state.queue.map((item) => item.feature_id)
+      },
+      instructions:
+        'Decide per-iteration prioritization. Emit REQUEST action=prioritize with feature_order to reprioritize active features.'
+    });
+
+    if (decision.priorityOrder.length === 0) {
+      return activeFeatureIds;
+    }
+
+    const activeSet = new Set(activeFeatureIds);
+    const prioritized: string[] = [];
+    for (const featureId of decision.priorityOrder) {
+      if (!activeSet.has(featureId)) {
+        continue;
+      }
+      activeSet.delete(featureId);
+      prioritized.push(featureId);
+    }
+
+    const remaining = [...activeSet].sort((a, b) => a.localeCompare(b));
+    return [...prioritized, ...remaining];
+  }
+}