r.log`, hash: createHash('sha256').update(String(error)).digest('hex'), metadata: { error: String(error) } }); this.emit('task.failed', task); } }

// Capture structured evidence from worker output private async collectEvidence(task: ExecutionTask, result: any): Promise<void> { const artifacts: EvidenceArtifact[] = [];

// Capture test output or process logs
if (result.stdout) {
  artifacts.push({
    type: 'process_log',
    path: `artifacts/${task.id}_stdout.log`,
    hash: createHash('sha256').update(result.stdout).digest('hex'),
    metadata: { exitCode: result.exitCode, duration: result.duration }
  });
}

// Capture file diffs if worker modifies workspace
const diffPath = `artifacts/${task.id}_diff.patch`;
// In production, run git diff or file watcher here
artifacts.push({
  type: 'diff',
  path: diffPath,
  hash: createHash('sha256').update(`diff-${task.id}-${Date.now()}`).digest('hex'),
  metadata: { scope: task.objective }
});

task.evidence = artifacts;

}

// Verify evidence against acceptance criteria before state transition private async verifyAndTransition(task: ExecutionTask): Promise<void> { task.status = 'verifying';

// Check acceptance criteria
const criteriaMet = task.acceptanceCriteria.every(criteria => {
  // In production: parse test results, validate diffs, run regression checks
  return task.evidence.some(e => e.metadata?.scope?.includes(criteria) || e.type === 'test_output');
});

// Enforce approval gates for high-risk tasks
if (task.riskLevel === 'critical' && !this.approvalQueue.has(task.id)) {
  task.status = 'blocked';
  this.emit('task.blocked', task, 'Approval gate pending for critical task');
  return;
}

if (criteriaMet && task.evidence.length > 0) {
  task.status = 'completed';
  this.emit('task.completed', task);
  // Trigger downstream dependency resolution
  this.taskGraph.forEach(t => {
    if (t.dependencies.includes(task.id)) this.resolveDependencies(t.id);
  });
} else {
  task.status = 'failed';
  task.evidence.push({
    type: 'blocker_reason',
    path: `logs/${task.id}_verification_failure.log`,
    hash: createHash('sha256').update('criteria_not_met').digest('hex'),
    metadata: { missingCriteria: task.acceptanceCriteria.filter(c => !task.evidence.some(e => e.metadata?.scope?.includes(c))) }
  });
  this.emit('task.failed', task);
}

}

// AFK execution loop with conservative assumptions async runAfkLoop(): Promise<void> { this.afkMode = true; while (this.afkMode) { const readyTasks = Array.from(this.taskGraph.values()).filter(t => t.status === 'ready'); if (readyTasks.length === 0) { const blockedTasks = Array.from(this.taskGraph.values()).filter(t => t.status === 'blocked'); if (blockedTasks.length > 0) { console.warn('AFK loop halted: unresolved blockers detected'); break; } await new Promise(r => setTimeout(r, 5000)); continue; }

  for (const task of readyTasks) {
    await this.executeTask(task.id);
  }
}

} }

### Architecture Decisions & Rationale

**Separation of Supervisor and Worker**: The runtime never delegates state management to external CLIs. Codex CLI or Claude Code execute commands, but the orchestrator owns the task graph, evidence validation, and state transitions. This prevents workers from self-reporting completion without verification.

**Explicit Evidence Schema**: Evidence is structured, not free-form text. Each artifact carries a type, path, cryptographic hash, and metadata. This enables deterministic verification, audit trails, and automated regression checks.

**Dependency-First Execution**: Tasks remain `pending` until all dependencies report `completed`. This eliminates race conditions and ensures that foundational changes (e.g., API schema updates) are verified before dependent tasks (e.g., UI integration) begin.

**Approval Gates for Critical Paths**: High-risk tasks automatically transition to `blocked` until explicit approval is granted. This prevents silent deployments, destructive operations, or backward-incompatible changes from proceeding without human oversight.

**AFK Conservatism**: The autonomous loop avoids optimistic continuation. It halts on unresolved blockers, skips non-critical clarification prompts, and maintains strict evidence requirements. AFK accelerates execution but never bypasses safety invariants.

## Pitfall Guide

### 1. Treating LLM Output as Verification
**Explanation**: Assuming that a model's summary ("I fixed the timeout bug") constitutes proof of completion. LLMs optimize for coherence, not correctness.
**Fix**: Route all worker output through an evidence pipeline. Require test execution, diff validation, or log parsing before state transition. Never accept textual claims as closure.

### 2. Skipping Dependency Resolution
**Explanation**: Executing tasks in parallel or out of order without verifying upstream completion. This causes cascading failures when foundational changes are incomplete.
**Fix**: Implement a strict dependency graph. Tasks remain `pending` until all referenced task IDs report `completed`. Use topological sorting for execution order.

### 3. Weak Evidence Definitions
**Explanation**: Accepting vague artifacts like "checked the file" or "ran a command" as evidence. This provides no audit trail or reproducibility.
**Fix**: Define an evidence schema requiring structured types (`test_output`, `diff`, `process_log`, `blocker_reason`). Mandate cryptographic hashing and metadata attachment. Reject tasks with missing or malformed evidence.

### 4. Unbounded AFK Execution
**Explanation**: Allowing autonomous loops to continue indefinitely without safety boundaries. This can trigger destructive operations, exhaust API quotas, or ignore critical blockers.
**Fix**: Implement explicit halt conditions: unresolved blockers, missing approvals, credential boundaries, or destructive command filters. Log all AFK decisions and require manual resume for critical paths.

### 5. Ignoring Approval Gates for High-Risk Tasks
**Explanation**: Executing migrations, deployments, or schema changes without human verification. This leads to production incidents and data loss.
**Fix**: Tag tasks with risk levels. Automatically transition `critical` or `high` tasks to `blocked` until explicit approval is recorded. Maintain an approval queue with audit timestamps.

### 6. Terminal Session Leaks
**Explanation**: Spawning long-running processes (dev servers, watchers, REPLs) without cleanup or isolation. This consumes resources, causes port conflicts, and leaves orphaned processes.
**Fix**: Implement session lifecycle management. Assign unique session IDs, enforce workspace boundaries, log all I/O, and provide explicit kill/restart commands. Monitor resource usage and auto-terminate idle sessions.

### 7. Cross-Worker State Drift
**Explanation**: Running multiple subagents or CLI workers that modify the same workspace without synchronization. This causes merge conflicts, overwritten files, and inconsistent state.
**Fix**: Use workspace partitioning or file locking. Assign exclusive file scopes to workers. Run a post-execution merge verification step. Maintain a central state store that all workers read from but only the supervisor writes to.

## Production Bundle

### Action Checklist
- [ ] Define explicit task states and transition rules before implementing the runtime
- [ ] Structure evidence artifacts with type, path, hash, and metadata fields
- [ ] Implement dependency resolution that blocks execution until upstream tasks complete
- [ ] Add approval gates for critical-path and high-risk operations
- [ ] Route all CLI/worker output through a verification pipeline before state transition
- [ ] Configure AFK mode with conservative assumptions and explicit halt conditions
- [ ] Implement terminal session lifecycle management with isolation and cleanup
- [ ] Log all state transitions, evidence attachments, and approval decisions for auditability

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Single-file refactor with clear tests | Conversational agent with tool calls | Low complexity, fast feedback loop | Minimal compute cost |
| Multi-module migration with backward compatibility | Evidence-driven state runtime | Requires dependency tracking, approval gates, and regression verification | Moderate compute + storage for evidence artifacts |
| Long-running audit or heavy test suite | Remote CLI worker + supervisor verification | Isolates resource-heavy work, prevents local environment drift | Higher infrastructure cost, but safer execution |
| Security/bug bounty scope validation | Intake-gated agent with strict boundaries | Prevents unauthorized scanning, enforces program rules | Low compute, high compliance value |
| Rapid prototyping with uncertain requirements | AFK mode with conservative assumptions | Accelerates exploration while halting on real blockers | Moderate compute, reduces idle wait time |

### Configuration Template

```yaml
runtime:
  workspace: ./project-root
  state_store: ./state/execution_graph.json
  evidence_dir: ./artifacts
  log_level: info

