feat: auto-deploy guided servers on run registration

2026-07-28 16:57:09 +08:00
parent e2d0bc0595
commit 7f64765c1c
15 changed files with 191 additions and 55 deletions
@@ -0,0 +1,20 @@
+## Decision
+
+The Platform owns the desired deployment definition. A successful, component-authenticated hello from the reserved dedicated Run endpoint is the trigger to enqueue the first guided installation. The enqueue uses a stable idempotency key derived from the server and deployment revision, so reconnects cannot duplicate work.
+
+The automatic path is restricted to target-bound `guided-install` servers in `draft`. Existing-server and custom-command modes remain explicit because a missing directory can be intentional or user-owned. A future reconcile capability may safely repair guided deployments after an attested drift check; it must not be simulated by blindly reinstalling on every hello.
+
+## Flow
+
+1. Create stores a target-bound draft and protected guided definition.
+2. The user generates, downloads, and starts the dedicated Run.
+3. Platform validates and persists the component hello/session.
+4. Platform atomically advances the draft to installing and creates one `process.install` job.
+5. Run claims the job through the existing job channel.
+
+## Boundaries
+
+- No host path, command, credential, or socket is returned to Platform Web or plugins.
+- A running server is never overwritten by this registration trigger.
+- Failed jobs use the existing bounded retry policy; reconnects do not create unbounded retries.
+- The former deploy endpoint may remain for compatibility, but is not part of the normal user journey.