hop2 0.9.0 → 0.9.1

package/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md (hop2)
+
+Guidance for agents working on hop2.
+
+## Project shape
+- `hop` is the main Node.js CLI/server entry point (bin target).
+- `sessions.html` is the built-in session picker UI.
+- `hay/` contains the terminal sharing stack (server/cli/web).
+- `hay-web/` is the built web client output served by `hop`.
+
+## Local state & config
+- Default config dir is `~/.hop2` (override via `HOP_HOME`).
+- State files here should remain private (permissions matter).
+- Be careful with migrations: preserve backward compatibility where possible.
+
+## Change discipline
+- Keep changes focused and consistent with existing patterns.
+- Avoid unrelated refactors; minimize surface area.
+- Add concise comments only for non-obvious logic.
+- Update docs when user-visible behavior changes.
+
+## Build & test
+- Build web assets via `npm run build` (builds `hay` then syncs to `hay-web`).
+- Basic sanity check: `npm test` (runs `node --check hop`).
+- If you don’t run tests, say so and suggest likely commands.
+
+## UI work
+- Preserve existing visual language unless a redesign is intended.
+- Ensure layouts remain usable on desktop and mobile.
+
+## Server/CLI work
+- Prefer clear errors and non-zero exit codes on failures.
+- Keep security-sensitive behavior conservative and explicit.

package/MULTI-AGENT-CHECKLIST.md

@@ -0,0 +1,30 @@
+# Multi-Agent Run Checklist
+
+## Goal
+Ensure concurrent agent sessions stay isolated, time-bounded, and recoverable.
+
+## Safety Gates
+
+- [ ] **Isolated terminals** — assign each agent its own PTY via `hop_create_terminal`; never share a session between agents.
+- [ ] **Destructive-command approval** — gate every `rm -rf`, force-push, or `DROP TABLE` behind explicit user confirmation, regardless of autonomy level.
+- [ ] **Per-command timeouts** — enforce `idle_ms` and `max_wait_ms` on every `hop_wait_terminal` call; escalate or kill on deadline breach.
+
+## Execution Loop
+
+1. **Create session** — one `hop_create_terminal` per agent.
+2. **Validate prompt** — call `hop_wait_terminal(until_prompt=true)` to confirm the shell is ready before sending any command.
+3. **Send command** — write via `hop_write_terminal`; never blind-write into mid-execution output.
+4. **Await result** — use `until_regex` or `until_prompt` with `max_wait_ms` to capture output and detect completion.
+5. **Assert state** — verify exit code / expected output before proceeding.
+6. **Repeat** steps 2–5 for each command in the plan.
+
+## Recovery
+
+| Step | Action |
+|------|--------|
+| 1 | Send `ctrl_c` via `hop_send_key` |
+| 2 | If unresponsive after 5 s → `hop_close_terminal(killSession=true)` |
+| 3 | On orchestrator crash → kill **all** child terminals (kill switch) |
+| 4 | Verify zero orphaned processes before declaring shutdown complete |
+
+**Rule:** Never skip escalation. Always tear down — never leave orphaned sessions.

package/README-MCP.md