tasks:
  default_risk: low
  approval_required:
    - critical
    - high
  evidence_schema:
    required_fields:
      - type
      - path
      - hash
      - metadata
    allowed_types:
      - test_output
      - diff
      - process_log
      - http_response
      - screenshot
      - blocker_reason

workers:
  codex_cli:
    command: codex
    args: ["exec", "--headless"]
    timeout_ms: 300000
    workspace_bound: true
  claude_code:
    command: claude
    args: ["--print", "--output-format", "json"]
    timeout_ms: 240000
    workspace_bound: true

afk:
  enabled: false
  conservative_assumptions: true
  halt_on_blockers: true
  max_concurrent_tasks: 3
  idle_timeout_ms: 60000

security:
  destructive_commands:
    - rm -rf
    - sudo
    - chmod 777
  approval_bypass: false
  credential_scopes:
    - production
    - billing
    - infrastructure

Quick Start Guide

1. Initialize the runtime: Create a new project directory, install dependencies (npm i execa crypto), and scaffold the ExecutionOrchestrator class. Configure the workspace root and evidence directory.
2. Define your execution plan: Write a YAML or JSON plan specifying objectives, task dependencies, acceptance criteria, and risk levels. Register each task using orchestrator.registerTask().
3. Configure workers: Set up Codex CLI or Claude Code configurations in the runtime. Ensure commands run in headless mode, respect workspace boundaries, and output structured results.
4. Run verification loop: Execute orchestrator.executeTask() for ready tasks. The runtime will spawn the worker, capture evidence, validate against acceptance criteria, and transition state. Monitor events via orchestrator.on('task.completed', ...).
5. Enable AFK or remote execution: For long-running workflows, set afk.enabled: true and deploy workers to isolated environments. The supervisor will continue processing ready tasks, halt on blockers, and maintain a complete audit trail of all state transitions and evidence artifacts.