Fix cli remote protocol gaps

.changeset/remote-cli-commands.md

@@ -0,0 +1,10 @@
+---
+"migrate-sdk": patch
+---
+
+Support every server-backed CLI command through `--server`, including registry
+listing, dependency graphs, status, messages, and lock recovery. Remote HTTP
+authentication failures now report 401 and 403 permission errors with a token
+configuration hint. Finalize the pre-adoption Migrate Protocol v1 baseline with
+static registry metadata and canonical selection-based status and message
+reports; servers from the earlier incomplete v1 draft must be redeployed.

README.md

@@ -88,6 +88,18 @@ pnpm exec migrate rollback articles --plan
 pnpm exec migrate rollback articles
 ```
 
+The same server-backed commands can target a remote Migrate Server without a
+local migration configuration:
+
+```sh
+MIGRATE_SERVER_TOKEN=secret pnpm exec migrate \
+  --server https://migrate.example.com/api/migrate \
+  list
+```
+
+Remote mode supports `list`, `graph`, `status`, `messages`, `unlock`, `run`,
+`rollback`, and `runs`. Migration Store schema administration remains local.
+
 ## Full and incremental source discovery
 
 Sources default to full discovery. Cursors let interrupted runs resume, but a

docs/adr/0007-server-boundary-for-local-and-remote-clients.md

@@ -79,6 +79,13 @@ the Effect RPC encoding incompatibly requires a new protocol version. An
 additive wire change may remain in the current protocol only when cross-version
 contract tests demonstrate compatibility in both client/server directions.
 
+Protocol v1 is finalized before external adoption by including the complete CLI
+inspection surface described below. Earlier `0.8.0` development deployments
+that advertised the incomplete v1 draft must be redeployed with the corrected
+server before using the new remote CLI inspection commands. This is a one-time
+baseline correction, not precedent for adding required operations to an adopted
+protocol version. Existing TUI operations and payloads remain unchanged.
+
 The currently implemented local connection uses a Node Migrate Server process
 started by the TUI. The Bun renderer communicates with that process over a
 reconnectable local Effect RPC socket, while the Node process loads the same
@@ -265,20 +272,35 @@ infrastructure-only commands may remain outside that interface.
 The CLI adopts that seam incrementally through a shared Node Migrate Connection
 owned by Migrate SDK rather than by the TUI package. Both clients use the same
 local socket or remote HTTPS connection, version checks, authentication header,
-and logical `MigrateClient`; renderer concerns remain in the TUI. The first CLI
-surface over this connection is run lifecycle management:
-
+and logical `MigrateClient`; renderer concerns remain in the TUI. CLI surfaces
+over this connection include registry inspection, migration control, and run
+lifecycle management:
+
+- `migrate list` lists registered Migration Definitions.
+- `migrate graph` renders Migration Definition dependencies.
+- `migrate status` and `migrate messages` inspect durable server state.
+- `migrate unlock` requests a lock break through the server.
+- `migrate run` and `migrate rollback` plan and start operations.
 - `migrate runs list` discovers active Migration Runs.
 - `migrate runs observe <run-id>` observes one run until it is terminal or the
   caller detaches.
 - `migrate runs stop <run-id>` explicitly requests durable cooperative
   cancellation.
 
-`migrate list` continues to mean registered Migration Definitions. Remote CLI
-commands accept a Migrate Server URL and read its bearer token from
-`MIGRATE_SERVER_TOKEN`; secrets are not accepted as command-line flags. Local
-commands discover the local migration configuration and connect to the same
-reconnectable Node Migrate Server used by the TUI.
+`GetRegistry` returns static registry entries and groups without reading
+Migration Stores. `GetRegistryStatus` and `GetRegistryMessages` accept the same
+selection and dependency-expansion inputs as their local registry operations;
+the server performs selection validation, source-scan concurrency, dependency
+deduplication, and global message ordering authoritatively. Clients render
+those canonical reports rather than reconstructing them from dashboard rows or
+per-definition requests.
+
+Remote CLI commands accept a Migrate Server URL and read its bearer token from
+`MIGRATE_SERVER_TOKEN`; secrets are not accepted as command-line flags. Store
+schema commands remain local infrastructure operations because the Migrate
+Protocol does not expose Migration Store administration. Local commands
+discover the local migration configuration and may continue using direct SDK
+services while the shared server seam is adopted incrementally.
 
 While observing in an interactive terminal, the first Ctrl+C offers three
 distinct choices: detach the observation, stop safely and keep observing while
@@ -315,8 +337,10 @@ unknown, active-run discovery is the recovery path.
   CLI-specific execution progress services, or wait on in-process run handles.
 - Execution providers remain replaceable behind Migration Executable instead of
   becoming TUI integrations.
-- The TUI and server negotiate protocol and SDK compatibility and exchange
-  registry and environment identity before operations begin.
+- Clients and servers negotiate Migrate Protocol compatibility and exchange
+  registry, environment, and SDK identity before operations begin. Remote SDK
+  versions are diagnostic; local socket connections additionally require exact
+  SDK identity.
 - Contextual availability, such as rollback support or whether a run can be
   stopped, is represented by migration and run data rather than server feature
   negotiation.