@@ -0,0 +1,213 @@
+# Hop MCP Server
+
+The Hop MCP server exposes hop’s terminal/session APIs over the Model Context Protocol (MCP), so agents can create terminals, stream output, and send input through Hop.
+
+## Quick Start
+
+1) Ensure Hop daemon is running locally (creates `~/.hop2/.tunnel-state`).
+
+2) Auto-configure supported MCP clients:
+
+```bash
+hop-mcp-setup
+```
+
+If you are running from source in this repo:
+
+```bash
+npm run setup-mcp
+```
+
+Supported auto-detected clients:
+- Claude Code
+- Claude Desktop
+- Cursor IDE
+- Gemini CLI
+- Codex CLI
+- VS Code / GitHub Copilot (workspace via `.vscode/mcp.json`)
+- Antigravity
+
+3) Or configure your MCP client manually:
+
+```json
+{
+  "mcpServers": {
+    "hop": {
+      "command": "hop-mcp"
+    }
+  }
+}
+```
+
+4) Restart your MCP client.
+
+The server auto-connects to the local Hop daemon via `~/.hop2/.tunnel-state`.
+
+## One Subagent Terminal (Claude/Codex)
+
+Recommended flow for driving one agent CLI safely:
+
+1) Launch a dedicated terminal:
+
+```
+hop_create_terminal(name="subagent", cwd="/path/to/repo")
+```
+
+2) Start the agent CLI:
+
+```
+hop_write_terminal(data="claude\n")
+# or
+hop_write_terminal(data="codex\n")
+```
+
+3) Wait for a prompt before sending work:
+
+```
+hop_wait_terminal(until_prompt=true, start_from="latest")
+```
+
+4) Run a multi-turn loop:
+- preferred: `hopx_send_and_wait(data="<task>", press_enter=true, capture="readable_raw")`
+- helper alternative: `hopx_agent_turn(data="<task>", mode="auto")`
+- manual split (if needed):
+- send one instruction with `hop_write_terminal(data="<task>\n")`
+- wait for output with `hop_wait_terminal(capture="readable_raw")` (defaults to `until_agent_done`)
+- continue with cursor-deltas via `hop_read_terminal(start_from="cursor", cursor=...)`
+- send the next instruction only after output is captured
+
+5) Stop/cleanup:
+- interrupt with `hop_send_key(key="ctrl_c")`
+- close with `hop_close_terminal(killSession=false)`
+
+Safety notes:
+- Keep one subagent per terminal (no multiplexing multiple agent CLIs in one PTY).
+- For existing user sessions, verify `agentPermitted` (or set with `hop_set_agent_permission`) before writing input.
+
+## Remote Hop
+
+To connect to a remote hop instance, set env vars or use `connect_server`:
+
+```bash
+HOP_API_URL="https://hop2.example.com" HOP_TOKEN="<token>" hop-mcp
+```
+
+Or from tools:
+
+```
+connect_server(base_url="https://hop2.example.com", token="<token>")
+```
+
+Optional verification:
+
+```
+connect_server(base_url="https://hop2.example.com", token="<token>", verify=true, verify_endpoint="/api/sessions")
+```
+
+## Tools
+
+Core tools (`hop_`): stable atomic operations.
+- `connect_server`
+- `hop_server_info`
+- `hop_list_sessions`
+- `hop_list_terminals`
+- `hop_create_terminal`
+- `hop_attach_terminal`
+- `hop_write_terminal`
+- `hop_send_key`
+- `hop_wait_terminal`
+- `hop_wait_start`
+- `hop_wait_poll`
+- `hop_resize_terminal`
+- `hop_read_terminal`
+- `hop_close_terminal`
+- `hop_set_agent_permission`
+- `hop_list_workspaces`
+- `hop_save_workspace`
+- `hop_load_workspace`
+- `hop_use_workspace`
+
+Helper tools (`hopx_`): convenience wrappers built on top of core tools.
+- `hopx_send_and_wait` (single-call send + wait wrapper)
+- `hopx_agent_turn` (single-turn send + wait + mode-aware output, default `mode="auto"`)
+
+## Resources
+
+- `hop://sessions`
+- `hop://terminals`
+- `hop://workspaces`
+
+## Notes
+
+- Agent access is gated by `agentPermitted` for sessions created by users.
+- `terminal_id` is an ephemeral daemon attachment handle; underlying hop `sessionName` is the stable identity.
+- On daemon restart, terminal-scoped tools auto-reattach once using stored session identity and retry transparently when possible.
+- `hop_read_terminal` returns a cursor for incremental polling.
+- `hop_read_terminal` supports `mode: "ui"` for structured terminal snapshots:
+  - `ui.lines`: visible screen lines
+  - `ui.cursor`: cursor position
+  - `ui.window.strategy`: `cursor_centered` with auto fallback to `densest_nonempty` when needed
+  - `rawTail`: optional lossless tail of recent raw events (for transient output)
+- Hop server now replays buffered terminal events on stream connect, so late attaches get immediate context instead of an empty first read.
+- `hop_read_terminal` supports `mode: "readable_raw"`:
+  - preserves printable text in `events[].text`
+  - includes compact control hints in `events[].controls` (cursor, erase, alt-screen, visibility)
+  - `control_level` tunes control noise:
+  - `full`
+  - `structural` (cursor/edit/screen controls; omits CR/LF noise)
+  - `none` (default; text only)
+  - `noise_filter` tunes status/spinner suppression:
+  - `balanced` (default; suppresses CR/erase rewrite bursts, commits stable lines, strips spinner-prefix/dot animation for dedupe)
+  - in `balanced`, recent shell echo lines for agent-sent input (prompt + command) and prompt-padding artifacts are compacted
+  - `off` (raw parsed text; useful for parser debugging)
+  - in default `none`, empty output frames are dropped to reduce event noise
+  - `coalesce_ms` and `coalesce_max_chars` can merge adjacent output frames for cleaner streaming text
+  - defaults: `coalesce_ms=250`, `coalesce_max_chars=32768`
+  - parses incrementally across chunk boundaries to avoid split ANSI artifacts
+  - reconstructs common inline edits (backspace/cursor rewrites) so text is cleaner for agent parsing
+  - avoids full ANSI noise while retaining interaction structure
+- `hop_send_key` sends normalized named keys (for example `enter`, `esc`, `up`, `ctrl_c`) to improve interactive TUI control without raw escape-string handling.
+- `hop_wait_terminal` blocks on output conditions without client polling loops:
+  - `start_from` controls where matching begins:
+  - `latest` (default): stream tail / new output only
+  - `cursor`: requires `cursor` argument
+  - `beginning`: oldest buffered event
+  - if no explicit condition is provided, it defaults to `until_agent_done=true`
+  - `async=true` starts a background wait job and returns `wait_id` immediately
+  - `until_agent_done` matches when output has started, terminal becomes quiet, and interactive cursor is visible (agent-friendly completion)
+  - regex match via `until_regex`
+  - prompt match via `until_prompt` (optional custom `prompt_regex`)
+  - quiet-period detection via `idle_ms`
+  - bounded event capture in `raw` or `readable_raw`
+  - for `capture="readable_raw"`, supports `control_level`, `noise_filter`, `coalesce_ms`, `coalesce_max_chars`, and optional `includeMetaEvents`
+- `hop_wait_start` / `hop_wait_poll` provide explicit async wait orchestration for long-running conditions:
+  - start with `hop_wait_start(...)` and poll with `hop_wait_poll(wait_id=..., wait=true)`
+  - use `consume=true` on poll to remove completed jobs
+- `hopx_send_and_wait` combines input send + optional enter/key + wait, and defaults to cursor-based delta capture from just before send.
+  - helper defaults are token-thrifty for interactive loops: `capture_max_events=60`, `control_level=none`, `noise_filter=balanced`, `coalesce_ms=350` (unless overridden)
+  - for `capture="readable_raw"`, `text_only` defaults to `true`; this condenses wait payloads by returning joined `wait.text`, setting `wait.events=[]`, `wait.eventCount=0`, and preserving prior count in `wait.originalEventCount` (set `text_only=false` to keep full events)
+- `hop_read_terminal` supports deterministic delta reads:
+  - `start_from`: `beginning` (default), `cursor`, or `latest`
+  - response includes `cursorStart`, `cursorEnd`, and `next_cursor`
+- `hopx_agent_turn` is a helper wrapper (not a core primitive):
+  - default `mode="auto"` chooses `ui` when terminal is in alternate-screen, otherwise `readable_raw`
+  - in `mode="auto"`, if alternate-screen starts during the same turn, it auto-promotes to `ui` for that response
+  - wait-only continuation is supported: omit `data`/`message` and use `control="wait"` to keep waiting on a terminal without sending new input
+  - `async=true` starts the turn wait in the background and returns `wait_id` immediately; continue polling or controlling that turn with `hopx_agent_turn(wait_id=..., wait=true|false, control=...)`
+  - `control="interrupt"` / `control="terminate"` send an explicit interrupt key (default `esc`); `terminate_message` can send a final follow-up after the interrupt
+  - `mode="ui"` returns a UI snapshot payload after wait
+  - for readable modes, `text_only` defaults to `true` and condenses waits the same way as `hopx_send_and_wait` (set `text_only=false` to keep full wait events)
+  - `text_only` is ignored for `mode="ui"` output snapshots
+  - `mode="ui"` defaults `includeRawTail=false` to reduce noisy tail payloads (opt in with `includeRawTail=true`)
+  - `mode="ui"` defaults wait capture to `capture_max_events=0` (override when you need readable wait-event diagnostics)
+  - when using default `until_agent_done` semantics in `mode="ui"`, hopx applies a short UI busy-guard pass to avoid returning while status lines still indicate active work (`esc to interrupt`, `working`, `waiting for process`, etc.)
+  - `mode="readable_raw"` / `mode="raw"` returns the same wait payload shape as `hopx_send_and_wait`
+- Tool calls that fail at the Hop API layer now return MCP errors (`isError: true`) with normalized fields:
+  - `ok`
+  - `status`
+  - `endpoint`
+  - `error`
+- Hop now isolates shell history per session and writes per-session NDJSON audit logs under `~/.hop2/workspaces/<workspace>/logs/<session>/audit.ndjson` with truncation metadata for large chunks.
+- Audit logging auto-switches to diff-suppressed `tui_keyframe` snapshots when alternate-screen apps (vim/htop/agent TUIs) are detected, while still capturing all input events.
+- Default fallback terminal size is `140x40` when no explicit `cols`/`rows` are provided.
+- `hop_create_terminal` / `hop_attach_terminal` now do a short output warmup before returning, reducing first-command races in interactive shells.

