agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/src/core/mainline-conflict.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonical utility for detecting pending mainline divergence conflicts
+ * in a feature's frontmatter conflicts array.
+ *
+ * Replaces 5 divergent implementations across the codebase.
+ */
+
+export function hasPendingMainlineConflict(conflicts: unknown): boolean {
+  if (!Array.isArray(conflicts)) {
+    return false;
+  }
+  return conflicts.some((entry) => {
+    if (!entry || typeof entry !== 'object') {
+      return false;
+    }
+    const conflict = entry as Record<string, unknown>;
+    return (
+      conflict.type === 'mainline_divergence' &&
+      (conflict.resolution_status === 'pending' || conflict.resolution_status === 'in_progress')
+    );
+  });
+}

package/apps/control-plane/src/core/merge-repair.ts

@@ -0,0 +1,149 @@
+import { STATUS } from './constants.js';
+
+type AnyRecord = Record<string, unknown>;
+
+export const DEFAULT_MERGE_REPAIR_MAX_ATTEMPTS = 5;
+
+export interface MergeRepairState {
+  attempts: number;
+  max_attempts: number;
+  active: boolean;
+  requested_at: string | null;
+  last_failed_at: string | null;
+  last_gate_evidence_path: string | null;
+  last_failure_summary: string | null;
+  reviewer_message: string | null;
+  exhausted_at: string | null;
+}
+
+function asRecord(value: unknown): AnyRecord | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as AnyRecord) : null;
+}
+
+function normalizeWholeNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : fallback;
+}
+
+function normalizeOptionalString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+
+export function normalizeMergeRepairState(frontMatter: AnyRecord): MergeRepairState {
+  const raw = asRecord(frontMatter.merge_repair);
+  const maxAttempts = Math.max(
+    1,
+    normalizeWholeNumber(raw?.max_attempts, DEFAULT_MERGE_REPAIR_MAX_ATTEMPTS),
+  );
+  const attempts = Math.min(normalizeWholeNumber(raw?.attempts, 0), maxAttempts);
+
+  return {
+    attempts,
+    max_attempts: maxAttempts,
+    active: raw?.active === true,
+    requested_at: normalizeOptionalString(raw?.requested_at),
+    last_failed_at: normalizeOptionalString(raw?.last_failed_at),
+    last_gate_evidence_path: normalizeOptionalString(raw?.last_gate_evidence_path),
+    last_failure_summary: normalizeOptionalString(raw?.last_failure_summary),
+    reviewer_message: normalizeOptionalString(raw?.reviewer_message),
+    exhausted_at: normalizeOptionalString(raw?.exhausted_at),
+  };
+}
+
+export function isBlockedMergeGateFailure(frontMatter: AnyRecord): boolean {
+  const status = normalizeOptionalString(frontMatter.status);
+  const gates = asRecord(frontMatter.gates);
+  const evidence = asRecord(frontMatter.evidence);
+  return (
+    status === STATUS.BLOCKED && evidence?.last_gate_mode === 'merge' && gates?.merge === 'fail'
+  );
+}
+
+export function buildMergeGateFailureState(
+  frontMatter: AnyRecord,
+  params: {
+    evidencePath: string | null;
+    failureSummary: string | null;
+    failedAt: string;
+  },
+): { status: string; mergeRepair: MergeRepairState } {
+  const current = normalizeMergeRepairState(frontMatter);
+  const exhausted = current.active && current.attempts >= current.max_attempts;
+  const status = exhausted ? STATUS.FAILED : STATUS.BLOCKED;
+
+  return {
+    status,
+    mergeRepair: {
+      ...current,
+      active: !exhausted,
+      last_failed_at: params.failedAt,
+      last_gate_evidence_path: params.evidencePath,
+      last_failure_summary: params.failureSummary,
+      exhausted_at: exhausted ? params.failedAt : null,
+    },
+  };
+}
+
+export function buildMergeRepairQaReroute(
+  frontMatter: AnyRecord,
+  params: {
+    requestedAt: string;
+    reviewerMessage: string | null;
+  },
+): {
+  allowed: boolean;
+  exhausted: boolean;
+  nextStatus: string | null;
+  attemptNumber: number | null;
+  mergeRepair: MergeRepairState;
+} {
+  const current = normalizeMergeRepairState(frontMatter);
+  if (!isBlockedMergeGateFailure(frontMatter)) {
+    return {
+      allowed: false,
+      exhausted: false,
+      nextStatus: null,
+      attemptNumber: null,
+      mergeRepair: current,
+    };
+  }
+
+  if (current.attempts >= current.max_attempts) {
+    return {
+      allowed: false,
+      exhausted: true,
+      nextStatus: STATUS.FAILED,
+      attemptNumber: null,
+      mergeRepair: {
+        ...current,
+        active: false,
+        exhausted_at: current.exhausted_at ?? params.requestedAt,
+      },
+    };
+  }
+
+  const nextAttempt = current.attempts + 1;
+  return {
+    allowed: true,
+    exhausted: false,
+    nextStatus: STATUS.QA,
+    attemptNumber: nextAttempt,
+    mergeRepair: {
+      ...current,
+      attempts: nextAttempt,
+      active: true,
+      requested_at: params.requestedAt,
+      reviewer_message: params.reviewerMessage,
+      exhausted_at: null,
+    },
+  };
+}
+
+export function clearActiveMergeRepair(frontMatter: AnyRecord): MergeRepairState {
+  const current = normalizeMergeRepairState(frontMatter);
+  return {
+    ...current,
+    active: false,
+  };
+}

