State file reference

{
  "runs": [
    {
      "runId": "1788337916070-aqhfn",
      "runFolder": "~/.hankweave-executions/1788337915373-x194-4a876b/.hankweave/runs/1788337916070-aqhfn",
      "gitBranch": "run-1788337916070-aqhfn",
      "startingConditions": {
        "type": "fresh"
      },
      "codons": [
        {
          "codonId": "summarize-notes",
          "startTime": "2026-09-02T08:31:56.104Z",
          "status": "completed",
          "claudePid": 952404,
          "claudeLogPath": ".hankweave/runs/1788337916070-aqhfn/summarize-notes-claude.log",
          "claudeSessionId": "83b52eaa-5147-4130-aef4-818c9c663c77",
          "currentCost": 0.01050655,
          "currentTokens": {
            "inputTokens": 25,
            "outputTokens": 654,
            "cacheCreationTokens": 683,
            "cacheReadTokens": 56488
          },
          "assistantMessageCount": 3,
          "extensionCount": 0,
          "endTime": "2026-09-02T08:32:08.079Z",
          "exitCode": 0,
          "finalCost": 0.01050655,
          "finalTokens": {
            "inputTokens": 25,
            "outputTokens": 654,
            "cacheCreationTokens": 683,
            "cacheReadTokens": 56488
          },
          "resultMessageReceived": true,
          "completionCheckpoint": "4ae2cf9d1a341fe1108487ddc2cea91ae4dd71ef"
        }
      ],
      "status": "completed",
      "startTime": "2026-09-02T08:31:56.071Z",
      "serverPid": 52624,
      "endTime": "2026-09-02T08:32:10.187Z"
    }
  ],
  "currentRunId": null,
  "executionPlan": [
    {
      "codon": {
        "type": "codon",
        "id": "summarize-notes",
        "name": "Summarize the notes",
        "promptFile": "<workspace>/fixtures/minimal-single-provider/prompts/summarize.md",
        "model": {
          "providerId": "anthropic",
          "modelId": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5 (latest)",
          "attachment": true,
          "reasoning": true,
          "tool_call": true,
          "temperature": true,
          "cost": {
            "input": 1,
            "output": 5,
            "cache_read": 0.1,
            "cache_write": 1.25
          },
          "limit": {
            "context": 200000,
            "output": 64000
          },
          "modalities": {
            "input": [
              "text",
              "image",
              "pdf"
            ],
            "output": [
              "text"
            ]
          },
          "knowledge": "2025-02-28",
          "release_date": "2025-10-15",
          "last_updated": "2025-10-15"
        },
        "continuationMode": "fresh",
        "checkpointedFiles": [
          "summary.md"
        ],
        "outputFiles": [
          {
            "copy": [
              "summary.md"
            ]
          }
        ],
        "maxExtensions": 100
      },
      "codonId": "summarize-notes"
    }
  ]
}

export interface Run {
  /**
   * Unique identifier for this run.
   * Also used as git branch name.
   *
   * Used by: State lookups, folder naming, git branches
   */
  runId: RunId;

  /**
   * Absolute path where run files are stored.
   * Example: "/project/.hankweave/runs/1234-abc"
   *
   * Used by: Log file storage, cleanup operations
   * Edge case: Folder might not exist if run failed early
   */
  runFolder: string;

  /**
   * Git branch name for this run.
   * Usually same as runId, but explicit for flexibility.
   *
   * Used by: Checkpoint system
   */
  gitBranch: string;

  /**
   * How this run started - fresh or continuation.
   * Immutable after run creation.
   *
   * Used by: UI to show run relationships, rollback tracking
   */
  startingConditions: StartingConditions;

  /**
   * Ordered list of codon executions in this run.
   * Append-only - new codons added as they start.
   *
   * Used by: Progress tracking, cost calculation
   * Invariant: Only one codon can be non-terminal at a time
   */
  codons: CodonExecution[];

  /**
   * Overall run status.
   * - running: Currently executing
   * - completed: All codons done successfully
   * - failed: Stopped due to codon failure
   * - crashed: Detected on recovery
   *
   * Used by: Run selection, cleanup decisions
   */
  status: "running" | "completed" | "failed" | "crashed";

  /**
   * When server started. Never changes.
   */
  startTime: string;

