docs(cloud): state deployment limitations

docs/CLOUD_DEPLOYMENT.md

@@ -109,6 +109,27 @@ For OpenAI, set `AI_PLANNER_PROVIDER=openai`, choose the deployed model through
 `AI_PLANNER_MODEL`, and provide `OPENAI_API_KEY`. Provider credentials belong
 only on the Host Agent; the Cloud API does not need them.
 
+## Operational Limitations
+
+Run exactly one scheduler-enabled Cloud API process. SQLite supports only the
+documented single-control-plane development mode. PostgreSQL row locking makes
+assignment and claim transactions safe if requests overlap, but this release
+does not implement scheduler leader election or claim active-active scheduler
+operation. Starting multiple Cloud API replicas would start one scheduler loop
+per replica and is outside the supported deployment topology.
+
+Device execution provides at-least-once side-effect semantics, not exactly-once
+semantics. A device action can succeed immediately before the Host Agent loses
+its lease or its result response, after which the control plane may retry the
+task. Lease renewal and cooperative stop checks prevent later interruptible
+actions where possible, but they cannot roll back an action already sent to a
+device or safely terminate an in-progress synchronous driver call.
+
+Use bounded attempts, inspect task attempt and failure metadata, and design
+device workflows to tolerate repeated actions when the target operation allows
+it. Do not use this release for operations that require a transactional
+exactly-once guarantee across the cloud database and an external device.
+
 ## Shutdown And Rollback
 
 For a normal shutdown, stop Host Agents first so they stop polling, interrupt

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

@@ -67,7 +67,7 @@
 - [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.
-- [ ] 8.5 Document the single scheduler-enabled control-plane limitation and the at-least-once device-side-effect trade-off.
+- [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