agentic-mobile-control/openspec/changes/cloud-console-governance/tasks.md

1. Preconditions and dependency reconciliation

• 1.1 Confirm cloud-planner-proxy is fully implemented, passes its strict validation and relevant runtime tests, and its deployed schema/API contract is the base for this change.
• 1.2 Complete and reconcile cloud-console-user-authentication, including the documented Console Users experience and its remaining PostgreSQL and HTTPS/Host-Agent verification tasks.
• 1.3 Rebase this change's delta specs against the then-current canonical platform-sdk, cloud-console-ui, cloud-planner-proxy, and agent-runtime specifications before implementation begins.

2. Governance domain, persistence, and migration

• 2.1 Define target-selector, user-submission-policy, Host-governance- policy, token-usage-event, and token-reservation domain models with non-secret representations and revision semantics.
• 2.2 Extend the Cloud repository port with transactional CRUD/query operations for policies, active Host capacity, budget reservations, settlement, expiry cleanup, and bounded usage summaries/events.
• 2.3 Add SQLAlchemy rows, indexes, conversion helpers, and concurrency- safe PostgreSQL/SQLite implementations for governance policies, usage events, reservations, and safe policy audits.
• 2.4 Add an Alembic forward/downgrade revision that preserves existing users, Hosts, devices, tasks, and attempts; advance schema readiness checks to the new head.
• 2.5 Add repository and migration tests for policy revisions, null versus empty allow-list semantics, active-task capacity, reservation races, settlement, expiry cleanup, audit redaction, and SQLite/PostgreSQL parity.

3. Targeted scheduling and public governance API

• 3.1 Extend task constraints, SDK request/response models, persistence serialization, status/list representations, and CloudClient for an optional Host/Device target; reject a Device without its Host.
• 3.2 Enforce target ownership/existence at public submission and filter scheduler candidates by target before strategy selection; keep an unavailable targeted task queued with no fallback assignment.
• 3.3 Add governance:read and governance:admin scopes and policy-aware public task authorization that combines tasks:submit with the authenticated human user's effective submission policy.
• 3.4 Add bounded, non-secret public governance routes and CloudClient methods for user policy, Host policy, Host AI-budget summaries, and paginated usage events; audit every policy mutation.
• 3.5 Add public API/SDK tests for targeted submission, target-policy denial, scope enforcement, status exposure, governance CRUD, and absence of secret fields in responses/audits.

4. Host policy synchronization and self-submission

• 4.1 Extend shared internal heartbeat request/response models with the Host's last policy revision and a revision-aware effective-policy reply.
• 4.2 Update Host heartbeat synchronization to persist only safe cached policy state and expose it through local status/history without adding an inbound Cloud connection.
• 4.3 Add the Host-scoped goal-only task-submission route and HostAgentClient method; derive Host targeting from authenticated credentials and validate any named local Device ownership.
• 4.4 Enforce the Host policy's self-submission and active-task limits in the Cloud service/scheduler, not only in Host-local code.
• 4.5 Add Cloud API and Host Agent tests for revision convergence, unchanged-policy replies, self-targeted task creation, foreign target rejection, disabled self-submission, and outbound-only compatibility.

5. Cloud-proxy usage metering and hard budget enforcement

• 5.1 Extend the dual-provider tool-calling result with optional non-secret provider usage fields while preserving AIPlanner's existing single-decision behavior and direct transport compatibility.
• 5.2 Extend planner-proxy request context and Host-Agent-local context binding so Cloud-proxied calls carry known task/attempt metadata without importing Host or Cloud concerns into runtime.
• 5.3 Add Cloud proxy preflight reservation, configured conservative per-call ceiling, provider invocation, actual-usage settlement, and bounded unknown-usage reservation expiry.
• 5.4 Record non-secret usage events and expose accurate used/reserved/remaining UTC-day budget summaries; explicitly report direct transport as unmetered.
• 5.5 Add provider-fake, repository concurrency, Cloud API, and Host Agent tests for usage parsing, over-budget rejection before provider invocation, concurrent reservations, settlement, timeout uncertainty, task-attempt attribution, and direct-transport labeling.

6. Cloud Console governance experience

• 6.1 Add task composer API bindings and a scope-aware Console form for goal/workflow submission, Host/Device target selection, and target/policy validation errors.
• 6.2 Complete or reconcile the admin Users view, then add user- submission-policy editing with safe refresh and conflict/error handling.
• 6.3 Add Host policy administration and AI-usage/budget views, including revision display, unmetered direct Hosts, and no rendering of prompts, screenshots, provider credentials, cookies, or lease secrets.
• 6.4 Add frontend tests for task composer scope/policy failures, governance navigation, policy mutations, usage rendering, unmetered status, CSRF writes, and retained session behavior on 403.

7. Documentation, verification, and rollout

• 7.1 Update deployment and Console documentation with the dependency order, migration/rollback sequence, policy semantics, Cloud transport prerequisite, budget reservation behavior, direct-host limitation, and safe administrator operations.
• 7.2 Run formatting, Ruff, compile checks, secret/redaction review, the complete non-integration workspace test suite, Cloud Console unit tests, type-check, and production build.
• 7.3 Run real PostgreSQL migration/concurrency coverage and a Compose HTTPS manual flow covering user restriction, targeted scheduling, Host policy delivery, Host self-submission, Cloud-proxy budget exhaustion, and a direct Host labelled unmetered.
• 7.4 Run openspec validate cloud-console-governance --strict and resolve all proposal, design, specification, and task validation errors.