oxe-cc 1.6.0 → 1.7.0

package/packages/runtime/src/plugins/capability-adapter.ts

@@ -1,11 +1,12 @@
 import fs from 'fs';
 import path from 'path';
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import type {
   OxePlugin,
   ToolProvider,
   ToolInvocationInput,
   ToolInvocationResult,
+  PreInvokeResult,
   VerifierProvider,
   VerificationInput,
 } from './plugin-abi';
@@ -19,6 +20,56 @@ interface CapabilityManifest {
   evidenceOutputs: string[];
   checkTypes: string[];
   dir: string;
+  timeoutMs: number;
+  preInvokeHook: string | null;
+  postInvokeHook: string | null;
+}
+
+const DEFAULT_CAPABILITY_TIMEOUT_MS = 60_000;
+
+export async function runCapabilityAsync(
+  program: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+  cwd: string,
+  timeoutMs: number,
+  onChunk?: (chunk: string, stream: 'stdout' | 'stderr') => void,
+): Promise<{ exitCode: number | null; stdout: string; stderr: string; timedOut: boolean }> {
+  return new Promise((resolve) => {
+    const proc = spawn(program, args, { cwd, env, stdio: 'pipe' });
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill('SIGTERM');
+    }, timeoutMs);
+
+    proc.stdout.on('data', (chunk: Buffer) => {
+      stdoutChunks.push(chunk);
+      onChunk?.(chunk.toString(), 'stdout');
+    });
+    proc.stderr.on('data', (chunk: Buffer) => {
+      stderrChunks.push(chunk);
+      onChunk?.(chunk.toString(), 'stderr');
+    });
+
+    proc.on('close', (exitCode) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode,
+        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr: Buffer.concat(stderrChunks).toString('utf8'),
+        timedOut,
+      });
+    });
+
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ exitCode: null, stdout: '', stderr: String(err), timedOut: false });
+    });
+  });
 }
 
 function parseFrontmatter(text: string): Record<string, string> {
@@ -62,6 +113,7 @@ function loadCapabilityManifests(projectRoot: string): CapabilityManifest[] {
       const fm = parseFrontmatter(raw);
       const id = String(fm.id || '').trim();
       if (!id) return null;
+      const rawTimeout = parseInt(String(fm.timeout_ms || ''), 10);
       return {
         id,
         entrypoint: String(fm.entrypoint || '').trim() || null,
@@ -69,6 +121,9 @@ function loadCapabilityManifests(projectRoot: string): CapabilityManifest[] {
         evidenceOutputs: parseArrayField(fm.evidence_outputs),
         checkTypes: parseArrayField(fm.check_types || fm.supports_checks),
         dir,
+        timeoutMs: isNaN(rawTimeout) ? DEFAULT_CAPABILITY_TIMEOUT_MS : rawTimeout,
+        preInvokeHook: String(fm.pre_invoke_hook || '').trim() || null,
+        postInvokeHook: String(fm.post_invoke_hook || '').trim() || null,
       };
     })
     .filter((item): item is CapabilityManifest => Boolean(item));
@@ -124,7 +179,7 @@ function buildToolProvider(projectRoot: string, manifest: CapabilityManifest): T
         };
       }
       const ext = path.extname(entrypoint).toLowerCase();
