agentic-orchestrator 0.2.7 → 0.2.10

package/apps/control-plane/src/application/services/intake-service.ts

@@ -604,6 +604,14 @@ function isOpenIntakeQuestion(question: QuestionEvidenceRecord): boolean {
   return question.status === 'open' && isIntakeQuestion(question);
 }
 
+function resolveQuestionAmbiguityIds(details: Record<string, unknown>): string[] {
+  const fromPlural = normalizeAmbiguityIds(details.ambiguity_ids);
+  if (fromPlural.length > 0) {
+    return fromPlural;
+  }
+  return normalizeAmbiguityIds(details.ambiguity_id);
+}
+
 function isAnsweredIntakeClarification(question: QuestionEvidenceRecord): boolean {
   return (
     question.status === 'answered' &&
@@ -613,7 +621,7 @@ function isAnsweredIntakeClarification(question: QuestionEvidenceRecord): boolea
     question.answered_at !== null &&
     question.answered_by !== null &&
     isIntakeQuestion(question) &&
-    normalizeAmbiguityIds(question.details.ambiguity_ids).length > 0
+    resolveQuestionAmbiguityIds(question.details).length > 0
   );
 }
 
@@ -625,7 +633,7 @@ function buildClarificationAnswers(
   return questions
     .filter((question) => isAnsweredIntakeClarification(question))
     .map((question) => {
-      const ambiguityIds = normalizeAmbiguityIds(question.details.ambiguity_ids);
+      const ambiguityIds = resolveQuestionAmbiguityIds(question.details);
       const obligationIds = normalizeObligationIds(question.details.obligation_ids);
       const resolutionStatus = ambiguityIds.every(
         (ambiguityId) => ambiguityStatus.get(ambiguityId) === 'resolved',
@@ -795,18 +803,9 @@ export class IntakeService {
         return false;
       });
     if (duplicateObligationIds.length > 0) {
-      throw {
-        normalizedResponse: fail(
-          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
-          'verified manifest contains duplicate obligation ids after normalization',
-          {
-            feature_id: featureId,
-            duplicate_obligation_ids: normalizeUniqueStrings(duplicateObligationIds),
-            retryable: false,
-            requires_human: true,
-          },
-        ),
-      };
+      console.warn(
+        `[intake] ${featureId}: deduplicating ${duplicateObligationIds.length} duplicate obligation ids (${normalizeUniqueStrings(duplicateObligationIds).join(', ')})`,
+      );
     }
 
     return {
@@ -1347,19 +1346,10 @@ export class IntakeService {
       verifiedManifest.source_bootstrap_version !== null &&
       verifiedManifest.source_bootstrap_version !== bootstrapManifest.manifest_version
     ) {
-      throw {
-        normalizedResponse: fail(
-          ERROR_CODES.INTAKE_SUBMISSION_INVALID,
-          'verified manifest must reference the current bootstrap manifest version',
-          {
-            feature_id: featureId,
-            expected_source_bootstrap_version: bootstrapManifest.manifest_version,
-            received_source_bootstrap_version: verifiedManifest.source_bootstrap_version,
-            retryable: false,
-            requires_human: true,
-          },
-        ),
-      };
+      console.warn(
+        `[intake] ${featureId}: auto-correcting source_bootstrap_version from ${verifiedManifest.source_bootstrap_version} to ${bootstrapManifest.manifest_version}`,
+      );
+      verifiedManifest.source_bootstrap_version = bootstrapManifest.manifest_version;
     }
     await this.validateVerificationBasisEvidence(
       featureId,

package/apps/control-plane/src/application/services/plan-service.ts

@@ -1021,22 +1021,22 @@ export class PlanService {
     );
 
     if (!traceValidation.valid) {
-      throw {
-        normalizedResponse: fail(
-          ERROR_CODES.PLAN_TRACE_INVALID,
-          'plan trace does not match the verified manifest contract',
-          {
-            feature_id: featureId,
-            missing_obligation_ids: traceValidation.missing_obligation_ids,
-            unknown_obligation_ids: traceValidation.unknown_obligation_ids,
-            duplicate_obligation_ids: traceValidation.duplicate_obligation_ids,
-            invalid_mappings: traceValidation.invalid_mappings,
-            invalid_mapping_details: traceValidation.invalid_mapping_details,
-            retryable: false,
-            requires_human: true,
-          },
-        ),
-      };
+      const issues: string[] = [];
+      if (traceValidation.missing_obligation_ids.length > 0) {
+        issues.push(`missing: ${traceValidation.missing_obligation_ids.join(', ')}`);
+      }
+      if (traceValidation.unknown_obligation_ids.length > 0) {
+        issues.push(`unknown: ${traceValidation.unknown_obligation_ids.join(', ')}`);
+      }
+      if (traceValidation.duplicate_obligation_ids.length > 0) {
+        issues.push(`duplicates: ${traceValidation.duplicate_obligation_ids.join(', ')}`);
+      }
+      if (traceValidation.invalid_mappings.length > 0) {
+        issues.push(`invalid mappings: ${traceValidation.invalid_mappings.join(', ')}`);
+      }
+      console.warn(
+        `[plan-trace] ${featureId}: trace mismatch accepted with warnings — ${issues.join('; ')}`,
+      );
     }
   }
 }

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

@@ -483,6 +483,15 @@ export class BuildWaveExecutor {
             await this.reactionsService.notifyEscalation(featureId, escalateCtx);
           }
         }
+      } catch (error) {
+        if ((error as Record<string, unknown>)?._failRun === true) {
+          throw error;
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        console.warn(
+          `[build-wave] feature ${featureId} failed, continuing with remaining features: ${msg}`,
+        );
+        await this.blockFeatureOnUnhandledError(featureId, error);
       } finally {
         if (this.safeCheckpointHook) {
           await this.safeCheckpointHook();
@@ -601,6 +610,7 @@ export class BuildWaveExecutor {
       message,
     });
     if (policyAction === 'fail_run') {
+      (error as Record<string, unknown>)._failRun = true;
       throw error;
     }
     await this.applyWorkerPolicyAction(featureId, policyAction, code, message, phase);
@@ -721,6 +731,7 @@ export class BuildWaveExecutor {
       const error = new Error(message) as Error & {
         code?: string;
         details?: Record<string, unknown>;
+        _failRun?: boolean;
       };
       error.code = errorCode;
       error.details = {
@@ -728,6 +739,7 @@ export class BuildWaveExecutor {
         retryable: false,
         requires_human: true,
       };
+      error._failRun = true;
       throw error;
     }
     await this.applyWorkerPolicyAction(featureId, action, errorCode, message, phase);
@@ -926,6 +938,20 @@ export class BuildWaveExecutor {
     }
   }
 
+  private async blockFeatureOnUnhandledError(featureId: string, error: unknown): Promise<void> {
+    const typed = error as { code?: string; message?: string };
+    const code =
+      typeof typed.code === 'string' && typed.code.length > 0
+        ? typed.code
+        : 'unhandled_build_error';
+    const message = typed.message ?? String(error);
+    try {
+      await this.applyWorkerPolicyAction(featureId, 'block_feature', code, message, 'build');
+    } catch {
+      // Best-effort
+    }
+  }
+
   private async applyWorkerPolicyAction(
     featureId: string,
     action:
@@ -941,6 +967,7 @@ export class BuildWaveExecutor {
       const error = new Error(message) as Error & {
         code?: string;
         details?: Record<string, unknown>;
+        _failRun?: boolean;
       };
       error.code = errorCode;
       error.details = {
@@ -948,6 +975,7 @@ export class BuildWaveExecutor {
         retryable: false,
         requires_human: true,
       };
+      error._failRun = true;
       throw error;
     }
 

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

@@ -466,6 +466,15 @@ export class PlanningWaveExecutor {
             plan_json: plan,
           });
         }
+      } catch (error) {
+        if (this.isFailRunPolicyError(error)) {
+          throw error;
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        console.warn(
+          `[planning-wave] feature ${featureId} failed, continuing with remaining features: ${msg}`,
+        );
+        await this.blockFeatureOnUnhandledError(featureId, error);
       } finally {
         if (this.safeCheckpointHook) {
           await this.safeCheckpointHook();
@@ -1128,6 +1137,7 @@ export class PlanningWaveExecutor {
       message,
     });
     if (policyAction === 'fail_run') {
+      (error as Record<string, unknown>)._failRun = true;
       throw error;
     }
     await this.applyWorkerPolicyAction(featureId, policyAction, code, message, 'planning');
@@ -1184,13 +1194,14 @@ export class PlanningWaveExecutor {
     if (this.outputLoopStallAction === 'fail_run') {
       const error = new Error(
         `Planner output loop detected after ${consecutiveIterations} consecutive identical iterations`,
-      ) as Error & { code?: string; details?: Record<string, unknown> };
+      ) as Error & { code?: string; details?: Record<string, unknown>; _failRun?: boolean };
       error.code = ERROR_CODES.PROVIDER_OUTPUT_LOOP;
       error.details = {
         feature_id: featureId,
         retryable: false,
         requires_human: true,
       };
+      error._failRun = true;
       throw error;
     }
 
@@ -1530,6 +1541,25 @@ export class PlanningWaveExecutor {
     };
   }
 
+  private isFailRunPolicyError(error: unknown): boolean {
+    const typed = error as { _failRun?: boolean };
+    return typed?._failRun === true;
+  }
+
+  private async blockFeatureOnUnhandledError(featureId: string, error: unknown): Promise<void> {
+    const typed = error as { code?: string; message?: string };
+    const code =
+      typeof typed.code === 'string' && typed.code.length > 0
+        ? typed.code
+        : 'unhandled_planning_error';
+    const message = typed.message ?? String(error);
+    try {
+      await this.applyWorkerPolicyAction(featureId, 'block_feature', code, message, 'planning');
+    } catch {
+      // Best-effort — if we can't block the feature, at least we logged above
+    }
+  }
+
   private async applyWorkerPolicyAction(
     featureId: string,
     action:
@@ -1545,6 +1575,7 @@ export class PlanningWaveExecutor {
       const error = new Error(message) as Error & {
         code?: string;
         details?: Record<string, unknown>;
+        _failRun?: boolean;
       };
       error.code = errorCode;
       error.details = {
@@ -1552,6 +1583,7 @@ export class PlanningWaveExecutor {
         retryable: false,
         requires_human: true,
       };
+      error._failRun = true;
       throw error;
     }
 

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

@@ -462,6 +462,15 @@ export class QaWaveExecutor {
           orchestrator_session_id: this.state.orchestratorSessionId ?? 'unknown',
           qa_session_id: newQa.session_id,
         });
+      } catch (error) {
+        if ((error as Record<string, unknown>)?._failRun === true) {
+          throw error;
+        }
+        const msg = error instanceof Error ? error.message : String(error);
+        console.warn(
+          `[qa-wave] feature ${featureId} failed, continuing with remaining features: ${msg}`,
+        );
+        await this.blockFeatureOnUnhandledError(featureId, error);
       } finally {
         if (this.safeCheckpointHook) {
           await this.safeCheckpointHook();
@@ -470,6 +479,18 @@ export class QaWaveExecutor {
     }
   }
 
+  private async blockFeatureOnUnhandledError(featureId: string, error: unknown): Promise<void> {
+    const typed = error as { code?: string; message?: string };
+    const code =
+      typeof typed.code === 'string' && typed.code.length > 0 ? typed.code : 'unhandled_qa_error';
+    const message = typed.message ?? String(error);
+    try {
+      await this.applyWorkerPolicyAction(featureId, 'block_feature', code, message, 'qa');
+    } catch {
+      // Best-effort
+    }
+  }
+
   private asRecord(value: unknown): Record<string, unknown> {
     return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
   }
@@ -568,6 +589,8 @@ export class QaWaveExecutor {
         policyAction: 'block_feature',
         message: `${message} (auto-retry once at same phase)`,
       });
+      // Tag for propagation — the coordinator retries the feature on the next iteration
+      (error as Record<string, unknown>)._failRun = true;
       return false;
     }
 
@@ -579,6 +602,7 @@ export class QaWaveExecutor {
       message,
     });
     if (policyAction === 'fail_run') {
+      (error as Record<string, unknown>)._failRun = true;
       throw error;
     }
     await this.applyWorkerPolicyAction(featureId, policyAction, code, message, phase);
@@ -699,6 +723,7 @@ export class QaWaveExecutor {
       const error = new Error(message) as Error & {
         code?: string;
         details?: Record<string, unknown>;
+        _failRun?: boolean;
       };
       error.code = errorCode;
       error.details = {
@@ -706,6 +731,7 @@ export class QaWaveExecutor {
         retryable: false,
         requires_human: true,
       };
+      error._failRun = true;
       throw error;
     }
     await this.applyWorkerPolicyAction(featureId, action, errorCode, message, phase);
@@ -876,6 +902,7 @@ export class QaWaveExecutor {
       const error = new Error(message) as Error & {
         code?: string;
         details?: Record<string, unknown>;
+        _failRun?: boolean;
       };
       error.code = errorCode;
       error.details = {
@@ -883,6 +910,7 @@ export class QaWaveExecutor {
         retryable: false,
         requires_human: true,
       };
+      error._failRun = true;
       throw error;
     }
 

package/apps/control-plane/test/organizer-sidecar-service.spec.ts

@@ -48,6 +48,84 @@ function makeMalformedResponse(): WorkerRunOutput {
   return { content: '{ not valid json' };
 }
 
+function makeEmbeddedJsonResponse(): WorkerRunOutput {
+  const ordering = {
+    type: 'ORDERING',
+    ordering: {
+      dependency_graph: {
+        feat_a: { depends_on: [], classification: 'no_dependency_found' },
+      },
+      ready_set: ['feat_a'],
+      deferred_set: [],
+      blocked_set: [],
+    },
+  };
+  return { content: `Here is the ordering:\n${JSON.stringify(ordering)}\nDone.` };
+}
+
+function makeTextFieldResponse(): WorkerRunOutput {
+  const ordering = {
+    type: 'ORDERING',
+    ordering: {
+      dependency_graph: {
+        feat_a: { depends_on: [], classification: 'no_dependency_found' },
+      },
+      ready_set: ['feat_a'],
+      deferred_set: [],
+      blocked_set: [],
+    },
+  };
+  return { text: JSON.stringify(ordering) } as unknown as WorkerRunOutput;
+}
+
+function makeResponseFieldOutput(): WorkerRunOutput {
+  const ordering = {
+    type: 'ORDERING',
+    ordering: {
+      dependency_graph: {
+        feat_a: { depends_on: [], classification: 'no_dependency_found' },
+      },
+      ready_set: ['feat_a'],
+      deferred_set: [],
+      blocked_set: [],
+    },
+  };
+  return { response: JSON.stringify(ordering) } as unknown as WorkerRunOutput;
+}
+
+function makeStringifyFallbackResponse(): WorkerRunOutput {
+  const ordering = {
+    type: 'ORDERING',
+    ordering: {
+      dependency_graph: {
+        feat_a: { depends_on: [], classification: 'no_dependency_found' },
+      },
+      ready_set: ['feat_a'],
+      deferred_set: [],
+      blocked_set: [],
+    },
+  };
+  // No content/text/response/outputs — forces stringify fallback
+  return { data: ordering } as unknown as WorkerRunOutput;
+}
+
+function makeOutputsArrayResponse(): WorkerRunOutput {
+  const ordering = {
+    type: 'ORDERING',
+    ordering: {
+      dependency_graph: {
+        feat_a: { depends_on: [], classification: 'no_dependency_found' },
+      },
+      ready_set: ['feat_a'],
+      deferred_set: [],
+      blocked_set: [],
+    },
+  };
+  return {
+    outputs: [{ content: JSON.stringify(ordering) }],
+  } as unknown as WorkerRunOutput;
+}
+
 function makeInvalidClassificationResponse(): WorkerRunOutput {
   const ordering = {
     type: 'ORDERING',
@@ -408,6 +486,234 @@ describe('OrganizerSidecarService', () => {
     await expect(service.stop()).resolves.toBeUndefined();
   });
 
+  it('GIVEN_relative_spec_path_WHEN_collecting_specs_THEN_resolves_against_repoRoot', async () => {
+    const specPath = join(specDir, 'feat_a.md');
+    await writeFile(specPath, '# Spec A\nRelative path test', 'utf8');
+
+    // Use a relative path from the temp dir acting as repoRoot
+    const relativeSpecPath = specPath.replace(tempDir + '/', '');
+    const kernel = {
+      getRepoRoot: () => tempDir,
+      drainPendingExecutionRequests: vi.fn().mockResolvedValue({
+        data: {
+          items: [
+            {
+              request_id: 'req-feat_a',
+              request_type: 'add_features' as const,
+              status: 'pending' as const,
+              requested_at: new Date().toISOString(),
+              processed_at: null,
+              requested_by: 'cli:add',
+              operation_id: 'op-feat_a',
+              features: [{ feature_id: 'feat_a', spec_path: relativeSpecPath }],
+              progress: null,
+              outcome: null,
+            },
+          ],
+        },
+      }),
+      readState: vi.fn().mockResolvedValue({
+        frontMatter: { spec_path: null, status: 'active' },
+        body: '',
+      }),
+    };
+    const provider = makeProvider([makeValidOrderingResponse()]);
+    const state = makeState();
+
+    const service = new OrganizerSidecarService({
+      artifactPath,
+      kernel: kernel as never,
+      provider,
+      state,
+      organizerSessionId: () => state.organizerSessionId ?? null,
+      schemaValidator: validator,
+    });
+
+    await (service as any).performReconcile();
+
+    expect(existsSync(artifactPath)).toBe(true);
+    expect(provider.runWorker).toHaveBeenCalledTimes(1);
+    const call = (provider.runWorker as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(call.instructions).toContain('Relative path test');
+  });
+
+  it('GIVEN_spec_missing_WHEN_collecting_specs_THEN_logs_warning_once_per_feature', async () => {
+    const kernel = makeKernel({ feat_missing: join(specDir, 'nonexistent.md') });
+    const provider = makeProvider([makeValidOrderingResponse()]);
+    const state = makeState();
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    try {
+      const service = new OrganizerSidecarService({
+        artifactPath,
+        kernel: kernel as never,
+        provider,
+        state,
+        organizerSessionId: () => state.organizerSessionId ?? null,
+        schemaValidator: validator,
+      });
+
+      // First reconcile — should log the warning
+      await (service as any).performReconcile();
+      const firstCallCount = warnSpy.mock.calls.filter((c) =>
+        String(c[0]).includes('spec file missing'),
+      ).length;
+      expect(firstCallCount).toBe(1);
+
+      // Second reconcile — should NOT log again for the same feature
+      await (service as any).performReconcile();
+      const secondCallCount = warnSpy.mock.calls.filter((c) =>
+        String(c[0]).includes('spec file missing'),
+      ).length;
+      expect(secondCallCount).toBe(1);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it('GIVEN_active_session_feature_with_spec_path_WHEN_collecting_specs_THEN_reads_from_state', async () => {
+    const specPath = join(specDir, 'feat_session.md');
+    await writeFile(specPath, '# Session Spec', 'utf8');
+
+    const kernel = {
+      getRepoRoot: () => '/repo',
+      drainPendingExecutionRequests: vi.fn().mockResolvedValue({ data: { items: [] } }),
+      readState: vi.fn().mockResolvedValue({
+        frontMatter: { spec_path: specPath, status: 'planning' },
+        body: '',
+      }),
+    };
+    const provider = makeProvider([makeValidOrderingResponse()]);
+    const state = makeState();
+    state.sessionsByFeature.set('feat_session', {
+      planner: 'session-001',
+      builder: 'unassigned',
+      qa: 'unassigned',
+    });
+
+    const service = new OrganizerSidecarService({
+      artifactPath,
+      kernel: kernel as never,
+      provider,
+      state,
+      organizerSessionId: () => state.organizerSessionId ?? null,
+      schemaValidator: validator,
+    });
+
+    await (service as any).performReconcile();
+
+    expect(kernel.readState).toHaveBeenCalledWith('feat_session');
+    expect(provider.runWorker).toHaveBeenCalledTimes(1);
+    const call = (provider.runWorker as ReturnType<typeof vi.fn>).mock.calls[0][0];
+    expect(call.instructions).toContain('Session Spec');
+  });
+
+  it('GIVEN_json_embedded_in_text_WHEN_parsing_response_THEN_extracts_valid_artifact', async () => {
+    const specPath = join(specDir, 'feat_a.md');
+    await writeFile(specPath, '# Spec A', 'utf8');
+
+    const kernel = makeKernel({ feat_a: specPath });
+    const provider = makeProvider([makeEmbeddedJsonResponse()]);
+    const state = makeState();
+
+    const service = new OrganizerSidecarService({
+      artifactPath,
+      kernel: kernel as never,
+      provider,
+      state,
+      organizerSessionId: () => state.organizerSessionId ?? null,
+      schemaValidator: validator,
+    });
+
+    await (service as any).performReconcile();
+    expect(existsSync(artifactPath)).toBe(true);
+  });
+
+  it('GIVEN_text_field_response_WHEN_extracting_text_THEN_reads_from_text_property', async () => {
+    const specPath = join(specDir, 'feat_a.md');
+    await writeFile(specPath, '# Spec A', 'utf8');
+
+    const kernel = makeKernel({ feat_a: specPath });
+    const provider = makeProvider([makeTextFieldResponse()]);
+    const state = makeState();
+
+    const service = new OrganizerSidecarService({
+      artifactPath,
+      kernel: kernel as never,
+      provider,
+      state,
+      organizerSessionId: () => state.organizerSessionId ?? null,
+      schemaValidator: validator,
+    });
+
+    await (service as any).performReconcile();
+    expect(existsSync(artifactPath)).toBe(true);
+  });
+
+  it('GIVEN_response_field_WHEN_extracting_text_THEN_reads_from_response_property', async () => {
+    const specPath = join(specDir, 'feat_a.md');
+    await writeFile(specPath, '# Spec A', 'utf8');
+
+    const kernel = makeKernel({ feat_a: specPath });
+    const provider = makeProvider([makeResponseFieldOutput()]);
+    const state = makeState();
+
+    const service = new OrganizerSidecarService({
+      artifactPath,
+      kernel: kernel as never,
+      provider,
+      state,
+      organizerSessionId: () => state.organizerSessionId ?? null,
+      schemaValidator: validator,
+    });
+
+    await (service as any).performReconcile();
+    expect(existsSync(artifactPath)).toBe(true);
+  });
+
+  it('GIVEN_no_standard_text_fields_WHEN_extracting_text_THEN_falls_back_to_stringify', async () => {
+    const specPath = join(specDir, 'feat_a.md');
+    await writeFile(specPath, '# Spec A', 'utf8');
+
+    const kernel = makeKernel({ feat_a: specPath });
+    const provider = makeProvider([makeStringifyFallbackResponse()]);
+    const state = makeState();
+
+    const service = new OrganizerSidecarService({
+      artifactPath,
+      kernel: kernel as never,
+      provider,
+      state,
+      organizerSessionId: () => state.organizerSessionId ?? null,
+      schemaValidator: validator,
+    });
+
+    await (service as any).performReconcile();
+    // Stringify of the whole response includes the valid ordering JSON — should parse
+    expect(existsSync(artifactPath)).toBe(true);
+  });
+
+  it('GIVEN_outputs_array_response_WHEN_extracting_text_THEN_reads_from_outputs_content', async () => {
+    const specPath = join(specDir, 'feat_a.md');
+    await writeFile(specPath, '# Spec A', 'utf8');
+
+    const kernel = makeKernel({ feat_a: specPath });
+    const provider = makeProvider([makeOutputsArrayResponse()]);
+    const state = makeState();
+
+    const service = new OrganizerSidecarService({
+      artifactPath,
+      kernel: kernel as never,
+      provider,
+      state,
+      organizerSessionId: () => state.organizerSessionId ?? null,
+      schemaValidator: validator,
+    });
+
+    await (service as any).performReconcile();
+    expect(existsSync(artifactPath)).toBe(true);
+  });
+
   it('GIVEN_valid_artifact_WHEN_schema_validation_runs_THEN_passes', async () => {
     const specPath = join(specDir, 'feat_a.md');
     await writeFile(specPath, '# Spec A', 'utf8');