State Machine

export const CodonTransitions: Record<CodonStatus, CodonStatus[]> = {
  preparing:            ["starting", "failed", "skipped"],
  starting:             ["initializing", "failed", "skipped"],
  initializing:         ["running", "failed", "skipped"],
  running:              ["completing-sentinels", "completed", "failed", "skipped"],
  "completing-sentinels": ["completed", "failed", "skipped"],
  completed:            [], // Terminal - no transitions
  failed:               [], // Terminal - no transitions
  skipped:              [], // Terminal - no transitions
};

{
  type: "CodonTransitioned";
  data: {
    runId: RunId;
    codonId: CodonId;
    from: CodonStatus;      // Current state
    to: CodonStatus;        // Target state
    metadata?: {
      // For starting → initializing
      claudePid?: number;
      claudeLogPath?: string;
      previousSessionId?: SessionId;
 
      // For initializing → running
      claudeSessionId?: SessionId;
 
      // For any → failed
      exitCode?: number;
      failureReason?: FailureReason;
      failedDuring?: CodonStatus;
 
      // For any → skipped
      skippedDuring?: CodonStatus;
 
      // For → completed
      resultMessageReceived?: boolean;
      checkpointSha?: string;
    };
  };
}

// From state-transition-guards.ts
function validateTransitionMetadata(to: CodonStatus, metadata: unknown): void {
  switch (to) {
    case "initializing":
      // Requires claudePid, claudeLogPath
      if (!hasInitializingMetadata(metadata)) throw new MetadataValidationError(...);
      break;
    case "running":
      // Requires claudeSessionId
      if (!hasRunningMetadata(metadata)) throw new MetadataValidationError(...);
      break;
    case "completed":
      // Requires checkpointSha
      if (!hasCompletedMetadata(metadata)) throw new MetadataValidationError(...);
      break;
    case "failed":
      // Requires exitCode, failureReason, failedDuring
      if (!hasFailedMetadata(metadata)) throw new MetadataValidationError(...);
      break;
    case "skipped":
      // Requires skippedDuring
      if (!hasSkippedMetadata(metadata)) throw new MetadataValidationError(...);
      break;
  }
}

// From state-manager.ts
private transitionQueue: StateTransition[] = [];
private isProcessing = false;
 
// Public API - fire and forget!
transition(event: StateTransition): void {
  this.transitionQueue.push(event);
  this.processQueue(); // Don't await - let it run
}
 
private async processQueue(): Promise<void> {
  if (this.isProcessing) return;
 
  this.isProcessing = true;
  while (this.transitionQueue.length > 0) {
    const event = this.transitionQueue.shift();
    // Validate, apply, persist...
    await this.save();
  }
  this.isProcessing = false;
}

stateManager.transition({
  type: "CostsUpdated",
  data: {
    runId,
    codonId,
    cost: 0.0234,      // New total
    tokens: { inputTokens: 1500, outputTokens: 800, ... }
  }
});

stateManager.transition({
  type: "CostsIncremented",
  data: {
    runId,
    codonId,
    costDelta: 0.0012,  // Amount to add
    tokensDelta: { inputTokens: 100, outputTokens: 50, ... }
  }
});

private costCache = {
  total: 0,
  currentRun: 0,
  lastUpdated: null
};
 
getCurrentRunCost(): number {
  return this.costCache.currentRun;
}
 
getTotalCost(): number {
  return this.costCache.total;
}

interface SentinelState {
  id: string;
  model: string;
  loadedAt: string;
  unloadedAt?: string;
  llmCallCount: number;
  failedLLMCalls: number;
  totalCost: number;
  status: "active" | "unloaded";
  unloadReason?: "codon-complete" | "fatal-error" | "consecutive-failures";
}

validate(state: unknown): StateValidation {
  const errors = [];
  const warnings = [];
 
  // Type structure validation
  if (!this.isValidStateStructure(state)) {
    errors.push({ type: "corrupted_data", message: "Invalid structure" });
  }
 
  // Referential integrity
  if (state.currentRunId && !state.runs.find(r => r.runId === state.currentRunId)) {
    errors.push({ type: "missing_run", message: "Current run not found" });
  }
 
  // Orphaned folders (warning, not error)
  // ...
 
  return { valid: errors.length === 0, errors, warnings };
}

async save(): Promise<void> {
  // 1. Backup current state
  if (fs.existsSync(this.statePath)) {
    await fs.copyFile(this.statePath, this.stateBackupPath);
  }
 
  // 2. Write to temp file
  const tempPath = `${this.statePath}.tmp`;
  await fs.writeFile(tempPath, JSON.stringify(this.state, null, 2));
 
  // 3. Atomic rename
  await fs.rename(tempPath, this.statePath);
}

InvalidTransitionError: Invalid transition from completed to running

MetadataValidationError: Missing required metadata for transition to running: claudeSessionId

async detectCrashedRuns(): Promise<void> {
  for (const run of this.state.runs) {
    if (run.status === "running" && run.runId !== this.state.currentRunId) {
      try {
        process.kill(run.serverPid, 0); // Check if process exists
      } catch {
        // Process doesn't exist - mark as crashed
        this.transition({
          type: "RunCrashed",
          data: { runId: run.runId, detectedAt: new Date().toISOString(), ... }
        });
      }
    }
  }
}

// The 8 codon states
type CodonStatus =
  | "preparing" | "starting" | "initializing" | "running"
  | "completing-sentinels"
  | "completed" | "failed" | "skipped";
 
// Discriminated union for codon execution
type CodonExecution =
  | PreparingCodon | StartingCodon | InitializingCodon
  | RunningCodon | CompletingSentinelsCodon
  | CompletedCodon | FailedCodon | SkippedCodon;
 
// Check if terminal
function isTerminalCodonStatus(status: CodonStatus): boolean {
  return status === "completed" || status === "failed" || status === "skipped";
}
 
// Get cost regardless of state
function getCodonCost(codon: CodonExecution): number {
  switch (codon.status) {
    case "completed": return codon.finalCost;
    case "failed": return codon.partialCost;
    case "skipped": return 0;
    case "running":
    case "completing-sentinels": return codon.currentCost;
    default: return 0;
  }
}

function handleCodon(codon: CodonExecution) {
  if (codon.status === "running") {
    // TypeScript knows: claudeSessionId, currentCost, etc. exist
    console.log(codon.currentCost);
  } else if (codon.status === "completed") {
    // TypeScript knows: finalCost, completionCheckpoint, etc. exist
    console.log(codon.finalCost);
  }
}