-      const env = {
+      const env: NodeJS.ProcessEnv = {
         ...process.env,
         OXE_CAPABILITY_INPUT: JSON.stringify(input.params || {}),
         OXE_CAPABILITY_RUN_ID: input.run_id,
@@ -141,19 +196,71 @@ function buildToolProvider(projectRoot: string, manifest: CapabilityManifest): T
         program = 'powershell';
         args = ['-File', entrypoint];
       }
-      const result = spawnSync(program, args, {
-        cwd: projectRoot,
-        encoding: 'utf8',
-        env,
-      });
+      const result = await runCapabilityAsync(program, args, env, projectRoot, manifest.timeoutMs);
+      const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+      if (result.timedOut) {
+        return {
+          success: false,
+          output,
+          evidence_paths: resolveEvidencePaths(projectRoot, manifest),
+          side_effects_applied: manifest.sideEffects,
+          error: `Capability ${manifest.id} timed out after ${manifest.timeoutMs}ms`,
+        };
+      }
       return {
-        success: result.status === 0 && !result.error,
-        output: [result.stdout || '', result.stderr || ''].filter(Boolean).join('\n').trim(),
+        success: result.exitCode === 0,
+        output,
         evidence_paths: resolveEvidencePaths(projectRoot, manifest),
         side_effects_applied: manifest.sideEffects,
-        error: result.error ? String(result.error) : result.status === 0 ? undefined : (result.stderr || result.stdout || `Capability exited with status ${result.status}`),
+        error: result.exitCode === 0 ? undefined : (result.stderr || result.stdout || `Capability exited with status ${result.exitCode}`),
       };
     },
+
+    async preInvoke(input: ToolInvocationInput): Promise<PreInvokeResult> {
+      if (!manifest.preInvokeHook) return { allowed: true };
+      const hookPath = path.isAbsolute(manifest.preInvokeHook)
+        ? manifest.preInvokeHook
+        : path.join(manifest.dir, manifest.preInvokeHook);
+      const env: NodeJS.ProcessEnv = {
+        ...process.env,
+        OXE_CAPABILITY_INPUT: JSON.stringify(input.params || {}),
+        OXE_CAPABILITY_RUN_ID: input.run_id,
+        OXE_CAPABILITY_WORK_ITEM_ID: input.work_item_id,
+        OXE_CAPABILITY_ATTEMPT_ID: input.attempt_id,
+        OXE_CAPABILITY_WORKSPACE_ROOT: input.workspace_root,
+      };
+      const ext = path.extname(hookPath).toLowerCase();
+      let program = hookPath;
+      let args: string[] = [];
+      if (ext === '.js' || ext === '.cjs' || ext === '.mjs') { program = process.execPath; args = [hookPath]; }
+      else if (ext === '.ps1') { program = 'powershell'; args = ['-File', hookPath]; }
+      const result = await runCapabilityAsync(program, args, env, projectRoot, 10_000);
+      return result.exitCode === 0
+        ? { allowed: true }
+        : { allowed: false, reason: result.stderr || result.stdout || `pre_invoke_hook exited with status ${result.exitCode}` };
+    },
+
+    async postInvoke(input: ToolInvocationInput, _result: ToolInvocationResult): Promise<void> {
+      if (!manifest.postInvokeHook) return;
+      const hookPath = path.isAbsolute(manifest.postInvokeHook)
+        ? manifest.postInvokeHook
+        : path.join(manifest.dir, manifest.postInvokeHook);
+      const env: NodeJS.ProcessEnv = {
+        ...process.env,
+        OXE_CAPABILITY_INPUT: JSON.stringify(input.params || {}),
+        OXE_CAPABILITY_RUN_ID: input.run_id,
+        OXE_CAPABILITY_WORK_ITEM_ID: input.work_item_id,
+        OXE_CAPABILITY_ATTEMPT_ID: input.attempt_id,
+        OXE_CAPABILITY_WORKSPACE_ROOT: input.workspace_root,
+        OXE_INVOKE_SUCCESS: _result.success ? '1' : '0',
+      };
+      const ext = path.extname(hookPath).toLowerCase();
+      let program = hookPath;
+      let args: string[] = [];
+      if (ext === '.js' || ext === '.cjs' || ext === '.mjs') { program = process.execPath; args = [hookPath]; }
+      else if (ext === '.ps1') { program = 'powershell'; args = ['-File', hookPath]; }
+      await runCapabilityAsync(program, args, env, projectRoot, 10_000).catch(() => {});
+    },
   };
 }
 

package/packages/runtime/src/plugins/plugin-abi.ts

@@ -21,12 +21,21 @@ export interface ToolInvocationResult {
   error?: string;
 }
 
