Human-in-the-Loop Override
Fly-by-Wire rejects actions that fail the gate chain. Most of the time, this is the correct outcome — the system is enforcing a physics-derived safety boundary. Occasionally, a human operator has context the system does not. The Human-in-the-Loop (HITL) override protocol provides a controlled path for that human judgment to enter the system.
When HITL Activates
Section titled “When HITL Activates”HITL activates when the evaluation pipeline produces a HUMAN_ESCALATION directive. This happens when gamma headroom drops below the critical threshold (less than 0.1 with an active warning) — meaning the system is very close to the stability floor and autonomous recovery is unlikely.
The integrating system receives the escalation directive and submits the evaluation to the HITL coordinator for operator review. The Sentinel provides a narrative assessment to give the operator context.
What Can Be Overridden
Section titled “What Can Be Overridden”Two decision types accept operator overrides:
| Decision | When it fires | Why it is overrideable |
|---|---|---|
REJECT_STATE | Gamma fell below the configured floor | The floor is a threshold judgment — a human may assess that the specific situation is acceptable despite low gamma |
REJECT_ACTION | Action preview showed unsafe outcome | The preview is a predictive judgment — a human may have context about the action that changes the risk assessment |
Both represent situations where the system’s quantitative assessment may be legitimately overridden by human judgment. The gamma floor is a configured threshold, not a physical law. The action preview is a prediction, not a certainty.
What Cannot Be Overridden
Section titled “What Cannot Be Overridden”Two decision types are absolute:
| Decision | Why it is non-overrideable |
|---|---|
REJECT_BASIN_COLLAPSE | The simulation shows total future collapse — every forward branch leads to a loss event. No amount of human context changes the topology. |
REJECT_PARADOX | Two actors have created a mutually exclusive state. This is a structural invariant violation that requires policy resolution, not a judgment call. |
Basin collapse and paradox represent broken physics. An operator approving an action into a collapsed basin does not make the basin un-collapsed. These boundaries are enforced unconditionally.
The Override Lifecycle
Section titled “The Override Lifecycle”A complete override flows through six stages:
1. Escalation. The evaluation pipeline rejects an action and produces a HUMAN_ESCALATION directive. The integrating system receives the evaluation response with the escalation details.
2. Submission. The integrating system submits the original evaluation request and response to the HITL Coordinator — a standalone service that manages override requests. If Sentinel is enabled, the telemetry feed and narrative are included.
3. Operator review. The operator sees the pending request in the TUI dashboard or via the CLI. The Sentinel assessment provides narrative context. The operator reviews the situation and decides to approve or deny.
4. Token issuance. If the operator approves, the Coordinator signs a cryptographic override token bound to the exact evaluation request. The token contains: a unique ID, the operator’s identity, a SHA-256 hash of the original request, the policy version, a time-to-live, and the operator’s justification.
5. Retry. The integrating system re-submits the original evaluation request with the override token attached. The evaluation pipeline runs the full gate chain again. If the token passes verification, the original rejection is converted to PASS.
6. Verification. The pipeline verifies the token through two stages. First, local verification checks the cryptographic signature, request binding, time bounds, policy version, and license match. Second, the Coordinator confirms the token has not already been redeemed (single-use enforcement).
If any verification step fails, the original rejection stands. The system is fail-closed at every stage.
The Coordinator
Section titled “The Coordinator”The HITL Coordinator is a lightweight control-plane service that manages the approval workflow. It runs as a standalone process (kairos hitl serve) backed by SQLite.
The Coordinator handles:
- Request tracking — accepting override submissions, persisting them with status (PENDING, APPROVED, DENIED, EXPIRED, REDEEMED), and managing the lifecycle
- Token signing — generating RSA-PSS signed override tokens with all binding claims
- Single-use enforcement — tracking which tokens have been redeemed via an atomic database update. A token that has already been used is rejected with
REPLAY_DETECTED - Operator load protection — when adaptive escalation is enabled, the Coordinator deduplicates pending requests by intent, enforces cooldown periods after denials, and requires material changes before re-escalation
Requests that are not acted on within the configured TTL expire automatically.
For the full Coordinator configuration, REST API, and database schema, see the HITL Coordinator technical reference.
The Operator Experience
Section titled “The Operator Experience”Operators interact with HITL through two interfaces:
The kairos hitl commands provide direct access to the Coordinator:
| Command | Action |
|---|---|
kairos hitl list | List override requests, optionally filtered by status |
kairos hitl get <id> | Retrieve full details for a specific request |
kairos hitl approve <id> | Approve and receive a signed token |
kairos hitl deny <id> | Deny the request |
The approve command outputs the signed token to stdout, which can be piped or redirected to a file for use in the retry request.
TUI Dashboard
Section titled “TUI Dashboard”The kairos observe dashboard includes an integrated HITL panel when launched with --hitl. The panel lists pending override requests with background polling, provides keyboard-driven approve/deny with confirmation dialogs, and automatically focuses the telemetry view on the actor associated with the selected request.
The Sentinel narrative appears alongside the raw telemetry, giving operators both quantitative and contextual information for their decision.
Single-Use Tokens
Section titled “Single-Use Tokens”Every override token is single-use. Once redeemed, it cannot be used again. Four independent mechanisms enforce this:
- Request binding — the token contains a SHA-256 hash of the specific evaluation request. A different request produces a different hash, and the token fails verification.
- Time binding — the token has a configurable TTL. Expired tokens are rejected.
- Coordinator redemption — the Coordinator performs an atomic database update on redemption. A second redemption attempt finds the token already consumed.
- In-session guard — the SubstrateSession maintains an in-memory set of redeemed token IDs as a best-effort supplement to the Coordinator.
The Coordinator is the authoritative source. The in-session guard does not survive process restarts and is not a primary defense.
For the full token structure, RSA-PSS signing details, canonical request hashing algorithm, and verification chain, see the HITL Override Protocol technical reference.