agentic-orchestrator 0.1.27 → 0.2.0

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

@@ -1,4 +1,5 @@
 import { TOOLS } from '../../core/constants.js';
+import type { GateLogExtraction } from '../../core/gate-log-extractor.js';
 import type {
   FeatureStatePayload,
   ToolCaller as SupervisorToolCaller,
@@ -46,6 +47,7 @@ export interface GateRepairContext {
     failed_at: string;
     retry_delay_ms?: number;
   }>;
+  failureAnalysis?: GateLogExtraction;
 }
 
 export interface ReactionsServiceDependencies {
@@ -180,24 +182,78 @@ export class ReactionsService {
             )
             .join('\n')
         : '(none)';
-    return [
-      'Gate execution failed. Review the error logs below and apply fixes.',
-      '',
-      `Gate: ${ctx.gateName}`,
-      `Exit Code: ${ctx.exitCode}`,
-      '',
-      'Logs:',
-      ctx.logs,
-      '',
-      'Evidence:',
-      ctx.evidenceSummary,
-      '',
-      `Retry: ${ctx.retryCount + 1} of ${maxRetries}`,
-      `Retry delay (ms): ${delayMs}`,
+
+    if (!ctx.failureAnalysis) {
+      return [
+        'Gate execution failed. Review the error logs below and apply fixes.',
+        '',
+        `Gate: ${ctx.gateName}`,
+        `Exit Code: ${ctx.exitCode}`,
+        '',
+        'Logs:',
+        ctx.logs,
+        '',
+        'Evidence:',
+        ctx.evidenceSummary,
+        '',
+        `Retry: ${ctx.retryCount + 1} of ${maxRetries}`,
+        `Retry delay (ms): ${delayMs}`,
+        '',
+        'Failure history (most recent first):',
+        failureSummary,
+      ].join('\n');
+    }
+
+    const { stepName, exitCode, affectedFiles, errorLines, summaryLines, errorCount, logTail } =
+      ctx.failureAnalysis;
+
+    const lines: string[] = [
+      `Gate \`${ctx.gateName}\` step \`${stepName}\` failed (exit ${exitCode}).`,
       '',
-      'Failure history (most recent first):',
-      failureSummary,
-    ].join('\n');
+    ];
+
+    if (affectedFiles.length > 0) {
+      lines.push(`Affected files (${affectedFiles.length}):`);
+      for (const ref of affectedFiles) {
+        const loc =
+          ref.col != null ? `${ref.path}:${ref.line}:${ref.col}` : `${ref.path}:${ref.line}`;
+        const msg = ref.message ? ` — ${ref.message}` : '';
+        lines.push(`  ${loc}${msg}`);
+      }
+      lines.push('');
+    }
+
+    if (errorCount != null || summaryLines.length > 0) {
+      const countLabel = errorCount != null ? `${errorCount} total` : '';
+      lines.push(`Errors${countLabel ? ` (${countLabel})` : ''}:`);
+      for (const sl of summaryLines) {
+        lines.push(`  ${sl}`);
+      }
+      lines.push('');
+    }
+
+    if (errorLines.length > 0) {
+      lines.push('Error output:');
+      for (const el of errorLines) {
+        lines.push(`  ${el}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('Fix all errors listed above before re-running.');
+    lines.push(`Retry: ${ctx.retryCount + 1} of ${maxRetries}`);
+    lines.push(`Retry delay (ms): ${delayMs}`);
+    lines.push('');
+    lines.push('Failure history (most recent first):');
+    lines.push(failureSummary);
+
+    if (logTail.trim().length > 0) {
+      lines.push('');
+      lines.push('Log tail (for reference):');
+      lines.push(logTail);
+    }
+
+    return lines.join('\n');
   }
 
   /**

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

@@ -0,0 +1,295 @@
+import fs from 'node:fs/promises';
+import { ensureDir, nowIso, pathExists, withFileLock } from '../../core/fs.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail, ok } from '../../core/response.js';
+import type { ToolResponse } from '../../core/response.js';
+import type { AopPathLayout } from '../../core/path-layout.js';
+
+export type IdempotencyStatus = 'none' | 'new' | 'replay' | 'mismatch';
+
+export interface TimelineEntry {
+  ts: string;
+  sequence: number;
+  run_id: string;
+  session_id: string;
+  actor_type: string;
+  feature_id: string | null;
+  tool_name: string;
+  mutating: boolean;
+  operation_id: string | null;
+  idempotency_status: IdempotencyStatus;
+  request_hash: string | null;
+  result: 'ok' | 'error';
+  error_code: string | null;
+  latency_ms: number;
+}
+
+interface RunMeta {
+  run_id: string;
+  sequence_head: number;
+  entry_count: number;
+  started_at: string;
+  last_entry_at: string;
+}
+
+export interface ReplayConfig {
+  enabled: boolean;
+  write_mode: 'best_effort' | 'required';
+  retention: {
+    max_runs: number;
+    max_entries_per_run: number;
+  };
+}
+
+const DEFAULT_CONFIG: ReplayConfig = {
+  enabled: true,
+  write_mode: 'best_effort',
+  retention: {
+    max_runs: 100,
+    max_entries_per_run: 50000,
+  },
+};
+
+function resolveConfig(policy: Record<string, unknown>): ReplayConfig {
+  const innovation = (policy.innovation ?? {}) as Record<string, unknown>;
+  const observability = (policy.observability ?? {}) as Record<string, unknown>;
+  const replay = (observability.replay ?? {}) as Record<string, unknown>;
+  const retention = (replay.retention ?? {}) as Record<string, unknown>;
+
+  const replayDebugger = innovation.replay_debugger !== false;
+  const replayEnabled = replay.enabled !== false;
+
+  if (!replayDebugger || !replayEnabled) {
+    return { ...DEFAULT_CONFIG, enabled: false };
+  }
+
+  const writeMode =
+    replay.write_mode === 'required' ? ('required' as const) : ('best_effort' as const);
+
+  return {
+    enabled: true,
+    write_mode: writeMode,
+    retention: {
+      max_runs:
+        typeof retention.max_runs === 'number'
+          ? retention.max_runs
+          : DEFAULT_CONFIG.retention.max_runs,
+      max_entries_per_run:
+        typeof retention.max_entries_per_run === 'number'
+          ? retention.max_entries_per_run
+          : DEFAULT_CONFIG.retention.max_entries_per_run,
+    },
+  };
+}
+
+export class ReplayTimelineService {
+  readonly pathLayout: AopPathLayout;
+
+  constructor(pathLayout: AopPathLayout) {
+    this.pathLayout = pathLayout;
+  }
+
+  async append(event: TimelineEntry, policy: Record<string, unknown>): Promise<void> {
+    const config = resolveConfig(policy);
+    if (!config.enabled) {
+      return;
+    }
+
+    const runId = event.run_id;
+
+    const doAppend = async (): Promise<void> => {
+      await ensureDir(this.pathLayout.replayDir());
+
+      const lockPath = this.pathLayout.replayLockPath(runId);
+      const metaPath = this.pathLayout.replayMetaPath(runId);
+      const timelinePath = this.pathLayout.replayTimelinePath(runId);
+
+      await withFileLock(lockPath, async () => {
+        let meta: RunMeta | null = null;
+        try {
+          const raw = await fs.readFile(metaPath, 'utf8');
+          meta = JSON.parse(raw) as RunMeta;
+        } catch {
+          // meta doesn't exist yet
+        }
+
+        const currentHead = meta?.sequence_head ?? -1;
+
+        if (currentHead + 1 >= config.retention.max_entries_per_run) {
+          process.stderr.write(
+            JSON.stringify({
+              level: 'warn',
+              msg: 'replay_timeline_max_entries_per_run_exceeded',
+              run_id: runId,
+              max_entries_per_run: config.retention.max_entries_per_run,
+            }) + '\n',
+          );
+          return;
+        }
+
+        const sequence = currentHead + 1;
+        const entry: TimelineEntry = { ...event, sequence };
+        const jsonl = JSON.stringify(entry) + '\n';
+
+        await fs.appendFile(timelinePath, jsonl, 'utf8');
+
+        const now = nowIso();
+        const updatedMeta: RunMeta = {
+          run_id: runId,
+          sequence_head: sequence,
+          entry_count: (meta?.entry_count ?? 0) + 1,
+          started_at: meta?.started_at ?? now,
+          last_entry_at: now,
+        };
+        await fs.writeFile(metaPath, JSON.stringify(updatedMeta, null, 2), 'utf8');
+      });
+    };
+
+    if (config.write_mode === 'required') {
+      try {
+        await doAppend();
+      } catch (err) {
+        throw Object.assign(
+          new Error(
+            `replay_timeline_write_failed: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+          { code: ERROR_CODES.REPLAY_TIMELINE_WRITE_FAILED },
+        );
+      }
+    } else {
+      try {
+        await doAppend();
+      } catch (err) {
+        process.stderr.write(
+          JSON.stringify({
+            level: 'warn',
+            msg: 'replay_timeline_write_failed_best_effort',
+            run_id: runId,
+            error: err instanceof Error ? err.message : String(err),
+          }) + '\n',
+        );
+      }
+    }
+
+    // Best-effort retention pruning — runs outside of lock, skip on error
+    try {
+      await this.pruneRetention(config.retention.max_runs);
+    } catch {
+      // best-effort only
+    }
+  }
+
+  async timelineGet(
+    runId: string,
+    filters: {
+      from_sequence?: number;
+      limit?: number;
+      feature_id?: string;
+      tool_name?: string;
+    },
+  ): Promise<ToolResponse> {
+    const timelinePath = this.pathLayout.replayTimelinePath(runId);
+
+    if (!(await pathExists(timelinePath))) {
+      return fail(
+        ERROR_CODES.REPLAY_RUN_NOT_FOUND,
+        `Replay timeline not found for run_id: ${runId}`,
+        {
+          retryable: false,
+          requires_human: false,
+          run_id: runId,
+        },
+      );
+    }
+
+    let rawContent: string;
+    try {
+      rawContent = await fs.readFile(timelinePath, 'utf8');
+    } catch (err) {
+      return fail(
+        ERROR_CODES.REPLAY_TIMELINE_CORRUPT,
+        `Failed to read timeline for run_id: ${runId}`,
+        {
+          retryable: false,
+          requires_human: true,
+          run_id: runId,
+          error: err instanceof Error ? err.message : String(err),
+        },
+      );
+    }
+
+    const lines = rawContent.split('\n').filter((l) => l.trim().length > 0);
+    const entries: TimelineEntry[] = [];
+
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line) as TimelineEntry;
+        entries.push(entry);
+      } catch {
+        process.stderr.write(
+          JSON.stringify({
+            level: 'warn',
+            msg: 'replay_timeline_malformed_line_skipped',
+            run_id: runId,
+          }) + '\n',
+        );
+      }
+    }
+
+    let filtered = entries.sort((a, b) => a.sequence - b.sequence);
+
+    if (filters.from_sequence !== undefined) {
+      filtered = filtered.filter((e) => e.sequence >= (filters.from_sequence ?? 0));
+    }
+    if (filters.feature_id !== undefined) {
+      filtered = filtered.filter((e) => e.feature_id === filters.feature_id);
+    }
+    if (filters.tool_name !== undefined) {
+      filtered = filtered.filter((e) => e.tool_name === filters.tool_name);
+    }
+    if (filters.limit !== undefined) {
+      filtered = filtered.slice(0, filters.limit);
+    }
+
+    return ok({ run_id: runId, entries: filtered, total: filtered.length });
+  }
+
+  private async pruneRetention(maxRuns: number): Promise<void> {
+    const replayDir = this.pathLayout.replayDir();
+    let files: string[];
+    try {
+      files = await fs.readdir(replayDir);
+    } catch {
+      return;
+    }
+
+    const metaFiles = files.filter((f) => f.endsWith('.meta.json'));
+    if (metaFiles.length <= maxRuns) {
+      return;
+    }
+
+    const metas: Array<{ runId: string; startedAt: string }> = [];
+    for (const metaFile of metaFiles) {
+      try {
+        const raw = await fs.readFile(`${replayDir}/${metaFile}`, 'utf8');
+        const meta = JSON.parse(raw) as RunMeta;
+        metas.push({ runId: meta.run_id, startedAt: meta.started_at });
+      } catch {
+        // skip unreadable meta
+      }
+    }
+
+    // Sort oldest first
+    metas.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+
+    const toDelete = metas.slice(0, metas.length - maxRuns);
+    for (const { runId } of toDelete) {
+      try {
+        await fs.rm(this.pathLayout.replayTimelinePath(runId), { force: true });
+        await fs.rm(this.pathLayout.replayMetaPath(runId), { force: true });
+      } catch {
+        // best-effort
+      }
+    }
+  }
+}

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

