feat: add authenticated resumable terminal

2026-10-09 07:59:12 -04:00
parent f50521072d
commit 16c84c450e
4 changed files with 414 additions and 270 deletions
@@ -0,0 +1,47 @@
+# Terminal UAT deployment runbook
+
+Status: prepared, 2026-10-09. This runbook targets the physical Framework node
+(`framework-pt`) and does not authorize an OTA, catalog publication, or wallet
+mutation.
+
+## Candidate contents
+
+Build and record the backend binary, dashboard bundle, and source commit from
+the isolated terminal worktree. The backend must have `ARCHY_SESSION_STATE_DIR`
+set to the developer account's shared state directory (or use the default
+resolution in `api/handler/terminal.rs`). Preserve the existing web root and
+service binary before any replacement.
+
+## Preconditions
+
+1. Verify the Framework hostname and SSH host key through the operator's
+   approved connection mechanism. A plain `ssh framework-pt` must not be used
+   until host-key verification is available.
+2. Capture service/container state, boot ID, running binary digest, served UI
+   digest, and the existing `/var/lib/archipelago/support` layout without
+   printing credentials, wallet files, or environment contents.
+3. Create a timestamped protected rollback directory under
+   `/var/lib/archipelago/support/terminal-uat-<timestamp>`.
+
+## Acceptance flow
+
+- Open the dashboard as the node owner; unauthenticated requests to
+  `/api/terminal/sessions` and `/ws/terminal` return 401.
+- Create a named session, type `printf 'uat\n'`, close the terminal, reopen it,
+  and resume the same session without a duplicate tmux process.
+- Refresh the browser and reconnect after a temporary network interruption.
+- Open a second owner browser and verify inventory visibility; verify only one
+  active attachment sends input at a time before enabling transfer controls.
+- Confirm explicit End stops the tmux process but preserves the workspace.
+- Reboot acceptance is separate: processes may stop, metadata must remain, and
+  the UI must call this interrupted rather than a live resume.
+- Verify the Omarchy-derived agent skill files and app starter are present in
+  the candidate source/artifact; do not treat a local npm install failure as a
+  successful app build.
+
+## Rollback
+
+Stop exposing the new dashboard before restoring the previous UI/backend pair.
+Restore only from the protected receipt, verify the previous hashes and health,
+and leave terminal session metadata/workspaces untouched unless the operator
+explicitly requests session cleanup.