agentic-mobile-control/openspec/changes/edge-host-enrollment/proposal.md

Why

Deploying a Device Host Agent currently requires an operator to pre-coordinate both host_id and every device_id with the Cloud Control Plane. This makes edge installation brittle and prevents a cloud-authoritative onboarding flow where a trusted control plane assigns stable identities after a host proves possession of a bootstrap credential.

What Changes

• Add an authenticated Host enrollment operation that consumes a configured one-time enrollment token and returns a cloud-generated host_id.
• Let the enrolling Host Agent generate its long-lived bearer secret locally, so retries remain idempotent without the control plane storing or returning plaintext credentials.
• Persist dynamically enrolled host credential digests in the cloud repository while retaining existing statically configured Host credentials for compatibility.
• Add an authenticated device enrollment operation that maps a host-scoped opaque local device reference to a cloud-generated device_id.
• Persist the cloud device mapping separately from transient heartbeat state and require heartbeat snapshots to use device IDs assigned to the authenticated host.
• Add Host Agent bootstrap and identity persistence so an edge installation can start with only the control-plane URL and an enrollment token, recover safely after response loss, and reuse assigned IDs after restart.
• Extend local device configuration with an optional cloud device mapping while keeping existing local Runtime device identifiers compatible.
• Update deployment configuration and operator documentation for enrollment-token provisioning, identity-state protection, migration, revocation, and static-credential fallback.

Capabilities

New Capabilities

• edge-host-enrollment: Secure, idempotent Host and device onboarding with cloud-assigned identities and edge-persisted credential/mapping state.

Modified Capabilities

• host-agent-protocol: Permit bootstrap enrollment before the normal authenticated heartbeat/claim protocol and require enrolled cloud device IDs in later Host Agent traffic.
• device-pool: Separate durable device enrollment identity from transient heartbeat state and accept only device identities assigned to the reporting host.
• cloud-control-plane: Persist dynamic Host credentials and enrollment records through the shared PostgreSQL/SQLite repository and schema migration contract.

Impact

• Cloud authentication, internal Host Agent API models/routes, repository protocol, SQLAlchemy models, migrations, and application composition.
• Device Host Agent configuration, startup/bootstrap client, local identity persistence, device configuration mapping, heartbeat construction, and assignment execution lookup.
• Environment variables, Compose wiring, deployment documentation, repository/HTTP/Host Agent tests, migration tests, and OpenSpec main capability contracts after archive.
• Existing deployments using CLOUD_HOST_CREDENTIALS_JSON with explicit HOST_AGENT_HOST_ID and HOST_AGENT_TOKEN remain supported during migration.