HITL Operator Workflow

This page walks through the operator experience of reviewing, approving, and denying override requests using the CLI and TUI.

CLI Commands

`kairos hitl serve`

Start the coordinator service.

kairos hitl serve --config coordinator.toml

`kairos hitl list`

List override requests, optionally filtered by status.

# All requests
kairos hitl list --url http://127.0.0.1:8787

# Pending only
kairos hitl list --url http://127.0.0.1:8787 --status pending

Flag	Default	Description
`--url`	`http://127.0.0.1:8787`	Coordinator URL
`--status`	All	Filter: `pending`, `approved`, `denied`, `expired`, `redeemed`

`kairos hitl get`

Retrieve full details for a specific override request.

kairos hitl get <coordinator-request-id> --url http://127.0.0.1:8787

Returns the complete request record including:

Original evaluationRequest and evaluationResponse
Sentinel summary (if submitted)
Current status and timestamps
Operator notes and token ID (if approved)

`kairos hitl approve`

Approve a pending request and receive a signed override token.

kairos hitl approve <coordinator-request-id> \
  --key-id operator-1 \
  --url http://127.0.0.1:8787 \
  --note "Approved for testing" \
  --ttl 300000

Flag	Default	Description
`--key-id`	Required	Authority key ID for signing
`--url`	`http://127.0.0.1:8787`	Coordinator URL
`--note`	None	Operator justification (recorded in audit log)
`--ttl`	Config default	Token TTL in milliseconds

Outputs the signed OverrideTokenEnvelope JSON to stdout. This can be piped or redirected:

kairos hitl approve <id> --key-id operator-1 > token.json

`kairos hitl deny`

Deny a pending request.

kairos hitl deny <coordinator-request-id> \
  --key-id operator-1 \
  --url http://127.0.0.1:8787 \
  --note "Insufficient justification"

TUI Operator Mode

The kairos observe dashboard includes an integrated HITL operator panel when launched with --hitl:

kairos observe \
  --scenario axelrod-tournament \
  --artifact artifact.json \
  --policy policy.json \
  --hitl \
  --coordinator-url http://127.0.0.1:8787 \
  --operator-key-id operator-1

HITL Panel Features

Lists pending override requests from the coordinator
Background polling every 3 seconds
Telemetry focus follows the selected request’s actor
Connection status indicator
Approve/deny with confirmation dialogs

HITL Keyboard Shortcuts

Key	Action
`Up` / `Down`	Navigate the request list
`Enter`	Toggle detail view for selected request
`A`	Approve selected request (opens confirmation)
`D`	Deny selected request (opens confirmation)
`R`	Force refresh from coordinator
`Y`	Confirm action (in confirmation dialog)
`N` / `Esc`	Cancel action (in confirmation dialog)

In HITL mode, actor tab selection is disabled — the telemetry view automatically follows the actor associated with the selected override request.

End-to-End Walkthrough

A complete override flow from escalation to redemption:

1. Escalation Triggers

During fly-by-wire evaluation, the Substrate runtime detects a condition that requires human attention (gamma below floor, action gate fired) and produces an evaluation response with escalationType: HUMAN_ESCALATION.

2. Submit Override Request

The override request is submitted to the coordinator — either automatically by the TUI or manually via REST:

curl -X POST http://127.0.0.1:8787/v1/override-requests \
  -H "Content-Type: application/json" \
  -d '{
    "evaluationRequest": {
      "envelopeVersion": 1,
      "requestId": "req-1",
      "snapshot": {
        "timestamp": "2026-03-21T12:00:00Z",
        "metrics": {
          "capabilityIndex": 42.0,
          "alignmentScore": 85.0
        }
      },
      "actorId": "agent-1"
    },
    "evaluationResponse": {
      "envelopeVersion": 1,
      "requestId": "req-1",
      "decision": "REJECT_STATE",
      "reasonCode": "GAMMA_BELOW_FLOOR",
      "mode": "state_gate",
      "policyVersion": 1,
      "adapterVersion": 1,
      "escalation": {
        "escalationType": "HUMAN_ESCALATION",
        "gammaHeadroom": 0.05,
        "stepsToBreach": 2.5
      }
    },
    "licenseId": "lic_test_001",
    "actorId": "agent-1"
  }'

Response:

{"coordinatorRequestId": "550e8400-e29b-41d4-a716-446655440000"}

3. Review Pending Requests

kairos hitl list --status pending

The operator reviews the request details, including the Sentinel assessment if available:

kairos hitl get 550e8400-e29b-41d4-a716-446655440000

4. Approve and Receive Token

kairos hitl approve 550e8400-e29b-41d4-a716-446655440000 \
  --key-id operator-1 \
  --note "Reviewed: headroom is low but trajectory is stabilizing" \
  > token.json

The token is a signed OverrideTokenEnvelope ready for use.

5. Attach Token to Request

Add the token to the original evaluation request:

jq '.overrideToken = input' original-request.json token.json > request-with-override.json

6. Evaluate with Override

kairos evaluate \
  --config artifact.json \
  --policy policy.json \
  --license license.key \
  --coordinator-url http://127.0.0.1:8787 \
  --request request-with-override.json

If the token is valid:

decision changes from REJECT_STATE to PASS
reasonCode changes to NONE
overrideOutcome.status is Applied
The token is marked as redeemed in the coordinator

7. Verify Single-Use

Attempting the same evaluation again with the same token:

kairos evaluate \
  --config artifact.json \
  --policy policy.json \
  --license license.key \
  --coordinator-url http://127.0.0.1:8787 \
  --request request-with-override.json

The original rejection is preserved:

decision remains REJECT_STATE
overrideOutcome.status is Rejected
overrideOutcome.failureReason is ReplayDetected

Sentinel Integration

When submitting override requests, the Sentinel telemetry feed and summary can be included to give operators additional context:

{
  "evaluationRequest": { ... },
  "evaluationResponse": { ... },
  "licenseId": "lic_test_001",
  "actorId": "agent-1",
  "sentinelFeed": {
    "escalationContext": { ... },
    "historicalWindow": [ ... ],
    "gammaFloor": 0.2,
    "gammaAtEscalation": 0.25
  },
  "sentinelSummary": {
    "narrative": "System stability is deteriorating rapidly...",
    "riskLevel": "CRITICAL",
    "highlights": [ ... ]
  }
}

The TUI operator panel displays this Sentinel assessment alongside the raw telemetry when the --sentinel flag is also enabled.