  /**
   * When server stopped. Set when status becomes terminal.
   */
  endTime?: string;

  /**
   * Server process ID for lock file validation.
   *
   * Used by: Detecting stale lock files, crash recovery
   * Edge case: Process might not exist anymore
   */
  serverPid: number;
}

/**
 * How a run started - fresh project or continuation.
 */
export type StartingConditions =
  | {
      type: "fresh";
      initialCheckpointSha?: string; // SHA of the initial checkpoint commit
    }
  | {
      type: "continuation";
      source: {
        /**
         * Which run we're continuing from.
         *
         * Used by: Building run relationships tree
         */
        runId: RunId;

        /**
         * Which codon to continue after.
         * null means start from beginning of that run.
         *
         * Example: "codon-2" means start from codon-3
         * Used by: Determining next codon to execute
         */
        afterCodon: CodonId | null;

        /**
         * Git commit SHA we restored to.
         * This is the exact state we're continuing from.
         *
         * Used by: Verifying correct restoration
         */
        checkpointSha: string;
      };

      /**
       * Human-readable reason for continuation.
       * Optional metadata for UI/analytics.
       *
       * Used by: Understanding user patterns
       */
      reason?: "retry" | "rollback" | "continue";
    };

// -------------
// Top-Level State
// -------------

/**
 * Root state object for Hankweave.
 * Stored in .hankweave/state.json.
 *
 * Design decisions:
 * - Single file instead of per-run for simplicity
 * - No version field per user request
 * - No denormalized costs - computed when needed
 */
export interface HankweaveState {
  /**
   * All runs, newest first.
   * Append-only - runs are never removed from history.
   *
   * Used by: History UI, cost calculations, rollback sources
   * Scaling: May need pagination/archival eventually
   */
  runs: Run[];

  /**
   * Currently active run ID.
   * null when server not running.
   *
   * Used by: State queries, preventing multiple servers
   * Invariant: Only one run can be "running" status
   */
  currentRunId: RunId | null;

  /**
   * Initial checkpoint SHA from git repository initialization.
   * This is the empty commit created when the checkpoint system starts.
   * Represents the project's clean state before any codons have executed.
   *
   * Used by: Rollback to clean state, project-level rollback commands
   */
  initialCheckpoint?: string;

  /**
   * Current execution plan with all loop iterations expanded.
   * This is the flattened plan that represents the actual execution sequence.
   * Rebuilt on server start but persisted for crash recovery and debugging.
   *
   * Note: May be empty array during initialization before first run starts,
   * but the field itself is always present.
   *
   * Used by: Codon execution, execution thread analysis, crash recovery
   */
  executionPlan: import("../execution-planner.js").ExecutionCodonEntry[];

/**
 * Codon execution status progression.
 *
 * Normal flow: preparing → starting → initializing → running → completing-sentinels → completed
 * Can skip to "failed" or "skipped" from any non-terminal state.
 *
 * Intent: Track granular progress for better crash recovery and user feedback.
 */
export type CodonStatus =
  | "preparing" // Rig setup running (copy files, run commands)
  | "starting" // Spawning Claude process
  | "initializing" // Process started, waiting for session ID
  | "running" // Claude is working (have session ID)
  | "completing-sentinels" // Completing sentinel work (draining queues)
  | "completed" // Success - terminal state
  | "failed" // Failed - terminal state
  | "skipped"; // User skipped - terminal state

/**
 * Base properties shared by all codon states.
 * These are set when the codon starts and never change.
 */
interface BaseCodon {
  /**
   * Which codon configuration this execution is for.
   * References the codon in hank.json.
   *
   * Used by: UI to show codon name, state queries for codon history
   */
  codonId: CodonId;

  /**
   * When this codon execution started.
   * ISO 8601 timestamp.
   *
   * Used by: Duration calculations, UI timeline display
   */
  startTime: string;