package/apps/control-plane/src/core/path-layout.ts

@@ -33,12 +33,32 @@ export class AopPathLayout {
     return path.join(this.runtimeDataRoot, 'operation-ledger');
   }
 
+  instanceRuntimeRoot(instanceId: string): string {
+    return path.join(this.runtimeDataRoot, instanceId);
+  }
+
   runLeaseFilePath(instanceId: string): string {
-    return path.join(this.runtimeDataRoot, instanceId, 'run-lease.json');
+    return path.join(this.instanceRuntimeRoot(instanceId), 'run-lease.json');
   }
 
   runLeaseLockPath(instanceId: string): string {
-    return path.join(this.runtimeDataRoot, instanceId, '.run-lease.lock');
+    return path.join(this.instanceRuntimeRoot(instanceId), '.run-lease.lock');
+  }
+
+  executionControlPath(instanceId: string): string {
+    return path.join(this.instanceRuntimeRoot(instanceId), 'execution-control.json');
+  }
+
+  organizerOrderingPath(instanceId: string): string {
+    return path.join(this.instanceRuntimeRoot(instanceId), 'organizer-ordering.json');
+  }
+
+  organizerOrderingSchemaPath(): string {
+    return path.join(
+      this.legacyOrchestratorRoot,
+      'schemas',
+      'organizer-ordering-artifact.schema.json',
+    );
   }
 
   get legacyFeaturesRoot(): string {
@@ -73,6 +93,10 @@ export class AopPathLayout {
     return path.join(this.featureRoot(featureId), 'plan.json');
   }
 
+  planMarkdownPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'plan.md');
+  }
+
   featureCostPath(featureId: string): string {
     return path.join(this.featureRoot(featureId), 'cost.json');
   }
@@ -85,6 +109,10 @@ export class AopPathLayout {
     return path.join(this.featureRoot(featureId), 'decisions.md');
   }
 
+  questionsPath(featureId: string): string {
+    return path.join(this.featureRoot(featureId), 'questions.json');
+  }
+
   logsPath(featureId: string): string {
     return path.join(this.featureRoot(featureId), 'logs');
   }
