agentic-mobile-control/openspec/changes/host-agent-local-console/specs/host-agent-local-console/spec.md

ADDED Requirements

Requirement: The local console starts with every Host Agent and is loopback-bound by default

The Host Agent SHALL start its local web console listener on every process start and SHALL bind that listener to a loopback address unless a separate, explicit configuration setting authorizes a non-loopback bind address.

Scenario: Default configuration starts a loopback console

• WHEN the Host Agent starts with no console-related configuration set
• THEN the local web console listener starts on 127.0.0.1:8765 and existing heartbeat/claim behavior continues alongside it

Scenario: Non-loopback bind requested without opt-in

• WHEN the console is configured to bind a non-loopback address without the separate non-loopback opt-in setting
• THEN the Host Agent fails configuration loading with a clear error and does not start

Scenario: Non-loopback bind requested with explicit opt-in

• WHEN the console is configured to bind a non-loopback address and the non-loopback opt-in setting is also set
• THEN the console listener binds to the configured address

Requirement: Console authentication reuses the existing local account

The local web console SHALL authenticate operators against the same local account credential used by the Host Agent's setup command, and SHALL NOT introduce a separate credential store.

Scenario: No local account exists

• WHEN the Console starts and no local account file is present
• THEN the console's login page reports that no account exists and directs the operator to run the setup command, without accepting any login attempt

Scenario: Valid login

• WHEN an operator submits the correct local account username and password to the console
• THEN the console establishes an authenticated session and grants access to console pages

Scenario: Invalid login

• WHEN an operator submits an incorrect password to the console
• THEN the console rejects the attempt without revealing whether the username or password was wrong and does not establish a session

Scenario: Unauthenticated access to a console page

• WHEN a request without a valid session reaches any console page other than the login page
• THEN the console redirects the request to the login page without exposing any status or device data

Requirement: Console sessions are cookie-based, session-scoped, and CSRF-protected

The console SHALL issue an opaque session token on successful login, SHALL require a valid, unexpired session for all non-login requests, and SHALL require a session-bound CSRF token on every state-changing request.

Scenario: Session expires

• WHEN a console session has been idle longer than the configured session timeout
• THEN subsequent requests using that session are treated as unauthenticated and redirected to login

Scenario: Mutating request without CSRF token

• WHEN an authenticated session submits a device change, password change, or logout request without a valid CSRF token
• THEN the console rejects the request and makes no change

Scenario: Process restart invalidates sessions

• WHEN the Host Agent process restarts while the Console is running
• THEN previously issued session tokens are no longer accepted and operators must log in again

Requirement: Console displays current heartbeat, enrollment, device, and assignment status

The console SHALL present, on an authenticated status page, the most recent heartbeat outcome, the current enrollment/identity state, the list of locally registered devices with their status, the in-progress assignment (if any) and its execution status, and the effective control-plane configuration with credential values never rendered.

Scenario: Status page reflects current state

• WHEN an operator loads the authenticated status page
• THEN it shows the last heartbeat time and outcome, enrollment/host identity state, each registered device and its status, and whether an assignment is currently executing

Scenario: Credentials are never rendered

• WHEN the status page renders the effective control-plane configuration
• THEN the host token, local account password, and any other credential value are omitted or masked, never shown in full

Scenario: Status page refreshes without a full reload

• WHEN an operator keeps the status page open
• THEN the page periodically fetches updated status fragments and updates the displayed heartbeat/assignment state without a full page navigation

Requirement: Console supports adding, editing, and removing local devices

The console SHALL allow an authenticated operator to add, edit, and remove locally registered device entries, and each change SHALL take effect on the running Host Agent immediately, without requiring a process restart.

Scenario: Add a device

• WHEN an operator submits a new device's driver type and connection info through the console
• THEN the device is persisted to local device configuration and becomes immediately available to the running Host Agent, including cloud enrollment when the Host is enrollment-managed

Scenario: Edit a device

• WHEN an operator updates an existing device's connection info through the console
• THEN the persisted configuration and the running Host Agent's device registration both reflect the update without a restart

Scenario: Remove a device

• WHEN an operator removes a device through the console
• THEN the device is deleted from local device configuration and unregistered from the running Host Agent immediately

Requirement: Console supports changing the local account password

The console SHALL allow an authenticated operator to change the local account password after re-confirming the current password, and SHALL NOT allow creating the first local account through the web console.

Scenario: Successful password change

• WHEN an operator submits the correct current password along with a new password and confirmation
• THEN the local account credential is updated and future console logins require the new password

Scenario: Incorrect current password

• WHEN an operator submits an incorrect current password while attempting to change it
• THEN the console rejects the change and the existing credential remains valid

Scenario: No console path to create the first account

• WHEN no local account exists
• THEN the console offers no form to create one, and only the Host Agent's setup command can create it

Requirement: Console shows a bounded local history of recent assignments and heartbeats

The Host Agent SHALL retain a bounded, local-only history of recent assignment outcomes and heartbeat syncs, and the console SHALL display this history to an authenticated operator, independent of whether the Cloud Console is reachable.

Scenario: Assignment outcome recorded

• WHEN the Host Agent reports a terminal assignment result to the control plane
• THEN a corresponding entry recording the outcome is added to the local history and becomes visible on the console's history page

Scenario: Heartbeat recorded

• WHEN the Host Agent completes a heartbeat sync
• THEN a corresponding entry is added to the local history

Scenario: History is bounded

• WHEN the number of recorded history entries exceeds the configured retention limit
• THEN the oldest entries are pruned so the stored history does not grow unbounded