Human Interaction Challenges

A Human Interaction Challenge is temporary, resumable, operator-bound input needed to continue an already-understood governed goal. It grants no capability, approval, identity, or execution authority and is not a second workflow engine.

The first consumer is Earthshaker Apple TV Companion pairing. Earthshaker owns the durable non-secret challenge and immutable playback continuation. A small transport-neutral runtime adapter exposes that same challenge to Luna and to an authenticated temporary Web surface. Conversation and Web submissions both call the same pairing coordinator; the Web transport never owns or duplicates the continuation.

Safe challenge contract

Operator-visible state contains an opaque challenge ID, challenge type, place/entity, current state, creation and expiry, expected input schema, safe instructions, continuation reference, and temporary Web path. It does not contain the PIN, credentials, authority, or unnecessary conversation text.

The Web path is not a bearer credential. It requires an existing canonical AncientOS Web session bound to the same principal as the challenge. POST also requires the session-bound CSRF value. A context-only challenge without a canonical principal remains conversational-only. Completion, cancellation, or expiry prevents reuse; retry starts a fresh live protocol attempt and TV code while preserving the bounded higher-level continuation.

Input and continuation semantics

The four-digit value is delivered directly to the process-local pyatv session. It is cleared from the mobile form immediately and is never placed in a URL, SQLite challenge record, Kernel Record, Zeus evidence, session history, report, or credential file. Pairing credentials are written only after verified pairing to the existing off-git owner-only credential path.

Successful input resumes the original play_available_title continuation. Earthshaker revalidates exact Basement authority, stable physical identity, readiness, and observed playback. Pairing success and HTTP dispatch are not playback success; only matching observed state allows Luna to claim playback.

The page is a bounded interaction view, not a generic form system. It is private, no-store, mobile-friendly, protected from framing/referrer leakage, and limited to PIN, retry, and cancel actions for the exact challenge.

Recoverable pairing states (pairing_required, awaiting_pin, pairing, awaiting_retry, expired, failed) keep blocker_type = human_interaction_required. Terminal states (paired, cancelled) do not remain actionable. An expired live protocol attempt is not a successful continuation; retry starts a fresh TV code while the original playback continuation remains eligible for revalidation.