## ADDED Requirements ### Requirement: Host identity is authenticated and bound to one host id The internal Host Agent API SHALL require a host-scoped bearer principal and SHALL reject any request that attempts to act for a `host_id` different from the authenticated principal's bound host. #### Scenario: Host authenticates as itself - **WHEN** a Host Agent presents valid credentials bound to its requested `host_id` - **THEN** the internal API authorizes permitted heartbeat, claim, renewal, and result operations #### Scenario: Host attempts to impersonate another host - **WHEN** valid credentials bound to host A are used on a request for host B - **THEN** the internal API rejects the request without reading or modifying host B's state ### Requirement: Host Agent synchronizes heartbeat and complete device snapshots The Host Agent SHALL periodically submit its complete local device snapshot to the control plane, and the control plane SHALL atomically refresh the host heartbeat and replace only that host's pooled-device records. #### Scenario: Host reports devices - **WHEN** a Host Agent submits a valid heartbeat containing its current devices - **THEN** the control plane updates the host's last-seen time and exposes the submitted devices through the aggregated pool #### Scenario: Host reports no devices - **WHEN** a previously populated host submits an empty device snapshot - **THEN** only that host's prior device records are removed while devices owned by other hosts remain unchanged ### Requirement: Host Agent receives work through outbound long-polling The Host Agent SHALL request assigned work for its own host through a configurable long-poll endpoint, and the control plane SHALL return at most one atomically claimable assignment per response or an empty timeout response. #### Scenario: Assigned work is available - **WHEN** a Host Agent long-polls and an unclaimed assignment exists for its host - **THEN** the control plane atomically transitions the assignment to dispatched and returns its task, device, attempt, lease, and execution payload #### Scenario: No work becomes available - **WHEN** no assignment for the host becomes available before the configured poll timeout - **THEN** the endpoint returns a normal empty response and the Host Agent may poll again with backoff ### Requirement: Active execution renews its lease The Host Agent SHALL renew the active assignment lease before expiry while execution continues, and SHALL treat loss or rejection of the lease as a stop condition for further planned actions where interruption is possible. #### Scenario: Lease renewal succeeds - **WHEN** the owning Host Agent renews an unexpired active lease - **THEN** the control plane extends its expiry without changing the task attempt or device assignment #### Scenario: Lease is stale or foreign - **WHEN** a Host Agent attempts to renew an expired, replaced, or differently owned lease - **THEN** the control plane returns a conflict and does not revive or alter the current attempt ### Requirement: Host execution composes existing Runtime and workflow runners The Host Agent SHALL execute goal assignments through the existing `TaskRunner` and workflow assignments through the existing `WorkflowRunner`, using its local `DeviceManager` and Runtime configuration rather than reimplementing execution behavior. #### Scenario: Execute a goal assignment - **WHEN** the Host Agent claims a goal-based assignment for a connected local device - **THEN** it runs a `Task` through the configured Runtime Planner/Executor loop and captures the terminal status and failure reason #### Scenario: Execute a workflow assignment - **WHEN** the Host Agent claims an assignment referencing an available workflow definition - **THEN** it invokes the existing workflow runner for the assigned device and captures the terminal workflow outcome ### Requirement: Terminal result reporting is idempotent The Host Agent SHALL report a terminal result using the task, attempt, and lease identifiers, and repeating the same report SHALL return the already recorded outcome without duplicating state transitions. #### Scenario: Report a successful result - **WHEN** the active lease owner reports successful completion - **THEN** the control plane marks the scheduled task done, releases the device reservation, and records the result metadata #### Scenario: Retry a result after response loss - **WHEN** the Host Agent repeats the identical terminal report for an already completed active lease - **THEN** the control plane returns the recorded terminal result without creating a new attempt or error #### Scenario: Stale attempt reports after requeue - **WHEN** an expired earlier attempt reports after a newer attempt has been created - **THEN** the control plane rejects the stale report and preserves the newer attempt's state ### Requirement: Host operation requires no inbound cloud connection The Host Agent SHALL perform synchronization, work retrieval, lease renewal, and result reporting using outbound requests only. #### Scenario: Host is behind NAT - **WHEN** the Host Agent can reach the control-plane URL but exposes no inbound listener - **THEN** it can register devices and execute cloud assignments through the complete protocol