@@ -1,9 +1,26 @@
-import { detectPlanCollisions } from '../../core/collisions.js';
-import { pathExists, readJson, stableHash } from '../../core/fs.js';
+import {
+  detectPlanCollisions,
+  splitPlanCollisionsByFeature,
+  type PlanCollisionsShape,
+} from '../../core/collisions.js';
+import type { ExecutionControlSnapshot } from '../../core/execution-control.js';
+import { pathExists, readJson } from '../../core/fs.js';
+import type { RoleUsageBreakdown, UsageAvailability } from '../usage-types.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyRecord = Record<string, any>;
 
+interface CostDataWithRoleBreakdown {
+  estimated_cost_usd: number;
+  tokens_used: number;
+  by_role?: RoleUsageBreakdown[];
+  aggregate_status?: UsageAvailability;
+}
+
+function asArray<T = unknown>(value: unknown): T[] {
+  return Array.isArray(value) ? (value as T[]) : [];
+}
+
 function normalizeSet(array: string[]): string[] {
   return [...new Set(array)].sort((a, b) => a.localeCompare(b));
 }
@@ -15,8 +32,51 @@ function readHeldLocks(frontMatter: AnyRecord): string[] {
   return held.filter((item: unknown): item is string => typeof item === 'string');
 }
 
