archy/docs/terminal-uat-deployment.md

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.
• Verify the terminal panel stays bounded while output grows, keeps an inner scroll position at the newest line, and supports drag, resize, minimize, refresh, and fullscreen controls without blocking dashboard navigation.
• 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.

The node's reverse proxy must route /api/terminal/ to the Archipelago daemon (127.0.0.1:5678) in both HTTP and HTTPS server blocks. /ws already carries the terminal WebSocket upgrade. Without the REST location, the SPA fallback returns index.html instead of the authenticated session response.

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.