## 1. Preconditions And Application Members

- [x] 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.
- [x] 1.2 Add `apps/cloud-api` as the `device-cloud-api` workspace project with an app factory and CLI/server entry point.
- [x] 1.3 Add `apps/device-host-agent` as the `device-host-agent` workspace project with a CLI entry point and explicit Runtime/cloud dependencies.
- [x] 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

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

## 3. Lease-Backed Scheduling

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

## 4. Authentication And Authorization

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

## 5. Host Agent Internal API

- [x] 5.1 Add versioned `/internal/v1` request/response models for heartbeat snapshots, long-poll claim, lease renewal, and terminal result reporting.
- [x] 5.2 Add atomic heartbeat/snapshot validation and device ownership-conflict handling before delegating to `DevicePool`.
- [x] 5.3 Add long-poll assignment delivery that returns at most one claimed task and produces a normal empty timeout response.
- [x] 5.4 Add lease-renewal and idempotent terminal-result endpoints with typed stale-lease conflicts.
- [x] 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

- [x] 6.1 Compose repository, pool, scheduler, plugin registry, public router, internal router, and auth providers in the cloud app factory.
- [x] 6.2 Implement FastAPI lifespan startup/shutdown for configuration validation, database checks, scheduler loop, and lease-reaper loop.
- [x] 6.3 Ensure lifecycle iteration failures are logged and retried without terminating later iterations.
- [x] 6.4 Add `/health/live` and `/health/ready` with separate process, database/schema, and worker-state semantics.
- [x] 6.5 Add structured correlation-aware logging for requests and task lifecycle events with sensitive payload redaction.
- [x] 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

- [x] 7.1 Implement an authenticated Host Agent client for heartbeat, long-poll claim, renewal, and result operations with bounded retry/backoff.
- [x] 7.2 Build complete device snapshots from the local `DeviceManager` and synchronize them at the configured interval.
- [x] 7.3 Compose local `TaskRunner` and `WorkflowRunner` factories without importing cloud concerns into Runtime-owned packages.
- [x] 7.4 Execute goal assignments through the configured Runtime Planner/Executor and workflow assignments through the existing workflow runner.
- [x] 7.5 Run lease renewal alongside active execution and stop further interruptible actions after confirmed lease loss.
- [x] 7.6 Normalize and report successful/failed terminal outcomes, including Runtime failure reasons, with idempotent retries after response loss.
- [x] 7.7 Implement graceful shutdown that stops polling, finishes or interrupts current work according to lease policy, and performs a final heartbeat when possible.
- [x] 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

- [x] 8.1 Extend public task status models/routes with attempt count, lease expiry metadata, and terminal failure details without exposing lease credentials.
- [x] 8.2 Add bearer authentication and typed authorization errors to `CloudClient` while preserving injectable HTTP clients for tests.
- [x] 8.3 Add container definitions and example environment configuration for the cloud API, PostgreSQL, and Host Agent without committing secrets.
- [x] 8.4 Document local SQLite startup, deployed PostgreSQL migration/startup, credential/scopes setup, Runtime AI Planner configuration, and shutdown/rollback procedures.
- [x] 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

- [x] 9.1 Run formatting, static checks, all non-integration tests, and targeted PostgreSQL integration/concurrency tests.
- [x] 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.
- [x] 9.3 Verify existing local REST/MCP/console behavior and dependency-boundary tests remain unchanged.
- [x] 9.4 Run OpenSpec validation for `cloud-control-plane-integration` and map automated tests to every new or modified scenario.
- [x] 9.5 Update the project index, architecture/deployment documentation, and runtime maturity memory after implementation verification.