  /**
   * Loop context if this codon is part of a loop iteration.
   * Used for resuming loops after interruption and rollback.
   */
  loopContext?: {
    loopId: CodonId; // ID of the loop this codon belongs to
    iteration: number; // Which iteration (0-indexed: 0 = first, 1 = second, etc.)
    codonIndexInLoop: number; // Position within loop.codons array
  };
}

/**
 * Codon is preparing rig (running rig setup operations).
 *
 * Next states:
 * - starting: Rig setup succeeded
 * - failed: Copy failed, command failed, etc.
 * - skipped: User skipped during prep
 */
export interface PreparingCodon extends BaseCodon {
  status: "preparing";
  // No Claude info yet - process not started
  // No costs yet - Claude not running
}

/**
 * Spawning Claude process.
 *
 * Next states:
 * - initializing: Process started successfully
 * - failed: Spawn failed (Claude not found, etc.)
 * - skipped: User skipped during startup
 */
export interface StartingCodon extends BaseCodon {
  status: "starting";

  /**
   * Git commit SHA after rig setup completed.
   * Only set if codon config has rigSetup operations.
   *
   * Used by: Rollback to know exact state after setup
   * Edge case: May be undefined if no rig setup configured
   */
  rigSetupCheckpoint?: string;

  /**
   * Sentinels loaded for this codon.
   * Set after sentinels load during starting state.
   */
  sentinels?: {
    loaded: SentinelState[];
    totalCost: number;
  };
}

/**
 * Claude process running but no session ID yet.
 * Waiting for init message from Claude.
 *
 * Next states:
 * - running: Got session ID from init message
 * - completed: Process exited cleanly but init message failed validation
 * - failed: Process crashed before init
 * - skipped: User skipped during init
 */
export interface InitializingCodon extends BaseCodon {
  status: "initializing";
  rigSetupCheckpoint?: string;

  /**
   * Claude process ID for monitoring/cleanup.
   *
   * Used by: Process manager to kill on skip/shutdown
   * Edge case: Process might already be dead
   */
  claudePid: number;

  /**
   * Path to Claude's JSONL log file.
   * Relative to .hankweave directory.
   * Example: "runs/1234-abc/codon-research-claude.log"
   *
   * Used by: Log parser, debugging, cleanup
   */
  claudeLogPath: string;

  /**
   * Session ID from previous codon if continuing.
   * Only set if codon has continueFromPrevious: true.
   *
   * Used by: Claude CLI --resume flag
   */
  previousSessionId?: SessionId;

  /**
   * Sentinels loaded for this codon.
   * Optional field added during starting state, carried forward to initializing.
   */
  sentinels?: {
    loaded: SentinelState[];
    totalCost: number;
  };
}

/**
 * Claude is actively working.
 * This is where most time is spent.
 *
 * Next states:
 * - completed: Claude process exited cleanly
 * - failed: Timeout, API error, crash
 * - skipped: User skipped
 */
export interface RunningCodon extends BaseCodon {
  status: "running";
  rigSetupCheckpoint?: string;
  claudePid: number;

  /**
   * Claude's session UUID from init message.
   * Required for continuation in later codons.
   *
   * Used by: Continue functionality, logs correlation
   */
  claudeSessionId: SessionId;
  claudeLogPath: string;
  previousSessionId?: SessionId;

  /**
   * Accumulated cost so far in USD.
   * Updated on each token usage message.
   *
   * Used by: Cost display, cost limits (future)
   * Edge case: May be stale if messages delayed
   */
  currentCost: number;

  /**
   * Accumulated token counts.
   * Updated on each assistant message with usage.
   *
   * Used by: Token display, rate limit tracking
   */
  currentTokens: TokenUsage;

  /**
   * Number of assistant messages received.
   * Used to determine if Claude has established a conversation.
   * Initialized to 0 when codon enters running state.
   *
   * Used by: Continue functionality to check if session is valid
   */
  assistantMessageCount: number;

  /**
   * Number of extensions performed so far.
   * 0 initially, increments with each extension.
   * Used for tracking progress and enforcing maxExtensions.
   */
  extensionCount: number;

  /**
   * Sentinels loaded for this codon.
   * Updated in-place during execution.
   */
  sentinels?: {
    loaded: SentinelState[];
    totalCost: number;
  };
}

/**
 * Codon is completing sentinel work.
 * Transient state between agent completion and final state.
 *
 * This state indicates:
 * - Main Claude agent has finished (process exited)
 * - Sentinel queues are being drained
 * - All pending LLM calls are completing
 * - Output files are being finalized
 *
 * Next states:
 * - completed: All work done successfully
 * - failed: Checkpoint creation failed
 * - skipped: Should not normally happen from this state
 */
export interface CompletingSentinelsCodon extends BaseCodon {
  status: "completing-sentinels";
  rigSetupCheckpoint?: string;
  claudePid: number;
  claudeSessionId: SessionId;
  claudeLogPath: string;
  previousSessionId?: SessionId;

