agentic-orchestrator 0.1.28 → 0.2.1

package/packages/web-dashboard/src/lib/blocked-state-guidance.ts

@@ -0,0 +1,475 @@
+/**
+ * Decodes blocked feature status_reason into human-readable guidance.
+ *
+ * Maps every known blocked sub-cause to a category, summary, explanation,
+ * and actionable recovery steps for the dashboard operator.
+ */
+
+import type { FeatureSummary } from '@/lib/types.js';
+
+export type BlockedCategory =
+  | 'gate_failure'
+  | 'mainline_divergence'
+  | 'provider_failure'
+  | 'operational'
+  | 'merge_repair'
+  | 'review_denied'
+  | 'unknown';
+
+export interface BlockedGuidance {
+  category: BlockedCategory;
+  summary: string;
+  explanation: string;
+  actions: BlockedAction[];
+  severity: 'info' | 'warning' | 'error';
+  autoRecoverable: boolean;
+}
+
+export interface BlockedAction {
+  label: string;
+  description: string;
+  actionType: 'retry' | 'resume' | 'resolve_conflicts' | 'answer_questions' | 'review' | 'manual';
+  dashboardAction?: string;
+  cliCommand?: string;
+}
+
+export function decodeBlockedGuidance(feature: FeatureSummary): BlockedGuidance {
+  if (feature.phase !== 'blocked') {
+    return unknownGuidance('Feature is not in blocked state');
+  }
+
+  const reason = (feature.status_reason ?? '').toLowerCase();
+  const gates = feature.gates ?? {};
+  const recovery = feature.recovery;
+  const mergeRepair = feature.merge_repair;
+
+  // 0. Plan collision — requires operator approval, highest priority because
+  // the feature cannot proceed until the user explicitly approves the overlap.
+  if (feature.collision) {
+    const withIds = feature.collision.with_feature_ids;
+    const filePaths = feature.collision.file_paths;
+    return {
+      category: 'operational',
+      summary: `Plan collision with ${withIds.length === 1 ? withIds[0] : `${withIds.length} features`}`,
+      explanation:
+        filePaths.length > 0
+          ? `This feature's plan overlaps with other active features on: ${filePaths.slice(0, 5).join(', ')}${filePaths.length > 5 ? ` (+${filePaths.length - 5} more)` : ''}. Approve the overlap to continue.`
+          : "This feature's plan overlaps with other active features. Approve the overlap to continue.",
+      actions: [
+        {
+          label: 'Approve Overlap',
+          description: 'Allow the intentional file overlap between these features',
+          actionType: 'manual' as const,
+          dashboardAction: 'collision.approve',
+        },
+        {
+          label: 'Retry',
+          description: 'Retry after the other feature merges or the plan is revised',
+          actionType: 'retry' as const,
+          dashboardAction: 'feature.retry',
+          cliCommand: `aop collision --allow --feature-id {feature_id} --with-feature-id ${withIds[0] ?? '<feature>'} --reason "<reason>" --resume`,
+        },
+      ],
+      severity: 'warning' as const,
+      autoRecoverable: false,
+    };
+  }
+
+  // 1. Active automated recovery — takes priority over other categorizations.
+  // Features with recovery.state === 'retrying' are NOT operator-blocked;
+  // the system is actively working on them.
+  if (recovery?.state === 'retrying') {
+    if (recovery.cause === 'mainline_divergence') {
+      return {
+        category: 'mainline_divergence' as const,
+        summary: 'Merge conflict — commit your changes',
+        explanation:
+          'Your mainline branch has diverged from this feature. Please commit any outstanding changes on your current branch so we can merge and resolve conflicts automatically.',
+        actions: [
+          {
+            label: 'Resolve Conflicts',
+            description: 'Open the conflicts tab to review and resolve',
+            actionType: 'resolve_conflicts' as const,
+            dashboardAction: 'feature.conflicts',
+          },
+          {
+            label: 'Retry',
+            description: 'Force a manual retry if recovery seems stuck',
+            actionType: 'retry' as const,
+            dashboardAction: 'feature.retry',
+            cliCommand: 'aop retry --feature-id {feature_id}',
+          },
+        ],
+        severity: 'warning' as const,
+        autoRecoverable: true,
+      };
+    }
+    const causeLabel = recovery.role
+      ? `${recovery.role} agent retrying`
+      : 'Automatic recovery in progress';
+    return {
+      category: 'operational' as const,
+      summary: causeLabel,
+      explanation:
+        'The system is actively working on this feature. No operator action is required unless it appears stuck.',
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Force a manual retry if recovery seems stuck',
+          actionType: 'retry' as const,
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+      ],
+      severity: 'info' as const,
+      autoRecoverable: true,
+    };
+  }
+
+  // 2. Mainline divergence (reconciler queue)
+  if (
+    reason.includes('mainline divergence') ||
+    reason.includes('reconciler lane') ||
+    reason.includes('queued for shared reconciler')
+  ) {
+    const queueMatch = reason.match(/position (\d+)/);
+    const queuePosition = queueMatch ? parseInt(queueMatch[1], 10) : null;
+    return {
+      category: 'mainline_divergence',
+      summary: 'Mainline divergence detected',
+      explanation:
+        queuePosition != null && queuePosition > 0
+          ? `This feature's branch has diverged from mainline. It is queued for automatic reconciliation at position #${queuePosition}.`
+          : "This feature's branch has diverged from mainline and needs conflict resolution before it can proceed.",
+      actions: [
+        {
+          label: 'View Conflicts',
+          description: 'Open the conflicts tab to see conflicting files and resolve them manually',
+          actionType: 'resolve_conflicts',
+        },
+        {
+          label: 'Retry',
+          description: 'Retry the feature to attempt automatic reconciliation',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+      ],
+      severity: 'warning',
+      autoRecoverable: true,
+    };
+  }
+
+  // 2. Review denied
+  if (reason.includes('dashboard review denied')) {
+    const denialReason = feature.status_reason?.replace(/^Dashboard review denied:\s*/i, '') ?? '';
+    return {
+      category: 'review_denied',
+      summary: 'Review denied by operator',
+      explanation: denialReason
+        ? `An operator denied this feature with reason: "${denialReason}". Address the feedback and retry.`
+        : 'An operator denied this feature during review. Address the feedback and retry.',
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Retry the feature after addressing the review feedback',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+      ],
+      severity: 'warning',
+      autoRecoverable: false,
+    };
+  }
+
+  // 3. Merge repair in progress
+  if (
+    mergeRepair?.active === true ||
+    reason.includes('merge_gate_repair') ||
+    reason.includes('merge gate repair')
+  ) {
+    const attempt = mergeRepair?.attempts ?? 0;
+    const maxAttempts = mergeRepair?.max_attempts ?? 5;
+    return {
+      category: 'merge_repair',
+      summary: `Merge gate repair (attempt ${attempt}/${maxAttempts})`,
+      explanation:
+        'The merge gate failed and automatic repair is in progress. The system is retrying with QA fixes.',
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Manually trigger another repair attempt',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+        {
+          label: 'Review Evidence',
+          description: 'Check the gate evidence to understand what failed',
+          actionType: 'review',
+        },
+      ],
+      severity: 'info',
+      autoRecoverable: true,
+    };
+  }
+
+  // 4. Gate failure — waiting for new work
+  if (reason.includes('gate_retry_waiting_for_new_work')) {
+    const modeMatch = reason.match(/gate_retry_waiting_for_new_work:(\w+)/);
+    const gateMode = modeMatch?.[1] ?? 'unknown';
+    return {
+      category: 'gate_failure',
+      summary: `${gateMode} gate failed — waiting for new work`,
+      explanation:
+        `The ${gateMode} gate failed and the system is waiting for new code changes before retrying. ` +
+        'The builder or QA agent needs to produce new checkpoint work.',
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Force retry the gate if you believe the issue is resolved',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+        {
+          label: 'Resume',
+          description: 'Resume execution to allow the agent to produce new work',
+          actionType: 'resume',
+          dashboardAction: 'feature.resume',
+          cliCommand: 'aop resume --feature-id {feature_id}',
+        },
+      ],
+      severity: 'warning',
+      autoRecoverable: true,
+    };
+  }
+
+  // 5. Gate failure — general (inferred from gates object)
+  if (gates.fast === 'fail' || gates.full === 'fail' || gates.merge === 'fail') {
+    const failedGate = gates.merge === 'fail' ? 'merge' : gates.full === 'fail' ? 'full' : 'fast';
+    return {
+      category: 'gate_failure',
+      summary: `${failedGate} gate failed`,
+      explanation: `The ${failedGate} quality gate failed. This typically means tests are failing or code quality checks did not pass.`,
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Retry the feature to re-run the gate after fixes',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+        {
+          label: 'Review Evidence',
+          description: 'Check the gate evidence artifacts to see what failed',
+          actionType: 'review',
+        },
+      ],
+      severity: 'error',
+      autoRecoverable: false,
+    };
+  }
+
+  // 6. Provider context stall
+  if (reason.includes('provider_context_stall') || reason.includes('context refresh')) {
+    const roleMatch = reason.match(/role[:\s]+(\w+)/i);
+    const role = roleMatch?.[1] ?? 'agent';
+    return {
+      category: 'provider_failure',
+      summary: `${role} stalled on context`,
+      explanation:
+        `The ${role} agent has been requesting context refreshes without making progress. ` +
+        'It may need additional information or clarification to continue.',
+      actions: [
+        {
+          label: 'Answer Questions',
+          description: 'Check if there are pending questions that need answers',
+          actionType: 'answer_questions',
+          cliCommand: 'aop questions --feature-id {feature_id}',
+        },
+        {
+          label: 'Retry',
+          description: 'Retry to reset the agent context and try again',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+      ],
+      severity: 'warning',
+      autoRecoverable: false,
+    };
+  }
+
+  // 7. Provider no progress
+  if (reason.includes('provider_no_progress') || reason.includes('no progress')) {
+    return {
+      category: 'provider_failure',
+      summary: 'Agent made no progress',
+      explanation:
+        'The agent has been running without making meaningful progress for multiple iterations. ' +
+        'This may indicate the task is too complex or the agent is stuck.',
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Retry to reset the agent and attempt fresh execution',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+        {
+          label: 'Send Message',
+          description: 'Send guidance to the agent to help it make progress',
+          actionType: 'manual',
+        },
+      ],
+      severity: 'error',
+      autoRecoverable: false,
+    };
+  }
+
+  // 8. Provider output loop
+  if (reason.includes('provider_output_loop') || reason.includes('output loop')) {
+    return {
+      category: 'provider_failure',
+      summary: 'Agent stuck in output loop',
+      explanation:
+        'The agent has been producing identical or near-identical output across multiple iterations. ' +
+        'It needs intervention to break out of the loop.',
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Retry to reset the agent state',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+        {
+          label: 'Send Message',
+          description: 'Send the agent specific guidance to try a different approach',
+          actionType: 'manual',
+        },
+      ],
+      severity: 'error',
+      autoRecoverable: false,
+    };
+  }
+
+  // 9. Provider output invalid
+  if (reason.includes('provider_output_invalid') || reason.includes('malformed')) {
+    return {
+      category: 'provider_failure',
+      summary: 'Agent produced invalid output',
+      explanation:
+        'The agent produced output that does not conform to the expected format. ' +
+        'This may be a transient issue that resolves on retry.',
+      actions: [
+        {
+          label: 'Retry',
+          description: 'Retry to give the agent another chance',
+          actionType: 'retry',
+          dashboardAction: 'feature.retry',
+          cliCommand: 'aop retry --feature-id {feature_id}',
+        },
+      ],
+      severity: 'warning',
+      autoRecoverable: true,
+    };
+  }
+
+  // 10. Lease expired
+  if (reason.includes('lease expired') || reason.includes('reclaimed')) {
+    return {
+      category: 'operational',
+      summary: 'Execution lease expired',
+      explanation:
+        "The feature's execution lease expired (the runtime was idle too long). " +
+        'Resume execution to continue where it left off.',
+      actions: [
+        {
+          label: 'Resume',
+          description: 'Resume execution to continue from the last checkpoint',
+          actionType: 'resume',
+          dashboardAction: 'feature.resume',
+          cliCommand: 'aop resume --feature-id {feature_id}',
+        },
+      ],
+      severity: 'info',
+      autoRecoverable: true,
+    };
+  }
+
+  // 11. Forced retry / retry_resume (from a previous retry attempt)
+  if (reason.includes('retry_resume:') || reason.includes('forced_retry:')) {
+    return {
+      category: 'gate_failure',
+      summary: 'Retried — execution in progress',
+      explanation:
+        'This feature was retried and is transitioning through its recovery phase. ' +
+        'If it remains blocked, the underlying gate failure may persist.',
+      actions: [
+        {
+          label: 'Resume',
+          description: 'Resume execution to continue the recovery',
+          actionType: 'resume',
+          dashboardAction: 'feature.resume',
+          cliCommand: 'aop resume --feature-id {feature_id}',
+        },
+      ],
+      severity: 'info',
+      autoRecoverable: true,
+    };
+  }
+
+  // Fallback — unknown blocked reason
+  return unknownGuidance(feature.status_reason ?? 'No status reason available');
+}
+
+function unknownGuidance(rawReason: string): BlockedGuidance {
+  return {
+    category: 'unknown',
+    summary: 'Blocked — reason unclear',
+    explanation: `This feature is blocked. Raw status: "${rawReason}". Check the feature log for more details.`,
+    actions: [
+      {
+        label: 'Retry',
+        description: 'Attempt a retry to see if the issue resolves',
+        actionType: 'retry',
+        dashboardAction: 'feature.retry',
+        cliCommand: 'aop retry --feature-id {feature_id}',
+      },
+      {
+        label: 'Check Logs',
+        description: 'Review the feature log for detailed error information',
+        actionType: 'review',
+      },
+    ],
+    severity: 'error',
+    autoRecoverable: false,
+  };
+}
+
+const CATEGORY_ICONS: Record<BlockedCategory, string> = {
+  gate_failure: '\u26D4',
+  mainline_divergence: '\u{1F500}',
+  provider_failure: '\u{1F916}',
+  operational: '\u23F1\uFE0F',
+  merge_repair: '\u{1F527}',
+  review_denied: '\u{1F6AB}',
+  unknown: '\u2753',
+};
+
+export function getCategoryIcon(category: BlockedCategory): string {
+  return CATEGORY_ICONS[category];
+}
+
+const SEVERITY_COLORS: Record<BlockedGuidance['severity'], string> = {
+  info: '#3b82f6',
+  warning: '#f59e0b',
+  error: '#ef4444',
+};
+
+export function getSeverityColor(severity: BlockedGuidance['severity']): string {
+  return SEVERITY_COLORS[severity];
+}

