Module agent_lifecycle 

Pure lifecycle logic for the runtime-owned agent process record (ADR-142 §1).

No database, no I/O: state transitions and the spawn fingerprint are derived entirely from in-memory values. AgentState, TerminalReason, and AgentRecord live in khive_types (re-exported here) so khive-db and khive-pack-agent can share them without depending on khive-runtime.

Structs

AgentRecord

The runtime-owned agent process record (ADR-142 §1, “Persistent process record”).

IllegalTransition

A trigger that is not legal from the given state. Never raised for the ADR’s explicit no-op rows — those return Ok(Transition { changed: false, .. }) instead.

Transition

The outcome of a successful transition attempt, including no-ops.

Enums

AgentState

One of the four lifecycle states an agent process record can occupy.

TerminalReason

Why a record reached Terminal. Set exactly once, at the transition into Terminal.

Trigger

The event driving a lifecycle transition attempt. Distinct from the wire-level verbs (agent.spawn/agent.resume/agent.kill/agent.suspend/agent.observe): Dispatch, Activity, Complete, Fail, Abandon, and HostRestart are runtime-internal triggers that ADR-142’s table drives automatically rather than through a caller-issued verb. agent.spawn itself is not a Trigger — it creates a record rather than transitioning an existing one, so it is out of scope for this function (see the module-level tests).

Functions

apply_transition

Apply one lifecycle trigger to a record currently in from (with terminal_reason if from is already Terminal), per the transition table in ADR-142 §1.

spawn_fingerprint

Canonical digest of a spawn’s compared argument set (ADR-142 §1, “Persistent process record”): provider, task, provider_session_id, checkpoint_session_id, in that key order, absent optionals omitted entirely rather than written as null. idempotency_key is excluded — it is the replay lookup key, not compared content.