  /**
   * Current cost accumulated while Claude was running.
   * Will become finalCost when transitioning to completed.
   */
  currentCost: number;

  /**
   * Current token counts.
   * Will become finalTokens when transitioning to completed.
   */
  currentTokens: TokenUsage;

  /**
   * Number of assistant messages received.
   */
  assistantMessageCount: number;

  /**
   * Extension count from the running state.
   * Preserved during sentinel completion.
   */
  extensionCount: number;

  /**
   * Sentinels being completed.
   * States are updated in-place as work completes.
   */
  sentinels?: {
    loaded: SentinelState[];
    totalCost: number;
  };
}

// -------------
// Terminal States - Immutable once reached
// -------------

/**
 * Codon completed successfully.
 * This is a terminal state - no further transitions possible.
 *
 * Immutability: All fields are final. To retry, start a new run.
 */
export interface CompletedCodon extends BaseCodon {
  status: "completed";

  /**
   * When codon completed. Used for duration calculation.
   */
  endTime: string;

  // Claude integration details
  claudeSessionId: SessionId;
  claudeLogPath: string;
  previousSessionId?: SessionId;

  /**
   * Always 0 for successful completion.
   *
   * Used by: Success detection
   */
  exitCode: 0;

  /**
   * Final cost from result message or last token update.
   * This is the authoritative cost for this codon.
   *
   * Used by: Billing, cost reports
   * Edge case: May be from token updates if result message timed out
   */
  finalCost: number;

  /**
   * Final token counts.
   *
   * Used by: Usage analytics, model comparison
   */
  finalTokens: TokenUsage;

  /**
   * Whether we got Claude's result message before timeout.
   * False means costs might be slightly off.
   *
   * Used by: Cost accuracy warnings
   */
  resultMessageReceived: boolean;

  /**
   * Final count of extensions performed.
   * Used for reporting and debugging.
   */
  extensionCount: number;

  // Checkpoints
  rigSetupCheckpoint?: string;

  /**
   * Git commit after successful completion.
   * Always created for successful codons.
   *
   * Used by: Rollback target points
   */
  completionCheckpoint: string;

  /**
   * Sentinels that executed during this codon (final state).
   * Field renamed from 'loaded' to 'executed' when codon completes.
   */
  sentinels?: {
    executed: SentinelState[];
    totalCost: number;
  };

  /** Present when codon was force-completed due to budget limit. */
  budgetExceeded?: BudgetExceededData;
}

/**
 * Codon failed with error.
 * Terminal state - must start new run to retry.
 */
export interface FailedCodon extends BaseCodon {
  status: "failed";
  endTime: string;

  /**
   * Which state we were in when failure occurred.
   * Helps understand how far we got.
   *
   * Used by: Error analysis, retry strategies
   * Example: "preparing" means rig setup failed
   * Note: Can include "completing-sentinels" if checkpoint creation fails during that codon
   */
  failedDuring: "preparing" | "starting" | "initializing" | "running" | "completing-sentinels";

  // Claude info - only set if we got that far
  claudePid?: number;
  claudeSessionId?: SessionId;
  claudeLogPath?: string;
  previousSessionId?: SessionId;

  /**
   * Process exit code. 0 means clean exit (shouldn't happen for failed).
   * Common codes:
   * - 1: General error
   * - -1: Killed by signal
   * - 130: Ctrl+C
   *
   * Used by: Debugging, retry decisions
   */
  exitCode: number;

  /**
   * Structured failure information.
   *
   * Used by: UI error display, retry logic
   */
  failureReason: FailureReason;

  /**
   * Costs accumulated before failure.
   * Will be 0 if failed before Claude started.
   *
   * Used by: Partial cost tracking
   */
  partialCost: number;
  partialTokens: TokenUsage;

  /**
   * Number of extensions performed before failure.
   * Only present if codon reached running state and attempted extensions.
   */
  extensionCount?: number;

  // Checkpoints
  rigSetupCheckpoint?: string;

