Lifecycle State Machines¶

Bernstein uses deterministic finite state machines (FSMs) for both task and agent lifecycle management. All transitions flow through the Lifecycle Governance Kernel (core/tasks/lifecycle.py), which validates transitions against an explicit transition table, rejects illegal moves with IllegalTransitionError, and emits typed LifecycleEvent records for audit, replay, and metrics.

Source of truth: src/bernstein/core/tasks/lifecycle.py (transition tables), src/bernstein/core/tasks/models.py (TaskStatus enum, AgentSession dataclass).

Task States (12 states)¶

Task State Diagram¶

stateDiagram-v2
    [*] --> PLANNED : plan mode
    [*] --> OPEN : dynamic creation

    PLANNED --> OPEN : approved
    PLANNED --> CANCELLED : rejected

    OPEN --> CLAIMED : agent claims task
    OPEN --> WAITING_FOR_SUBTASKS : decomposed before claim
    OPEN --> CANCELLED : manual cancel

    CLAIMED --> IN_PROGRESS : agent starts work
    CLAIMED --> OPEN : unclaim / force-reassign
    CLAIMED --> DONE : fast completion (trivial task)
    CLAIMED --> FAILED : immediate failure
    CLAIMED --> CANCELLED : manual cancel
    CLAIMED --> WAITING_FOR_SUBTASKS : agent splits work
    CLAIMED --> BLOCKED : dependency discovered

    IN_PROGRESS --> DONE : agent reports success
    IN_PROGRESS --> FAILED : agent reports failure
    IN_PROGRESS --> BLOCKED : dependency discovered
    IN_PROGRESS --> WAITING_FOR_SUBTASKS : agent decomposes task
    IN_PROGRESS --> OPEN : requeue (force-reassign)
    IN_PROGRESS --> CANCELLED : manual cancel
    IN_PROGRESS --> ORPHANED : agent crash detected

    ORPHANED --> DONE : partial work merged successfully
    ORPHANED --> FAILED : unrecoverable
    ORPHANED --> OPEN : requeued for retry

    BLOCKED --> OPEN : dependency resolved
    BLOCKED --> CANCELLED : manual cancel

    WAITING_FOR_SUBTASKS --> DONE : all subtasks completed
    WAITING_FOR_SUBTASKS --> BLOCKED : subtask timeout escalation
    WAITING_FOR_SUBTASKS --> CANCELLED : manual cancel

    FAILED --> OPEN : retry (within max_retries)

    DONE --> CLOSED : janitor verified + merged
    DONE --> FAILED : verification rejected

    CLOSED --> [*]
    CANCELLED --> [*]

    %% PENDING_APPROVAL is a terminal state set directly by the approval
    %% subsystem. It has no FSM-managed inbound or outbound transitions.
    PENDING_APPROVAL --> [*]

Note — PENDING_APPROVAL: This state exists in the TaskStatus enum and is used by the approval subsystem (see src/bernstein/core/security/approval.py). It is set directly rather than through the TASK_TRANSITIONS table, so it has no FSM-managed entry or exit path. Tasks in this state await human review and cannot progress further without manual intervention.

Task Transition Table (exhaustive)¶

Every allowed transition is listed below. The guard function for all transitions is _always (unconditional). Any transition not in this table raises IllegalTransitionError.

Terminal States¶

Terminal states have no outbound transitions. Computed by the lifecycle kernel: - CLOSED - CANCELLED - PENDING_APPROVAL (awaits external action; no programmatic exit)

Adaptive Timeout¶

Task timeouts are not static. The adaptive timeout system (src/bernstein/core/orchestration/adaptive_timeout.py) adjusts wall-clock timeouts based on historical task durations. Default scope-based timeouts are defined in src/bernstein/core/defaults.py (TASK.scope_timeout_s): small=15 min, medium=30 min, large=60 min, XL=120 min.

Graduated Access Control¶

The graduated access control system (src/bernstein/core/security/graduated_access.py) gates which lifecycle transitions an agent is permitted to perform based on its trust level and track record. New agents start with restricted permissions that expand as they demonstrate reliability.

Agent States (4 states)¶

Agent State Diagram¶

stateDiagram-v2
    [*] --> starting : spawn()

    starting --> working : process confirmed alive
    starting --> dead : spawn failure / fast exit

    working --> idle : task completed, agent awaiting reuse
    working --> dead : crash / kill / timeout / circuit break

    idle --> working : new task assigned
    idle --> dead : idle recycled (resource reclaim)

    dead --> [*]

Agent Transition Table (exhaustive)¶

Transition Metadata¶

Every transition produces a LifecycleEvent with: - timestamp (Unix epoch) - entity_type ("task" or "agent") - entity_id (task ID or session ID) - from_status / to_status - actor (who triggered it: "task_store", "spawner", "janitor", "plan_approval", etc.) - reason (human-readable explanation) - transition_reason (canonical TransitionReason enum, when applicable) - abort_reason (canonical AbortReason enum, for abnormal agent termination)

TransitionReason Values¶

These canonical reasons classify why a lifecycle transition occurred:

AbortReason Values¶

These classify abnormal agent terminations:

TUI Visual States (7 classifications)¶

The Bernstein terminal dashboard classifies agents into visual states derived from session metadata — not from the FSM directly. These presentation-layer states help operators understand agent health at a glance.

Source: src/bernstein/tui/agent_states.py (AgentState, classify_agent_state).

Mapping to Core FSM States¶

TUI visual states are derived from the core FSM state (starting, working, idle, dead) plus process-level metadata (PID presence, heartbeat timestamp, elapsed time). They do not correspond 1:1 to FSM states.

Thresholds (configurable via AgentStateThresholds): stall threshold = 300 s (5 min), spawn timeout = 60 s.

Agent Turn States (10 states)¶

The agent turn FSM operates at a finer granularity than the agent session FSM above. It tracks the lifecycle of a single task handling turn within an agent process — from the moment a task is claimed through to cleanup.

Source of truth: src/bernstein/core/agents/agent_turn_state.py (AgentTurnState, AgentTurnEvent, AgentTurnStateMachine).

Agent Turn State Diagram¶

Events that drive transitions are shown on each arrow.

stateDiagram-v2
    [*] --> IDLE

    IDLE --> CLAIMING : task_claimed

    CLAIMING --> SPAWNING : agent_spawned
    CLAIMING --> FAILED : task_failed

    SPAWNING --> RUNNING : agent_spawned
    SPAWNING --> FAILED : task_failed

    RUNNING --> TOOL_USE : tool_started
    RUNNING --> COMPACTING : compact_needed
    RUNNING --> VERIFYING : verify_requested
    RUNNING --> FAILED : task_failed

    TOOL_USE --> RUNNING : tool_completed
    TOOL_USE --> FAILED : task_failed

    COMPACTING --> RUNNING : verify_requested
    COMPACTING --> FAILED : task_failed

    VERIFYING --> COMPLETING : task_completed
    VERIFYING --> RUNNING : compact_needed
    VERIFYING --> FAILED : task_failed

    COMPLETING --> REAPED : agent_reaped

    FAILED --> REAPED : agent_reaped

    REAPED --> [*]

Agent Turn Transition Table (exhaustive)¶

Events Reference¶

Abort Chain Hierarchy¶

Agent aborts follow a three-level containment hierarchy:

TOOL  <  SIBLING  <  SESSION

Escalation between levels is opt-in via AbortPolicy. By default, each level contains its failure without propagating upward.