package/README.md

@@ -4,6 +4,8 @@
 
 Access your Mac's terminal from your phone, tablet, or any browser — secured with password + 2FA, tunneled through Cloudflare.
 
+Hop also ships with a built-in MCP server, so Claude Code, Codex, Gemini, Cursor, and other MCP clients can create terminals, stream output, and drive agent sessions through Hop.
+
 > **🍎 macOS/Linux** — Requires cloudflared for tunneling
 
 ```
@@ -16,6 +18,7 @@ Access your Mac's terminal from your phone, tablet, or any browser — secured w
 
 - 🔐 **Password + 2FA** — Optional password plus TOTP (required for custom domains)
 - 🌍 **Access Anywhere** — Cloudflare tunnel, no port forwarding
+- 🤖 **Built-in MCP Server** — Turn Hop into an agent-facing terminal platform for Claude Code, Codex, Gemini, Cursor, and more
 - 🌐 **Custom Domains + Multi‑User** — Share subdomains with per‑user credentials
 - 📱 **Mobile Virtual Keyboard** — Custom keyboard with Esc, Ctrl, Alt, arrows, and more
 - ⌨️ **Native Keyboard Support** — Tap the blue button for dictation, spellcheck & autocomplete
@@ -33,6 +36,11 @@ Access your Mac's terminal from your phone, tablet, or any browser — secured w
 npm install -g hop2
 ```
 