-function createCollisionFingerprint(collisions: unknown): string {
-  return stableHash(JSON.stringify(collisions));
+type CollisionOverride = {
+  override_id: string;
+  feature_ids: [string, string];
+  approved_collision_fingerprint: string;
+  status: 'active' | 'stale' | 'revoked' | 'applied';
+  rationale: string;
+  approved_paths: string[];
+  last_seen_at?: string;
+  applied_at?: string;
+  source_collision_id: string;
+};
+
+type CollisionRecord = {
+  collision_id: string;
+  feature_id: string;
+  with_feature_ids: string[];
+  detected_at: string;
+  collision_fingerprint: string;
+  collisions: PlanCollisionsShape;
+  resolution: string;
+  resolution_details?: {
+    override_id?: string;
+    resolved_at?: string;
+    note?: string;
+  };
+};
+
+function asCollisionOverrides(value: unknown): CollisionOverride[] {
+  return asArray<CollisionOverride>(value).filter(
+    (entry): entry is CollisionOverride => entry !== null && typeof entry === 'object',
+  );
+}
+
+function asCollisionRecords(value: unknown): CollisionRecord[] {
+  return asArray<CollisionRecord>(value).filter(
+    (entry): entry is CollisionRecord => entry !== null && typeof entry === 'object',
+  );
+}
+
+function normalizeFeaturePair(featureA: string, featureB: string): [string, string] {
+  return [featureA, featureB].sort((left, right) => left.localeCompare(right)) as [string, string];
+}
+
+function sameFeaturePair(pair: [string, string], override: CollisionOverride): boolean {
+  return override.feature_ids[0] === pair[0] && override.feature_ids[1] === pair[1];
 }
 
 /**
@@ -33,6 +93,7 @@ export interface ReportingServicePort {
   featureStateGet(featureId: string): Promise<{ data: { front_matter: AnyRecord } }>;
   repoDiffBundle(featureId: string): Promise<{ data: AnyRecord }>;
   qaTestIndexGet(featureId: string): Promise<{ data: AnyRecord }>;
+  executionRequestList(): Promise<{ data: ExecutionControlSnapshot }>;
 }
 
 /**
@@ -93,6 +154,8 @@ export class ReportingService {
    */
   async collisionsScan() {
     const plans = await this.port.collectAcceptedPlans();
+    const index = await this.port.readIndex();
+    const overrides = asCollisionOverrides(index.collision_overrides);
     const matrix = [];
 
     for (let i = 0; i < plans.length; i += 1) {
@@ -105,19 +168,62 @@ export class ReportingService {
           this.port.getPolicySnapshot() as Parameters<typeof detectPlanCollisions>[2],
         );
         if (result.hasCollisions) {
+          const pair = splitPlanCollisionsByFeature(candidatePlan.feature_id, result.collisions)[0];
+          const featurePair = normalizeFeaturePair(
+            candidatePlan.feature_id,
+            comparisonPlan.feature_id,
+          );
+          const matchingOverride = overrides.find(
+            (entry) =>
+              sameFeaturePair(featurePair, entry) &&
+              entry.approved_collision_fingerprint === pair.fingerprint &&
+              (entry.status === 'active' || entry.status === 'applied'),
+          );
           matrix.push({
             feature_id: candidatePlan.feature_id,
             with_feature_id: comparisonPlan.feature_id,
             collisions: result.collisions,
-            fingerprint: createCollisionFingerprint(result.collisions),
+            fingerprint: pair.fingerprint,
+            approval_status: matchingOverride ? 'approved_active' : 'unapproved_active',
+            override: matchingOverride
+              ? {
+                  override_id: matchingOverride.override_id,
+                  status: matchingOverride.status,
+                  rationale: matchingOverride.rationale,
+                  approved_paths: matchingOverride.approved_paths,
+                }
+              : null,
           });
         }
       }
     }
 
+    const stale_overrides = overrides
+      .filter((entry) => entry.status === 'stale')
+      .map((entry) => ({
+        override_id: entry.override_id,
+        feature_ids: entry.feature_ids,
+        status: entry.status,
+        rationale: entry.rationale,
+        approved_paths: entry.approved_paths,
+        last_seen_at: entry.last_seen_at ?? null,
+      }));
+    const revoked_overrides = overrides
+      .filter((entry) => entry.status === 'revoked')
+      .map((entry) => ({
+        override_id: entry.override_id,
+        feature_ids: entry.feature_ids,
+        status: entry.status,
+        rationale: entry.rationale,
+        approved_paths: entry.approved_paths,
+        last_seen_at: entry.last_seen_at ?? null,
+      }));
+
     return {
       data: {
         collisions: matrix,
+        stale_overrides,
+        revoked_overrides,
       },
     };
   }