  /**
   * Error checkpoint if created.
   * On error branch in git.
   *
   * Edge case: Might not exist if git operations failed
   */
  errorCheckpoint?: string;

  /**
   * Sentinels that executed before failure.
   */
  sentinels?: {
    executed: SentinelState[];
    totalCost: number;
  };
}

/**
 * Codon was skipped by user.
 * Terminal state - represents user choice to skip.
 */
export interface SkippedCodon extends BaseCodon {
  status: "skipped";
  endTime: string;

  /**
   * Which state we were in when skipped.
   *
   * Used by: Understanding skip patterns
   */
  skippedDuring: "preparing" | "starting" | "initializing" | "running";

  // Claude info - only set if we got that far
  claudePid?: number;
  claudeSessionId?: SessionId;
  claudeLogPath?: string;
  previousSessionId?: SessionId;

  /**
   * Partial cost accumulated before skip.
   * Usually 0, but may have accumulated costs if skipped while running.
   *
   * Used by: Cost calculations, continuation logic
   */
  partialCost: number;

  /**
   * All zeros - no tokens used for skipped.
   */
  partialTokens: TokenUsage;

  /**
   * Number of assistant messages received before skip.
   * Used to determine if session can be continued.
   *
   * Used by: Continue functionality
   */
  assistantMessageCount?: number;

  // Checkpoints
  rigSetupCheckpoint?: string;

  /**
   * Skip checkpoint if any files were being tracked.
   * Even empty commits are created for skip markers.
   *
   * Used by: Skip history in git
   */
  skipCheckpoint?: string;

  /**
   * Sentinels that executed before skip.
   */
  sentinels?: {
    executed: SentinelState[];
    totalCost: number;
  };
}

/**
 * Union of all possible codon states.
 * Use discriminated union on `status` field for type narrowing.
 */
export type CodonExecution =
  | PreparingCodon
  | StartingCodon
  | InitializingCodon
  | RunningCodon
  | CompletingSentinelsCodon
  | CompletedCodon
  | FailedCodon
  | SkippedCodon;

{
  "codonId": "normalize",
  "startTime": "2026-01-01T12:00:00.000Z",
  "status": "running",
  "claudePid": 12345,
  "claudeLogPath": "runs/run-1/normalize.log",
  "claudeSessionId": "session-1",
  "currentCost": 0.0234,
  "currentTokens": {
    "inputTokens": 1500,
    "outputTokens": 800,
    "cacheCreationTokens": 0,
    "cacheReadTokens": 500
  },
  "assistantMessageCount": 5,
  "extensionCount": 0,
  "sentinels": { "loaded": [], "totalCost": 0 }
}

export interface ExecutionCodonEntry {
  // The actual codon config to execute (always Codon, never Loop)
  codon: Codon;

  // Runtime-generated ID (e.g., "review#0", "review#1" for loop iterations)
  codonId: CodonId;

  // If from a loop, track context for resume/rollback
  loopContext?: {
    loopId: CodonId; // ID of the loop this codon belongs to
    iteration: number; // Which iteration (0-indexed: 0 = first, 1 = second, etc.)
    codonIndexInLoop: number; // Position within loop.codons array
    // Loop's own budget config (if declared), carried for Budget class to use
    loopBudget?: {
      maxDollars?: number;
      maxTimeSeconds?: number;
      allocation?: AllocationMode;
      shares?: Record<string, number>;
      onExceeded?: "complete" | "fail";
    };
  };
}

/**
 * State tracking for a single sentinel within a codon.
 * Mutable structure updated in-place during codon execution.
 */
export interface SentinelState {
  id: string;
  model: string;
  loadedAt: string;
  unloadedAt?: string;
  llmCallCount: number;
  failedLLMCalls: number;
  lastLlmCallAt?: string;
  totalTriggers: number;
  totalCost: number;
  status: "active" | "unloaded";
  unloadReason?: "codon-complete" | "fatal-error" | "consecutive-failures";
}

{
  "sentinels": {
    "loaded": [
      {
        "id": "quality",
        "model": "sonnet",
        "loadedAt": "2026-01-01T12:00:05.000Z",
        "llmCallCount": 2,
        "failedLLMCalls": 0,
        "totalTriggers": 3,
        "totalCost": 0.0012,
        "status": "active"
      }
    ],
    "totalCost": 0.0012
  }
}