@pixelbyte-software/pixcode 1.42.1 → 1.42.3

package/scripts/smoke/workflow-fallback-replay.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+const fallbackPolicy = read('server/modules/orchestration/workflows/workflow-fallback-policy.ts');
+assert.match(fallbackPolicy, /PIXCODE_FALLBACK_POLICY_PROTOCOL/, 'Fallback policy should declare a stable protocol id.');
+assert.match(fallbackPolicy, /pixcode\.fallback-policy\.v1/, 'Fallback policy should use the v1 protocol id.');
+assert.match(fallbackPolicy, /provider_failure/, 'Fallback policy should classify provider failures.');
+assert.match(fallbackPolicy, /timeout/, 'Fallback policy should classify timeouts.');
+assert.match(fallbackPolicy, /tool_failure/, 'Fallback policy should classify tool failures.');
+assert.match(fallbackPolicy, /invalid_output/, 'Fallback policy should classify invalid output.');
+assert.match(fallbackPolicy, /resolveWorkflowFallbackDecision/, 'Fallback policy should expose a decision helper.');
+
+const replay = read('server/modules/orchestration/workflows/workflow-replay.ts');
+assert.match(replay, /PIXCODE_REPLAY_PROTOCOL/, 'Replay support should declare a stable protocol id.');
+assert.match(replay, /pixcode\.workflow-replay\.v1/, 'Replay support should use the v1 protocol id.');
+assert.match(replay, /buildWorkflowReplayPlan/, 'Replay support should build a replay plan from stored run data.');
+assert.match(replay, /requiresApproval/, 'Replay plans should expose approval requirements.');
+assert.match(replay, /file-write/, 'Replay safety should detect file-write actions.');
+assert.match(replay, /shell/, 'Replay safety should detect shell actions.');
+assert.match(replay, /network/, 'Replay safety should detect network actions.');
+
+const runner = read('server/modules/orchestration/workflows/workflow-runner.ts');
+assert.match(runner, /resolveWorkflowFallbackDecision/, 'Workflow runner should use policy-driven fallback decisions.');
+assert.match(runner, /fallbackTrigger/, 'Fallback nodes should record the trigger that launched them.');
+assert.match(runner, /fallbackSkippedEvents/, 'Skipped fallback decisions should be recorded.');
+
+const trace = read('server/modules/orchestration/workflows/workflow-trace.ts');
+assert.match(trace, /workflow\.trace\.fallback/, 'Trace timeline should surface fallback events.');
+assert.match(trace, /workflow\.trace\.replay/, 'Trace timeline should surface replay metadata.');
+
+const routes = read('server/modules/orchestration/workflows/workflow.routes.ts');
+assert.match(routes, /replay-plan/, 'Workflow routes should expose a replay plan endpoint.');
+assert.match(routes, /REPLAY_APPROVAL_REQUIRED/, 'Replay route should require approval before unsafe replay.');
+assert.match(routes, /workflowRunner\.start\(\s*replayPlan\.workflow/s, 'Replay route should start from the generated replay workflow.');
+
+const panel = read('src/components/orchestration/workflows/WorkflowRunPanel.tsx');
+assert.match(panel, /loadReplayPlan/, 'Workflow run panel should load replay plans.');
+assert.match(panel, /replayRun/, 'Workflow run panel should expose a replay action.');
+assert.match(panel, /approveReplay/, 'Workflow run panel should expose explicit approval for guarded replay.');
+assert.match(panel, /orchestration\.replayRun/, 'Workflow UI should render replay labels.');
+
+const en = read('src/i18n/locales/en/common.json');
+const tr = read('src/i18n/locales/tr/common.json');
+assert.match(en, /"replayRun"/, 'English replay translation is missing.');
+assert.match(tr, /"replayRun"/, 'Turkish replay translation is missing.');
+
+console.log('workflow fallback replay smoke passed');

package/server/modules/orchestration/tasks/orchestration-task.service.ts

@@ -2,6 +2,7 @@ import { OrchestrationTaskStore } from '@/modules/orchestration/tasks/orchestrat
 import type { CreateOrchestrationTaskInput, DispatchOrchestrationTaskInput, OrchestrationTask } from '@/modules/orchestration/tasks/orchestration-task.types.js';
 import { a2aBus } from '@/modules/orchestration/a2a/bus.js';
 import type { TaskState } from '@/modules/orchestration/a2a/types.js';
+import type { WorkflowNodeRun, WorkflowRun } from '@/modules/orchestration/workflows/workflow.types.js';
 
 function newId(prefix: string): string {
   return `${prefix}_${Math.random().toString(36).slice(2, 10)}`;
@@ -9,6 +10,52 @@ function newId(prefix: string): string {
 
 const TERMINAL_A2A_STATES: TaskState[] = ['completed', 'canceled', 'failed'];
 
+function uniqueStrings(values: Array<string | undefined>): string[] {
+  return [...new Set(values.filter((value): value is string => Boolean(value?.trim())))]
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function changedFilesFromNode(node: WorkflowNodeRun): string[] {
+  const files: string[] = [];
+  if (node.handoffArtifact?.changedFiles) {
+    files.push(...node.handoffArtifact.changedFiles);
+  }
+  for (const artifact of node.artifacts ?? []) {
+    const data = readRecord(artifact.data);
+    const metadata = readRecord(artifact.metadata);
+    files.push(
+      ...[readString(data?.path), readString(data?.file), readString(metadata?.path), readString(metadata?.file)]
+        .filter((value): value is string => Boolean(value)),
+    );
+    for (const key of ['files', 'changedFiles']) {
+      const value = data?.[key] ?? metadata?.[key];
+      if (Array.isArray(value)) {
+        files.push(...value.map((entry) => readString(entry)).filter((entry): entry is string => Boolean(entry)));
+      }
+    }
+  }
+  return uniqueStrings(files);
+}
+
+function changedFilesFromWorkflowRun(run: WorkflowRun): string[] {
+  return uniqueStrings(run.nodeRuns.flatMap((node) => changedFilesFromNode(node)));
+}
+
+function workflowRunState(run: WorkflowRun): OrchestrationTask['state'] {
+  if (run.status === 'completed') return 'done';
+  if (run.status === 'failed') return 'failed';
+  if (run.status === 'canceled') return 'canceled';
+  return 'in_progress';
+}
+
 class OrchestrationTaskService {
   private store: OrchestrationTaskStore;
 
@@ -33,6 +80,8 @@ class OrchestrationTaskService {
       title: input.title,
       description: input.description,
       taskmasterId: input.taskmasterId,
+      acceptanceCriteria: input.acceptanceCriteria,
+      changedFiles: input.changedFiles,
       state: 'todo',
       createdAt: now,
       updatedAt: now,
@@ -48,6 +97,8 @@ class OrchestrationTaskService {
     if (existing) {
       existing.title = input.title;
       existing.description = input.description;
+      existing.acceptanceCriteria = input.acceptanceCriteria ?? existing.acceptanceCriteria;
+      existing.changedFiles = uniqueStrings([...(existing.changedFiles ?? []), ...(input.changedFiles ?? [])]);
       existing.updatedAt = Date.now();
       this.store.set(existing);
       return existing;
@@ -99,6 +150,49 @@ class OrchestrationTaskService {
     return task;
   }
 
+  linkWorkflowRun(taskId: string, run: WorkflowRun): OrchestrationTask | undefined {
+    const task = this.store.get(taskId);
+    if (!task) return undefined;
+    task.workflowRunIds = uniqueStrings([...(task.workflowRunIds ?? []), run.id]);
+    task.state = workflowRunState(run);
+    task.updatedAt = Date.now();
+    this.store.set(task);
+    return task;
+  }
+
+  updateFromWorkflowRun(run: WorkflowRun): OrchestrationTask | undefined {
+    const metadata = run.metadata ?? {};
+    const taskId = readString(metadata.orchestrationTaskId);
+    const taskmasterId = readString(metadata.taskmasterId);
+    const task = taskId
+      ? this.store.get(taskId)
+      : taskmasterId
+        ? this.store.list(readString(metadata.projectId)).find((candidate) => candidate.taskmasterId === taskmasterId)
+        : undefined;
+    if (!task) return undefined;
+
+    const changedFiles = changedFilesFromWorkflowRun(run);
+    task.workflowRunIds = uniqueStrings([...(task.workflowRunIds ?? []), run.id]);
+    task.changedFiles = uniqueStrings([...(task.changedFiles ?? []), ...changedFiles]);
+    task.state = workflowRunState(run);
+    task.acceptanceCriteria = [
+      ...(task.acceptanceCriteria ?? []).filter((criterion) => criterion.id !== `run-${run.id}`),
+      {
+        id: `run-${run.id}`,
+        label: `Workflow ${run.workflowId} ${run.status}`,
+        status: run.status === 'completed' ? 'passed' : run.status === 'failed' || run.status === 'canceled' ? 'failed' : 'pending',
+        source: 'workflow',
+      },
+    ];
+    task.updatedAt = Date.now();
+    this.store.set(task);
+
+    if (task.taskmasterId && task.state === 'done') {
+      this.syncTaskMasterStatus(task.taskmasterId, 'done');
+    }
+    return task;
+  }
+
   updateState(taskId: string, state: OrchestrationTask['state']): OrchestrationTask | undefined {
     const task = this.store.get(taskId);
     if (!task) return undefined;

package/server/modules/orchestration/tasks/orchestration-task.types.ts

@@ -3,11 +3,19 @@ export type OrchestrationTaskState = 'todo' | 'in_progress' | 'in_review' | 'don
 export interface OrchestrationTask {
   id: string;
   a2aTaskId?: string;
+  workflowRunIds?: string[];
   taskmasterId?: string;
   projectId: string;
   title: string;
   description?: string;
   state: OrchestrationTaskState;
+  acceptanceCriteria?: Array<{
+    id: string;
+    label: string;
+    status: 'pending' | 'passed' | 'failed';
+    source: 'taskmaster' | 'workflow';
+  }>;
+  changedFiles?: string[];
   adapterId?: string;
   adapterSelector?: string;
   workspaceKind?: 'host' | 'worktree' | 'docker';
@@ -21,6 +29,8 @@ export interface CreateOrchestrationTaskInput {
   title: string;
   description?: string;
   taskmasterId?: string;
+  acceptanceCriteria?: OrchestrationTask['acceptanceCriteria'];
+  changedFiles?: string[];
 }
 
 export interface DispatchOrchestrationTaskInput {

package/server/modules/orchestration/tasks/task-run-graph.ts

@@ -0,0 +1,219 @@
+import type { WorkflowNodeRun, WorkflowRun } from '@/modules/orchestration/workflows/workflow.types.js';
+import { workflowStore } from '@/modules/orchestration/workflows/workflow-store.js';
+import { orchestrationTaskService } from '@/modules/orchestration/tasks/orchestration-task.service.js';
+import type { OrchestrationTask } from '@/modules/orchestration/tasks/orchestration-task.types.js';
+
+export const PIXCODE_TASK_RUN_GRAPH_PROTOCOL = 'pixcode.task-run-graph.v1';
+
+export type TaskRunGraphCriterionStatus = 'pending' | 'passed' | 'failed';
+
+export interface TaskRunGraphCriterion {
+  id: string;
+  label: string;
+  status: TaskRunGraphCriterionStatus;
+  source: 'taskmaster' | 'workflow';
+}
+
+export interface TaskRunGraphRunSummary {
+  id: string;
+  workflowId: string;
+  status: WorkflowRun['status'];
+  startedAt: number;
+  finishedAt?: number;
+  taskmasterId?: string;
+  orchestrationTaskId?: string;
+  changedFiles: string[];
+}
+
+export interface TaskRunGraph {
+  protocol: typeof PIXCODE_TASK_RUN_GRAPH_PROTOCOL;
+  projectId: string;
+  taskmasterId?: string;
+  orchestrationTaskId?: string;
+  workflowRuns: TaskRunGraphRunSummary[];
+  changedFiles: string[];
+  acceptanceCriteria: TaskRunGraphCriterion[];
+  status: {
+    totalRuns: number;
+    completedRuns: number;
+    failedRuns: number;
+    passedCriteria: number;
+    failedCriteria: number;
+  };
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function uniqueStrings(values: Array<string | undefined>): string[] {
+  return [...new Set(values.filter((value): value is string => Boolean(value?.trim())))]
+    .sort((a, b) => a.localeCompare(b));
+}
+
+function taskStatusPassed(status: unknown): boolean {
+  const normalized = String(status ?? '').toLocaleLowerCase('en');
+  return normalized === 'done' || normalized === 'completed';
+}
+
+function taskStatusFailed(status: unknown): boolean {
+  const normalized = String(status ?? '').toLocaleLowerCase('en');
+  return normalized === 'failed' || normalized === 'blocked' || normalized === 'cancelled' || normalized === 'canceled';
+}
+
+function criterionStatus(status: unknown): TaskRunGraphCriterionStatus {
+  if (taskStatusPassed(status)) return 'passed';
+  if (taskStatusFailed(status)) return 'failed';
+  return 'pending';
+}
+
+function taskmasterAcceptanceCriteria(taskmasterTask: Record<string, unknown> | undefined): TaskRunGraphCriterion[] {
+  if (!taskmasterTask) return [];
+
+  const criteria: TaskRunGraphCriterion[] = [];
+  const testStrategy = readString(taskmasterTask.testStrategy) ?? readString(taskmasterTask.test_strategy);
+  if (testStrategy) {
+    criteria.push({
+      id: 'test-strategy',
+      label: testStrategy,
+      status: criterionStatus(taskmasterTask.status),
+      source: 'taskmaster',
+    });
+  }
+
+  const subtasks = Array.isArray(taskmasterTask.subtasks) ? taskmasterTask.subtasks : [];
+  subtasks.forEach((subtask, index) => {
+    const record = readRecord(subtask);
+    if (!record) return;
+    const title = readString(record.title);
+    if (!title) return;
+    criteria.push({
+      id: `subtask-${readString(record.id) ?? index + 1}`,
+      label: title,
+      status: criterionStatus(record.status),
+      source: 'taskmaster',
+    });
+  });
+
+  return criteria;
+}
+
+function metadataTaskmasterId(run: WorkflowRun): string | undefined {
+  return readString(run.metadata?.taskmasterId)
+    ?? readString(readRecord(run.metadata?.taskGraph)?.taskmasterId)
+    ?? readString(readRecord(run.metadata?.replay)?.taskmasterId);
+}
+
+function metadataOrchestrationTaskId(run: WorkflowRun): string | undefined {
+  return readString(run.metadata?.orchestrationTaskId)
+    ?? readString(readRecord(run.metadata?.taskGraph)?.orchestrationTaskId);
+}
+
+function artifactChangedFiles(node: WorkflowNodeRun): string[] {
+  const files: string[] = [];
+
+  if (node.handoffArtifact?.changedFiles) {
+    files.push(...node.handoffArtifact.changedFiles);
+  }
+
+  for (const artifact of node.artifacts ?? []) {
+    const data = readRecord(artifact.data);
+    const metadata = readRecord(artifact.metadata);
+    const candidates = [
+      readString(metadata?.path),
+      readString(metadata?.file),
+      readString(data?.path),
+      readString(data?.file),
+    ];
+    files.push(...candidates.filter((value): value is string => Boolean(value)));
+
+    for (const key of ['files', 'changedFiles']) {
+      const value = data?.[key] ?? metadata?.[key];
+      if (Array.isArray(value)) {
+        files.push(...value.map((entry) => readString(entry)).filter((entry): entry is string => Boolean(entry)));
+      }
+    }
+  }
+
+  return uniqueStrings(files);
+}
+
+export function changedFilesFromWorkflowRun(run: WorkflowRun): string[] {
+  return uniqueStrings(run.nodeRuns.flatMap((node) => artifactChangedFiles(node)));
+}
+
+function workflowRunMatchesTask(run: WorkflowRun, task: OrchestrationTask | undefined, taskmasterId: string | undefined): boolean {
+  const runTaskmasterId = metadataTaskmasterId(run);
+  const runOrchestrationTaskId = metadataOrchestrationTaskId(run);
+  if (taskmasterId && runTaskmasterId === taskmasterId) return true;
+  if (task?.id && runOrchestrationTaskId === task.id) return true;
+  if (task?.workflowRunIds?.includes(run.id)) return true;
+  return false;
+}
+
+function runSummary(run: WorkflowRun): TaskRunGraphRunSummary {
+  return {
+    id: run.id,
+    workflowId: run.workflowId,
+    status: run.status,
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    taskmasterId: metadataTaskmasterId(run),
+    orchestrationTaskId: metadataOrchestrationTaskId(run),
+    changedFiles: changedFilesFromWorkflowRun(run),
+  };
+}
+
+export function buildTaskRunGraph({
+  projectId,
+  taskmasterId,
+  taskmasterTask,
+}: {
+  projectId: string;
+  taskmasterId?: string;
+  taskmasterTask?: Record<string, unknown>;
+}): TaskRunGraph {
+  const orchestrationTask = taskmasterId
+    ? orchestrationTaskService.list(projectId).find((task) => task.taskmasterId === taskmasterId)
+    : undefined;
+  const workflowRuns = workflowStore
+    .listRuns()
+    .filter((run) => workflowRunMatchesTask(run, orchestrationTask, taskmasterId))
+    .map(runSummary);
+  const workflowCriteria: TaskRunGraphCriterion[] = workflowRuns.map((run) => ({
+    id: `run-${run.id}`,
+    label: `Workflow ${run.workflowId} ${run.status}`,
+    status: run.status === 'completed' ? 'passed' : run.status === 'failed' || run.status === 'canceled' ? 'failed' : 'pending',
+    source: 'workflow',
+  }));
+  const acceptanceCriteria = [
+    ...taskmasterAcceptanceCriteria(taskmasterTask),
+    ...(orchestrationTask?.acceptanceCriteria ?? []),
+    ...workflowCriteria,
+  ];
+  const changedFiles = uniqueStrings([
+    ...(orchestrationTask?.changedFiles ?? []),
+    ...workflowRuns.flatMap((run) => run.changedFiles),
+  ]);
+
+  return {
+    protocol: PIXCODE_TASK_RUN_GRAPH_PROTOCOL,
+    projectId,
+    taskmasterId,
+    orchestrationTaskId: orchestrationTask?.id,
+    workflowRuns,
+    changedFiles,
+    acceptanceCriteria,
+    status: {
+      totalRuns: workflowRuns.length,
+      completedRuns: workflowRuns.filter((run) => run.status === 'completed').length,
+      failedRuns: workflowRuns.filter((run) => run.status === 'failed' || run.status === 'canceled').length,
+      passedCriteria: acceptanceCriteria.filter((criterion) => criterion.status === 'passed').length,
+      failedCriteria: acceptanceCriteria.filter((criterion) => criterion.status === 'failed').length,
+    },
+  };
+}

package/server/modules/orchestration/workflows/workflow-fallback-policy.ts

@@ -0,0 +1,161 @@
+import type { WorkflowNode, WorkflowRun } from '@/modules/orchestration/workflows/workflow.types.js';
+
+export const PIXCODE_FALLBACK_POLICY_PROTOCOL = 'pixcode.fallback-policy.v1';
+
+export type WorkflowFallbackTrigger = 'provider_failure' | 'timeout' | 'tool_failure' | 'invalid_output';
+
+export interface WorkflowFallbackPolicy {
+  protocol: typeof PIXCODE_FALLBACK_POLICY_PROTOCOL;
+  enabled: boolean;
+  triggers: WorkflowFallbackTrigger[];
+  maxFallbacksPerRun: number;
+  requireDifferentAgent: boolean;
+}
+
+export interface WorkflowFallbackDecision {
+  shouldFallback: boolean;
+  trigger: WorkflowFallbackTrigger;
+  reason: string;
+  policy: WorkflowFallbackPolicy;
+  skippedReason?: string;
+}
+
+const DEFAULT_TRIGGERS: WorkflowFallbackTrigger[] = [
+  'provider_failure',
+  'timeout',
+  'tool_failure',
+  'invalid_output',
+];
+
+export const DEFAULT_WORKFLOW_FALLBACK_POLICY: WorkflowFallbackPolicy = {
+  protocol: PIXCODE_FALLBACK_POLICY_PROTOCOL,
+  enabled: true,
+  triggers: DEFAULT_TRIGGERS,
+  maxFallbacksPerRun: 3,
+  requireDifferentAgent: true,
+};
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function readBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function isWorkflowFallbackTrigger(value: unknown): value is WorkflowFallbackTrigger {
+  return value === 'provider_failure'
+    || value === 'timeout'
+    || value === 'tool_failure'
+    || value === 'invalid_output';
+}
+
+function readFallbackTriggers(value: unknown): WorkflowFallbackTrigger[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const triggers = value.filter(isWorkflowFallbackTrigger);
+  return triggers.length > 0 ? [...new Set(triggers)] : undefined;
+}
+
+export function readWorkflowFallbackPolicy(metadata?: Record<string, unknown>): WorkflowFallbackPolicy {
+  const settings = readRecord(metadata?.settings) ?? {};
+  const configured = readRecord(settings.fallbackPolicy) ?? {};
+  const maxFallbacksPerRun = readNumber(configured.maxFallbacksPerRun);
+
+  return {
+    protocol: PIXCODE_FALLBACK_POLICY_PROTOCOL,
+    enabled: readBoolean(configured.enabled) ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.enabled,
+    triggers: readFallbackTriggers(configured.triggers) ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.triggers,
+    maxFallbacksPerRun: maxFallbacksPerRun === undefined
+      ? DEFAULT_WORKFLOW_FALLBACK_POLICY.maxFallbacksPerRun
+      : Math.max(0, Math.min(8, Math.round(maxFallbacksPerRun))),
+    requireDifferentAgent: readBoolean(configured.requireDifferentAgent)
+      ?? DEFAULT_WORKFLOW_FALLBACK_POLICY.requireDifferentAgent,
+  };
+}
+
+export function classifyWorkflowFailure(
+  reason: string,
+  explicitTrigger?: WorkflowFallbackTrigger,
+): WorkflowFallbackTrigger {
+  if (explicitTrigger) return explicitTrigger;
+
+  const text = reason.toLocaleLowerCase('en');
+  if (/timed out|timeout|deadline/u.test(text)) return 'timeout';
+  if (/invalid (handoff|output|artifact|json|schema)|parse|protocol/u.test(text)) return 'invalid_output';
+  if (
+    /tool|command|shell|exit code|permission|file write|write failed|network|fetch|curl|wget|gh |npm |git /u
+      .test(text)
+  ) {
+    return 'tool_failure';
+  }
+  return 'provider_failure';
+}
+
+function fallbackEventCount(run: WorkflowRun): number {
+  return Array.isArray(run.metadata?.fallbackEvents) ? run.metadata.fallbackEvents.length : 0;
+}
+
+export function resolveWorkflowFallbackDecision({
+  run,
+  node,
+  reason,
+  trigger,
+  fallbackAgentInstanceId,
+}: {
+  run: WorkflowRun;
+  node: WorkflowNode;
+  reason: string;
+  trigger?: WorkflowFallbackTrigger;
+  fallbackAgentInstanceId?: string;
+}): WorkflowFallbackDecision {
+  const fallbackTrigger = classifyWorkflowFailure(reason, trigger);
+  const policy = readWorkflowFallbackPolicy(run.metadata);
+
+  if (!policy.enabled) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: 'Fallback policy is disabled.',
+    };
+  }
+  if (!policy.triggers.includes(fallbackTrigger)) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: `Fallback trigger ${fallbackTrigger} is not enabled.`,
+    };
+  }
+  if (fallbackEventCount(run) >= policy.maxFallbacksPerRun) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: `Fallback limit ${policy.maxFallbacksPerRun} reached.`,
+    };
+  }
+  if (policy.requireDifferentAgent && fallbackAgentInstanceId && fallbackAgentInstanceId === node.agentInstanceId) {
+    return {
+      shouldFallback: false,
+      trigger: fallbackTrigger,
+      reason,
+      policy,
+      skippedReason: 'Fallback agent must be different from the failed agent.',
+    };
+  }
+
+  return {
+    shouldFallback: true,
+    trigger: fallbackTrigger,
+    reason,
+    policy,
+  };
+}