+This installs:
+- `hop` — main CLI / daemon / browser terminal entrypoint
+- `hop-mcp` — MCP server exposing Hop terminals and sessions
+- `hop-mcp-setup` — MCP client auto-config helper
+
 Then just run:
 ```bash
 hop
@@ -69,9 +77,6 @@ source ~/.zshrc
 ```bash
 # Start hopping!
 hop
-
-# Use iTerm control mode for local session
-hop --iterm
 ```
 
 **First time:**
@@ -86,6 +91,27 @@ hop --iterm
 3. Pick or create a session
 4. 🐰 You're in! Use the virtual keyboard for terminal keys, or tap the blue button for native input
 
+## 🤖 Hop MCP
+
+Hop is not just a browser terminal. It also exposes terminals and sessions over MCP so agents can safely operate through the same platform.
+
+Use cases:
+- Launch a dedicated Claude Code / Codex / Gemini terminal and drive it over multiple turns
+- Create isolated agent sessions with per-session history and audit logs
+- Read terminal output incrementally instead of screen-scraping a browser
+- Build higher-level agent workflows on top of stable terminal/session primitives
+
+Quick start:
+
+```bash
+hop
+hop-mcp-setup
+```
+
+Then restart your MCP client. `hop-mcp-setup` auto-detects and configures supported clients such as Claude Code, Claude Desktop, Cursor, Gemini CLI, Codex CLI, VS Code / Copilot, and Antigravity.
+
+For full MCP usage, tools, and subagent workflows, see [README-MCP.md](./README-MCP.md).
+
 ## 🪟 Sessions
 
 Create multiple independent terminal sessions from the Session Picker (`/sessions`):
@@ -98,8 +124,37 @@ You can also create **Port Sessions** that proxy to a local HTTP/WS service on y
 Use the Session Picker or:
 ```bash
 hop session add myapp --port 3000