+export interface PreInvokeResult {
+  allowed: boolean;
+  reason?: string;
+}
+
 export interface ToolProvider {
   readonly name: string;
   readonly kind: 'read' | 'mutation' | 'verification' | 'analysis' | 'external_operation';
   readonly idempotent: boolean;
   supports(actionType: string): boolean;
   invoke(input: ToolInvocationInput): Promise<ToolInvocationResult>;
+  /** Optional: called before invoke. Return allowed:false to block execution. */
+  preInvoke?(input: ToolInvocationInput): Promise<PreInvokeResult>;
+  /** Optional: called after invoke. Errors are swallowed — does not affect outcome. */
+  postInvoke?(input: ToolInvocationInput, result: ToolInvocationResult): Promise<void>;
 }
 
 // ─── WorkspaceProvider ───────────────────────────────────────────────────────

package/packages/runtime/src/plugins/plugin-registry.ts

@@ -53,11 +53,20 @@ export class PluginRegistry {
     return loaded;
   }
 
-  toolProviderFor(actionType: string): ToolProvider | null {
+  toolProviderFor(actionType: string, required: true): ToolProvider;
+  toolProviderFor(actionType: string, required?: false): ToolProvider | null;
+  toolProviderFor(actionType: string, required = false): ToolProvider | null {
     for (const plugin of this.plugins) {
       const provider = plugin.toolProviders?.find((p) => p.supports(actionType));
       if (provider) return provider;
     }
+    if (required) {
+      const loaded = this.plugins.map(p => p.name).join(', ') || '(none)';
+      throw new Error(
+        `[plugin-registry] No provider supports action type "${actionType}". ` +
+        `Loaded plugins: [${loaded}]. Load errors: ${this.loadErrors.length}.`
+      );
+    }
     return null;
   }
 

package/packages/runtime/src/reducers/run-state-reducer.ts

@@ -61,6 +61,56 @@ export function reduce(events: OxeEvent[]): RunState {
 // Exported alias so debug-reducer can import applyEvent without circular issues
 export { applyEvent as applyEventExported };
 
+// ─── State machine: valid transitions ─────────────────────────────────────────
+
+import type { WorkItemStatus } from '../models/work-item';
+import type { RunStatus } from '../models/run';
+
+const VALID_WORK_ITEM_TRANSITIONS: Record<WorkItemStatus, readonly WorkItemStatus[]> = {
+  pending:   ['ready'],
+  ready:     ['running', 'completed', 'failed', 'blocked'],
+  running:   ['completed', 'failed', 'blocked'],
+  failed:    ['ready'],      // retry path
+  completed: [],             // terminal
+  blocked:   [],             // terminal
+  skipped:   [],             // terminal
+};
+
+const VALID_RUN_TRANSITIONS: Record<RunStatus, readonly RunStatus[]> = {
+  planned:          ['running'],
+  running:          ['paused', 'failed', 'completed', 'aborted', 'cancelled', 'waiting_approval'],
+  paused:           ['running', 'cancelled'],
+  waiting_approval: ['running', 'cancelled'],
+  failed:           ['replaying'],
+  replaying:        ['running', 'failed', 'completed'],
+  completed:        [],
+  aborted:          [],
+  cancelled:        [],
+};
+
+function assertWorkItemTransition(
+  itemId: string,
+  from: WorkItemStatus,
+  to: WorkItemStatus,
+  eventType: string
+): void {
+  const allowed = VALID_WORK_ITEM_TRANSITIONS[from] ?? [];
+  if (!(allowed as readonly string[]).includes(to)) {
+    throw new Error(
+      `[state-machine] Invalid work item transition for "${itemId}": ${from} → ${to} (event: ${eventType})`
+    );
+  }
+}
+
+function assertRunTransition(from: RunStatus, to: RunStatus, eventType: string): void {
+  const allowed = VALID_RUN_TRANSITIONS[from] ?? [];
+  if (!(allowed as readonly string[]).includes(to)) {
+    throw new Error(
+      `[state-machine] Invalid run transition: ${from} → ${to} (event: ${eventType})`
+    );
+  }
+}
+
 function applyEvent(state: RunState, event: OxeEvent): RunState {
   switch (event.type) {
     case 'RunStarted': {
@@ -71,6 +121,7 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
     case 'RunCompleted': {
       if (!state.run) return state;
       const status = (event.payload as { status?: Run['status'] }).status ?? 'completed';
+      assertRunTransition(state.run.status, status, event.type);
       return {
         ...state,
         run: { ...state.run, status, ended_at: event.timestamp },
@@ -121,7 +172,10 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
       if (!event.work_item_id) return state;
       const workItems = new Map(state.workItems);
       const item = workItems.get(event.work_item_id);
-      if (item) workItems.set(event.work_item_id, { ...item, status: 'completed' });
+      if (item) {
+        assertWorkItemTransition(event.work_item_id, item.status, 'completed', event.type);
+        workItems.set(event.work_item_id, { ...item, status: 'completed' });
+      }
       const completedWorkItems = new Set(state.completedWorkItems);
       completedWorkItems.add(event.work_item_id);
       // Collect evidence refs from payload
@@ -139,7 +193,10 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
       if (!event.work_item_id) return state;
       const workItems = new Map(state.workItems);
       const item = workItems.get(event.work_item_id);
-      if (item) workItems.set(event.work_item_id, { ...item, status: 'blocked' });
+      if (item) {
+        assertWorkItemTransition(event.work_item_id, item.status, 'blocked', event.type);
+        workItems.set(event.work_item_id, { ...item, status: 'blocked' });
+      }
       const blockedWorkItems = new Set(state.blockedWorkItems);
       blockedWorkItems.add(event.work_item_id);
       return { ...state, workItems, blockedWorkItems };

package/packages/runtime/src/scheduler/scheduler.ts

@@ -1,3 +1,5 @@
+import path from 'path';
+import fs from 'fs';
 import { appendEvent } from '../events/bus';
 import type { OxeEvent } from '../events/envelope';
 import type { EventInput } from '../events/bus';
@@ -18,10 +20,14 @@ import {
   createJournal,
 } from './run-journal';
 import type { RunJournal } from './run-journal';
+import type { FailureClass } from '../models/failure';
+import { listMemos } from '../decision/decision-memo';
+import type { RollbackPlan } from '../decision/decision-memo';
+import { runCapabilityAsync } from '../plugins/capability-adapter';
 
 export interface TaskResult {
   success: boolean;
-  failure_class: 'env' | 'policy' | 'test' | 'timeout' | null;
+  failure_class: FailureClass;
   evidence: string[];
   output: string;
 }
@@ -35,6 +41,11 @@ export interface TaskExecutor {
   ): Promise<TaskResult>;
 }
 
+export interface SchedulerOptions {
+  maxRunDurationMs?: number;   // default: 30 min
+  staleProgressMs?: number;    // default: 5 min without any task completing
+}
+
 export interface SchedulerContext {
   projectRoot: string;
   sessionId: string | null;
@@ -48,15 +59,17 @@ export interface SchedulerContext {
   quota?: RunQuota;
   policyActor?: string;
   onEvent?: (event: OxeEvent) => void;
+  options?: SchedulerOptions;
 }
 
 export interface RunResult {
   run_id: string;
-  status: 'completed' | 'failed' | 'blocked' | 'cancelled' | 'paused';
+  status: 'completed' | 'failed' | 'blocked' | 'cancelled' | 'paused' | 'aborted';
   completed: string[];
   failed: string[];
   blocked: string[];
   pending_gates?: string[];
+  reason?: string;
 }
 
 type NodeStatus = 'pending' | 'ready' | 'running' | 'completed' | 'failed' | 'blocked';
@@ -66,11 +79,43 @@ export class Scheduler {
   private paused = false;
   private journal: RunJournal | null = null;
   private ctx: SchedulerContext | null = null;
+  private runStartMs = 0;
+  private lastProgressMs = 0;
+
+  private recordProgress(): void {
+    this.lastProgressMs = Date.now();
+  }
+
+  private async executeRollback(plan: RollbackPlan, ctx: SchedulerContext): Promise<void> {
+    try {
+      switch (plan.strategy) {
+        case 'revert_commit':
+          await runCapabilityAsync('git', ['revert', 'HEAD', '--no-edit'], {}, ctx.projectRoot, 30_000);
+          break;
+        case 'restore_workspace':
+          await runCapabilityAsync('git', ['checkout', '.'], {}, ctx.projectRoot, 30_000);
+          break;
+        case 'undo_patch':
+          for (const p of plan.steps) {
+            await runCapabilityAsync('git', ['checkout', 'HEAD', '--', p], {}, ctx.projectRoot, 10_000);
+          }
+          break;
+        case 'no_rollback':
+        default:
+          break;
+      }
+      this.emit(ctx, { type: 'RollbackExecuted', payload: { strategy: plan.strategy } });
+    } catch (err) {
+      this.emit(ctx, { type: 'RollbackFailed', payload: { strategy: plan.strategy, error: String(err) } });
+    }
+  }
 
   async run(graph: ExecutionGraph, ctx: SchedulerContext): Promise<RunResult> {
     this.cancelled = false;
     this.paused = false;
     this.ctx = ctx;
+    this.runStartMs = Date.now();
+    this.lastProgressMs = Date.now();
 
     const status = new Map<string, NodeStatus>();
     for (const id of graph.nodes.keys()) status.set(id, 'pending');
@@ -79,6 +124,30 @@ export class Scheduler {
     const failed: string[] = [];
     const blocked: string[] = [];
 
+    // Plan hash drift detection: abort if the graph was recompiled since ACTIVE-RUN was saved
+    const activeRunPath = ctx.sessionId
+      ? path.join(ctx.projectRoot, '.oxe', ctx.sessionId, 'execution', 'ACTIVE-RUN.json')
+      : path.join(ctx.projectRoot, '.oxe', 'ACTIVE-RUN.json');
+    if (fs.existsSync(activeRunPath)) {
+      try {
+        const activeRun = JSON.parse(fs.readFileSync(activeRunPath, 'utf8')) as Record<string, unknown>;
+        const savedHash = activeRun.plan_hash as string | undefined;
+        const currentHash = graph.metadata.plan_hash;
+        if (savedHash && savedHash !== currentHash) {
+          return {
+            run_id: ctx.runId,
+            status: 'aborted',
+            completed: [],
+            failed: [],
+            blocked: [],
+            reason: `plan_drift: graph recompiled (${savedHash} → ${currentHash}). Run /oxe-plan --replan to realign.`,
+          };
+        }
+      } catch {
+        // ACTIVE-RUN not parseable — continue without drift check
+      }
+    }
+
     this.journal = createJournal(ctx.runId);
     saveJournal(ctx.projectRoot, ctx.runId, this.journal);
 
@@ -88,9 +157,24 @@ export class Scheduler {
       detail: { session_id: ctx.sessionId ?? null },
     });
 
+    const maxRunMs  = ctx.options?.maxRunDurationMs ?? 30 * 60_000;
+    const staleMs   = ctx.options?.staleProgressMs  ?? 5 * 60_000;
+
     for (const wave of graph.waves) {
       if (this.cancelled) break;
 
+      // Global run timeout
+      if (Date.now() - this.runStartMs > maxRunMs) {
+        this.emit(ctx, { type: 'RunAborted', payload: { reason: 'global_timeout' } });
+        return { run_id: ctx.runId, status: 'aborted', completed: [], failed: [], blocked: [], reason: 'global_timeout' };
+      }
+
+      // Stale progress timeout (no task completed in staleMs)
+      if (Date.now() - this.lastProgressMs > staleMs) {
+        this.emit(ctx, { type: 'RunAborted', payload: { reason: 'no_progress_timeout' } });
+        return { run_id: ctx.runId, status: 'aborted', completed: [], failed: [], blocked: [], reason: 'no_progress_timeout' };
+      }
+
       // Respect pause: persist journal and return paused result
       if (this.paused) {
         this.journal.scheduler_state = 'paused';
@@ -123,7 +207,17 @@ export class Scheduler {
       this.journal.blocked_work_items = blocked.slice();
       saveJournal(ctx.projectRoot, ctx.runId, this.journal);
 
-      if (waveFailed) break;
+      if (waveFailed) {
+        // Execute rollback plan if one was created for this run
+        const memos = listMemos(ctx.projectRoot, ctx.runId);
+        for (const memo of memos) {
+          if (memo.rollback_plan.strategy !== 'no_rollback') {
+            await this.executeRollback(memo.rollback_plan, ctx);
+            break; // apply at most one rollback plan per wave failure
+          }
+        }
+        break;
+      }
     }
 
     // Any remaining pending nodes become blocked
@@ -305,6 +399,15 @@ export class Scheduler {
     };
   }
 
+  private isConcurrentSafe(nodeId: string, graph: ExecutionGraph, ctx: SchedulerContext): boolean {
+    const node = graph.nodes.get(nodeId)!;
+    if (node.mutation_scope.length > 0) return false;
+    const primaryAction = pickPrimaryAction(node, ctx.pluginRegistry);
+    if (!primaryAction) return true;
+    const provider = ctx.pluginRegistry?.toolProviderFor(primaryAction.type);
+    return provider?.idempotent ?? true;
+  }
+
   private async runWave(
     nodeIds: string[],
     graph: ExecutionGraph,
@@ -338,10 +441,7 @@ export class Scheduler {
       });
     }
 
-    const readOnly = eligible.filter((id) => {
-      const node = graph.nodes.get(id)!;
-      return node.mutation_scope.length === 0;
-    });
+    const readOnly = eligible.filter((id) => this.isConcurrentSafe(id, graph, ctx));
     const mutations = eligible.filter((id) => !readOnly.includes(id));
 
     if (readOnly.length > 0) {
@@ -453,6 +553,7 @@ export class Scheduler {
           });
           status.set(nodeId, 'completed');
           completed.push(nodeId);
+          this.recordProgress();
           return;
         }
 
@@ -464,29 +565,47 @@ export class Scheduler {
             this.blockNode(nodeId, ctx, status, blocked, 'quota_exceeded', retryBlocked);
             return;
           }
+          // Exponential backoff with jitter: 1s * 2^(attempt-1) + [0, 500ms], capped at 30s
+          const backoffMs = Math.min(
+            1_000 * Math.pow(2, attempt - 1) + Math.random() * 500,
+            30_000
+          );
+          await new Promise<void>(resolve => setTimeout(resolve, backoffMs));
           this.emit(ctx, {
             type: 'RetryScheduled',
             work_item_id: nodeId,
-            payload: { next_attempt: attempt + 1, reason: lastResult.failure_class },
+            payload: { next_attempt: attempt + 1, reason: lastResult.failure_class, backoff_ms: backoffMs },
           });
         }
-      } catch (err) {
+      } catch (err: unknown) {
+        // Error boundary: isolate task failure, emit structured event, do not crash scheduler
+        const message = err instanceof Error ? err.message : String(err);
+        const stack   = err instanceof Error ? err.stack   : undefined;
+        this.emit(ctx, {
+          type: 'TaskErrorBoundaryTripped',
+          work_item_id: nodeId,
+          payload: { message, stack, attempt },
+        });
         lastResult = {
           success: false,
           failure_class: 'env',
           evidence: [],
-          output: String(err),
+          output: `[error_boundary] ${message}`,
         };
         if (attempt < maxAttempts) {
+          const backoffMs = Math.min(1_000 * Math.pow(2, attempt - 1) + Math.random() * 500, 30_000);
+          await new Promise<void>(resolve => setTimeout(resolve, backoffMs));
           this.emit(ctx, {
             type: 'RetryScheduled',
             work_item_id: nodeId,
-            payload: { next_attempt: attempt + 1, reason: 'env' },
+            payload: { next_attempt: attempt + 1, reason: 'env', backoff_ms: backoffMs },
           });
         }
       } finally {
         if (lease) {
-          await ctx.workspaceManager.dispose(lease.workspace_id).catch(() => {});
+          await ctx.workspaceManager.dispose(lease.workspace_id).catch((e: unknown) =>
+            this.emit(ctx!, { type: 'WorkspaceDisposeFailed', payload: { workspace_id: lease?.workspace_id, error: String(e) } })
+          );
           lease = null;
         }
       }
@@ -562,7 +681,7 @@ export class Scheduler {
       payload: { provider: provider.name, action_type: primaryAction.type },
     });
 
-    const result = await provider.invoke({
+    const invocationInput = {
       action_type: primaryAction.type,
       work_item_id: node.id,
       run_id: ctx.runId,
@@ -572,7 +691,26 @@ export class Scheduler {
         targets: primaryAction.targets ?? [],
       },
       workspace_root: lease.root_path,
-    });
+    };
+
+    if (provider.preInvoke) {
+      const preCheck = await provider.preInvoke(invocationInput);
+      if (!preCheck.allowed) {
+        this.emit(ctx, {
+          type: 'ToolFailed',
+          work_item_id: node.id,
+          attempt_id: attemptId,
+          payload: { provider: provider.name, action_type: primaryAction.type, error: preCheck.reason ?? 'pre_invoke blocked', evidence_paths: [], side_effects_applied: [] },
+        });
+        return { success: false, failure_class: 'policy', evidence: [], output: preCheck.reason ?? 'pre_invoke blocked' };
+      }
+    }
+
+    const result = await provider.invoke(invocationInput);
+
+    if (provider.postInvoke) {
+      await provider.postInvoke(invocationInput, result).catch(() => {});
+    }
 
     this.emit(ctx, {
       type: result.success ? 'ToolCompleted' : 'ToolFailed',

package/packages/runtime/src/verification/verification-manifest.ts

@@ -6,13 +6,17 @@ import type { CheckResult } from './verification-compiler';
 
 export type VerificationProfile = 'quick' | 'standard' | 'critical';
 
-export type FailureClass =
-  | 'deterministic'
-  | 'flaky'
-  | 'timeout'
-  | 'env_setup'
-  | 'policy_failure'
-  | 'evidence_missing';
+/** Verification-specific failure classification (why a check failed, not why a task failed). */
+export type VerificationFailureClass =
+  | 'deterministic'    // check always fails regardless of retry
+  | 'flaky'            // check outcome is non-deterministic
+  | 'timeout'          // check exceeded time budget
+  | 'env_setup'        // environment/infrastructure prevented check from running
+  | 'policy_failure'   // policy blocked the check
+  | 'evidence_missing'; // required evidence was never collected
+
+/** @deprecated Use VerificationFailureClass. Kept for backwards compat. */
+export type FailureClass = VerificationFailureClass;
 
 export type VerificationGranularity = 'work_item' | 'wave' | 'run';
 
@@ -20,7 +24,7 @@ export interface ManifestCheck {
   check_id: string;
   acceptance_ref: string | null;
   status: VerificationStatus;
-  failure_class: FailureClass | null;
+  failure_class: VerificationFailureClass | null;
   evidence_refs: string[];
   duration_ms: number;
 }

package/vscode-extension/package.json

@@ -2,7 +2,7 @@
   "name": "oxe-agents",
   "displayName": "OXE Agents",
   "description": "Agentes OXE para GitHub Copilot Chat — cada fase do ciclo como um @agente no VS Code",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "publisher": "oxe-cc",
   "license": "MIT",
   "engines": {