@@ -136,6 +242,8 @@ export class ReportingService {
    */
   async reportDashboard() {
     const index = await this.port.readIndex();
+    const executionRequests = await this.port.executionRequestList();
+    const collisionScan = await this.collisionsScan();
     const featureIds = normalizeSet([
       ...index.active,
       ...index.blocked,
@@ -150,13 +258,25 @@ export class ReportingService {
         continue;
       }
       const state = await this.port.readState(featureId);
-      const costData = await readJson<{ estimated_cost_usd: number; tokens_used: number }>(
+      const costData = await readJson<CostDataWithRoleBreakdown>(
         this.port.featureCostPath(featureId),
         null,
       );
       features.push({
         feature_id: featureId,
         status: state.frontMatter.status,
+        human_input: state.frontMatter.human_input ?? {
+          open_question_id: null,
+          open_question_count: 0,
+          awaiting_since: null,
+          requested_by_role: null,
+          prompt_summary: null,
+          resume_status: null,
+        },
+        intake:
+          state.frontMatter.intake && typeof state.frontMatter.intake === 'object'
+            ? state.frontMatter.intake
+            : null,
         branch:
           typeof state.frontMatter.worktree_branch === 'string'
             ? state.frontMatter.worktree_branch
@@ -172,8 +292,24 @@ export class ReportingService {
         activity_last_event_at: state.frontMatter.activity_last_event_at,
         activity_detected_via: state.frontMatter.activity_detected_via,
         cost: costData
-          ? { estimated_cost_usd: costData.estimated_cost_usd, tokens_used: costData.tokens_used }
+          ? {
+              estimated_cost_usd: costData.estimated_cost_usd,
+              tokens_used: costData.tokens_used,
+              by_role: costData.by_role ?? [],
+              aggregate_status: costData.aggregate_status ?? null,
+            }
           : null,
+        collision_overrides: asCollisionOverrides(index.collision_overrides)
+          .filter((entry) => entry.feature_ids.includes(featureId))
+          .map((entry) => ({
+            override_id: entry.override_id,
+            status: entry.status,
+            counterpart_feature_id:
+              entry.feature_ids[0] === featureId ? entry.feature_ids[1] : entry.feature_ids[0],
+            rationale: entry.rationale,
+            approved_paths: entry.approved_paths,
+            applied_at: entry.applied_at ?? null,
+          })),
       });
     }
 
@@ -181,6 +317,21 @@ export class ReportingService {
       data: {
         index,
         features,
+        collision_summary: {
+          active_unapproved: collisionScan.data.collisions.filter(
+            (entry: { approval_status?: string }) => entry.approval_status === 'unapproved_active',
+          ).length,
+          active_approved: collisionScan.data.collisions.filter(
+            (entry: { approval_status?: string }) => entry.approval_status === 'approved_active',
+          ).length,
+          stale_overrides: asCollisionOverrides(index.collision_overrides).filter(
+            (entry) => entry.status === 'stale',
+          ).length,
+          revoked_overrides: asCollisionOverrides(index.collision_overrides).filter(
+            (entry) => entry.status === 'revoked',
+          ).length,
+        },
+        execution_requests: executionRequests.data,
       },
     };
   }
@@ -200,9 +351,22 @@ export class ReportingService {
    * ```
    */
   async reportFeatureSummary(featureId: string | null) {
-    const state = await this.port.featureStateGet(featureId as unknown as string);
-    const bundle = await this.port.repoDiffBundle(featureId as unknown as string);
-    const qa = await this.port.qaTestIndexGet(featureId as unknown as string);
+    const resolvedFeatureId = featureId ?? '';
+    const state = await this.port.featureStateGet(resolvedFeatureId);
+    const bundle = await this.port.repoDiffBundle(resolvedFeatureId);
+    const qa = await this.port.qaTestIndexGet(resolvedFeatureId);
+    const index = await this.port.readIndex();
+    const overrides = asCollisionOverrides(index.collision_overrides).filter((entry) =>
+      entry.feature_ids.includes(resolvedFeatureId),
+    );
+    const collisionRecords = asCollisionRecords(index.collision_records)
+      .filter(
+        (entry) =>
+          entry.feature_id === resolvedFeatureId ||
+          entry.with_feature_ids.includes(resolvedFeatureId),
+      )
+      .sort((left, right) => right.detected_at.localeCompare(left.detected_at));
+    const latestCollision = collisionRecords[0] ?? null;
 
     return {
       data: {
@@ -212,6 +376,26 @@ export class ReportingService {
         touched_files: bundle.data.touched_files,
         last_gate_summary: bundle.data.last_gate_summary,
         qa_summary: qa.data.summary,
+        active_collision_overrides: overrides.map((entry) => ({
+          override_id: entry.override_id,
+          status: entry.status,
+          counterpart_feature_id:
+            entry.feature_ids[0] === featureId ? entry.feature_ids[1] : entry.feature_ids[0],
+          rationale: entry.rationale,
+          approved_paths: entry.approved_paths,
+          approved_collision_fingerprint: entry.approved_collision_fingerprint,
+          last_seen_at: entry.last_seen_at ?? null,
+          applied_at: entry.applied_at ?? null,
+        })),
+        recent_collision_records: collisionRecords.slice(0, 5),
+        latest_collision_status: latestCollision
+          ? {
+              collision_id: latestCollision.collision_id,
+              resolution: latestCollision.resolution,
+              resolved_at: latestCollision.resolution_details?.resolved_at ?? null,
+              override_id: latestCollision.resolution_details?.override_id ?? null,
+            }
+          : null,
       },
     };
   }