feat(cloud): add targeted task governance foundation

openspec/changes/cloud-console-governance/tasks.md

@@ -0,0 +1,113 @@
+## 1. Preconditions and dependency reconciliation
+
+- [x] 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
+
+- [x] 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.
+- [x] 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.
+- [x] 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
+
+- [x] 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.
+- [x] 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
+
+- [x] 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
+
+- [x] 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.
+- [x] 7.4 Run `openspec validate cloud-console-governance --strict` and resolve
+      all proposal, design, specification, and task validation errors.