agentic-mobile-control/openspec/changes/cloud-control-plane-integration/tasks.md

1. Preconditions And Application Members

• 1.1 Complete and verify every task in uv-workspace-packaging before changing cloud behavior.
  • Verified 17/17 tasks complete, strict OpenSpec validation passed, and the shared lockfile is current.
• 1.2 Add apps/cloud-api as the device-cloud-api workspace project with an app factory and CLI/server entry point.
• 1.3 Add apps/device-host-agent as the device-host-agent workspace project with a CLI entry point and explicit Runtime/cloud dependencies.
• 1.4 Add configuration models that validate environment, database URL, scheduler intervals, lease durations, retry limits, poll settings, host identity, and insecure-development overrides.

2. Repository Contract And Migrations

• 2.1 Define the cloud repository contract for hosts, device snapshots, plugins, tasks, attempts, leases, reservations, and transactional assignment operations.
• 2.2 Implement SQLAlchemy models and a repository adapter that preserves existing CloudStore observable behavior.
• 2.3 Add PostgreSQL and SQLite database URL support with engine/session lifecycle owned by the cloud application.
• 2.4 Add Alembic configuration and a baseline migration that preserves existing host, device, task, and plugin data while adding lease/attempt/result fields.
• 2.5 Add forward/downgrade migration tests and schema-version readiness checks.
• 2.6 Run repository contract tests against SQLite and PostgreSQL, including rollback and process-restart cases.

3. Lease-Backed Scheduling

• 3.1 Extend scheduled-task persistence with attempt count, lease id/expiry, terminal result, failure reason, and auditable attempt records.
• 3.2 Implement atomic queued-task assignment and device reservation while excluding devices with active assignments even when snapshots report idle.
• 3.3 Implement owning-host claim that atomically transitions one assigned attempt to dispatched under its active lease.
• 3.4 Implement lease renewal with host/task/attempt ownership validation and conflict responses for stale leases.
• 3.5 Implement idempotent terminal result recording and reservation release for active leases.
• 3.6 Implement expired-lease requeue/failure behavior with bounded attempts and preserved attempt history.
• 3.7 Add PostgreSQL concurrency tests proving one assignment/claim winner and SQLite tests documenting single-control-plane behavior.

4. Authentication And Authorization

• 4.1 Extend authenticated principals with scopes and implement constant-time configured bearer-token verification without logging credentials.
• 4.2 Add public scopes for task submission/read, pool read, plugin read, and plugin administration and enforce them on every /v1 route.
• 4.3 Add host principals bound to one host_id and reject cross-host heartbeat, claim, renewal, or result operations.
• 4.4 Make missing production credentials a startup/readiness failure and permit anonymous mode only through the explicit non-production override.
• 4.5 Add authentication tests covering invalid tokens, missing scopes, host impersonation, plugin administration, and secret redaction.

5. Host Agent Internal API

• 5.1 Add versioned /internal/v1 request/response models for heartbeat snapshots, long-poll claim, lease renewal, and terminal result reporting.
• 5.2 Add atomic heartbeat/snapshot validation and device ownership-conflict handling before delegating to DevicePool.
• 5.3 Add long-poll assignment delivery that returns at most one claimed task and produces a normal empty timeout response.
• 5.4 Add lease-renewal and idempotent terminal-result endpoints with typed stale-lease conflicts.
• 5.5 Add internal API integration tests for multi-host isolation, duplicate device ids, timeout behavior, stale attempts, and repeated result reports.

6. Cloud Control Plane Composition

• 6.1 Compose repository, pool, scheduler, plugin registry, public router, internal router, and auth providers in the cloud app factory.
• 6.2 Implement FastAPI lifespan startup/shutdown for configuration validation, database checks, scheduler loop, and lease-reaper loop.
• 6.3 Ensure lifecycle iteration failures are logged and retried without terminating later iterations.
• 6.4 Add /health/live and /health/ready with separate process, database/schema, and worker-state semantics.
• 6.5 Add structured correlation-aware logging for requests and task lifecycle events with sensitive payload redaction.
• 6.6 Add app-level tests for startup failures, readiness transitions, graceful shutdown, persisted queue recovery, and expired-lease recovery.

7. Device Host Agent Execution Loop

• 7.1 Implement an authenticated Host Agent client for heartbeat, long-poll claim, renewal, and result operations with bounded retry/backoff.
• 7.2 Build complete device snapshots from the local DeviceManager and synchronize them at the configured interval.
• 7.3 Compose local TaskRunner and WorkflowRunner factories without importing cloud concerns into Runtime-owned packages.
• 7.4 Execute goal assignments through the configured Runtime Planner/Executor and workflow assignments through the existing workflow runner.
• 7.5 Run lease renewal alongside active execution and stop further interruptible actions after confirmed lease loss.
• 7.6 Normalize and report successful/failed terminal outcomes, including Runtime failure reasons, with idempotent retries after response loss.
• 7.7 Implement graceful shutdown that stops polling, finishes or interrupts current work according to lease policy, and performs a final heartbeat when possible.
• 7.8 Add fake-driver end-to-end tests for one host, multiple hosts, NAT-style outbound-only operation, control-plane restart, Host Agent restart, and lease loss.

8. Public SDK And Operational Delivery

• 8.1 Extend public task status models/routes with attempt count, lease expiry metadata, and terminal failure details without exposing lease credentials.
• 8.2 Add bearer authentication and typed authorization errors to CloudClient while preserving injectable HTTP clients for tests.
• 8.3 Add container definitions and example environment configuration for the cloud API, PostgreSQL, and Host Agent without committing secrets.
• 8.4 Document local SQLite startup, deployed PostgreSQL migration/startup, credential/scopes setup, Runtime AI Planner configuration, and shutdown/rollback procedures.
• 8.5 Document the single scheduler-enabled control-plane limitation and the at-least-once device-side-effect trade-off.

9. Verification And Project Records

• 9.1 Run formatting, static checks, all non-integration tests, and targeted PostgreSQL integration/concurrency tests.
• 9.2 Run an end-to-end cloud submission through a Host Agent and fake device until the public SDK reports done and a failure case until it reports failed.
• 9.3 Verify existing local REST/MCP/console behavior and dependency-boundary tests remain unchanged.
• 9.4 Run OpenSpec validation for cloud-control-plane-integration and map automated tests to every new or modified scenario.
• 9.5 Update the project index, architecture/deployment documentation, and runtime maturity memory after implementation verification.