+hop session add workspace-shell --cwd ~/src/my-project
 ```
 
+## 🧾 Session History & Audit Logs
+
+Hop always writes per-session audit logs.
+Shell history isolation is role-based by default:
+
+- Agent-created terminal sessions: isolated history file per session
+- User-created terminal sessions: keep your shell default history file (opt-in isolation available)
+
+- Isolated history file path: `~/.hop2/workspaces/<workspace>/history/<internal-session>.history`
+- Audit log (NDJSON): `~/.hop2/workspaces/<workspace>/logs/<internal-session>/audit.ndjson`
+- Audit events include `session_start`, `input`, `resize`, `session_end`, plus:
+- `audit_mode` / `pty_state` transitions (auto-switches between `stream` and `tui_keyframe`)
+- `tui_keyframe` snapshots (diff-suppressed; emitted only when content changes)
+- `command_launch` metadata (captures launched command token and detected agent CLI type)
+- Large input/output chunks are truncated with metadata (`bytes`, `omittedBytes`, `dataHead`, `dataTail`)
+
+Tunable defaults:
+
+- `HOP_SESSION_HISTORY_SIZE` (default `5000`)
+- `HOP_AGENT_HISTORY_ISOLATION` (default `1`)
+- `HOP_USER_HISTORY_ISOLATION` (default `0`)
+- `HOP_AGENT_POST_START_HISTORY_INIT` (default `1`)
+- `HOP_POST_START_HISTORY_INIT` (default `0`, forces post-start history init for all sessions)
+- `HOP_SESSION_AUDIT_INLINE_MAX_BYTES` (default `4096`)
+- `HOP_SESSION_TUI_KEYFRAME_INTERVAL_MS` (default `750`)
+- `HOP_SESSION_TUI_KEYFRAME_TAIL_CHARS` (default `20000`)
+- `HOP_SESSION_TUI_KEYFRAME_MAX_LINES` (default `80`)
+
 ## 🌐 Custom Domains & Multi‑User
 
 ### Admin (your machine)
@@ -145,13 +200,13 @@ On mobile devices, Hop provides a custom virtual keyboard designed for terminal
 - First-time users will see a tooltip pointing to the native keyboard button
 - Use the native keyboard for longer text input with autocomplete
 
-## 🖥️ iTerm Integration
+## 🖥️ Local Attach
 
 ```bash