@@ -96,6 +124,22 @@ export class AopPathLayout {
   specPath(featureId: string): string {
     return path.join(this.featureRoot(featureId), 'spec.md');
   }
+
+  replayDir(): string {
+    return path.join(this.runtimeDataRoot, 'replay');
+  }
+
+  replayTimelinePath(runId: string): string {
+    return path.join(this.replayDir(), `${runId}.timeline.jsonl`);
+  }
+
+  replayMetaPath(runId: string): string {
+    return path.join(this.replayDir(), `${runId}.meta.json`);
+  }
+
+  replayLockPath(runId: string): string {
+    return path.join(this.replayDir(), `${runId}.lock`);
+  }
 }
 
 async function copyLegacyRuntimeTree(sourcePath: string, targetPath: string): Promise<void> {

package/apps/control-plane/src/core/path-rules.ts

@@ -6,6 +6,10 @@ function normalizeSeparators(value: string): string {
   return value.replaceAll('\\\\', '/');
 }
 
+function hasGlobSyntax(value: string): boolean {
+  return /[*?[\]{}()!+@]/.test(value);
+}
+
 export class RepoPathNormalizer {
   async normalize(
     repoRoot: string,
@@ -40,12 +44,16 @@ export class RepoPathNormalizer {
 
 export class AreaMatchingPolicy {
   areaMatches(repoRelativePath: string, area: string, matchingMode = 'repo_prefix'): boolean {
-    if (matchingMode === 'glob') {
+    const normalizedArea = area.endsWith('/') ? area : `${area}/`;
+    if (repoRelativePath === area || repoRelativePath.startsWith(normalizedArea)) {
+      return true;
+    }
+
+    if (matchingMode === 'glob' || hasGlobSyntax(area)) {
       return new Minimatch(area, { dot: true, nocase: false }).match(repoRelativePath);
     }
 
-    const normalizedArea = area.endsWith('/') ? area : `${area}/`;
-    return repoRelativePath === area || repoRelativePath.startsWith(normalizedArea);
+    return false;
   }
 
   anyAreaMatch(repoRelativePath: string, areas: string[], matchingMode = 'repo_prefix'): boolean {

package/apps/control-plane/src/core/plan-submit-recovery.ts

@@ -0,0 +1,130 @@
+import { ERROR_CODES } from './error-codes.js';
+import { stableHash } from './fs.js';
+
+export type PlanRecord = Record<string, unknown>;
+
+export function asPlanRecord(value: unknown): PlanRecord {
+  return value && typeof value === 'object' ? (value as PlanRecord) : {};
+}
+
+export function readPlanVersion(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+    return null;
+  }
+  return Math.floor(value);
+}
+
+function sortJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJsonValue(item));
+  }
+
+  if (value && typeof value === 'object') {
+    const record = value as PlanRecord;
+    return Object.fromEntries(
+      Object.keys(record)
+        .sort((left, right) => left.localeCompare(right))
+        .map((key) => [key, sortJsonValue(record[key])]),
+    );
+  }
+
+  return value;
+}
+
+export function comparablePlanHash(plan: PlanRecord): string {
+  const comparable = {
+    ...plan,
+    plan_version: undefined,
+    revision_of: undefined,
+    revision_reason: undefined,
+  };
+  return stableHash(JSON.stringify(sortJsonValue(comparable)));
+}
+
+export function buildRecoveredPlanUpdate(
+  featureId: string,
+  submittedPlan: PlanRecord,
+  currentPlanVersion: number,
+): PlanRecord {
+  const trimmedReason =
+    typeof submittedPlan.revision_reason === 'string' ? submittedPlan.revision_reason.trim() : '';
+
+  return {
+    ...submittedPlan,
+    feature_id: featureId,
+    plan_version: currentPlanVersion + 1,
+    revision_of: currentPlanVersion,
+    revision_reason:
+      trimmedReason.length > 0
+        ? trimmedReason
+        : 'Recovered stale planner plan mutation after a newer accepted plan already existed.',
+  };
+}
+
+export function isPlanVersionConflictError(error: unknown): boolean {
+  const directCode =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? (error as { code?: unknown }).code
+      : null;
+  if (directCode === ERROR_CODES.VERSION_CONFLICT) {
+    return true;
+  }
+
+  const normalizedCode =
+    typeof error === 'object' &&
+    error !== null &&
+    'normalizedResponse' in error &&
+    typeof (error as { normalizedResponse?: unknown }).normalizedResponse === 'object' &&
+    (error as { normalizedResponse?: { error?: { code?: unknown } } }).normalizedResponse?.error
+      ?.code === ERROR_CODES.VERSION_CONFLICT;
+  return normalizedCode;
+}
+
+export async function recoverStalePlanVersionConflict<TResult>(params: {
+  error: unknown;
+  featureId: string;
+  submittedPlan: PlanRecord;
+  readAcceptedPlan: (featureId: string) => Promise<unknown>;
+  submitPlanUpdate: (
+    featureId: string,
+    expectedPlanVersion: number,
+    plan: PlanRecord,
+  ) => Promise<TResult>;
+  buildEquivalentSuccess: (featureId: string, currentPlanVersion: number) => TResult;
+}): Promise<TResult | null> {
+  if (!isPlanVersionConflictError(params.error) || Object.keys(params.submittedPlan).length === 0) {
+    return null;
+  }
+
+  const currentPlan = asPlanRecord(await params.readAcceptedPlan(params.featureId));
+  const currentPlanVersion = readPlanVersion(currentPlan.plan_version);
+  if (currentPlanVersion == null) {
+    return null;
+  }
+
+  if (comparablePlanHash(currentPlan) === comparablePlanHash(params.submittedPlan)) {
+    return params.buildEquivalentSuccess(params.featureId, currentPlanVersion);
+  }
+
+  const promotedPlan = buildRecoveredPlanUpdate(
+    params.featureId,
+    params.submittedPlan,
+    currentPlanVersion,
+  );
+  return await params.submitPlanUpdate(params.featureId, currentPlanVersion, promotedPlan);
+}
+
+export async function recoverStalePlanSubmitConflict<TResult>(params: {
+  error: unknown;
+  featureId: string;
+  submittedPlan: PlanRecord;
+  readAcceptedPlan: (featureId: string) => Promise<unknown>;
+  submitPlanUpdate: (
+    featureId: string,
+    expectedPlanVersion: number,
+    plan: PlanRecord,
+  ) => Promise<TResult>;
+  buildEquivalentSuccess: (featureId: string, currentPlanVersion: number) => TResult;
+}): Promise<TResult | null> {
+  return await recoverStalePlanVersionConflict(params);
+}

package/apps/control-plane/src/core/questions.ts

@@ -0,0 +1,49 @@
+export type QuestionStatus = 'open' | 'answered' | 'expired' | 'withdrawn';
+
+export type QuestionType =
+  | 'clarification'
+  | 'permission_override'
+  | 'external_decision'
+  | 'risk_ack';
+
+export interface QuestionExpectedAnswer {
+  kind: string;
+  choices?: string[];
+  schema?: Record<string, unknown>;
+}
+
+export interface QuestionRecord {
+  question_id: string;
+  status: QuestionStatus;
+  blocking: boolean;
+  question_type: QuestionType;
+  role: string;
+  phase: string;
+  request_action: string;
+  session_id: string;
+  prompt: string;
+  details: Record<string, unknown>;
+  expected_answer: QuestionExpectedAnswer | null;
+  created_at: string;
+  expires_at: string | null;
+  answer: string | Record<string, unknown> | null;
+  answered_at: string | null;
+  answered_by: string | null;
+  resume_status: string | null;
+  resume_phase: string | null;
+}
+
+export interface QuestionArtifact {
+  version: 1;
+  feature_id: string;
+  items: QuestionRecord[];
+}
+
+export interface HumanInputStateSnapshot {
+  open_question_id: string | null;
+  open_question_count: number;
+  awaiting_since: string | null;
+  requested_by_role: string | null;
+  prompt_summary: string | null;
+  resume_status: string | null;
+}

package/apps/control-plane/src/core/runtime-sessions.ts

@@ -7,6 +7,10 @@ export interface RuntimeFeatureSessions {
 export interface RuntimeSessionsSnapshot {
   run_id: string;
   orchestrator_session_id: string;
+  reconciler_session_id?: string;
+  organizer_session_id?: string;
+  reconciler_active_feature_id?: string | null;
+  reconciler_queue?: string[];
   provider: string;
   model: string;
   provider_config_ref_hash: string;

package/apps/control-plane/src/core/schemas.ts

@@ -19,6 +19,7 @@ export interface SchemaValidator {
 
 type AjvLike = {
   compile(schema: AnySchema): ValidateFunction;
+  addSchema?: (schema: AnySchema, key?: string) => AjvLike;
   addFormat?: (
     name: string,
     format:
@@ -28,6 +29,7 @@ type AjvLike = {
           validate: (value: string) => boolean;
         },
   ) => AjvLike;
+  getSchema?: (key: string) => ValidateFunction | undefined;
 };
 
 const RFC3339_DATE_TIME =
@@ -103,6 +105,7 @@ export class SchemaRegistry implements SchemaValidator {
   readonly schemaRoot: string;
   private readonly ajv: AjvLike;
   private readonly validators: Map<SchemaId, ValidateFunction>;
+  private localSchemasPreloaded: boolean;
 
   constructor(repoRoot: string) {
     this.repoRoot = repoRoot;
@@ -116,6 +119,7 @@ export class SchemaRegistry implements SchemaValidator {
       validate: isStrictRfc3339DateTime,
     });
     this.validators = new Map();
+    this.localSchemasPreloaded = false;
   }
 
   private resolveSchemaRoot(): string {
@@ -144,11 +148,46 @@ export class SchemaRegistry implements SchemaValidator {
     return path.join(this.schemaRoot, name);
   }
 
+  private async preloadLocalSchemas(): Promise<void> {
+    if (this.localSchemasPreloaded || !this.ajv.addSchema) {
+      this.localSchemasPreloaded = true;
+      return;
+    }
+
+    const entries = await fs.readdir(this.schemaRoot, { withFileTypes: true });
+    const schemaFiles = entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+      .map((entry) => entry.name)
+      .sort((left, right) => left.localeCompare(right));
+
+    for (const fileName of schemaFiles) {
+      const filePath = this.schemaPath(fileName);
+      const schemaText = await fs.readFile(filePath, 'utf8');
+      const schema = JSON.parse(schemaText) as AnySchema;
+      const schemaId =
+        typeof (schema as Record<string, unknown>).$id === 'string'
+          ? ((schema as Record<string, unknown>).$id as string)
+          : null;
+      if (!schemaId || this.ajv.getSchema?.(schemaId)) {
+        continue;
+      }
+      this.ajv.addSchema(schema);
+    }
+
+    this.localSchemasPreloaded = true;
+  }
+
   async loadSchema(name: SchemaId): Promise<ValidateFunction> {
+    await this.preloadLocalSchemas();
     const filePath = this.schemaPath(name);
     const schemaText = await fs.readFile(filePath, 'utf8');
     const schema = JSON.parse(schemaText) as AnySchema;
-    const validator = this.ajv.compile(schema);
+    const schemaId =
+      typeof (schema as Record<string, unknown>).$id === 'string'
+        ? ((schema as Record<string, unknown>).$id as string)
+        : null;
+    const validator =
+      (schemaId ? this.ajv.getSchema?.(schemaId) : undefined) ?? this.ajv.compile(schema);
     this.validators.set(name, validator);
     return validator;
   }

package/apps/control-plane/src/core/tool-caller.ts

@@ -1,4 +1,10 @@
-export type RuntimeRole = 'orchestrator' | 'planner' | 'builder' | 'qa';
+export type RuntimeRole =
+  | 'orchestrator'
+  | 'planner'
+  | 'builder'
+  | 'qa'
+  | 'reconciler'
+  | 'organizer';
 
 export interface GatesRunToolArgs {
   feature_id: string;
@@ -23,6 +29,17 @@ export interface ToolCaller {
   ): Promise<{ ok: true; data: TData }>;
 }
 
+export interface FeatureRecoveryState {
+  state: 'retrying' | 'awaiting_operator';
+  cause?: string;
+  role?: 'planner' | 'builder' | 'qa' | 'orchestrator' | 'reconciler' | string;
+  resume_phase?: string;
+  attempt?: number;
+  run_id?: string;
+  started_at?: string;
+  last_attempt_at?: string;
+}
+
 export interface FeatureStateFrontMatter {
   version: number;
   status: string;
@@ -35,6 +52,9 @@ export interface FeatureStateFrontMatter {
     violations?: string[];
     severity?: 'info' | 'warning' | 'error' | 'critical';
     diff_snapshot?: string;
+    diff_hash?: string;
+    duplicate_of_checkpoint_id?: string;
+    net_new_worktree_change?: boolean;
   }>;
   cluster?: Record<string, string>;
   gate_retry_count?: number;
@@ -43,6 +63,10 @@ export interface FeatureStateFrontMatter {
   last_run_at?: string;
   worktree_branch?: string;
   branch?: string;
+  status_reason?: string;
+  recovery?: FeatureRecoveryState | null;
+  gates?: Record<string, string>;
+  evidence?: Record<string, unknown>;
   pr?: {
     number: number;
     url: string;

package/apps/control-plane/src/core/utils/index-normalizer.ts

@@ -9,6 +9,9 @@ export function emptyRuntimeSessions(at = nowIso()): RuntimeSessionsSnapshot {
   return {
     run_id: 'none',
     orchestrator_session_id: 'unknown',
+    reconciler_session_id: 'unknown',
+    reconciler_active_feature_id: null,
+    reconciler_queue: [],
     provider: 'unknown',
     model: 'unknown',
     provider_config_ref_hash: stableHash('none'),
@@ -42,6 +45,9 @@ export function normalizeRuntimeSessions(value: unknown, at = nowIso()): Runtime
       builder_session_id:
         typeof typed.builder_session_id === 'string' ? typed.builder_session_id : 'unassigned',
       qa_session_id: typeof typed.qa_session_id === 'string' ? typed.qa_session_id : 'unassigned',
+      ...(typeof typed.reconciler_session_id === 'string'
+        ? { reconciler_session_id: typed.reconciler_session_id }
+        : {}),
     };
   }
 
@@ -56,6 +62,18 @@ export function normalizeRuntimeSessions(value: unknown, at = nowIso()): Runtime
       typeof source.orchestrator_session_id === 'string' && source.orchestrator_session_id
         ? source.orchestrator_session_id
         : fallback.orchestrator_session_id,
+    reconciler_session_id:
+      typeof source.reconciler_session_id === 'string' && source.reconciler_session_id
+        ? source.reconciler_session_id
+        : fallback.reconciler_session_id,
+    reconciler_active_feature_id:
+      typeof source.reconciler_active_feature_id === 'string' &&
+      source.reconciler_active_feature_id.length > 0
+        ? source.reconciler_active_feature_id
+        : null,
+    reconciler_queue: asArray(source.reconciler_queue).filter(
+      (item): item is string => typeof item === 'string' && item.length > 0,
+    ),
     provider:
       typeof source.provider === 'string' && source.provider ? source.provider : fallback.provider,
     model: typeof source.model === 'string' && source.model ? source.model : fallback.model,
@@ -103,6 +121,12 @@ export function normalizeIndexShape(value: unknown): AnyRecord {
     lock_leases:
       source.lock_leases && typeof source.lock_leases === 'object' ? source.lock_leases : {},
     blocked_queue: asArray(source.blocked_queue).filter((item) => item && typeof item === 'object'),
+    collision_records: asArray(source.collision_records).filter(
+      (item) => item && typeof item === 'object',
+    ),
+    collision_overrides: asArray(source.collision_overrides).filter(
+      (item) => item && typeof item === 'object',
+    ),
     dep_blocked: asArray(source.dep_blocked).filter((item) => item && typeof item === 'object'),
     updated_at:
       typeof source.updated_at === 'string' && source.updated_at ? source.updated_at : now,
@@ -112,8 +136,5 @@ export function normalizeIndexShape(value: unknown): AnyRecord {
 
 export function isRunLeaseFresh(runtimeSessions: RuntimeSessionsSnapshot): boolean {
   const expiry = new Date(runtimeSessions.lease_expires_at).getTime();
-  if (!Number.isFinite(expiry)) {
-    return false;
-  }
-  return expiry > Date.now();
+  return Number.isFinite(expiry) && expiry > Date.now();
 }