package/packages/web-dashboard/src/lib/collision-radar.ts

@@ -0,0 +1,136 @@
+import type { CollisionEntry, CollisionRadarSnapshot } from '@/lib/types.js';
+
+function normalizePaths(paths: string[]): string[] {
+  return Array.from(
+    new Set(paths.filter((path) => typeof path === 'string' && path.trim().length > 0)),
+  ).sort((left, right) => left.localeCompare(right));
+}
+
+function topLevelModule(path: string): string | null {
+  const parts = path.split('/').filter((part) => part.length > 0);
+  if (parts.length === 0) {
+    return null;
+  }
+  if (['src', 'apps', 'packages'].includes(parts[0] ?? '') && parts.length > 1) {
+    return parts.slice(0, 2).join('/');
+  }
+  return parts[0] ?? null;
+}
+
+function parentDirectory(path: string): string | null {
+  const parts = path.split('/').filter((part) => part.length > 0);
+  if (parts.length <= 1) {
+    return null;
+  }
+  return parts.slice(0, -1).join('/');
+}
+
+function depthOf(path: string): number {
+  const parts = path.split('/').filter((part) => part.length > 0);
+  return Math.max(0, parts.length - 1);
+}
+
+function sortByRisk(left: CollisionEntry, right: CollisionEntry): number {
+  const rank = { high: 0, medium: 1, low: 2 } as const;
+  return (
+    rank[left.risk] - rank[right.risk] ||
+    left.depth - right.depth ||
+    left.path.localeCompare(right.path)
+  );
+}
+
+export function deriveCollisionRisk(
+  thisFeatureFiles: string[],
+  otherFeatures: Record<string, string[]>,
+): CollisionEntry[] {
+  const baselineFiles = normalizePaths(thisFeatureFiles);
+
+  if (baselineFiles.length === 0) {
+    return [];
+  }
+
+  const entries = baselineFiles.flatMap<CollisionEntry>((filePath) => {
+    const exactMatches = new Set<string>();
+    const directoryMatches = new Set<string>();
+    const topLevelMatches = new Set<string>();
+    const directory = parentDirectory(filePath);
+    const topLevel = topLevelModule(filePath);
+
+    for (const [featureId, files] of Object.entries(otherFeatures)) {
+      const normalizedFiles = Array.isArray(files) ? files : [];
+      if (normalizedFiles.includes(filePath)) {
+        exactMatches.add(featureId);
+        continue;
+      }
+
+      if (
+        directory &&
+        normalizedFiles.some((candidate) => parentDirectory(candidate) === directory)
+      ) {
+        directoryMatches.add(featureId);
+        continue;
+      }
+
+      if (topLevel && normalizedFiles.some((candidate) => topLevelModule(candidate) === topLevel)) {
+        topLevelMatches.add(featureId);
+      }
+    }
+
+    if (exactMatches.size > 0) {
+      return [
+        {
+          path: filePath,
+          depth: depthOf(filePath),
+          competing_features: Array.from(exactMatches).sort((left, right) =>
+            left.localeCompare(right),
+          ),
+          risk: 'high',
+        },
+      ];
+    }
+
+    if (directoryMatches.size > 0) {
+      return [
+        {
+          path: filePath,
+          depth: depthOf(filePath),
+          competing_features: Array.from(directoryMatches).sort((left, right) =>
+            left.localeCompare(right),
+          ),
+          risk: 'medium',
+        },
+      ];
+    }
+
+    if (topLevelMatches.size > 0) {
+      return [
+        {
+          path: filePath,
+          depth: depthOf(filePath),
+          competing_features: Array.from(topLevelMatches).sort((left, right) =>
+            left.localeCompare(right),
+          ),
+          risk: 'low',
+        },
+      ];
+    }
+
+    return [];
+  });
+
+  return entries.sort(sortByRisk);
+}
+
+export function buildCollisionRadar(
+  thisFeatureFiles: string[],
+  otherFeatures: Record<string, string[]>,
+): CollisionRadarSnapshot {
+  const entries = deriveCollisionRisk(thisFeatureFiles, otherFeatures);
+  return {
+    this_feature_files: normalizePaths(thisFeatureFiles),
+    entries,
+    high_count: entries.filter((entry) => entry.risk === 'high').length,
+    medium_count: entries.filter((entry) => entry.risk === 'medium').length,
+    low_count: entries.filter((entry) => entry.risk === 'low').length,
+  };
+}