-hop --iterm
+hop attach <session>
 ```
 
-Uses tmux control mode (`-CC`) for native scrolling, copy/paste, splits, and search. Session remains accessible via web.
+Attach your local terminal client to an existing hop terminal session.
 
 ## 🔌 Port Sessions
 
@@ -168,10 +223,12 @@ Works with dev servers, Jupyter, APIs — anything on localhost. Supports WebSoc
 
 | Command | Description |
 |---------|-------------|
-| `hop` | Start hop (or attach to existing tunnel) |
-| `hop --iterm` | Use iTerm tmux control mode for local session |
+| `hop` | Start hop daemon/tunnel if needed, then launch a local terminal |
+| `hop attach all` | Attach sequentially to all terminal sessions |
+| `hop local [session]` | Start a daemonless local terminal (`[session]` attaches if it exists) |
 | `hop url` | Print current tunnel URL |
-| `hop qr` | Show QR code for current URL |
+| `hop qr` | Show QR code for current tunnel URL |
+| `hop qr auth` | Show QR code for authenticator app setup |
 | `hop domain <hostname>` | Set custom domain (named tunnel) |
 | `hop domain-clear` | Remove custom domain, use random URLs |
 | `hop password set` | Set/change password |
@@ -180,19 +237,36 @@ Works with dev servers, Jupyter, APIs — anything on localhost. Supports WebSoc
 | `hop user add <name>` | Add user + subdomain |
 | `hop user remove <name>` | Remove user |
 | `hop user export <name>` | Export user credentials |
-| `hop session list` | List sessions |
-| `hop session add <name>` | Create a terminal session |
+| `hop session list` | List sessions with `LIVE` vs `SAVED` terminal status |
+| `hop session add <name> [--cwd P]` | Create a terminal session |
 | `hop session add <name> --port N` | Create a port session (proxy) |
+| `hop session rename <old> <new>` | Rename a session |
 | `hop session remove <name>` | Remove a session |
 | `hop client <credentials>` | Run hop with exported credentials |
-| `hop wipe` | Kill all hop tmux sessions |
+| `hop wipe [--all]` | Remove saved sessions (`--all` also kills live sessions) |
 | `quit` | Type at exit prompt to shutdown tunnel |
 
+Additional installed binaries:
+- `hop-mcp` — Start the Hop MCP server directly
+- `hop-mcp-setup` — Auto-configure supported MCP clients
+
+Startup behavior:
+- Hop reconciles already-running external Hay sessions first, then applies the default workspace as additional startup state.
+
+## 🧪 Terminal Backend
+
+Hop always uses the `external` terminal runtime (PTYs in a separate local hay host process).
+
+- The host persists across hop daemon restarts.
+- Host state is tracked in `~/.hop2/.hay-host-state`.
+- On startup and session listing, Hop discovers live hay-host processes and adopts the one(s) that still own runtime rooms if the state file is stale.
+- Local CLI transport is direct to hay-host; daemon restarts do not terminate local terminal sessions.
+- Bare `hop` prompts on cwd match (`Attach existing` vs `Create new`, default `Create new`); non-interactive runs always create new.
+- `HOP_TERMINAL_BACKEND` is accepted for compatibility but ignored.
+
 ## 📦 Dependencies
 
 Installed automatically via Homebrew:
-- `tmux` — Terminal multiplexer
-- `ttyd` — Web terminal
 - `cloudflared` — Cloudflare tunnel
 
 Node.js packages:
@@ -206,6 +280,7 @@ Node.js packages:
 - **Password + TOTP** — Password optional, but required for custom domains
 - **Rate Limiting** — Exponential backoff on failed attempts
 - **Secure Cookies** — `httpOnly`, `secure`, `sameSite=lax`
+- **Session persistence** — Login cookies are signed with a stable session secret by default, so browser sessions can survive `hop stop/start` without reauth.
 - **Random URL** — Unguessable tunnel URL for quick tunnels
 - **Fixed URL** — Custom domains keep a stable URL
 - **Local Binding** — Server only listens on 127.0.0.1
@@ -214,6 +289,7 @@ Node.js packages:
 **Passwords:** Recommended for any public URL; required for custom domains.
 
 **Secrets:** Stored in `~/.hop2/` (treat like `~/.ssh/`)
+Set `HOP_PERSIST_SESSION_SECRET=0` to force a fresh login cookie secret every daemon restart.
 
 ## 🛠 Development (Hay)
 
@@ -226,10 +302,31 @@ npm run build
 This builds hay (web + cli) and syncs `hay/apps/web/dist` into `hay-web/` for Hop to serve.
 If `./hay` exists and the dist folder is missing, `hop` will auto-build hay on startup.
 
+## 🤖 Hop MCP (One Subagent Terminal)
+
+Use one dedicated terminal when driving a subagent CLI through Hop MCP.
+
+1. Create a terminal with `hop_create_terminal` (set `name` and `cwd`).
+2. Start the agent CLI with `hop_write_terminal` (`claude` or `codex`).
+3. Wait for readiness with `hop_wait_terminal(until_prompt=true)`.
+4. Send one instruction at a time via `hopx_send_and_wait` (or `hop_write_terminal` + `hop_wait_terminal`).
+5. Optional helper path: use `hopx_agent_turn(mode="auto")` for a single send+wait turn with mode-aware output (`ui` for TUI screens, `readable_raw` otherwise); it auto-promotes to `ui` if alternate-screen starts mid-turn and uses lean capture defaults (`capture_max_events=60` for readable modes, `0` for `ui` unless overridden, plus `text_only=true` by default for readable waits).
+6. For long waits, prefer `hopx_agent_turn(async=true, ...)` and continue with `hopx_agent_turn(wait_id=..., wait=true, control="wait")`; fall back to `hop_wait_start(...)` / `hop_wait_poll(...)` when you want the lower-level primitives directly.
+7. After each turn, collect output with `hop_wait_terminal` or incremental `hop_read_terminal` cursor reads.
+8. Interrupt with `hop_send_key(key="ctrl_c")` and close using `hop_close_terminal`.
+
+Safety tips:
+- Keep one subagent per terminal.
+- Do not queue a second instruction before reading the first response.
+- For attached user sessions, confirm `agentPermitted` before sending input.
+
 ## 🐛 Troubleshooting
 
-**QR code not working?**
-Delete `.auth_secret` and restart hop to generate a new code.
+**Authenticator QR code needed again?**
+Run `hop qr auth` to re-show the current TOTP setup QR for Duo/Authy/1Password.
+
+**Need to reset TOTP entirely?**
+Delete `.auth_secret` and restart hop to generate a new authenticator secret and QR code.
 
 **Client reset (user mode)?**
 Delete `~/.hop2/clients/<tunnel-id>/` and run `hop client` again.
@@ -237,9 +334,12 @@ Delete `~/.hop2/clients/<tunnel-id>/` and run `hop client` again.
 **Tunnel not starting?**
 Make sure `cloudflared` is installed: `brew install cloudflared`
 
+**Tunnel returns 502 or died after network changes?**
+Run `hop health --restart`. Hop now waits for the public URL to become healthy again instead of only sending a fire-and-forget restart request.
+
 **Stuck processes?**
 ```bash
-pkill ttyd; pkill cloudflared; tmux kill-server
+pkill cloudflared
 ```
 
 ## 📝 License

package/hay/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [Unreleased]
+
+### Bug Fixes
+
+- Fixed the mobile terminal layout so the virtual keyboard anchors to the viewport bottom and no longer leaves a large gap above the screen edge.
+
 ## [0.8.0] - 2025-01-25
 
 ### Major Changes