hop2 0.11.0 → 0.11.2

package/docs/restore-reliability.md

@@ -0,0 +1,139 @@
+# Session restore: failure taxonomy and the design that closes it
+
+Status: living document · Last updated 2026-07-26
+
+Every failure below was observed on the real fleet, not imagined. Each entry
+names the mechanism, the symptom the user saw, and where it is closed.
+
+## The two things restore must get right
+
+Restore answers exactly two questions per session, and every bug so far has
+been one of them getting a wrong answer confidently:
+
+1. **Identity** — *which conversation belongs to this session?*
+2. **Execution** — *did the relaunch actually happen?*
+
+Everything else (buffers, cwd, flags, config roots) is detail hanging off
+those two.
+
+---
+
+## A. Identity failures
+
+### A1. A helper claude steals the session's record
+**Mechanism.** The SessionStart hook keys its record on `HOP_SESSION`. Any
+claude started *inside* a session inherits that variable — including hop's
+own `hop ai tagline` helper, which runs `claude -p --model haiku` in a temp
+dir. It recorded itself as the session's conversation.
+**Symptom.** "Solstice didn't recover — I had to start claude manually."
+Restore refused a record whose cwd was a temp dir and opened a plain shell.
+**Closed by.** `aiChildEnv()` deletes `HOP_SESSION`/`HOP_SESSION_INTERNAL`, so
+hop's own helpers are invisible to the hook.
+
+### A2. A nested/side claude clobbers the record
+**Mechanism.** Same hook, different intruder: an MCP/agent workspace claude
+launched by a tool inside the session. The hook's original guard keyed on
+`CLAUDE_CODE_SESSION_ID`, which hop deliberately scrubs — so the guard never
+fired.
+**Symptom.** A `~/Code/nebula-slides` session came back in the slides tool's
+`agent-home/claude-workspace`; the room "became" a different session.
+**Closed by.** The hook refuses to overwrite an existing record when the new
+claude's cwd differs, parking the intruder at `<session>.other.json`.
+
+### A3. The record disagrees with where the session actually is
+**Mechanism.** Even with the guards, a record can predate a `cd`, or belong
+to a foreign tree.
+**Symptom.** Resuming resurrects the wrong conversation in the wrong place.
+**Closed by.** The room's **live cwd** — persisted to the durable meta from
+the host, which no nested process can forge — is the arbiter.
+`restorePlanForSession` refuses a record whose cwd disagrees, and promotes a
+parked `.other.json` whose cwd *matches*. Otherwise it opens a shell in the
+right directory with a visible warning.
+
+### A4. The recorded conversation doesn't exist on this host
+**Symptom.** `⚠ recorded claude conversation 673a1060… has no transcript on
+this host` (Hubble).
+**Closed by.** Detected before relaunch; falls back to a plain shell in the
+right cwd rather than running a command that would fail.
+
+### A5. Two sessions wearing one name
+**Mechanism.** A session renamed to a name that a *later* session owns as its
+internal name. Display names are not unique, so every name-addressed
+operation picked an arbitrary one of the two.
+**Symptom.** One tile flickering between a shell and a claude session;
+rename hitting the wrong session.
+**Closed by.** Rename addresses sessions by internal name; hydration detects
+a display name owned by another live session and gives it back.
+
+---
+
+## B. Execution failures
+
+### B1. Typing on a timer
+**Mechanism.** Restore typed the relaunch 800ms after attaching, then walked
+away. A shell still booting swallowed the keystrokes.
+**Symptom.** Orion: a bare shell holding **62 copies** of an un-run resume
+command, while restore reported success.
+**Closed by.** A per-session state machine (`wait-ready → type → verify →
+one retry → fail`) driven by the host's own view of the room.
+
+### B2. No idempotence
+**Mechanism.** Nothing checked whether the session was already running before
+typing, so every restore added another copy.
+**Closed by.** A room whose foreground process is not a shell is left alone.
+
+### B3. Silent failure
+**Mechanism.** Restore's report was its *plan*, not its result.
+**Closed by.** Per-session outcomes (`resumed` / `already-running` /
+`never-started` / `timeout`), printed for failures and returned to callers.
+
+### B4. Flags accumulating
+**Mechanism.** The hook records the argv claude actually ran with — which
+already contains the flags the previous restore added.
+**Symptom.** `--dangerously-skip-permissions` five times in one command.
+**Closed by.** Valueless flags deduped when rebuilding the launch.
+
+### B5. Restart races
+**Mechanism.** A daemon restart during the salvage script's restore phase
+cycled the host; PTYs died mid-restore.
+**Symptom.** 17 sessions lost at once (recovered via `hop restore`).
+**Open.** See below.
+
+---
+
+## C. What was open — now closed
+
+1. **Restart races (B5).** A pid-stamped lifecycle lock
+   (`~/.hop2/.lifecycle.lock`) serializes `hop start`, `hop stop`,
+   `hop restore` and the salvage script. Stale holders (dead pid, or held
+   >10min) are taken over, so a crash cannot wedge restarts.
+2. **The resume-choice prompt.** Sessions parked on claude's
+   "resume from summary / full session" question are marked **NEEDS YOU** on
+   the wall, detected from preview text already fetched. hop still never
+   answers it — that choice can consume a large share of a usage limit.
+3. **Restore is no longer keystrokes.** The relaunch is the room's own argv:
+   `shell -lc "<cmd>; exec shell -l"`, threaded from the daemon through
+   `POST /rooms` to `createPty`. No prompt to race, nothing half-typed, no
+   command echo in the scrollback; the session still drops to an interactive
+   shell when the app exits. Typing survives only as the fallback for a host
+   that predates this.
+
+## Remaining risk
+
+The failure classes above are structurally closed, but two things still
+depend on the environment rather than on hop:
+
+- A conversation whose transcript is missing on this host (A4) can only ever
+  become a plain shell in the right directory.
+- Restore cannot tell whether the app itself will succeed once launched (a
+  bad API key, an exhausted usage limit). Verification confirms the process
+  started, not that it is happy.
+
+## The invariant to hold on to
+
+> Never infer what can be observed, and never assume what can be verified.
+
+Identity comes from the room's live state (which the host owns), not from a
+file anything can overwrite. Execution is confirmed by watching the room's
+process, not by a timer. Every failure above is one of those two rules being
+broken.

package/docs/session-identity.md

@@ -0,0 +1,76 @@
+# Session identity: names, layers, and the rules that keep them honest
+
+Renaming a session has broken, in a different way, four times. Each fix
+addressed the symptom in front of it (persistence, then a false 409, then
+duplicate display names) and the next failure arrived from the same
+direction. This document names the underlying structure so the class stays
+closed.
+
+## The layers
+
+A session's metadata lives in three places, and every one of them can answer
+"what is this session called?":
+
+| Layer | Where | Lifetime | Written by |
+|---|---|---|---|
+| Store config | `sessionStore.sessions[internal]` (in memory; a workspace file only when a workspace exists) | until daemon exit | `setSessionConfig`, restore (`saveDefinition: true`), session creation |
+| Runtime metadata | `runtimeSessionMetadata` map | until daemon exit | `rememberRuntimeSessionMetadata`, every reconcile tick |
+| Durable meta | `~/.hop2/claude-sessions/<internal>.meta` | forever | rename, park/archive, tagline, hook records |
+
+A session is addressed by its **internal name** — the room id, immutable for
+the session's life. The **display name** is a label, and the alias map
+(`sessionAliases`) redirects old labels to current ones.
+
+## The rules
+
+1. **Write through every layer a reader consults.** Not "the right one" —
+   all of them. The recurring rename bug was a write/read asymmetry:
+   `renameSessionDisplayName` chose its target via the workspace-GATED
+   `getSavedSessionConfig`, while `getEffectiveSessionConfig`,
+   `reconcileExternalRuntimeSessions`, and `getSessionDisplayName` all read
+   the UNGATED store first. Any session with a store entry and no workspace —
+   which is every restored session — took the runtime branch, and the next
+   reconcile copied the stale store name back over it. The rename reverted
+   seconds later, which is why it kept looking like "rename doesn't persist."
+
+2. **Durable meta is the authority for a name.** It is the only layer written
+   by every rename and the only one that survives a restart. Reconcile
+   resolves `displayName` from meta first, then store, then runtime.
+
+3. **Never invent a session.** `resolveSessionDisplayName` returns `null`
+   when nothing owns a name, and callers refuse. It used to return the
+   requested name either way (both ternary branches were identical), so
+   `/ws?room=<name>` CREATED an empty session wearing that name. Combined
+   with rule 1's revert, one rename produced a phantom shell holding the new
+   name while the real session ran on, unreachable, behind the old one — and
+   because the alias pointed the old name at the new one, *both* names
+   resolved to the phantom. Any typo'd room name in a URL did the same thing.
+
+4. **Address by internal name whenever the caller knows it.** Display names
+   collide; the UI passes `internalName` so a rename always lands on the
+   session the user clicked.
+
+5. **A name conflict resolves in favour of the room that owns it.** If a
+   session's claimed display name is another live room's internal name, the
+   claimant falls back to its own name and the collision is logged. Two
+   identically-named sessions are indistinguishable in the UI and ambiguous
+   to address.
+
+## Diagnosing the next one
+
+- `[ws] refused attach to unknown session "X"` — a client is asking for a
+  name nothing owns. Before rule 3, this line was a new session instead.
+- `[rename] "X" is another live session's name` — rule 5 fired.
+- Disagreement between `<name>.meta` on disk and `/api/sessions` output means
+  a layer is stale: rule 1 or 2 has been violated by a new code path.
+
+## Covered by
+
+`npm run test:identity` — CI runs unit suites only (the integration tests
+need a real daemon and PTYs), so these guards do NOT run on push. Run them
+locally before shipping anything that touches naming, aliases, or attach.
+
+`tests/terminal-api.integration.test.cjs`:
+- *websocket attach to an unknown session refuses instead of creating one*
+  (fails without rule 3)
+- *rename sticks across reconcile ticks and never manufactures a session*

package/docs/switcher-first-ux.md

@@ -0,0 +1,103 @@
+# Switcher-first hop: design direction
+
+Status: proposal · Author: drafted with Claude · Date: 2026-07-25
+
+## The shift
+
+hop was built terminal-first: you land in a session, and the switcher is a
+palette you summon (⌘K) to leave it. The way hop is actually used — supervising
+many concurrent agent sessions, often from a phone — inverts that. The wall of
+sessions is the workspace; a single full-screen terminal is one mode of looking
+at it.
+
+This document proposes making the switcher the primary surface, with full-screen
+as a first-class mode, and **the default a user choice**. Both must remain
+one gesture apart.
+
+## What already supports this
+
+The switcher has quietly grown most of the machinery:
+
+- **Zoom ladder** (9 levels, +/−, viewport-capped) — the wall scales from a
+  dense overview to near-readable panes.
+- **Interactive tiles** above zoom level 6 — click a tile and type in it in
+  place, with a reconnect lifecycle of its own.
+- **Grid previews** — every tile shows the session's true current screen,
+  cheaply, because the daemon keeps a real parsed grid per room.
+- **Frozen ordering + activity glow** — the wall stops moving while you scan
+  it; activity signals in place.
+- **Taglines** — each session says what it is *for*, generated automatically.
+- **Search over content** — filter matches session names, working directories,
+  and terminal/transcript content, with previews retained in results.
+
+The gap is not capability. It is that the switcher still behaves like a
+transient palette: it resets on open, it has no durable identity of its own,
+and full-screen is where hop assumes you live.
+
+## Principles
+
+1. **The wall is a place, not a popup.** State the user establishes (zoom,
+   sort, scope, scroll position) persists across opens.
+2. **One gesture between modes, in both directions.** ⌘⏎ from a tile opens it
+   full screen; ⌘. returns. Escape never destroys work.
+3. **The default surface is a setting, not an opinion.** Some sessions are a
+   long single conversation; some are a fleet.
+4. **Nothing on the wall requires a round trip to be useful.** Tagline,
+   activity state, and last screen are all readable at a glance.
+5. **Phone-first ergonomics.** Thumb reach, no hover dependencies, and no
+   layout that assumes a mouse.
+
+## Proposed changes
+
+### 1. Default surface setting
+`Settings → Start on:` **Session wall** | **Last session** (current behavior).
+The daemon's landing redirect honors it, so opening hop goes where the user
+wants without a flash of the wrong surface.
+
+### 2. The wall gets an identity
+- A stable URL (`/wall`) so it can be bookmarked and returned to.
+- Zoom, sort mode, origin scope, and scroll offset persist per device.
+- Opening it does not reset scope to `user` (today it does).
+
+### 3. Mode switching becomes symmetric
+| From | Gesture | To |
+|---|---|---|
+| Wall | Enter / tap | Session, full screen |
+| Wall | ⌘⏎ on a tile | Interactive tile, stay on the wall |
+| Session | ⌘K / swipe down | Wall |
+| Interactive tile | ⌘⏎ | Session, full screen |
+| Interactive tile | ⌘. | Release, stay on the wall |
+
+Escape from the wall returns to the previous session when there is one;
+otherwise it is a no-op (never a dead end).
+
+### 4. Wall-native actions
+Rename, kill, and "new session here" already exist per tile. Add: pin a
+session to the top, and a compact keyboard path for each (the wall should be
+fully drivable without a pointer).
+
+### 5. Attention model
+Bell and unread dots stay. With ordering frozen, attention is communicated
+by the in-place glow plus an optional "N sessions want you" affordance that
+jumps to the next one — supervising twenty sessions should not require
+scanning twenty tiles.
+
+## Open questions
+
+- Does the wall replace the hub landing page, or are they the same surface in
+  two states? (Leaning: same surface; the hub is simply the wall with no
+  current session.)
+- On a phone, is the interactive tile worth the complexity versus always going
+  full screen for input? Real usage should decide.
+- Should panes and the wall converge — is a split pane just two pinned tiles?
+
+## Sequencing
+
+1. Default-surface setting + stable `/wall` URL (small, unblocks the rest).
+2. Persist wall state across opens; stop resetting scope.
+3. Symmetric mode gestures + Escape semantics.
+4. Attention jump affordance.
+5. Revisit panes vs. wall convergence.
+
+Each step is independently shippable and leaves hop usable if the next never
+lands.

package/hay/CHANGELOG.md

@@ -1,10 +1,65 @@
 # Changelog
 
+## [Unreleased]
+
+### New Features
+
+#### Tooling
+- **Deterministic turn-completion signal for agent driving**: the Claude hook installed by `hop claude-hook install` now also registers a `Stop` hook that bumps a per-turn counter at `<HOP_HOME>/claude-sessions/<HOP_SESSION>.turn` (`{ sessionId, count, at }`) each time Claude finishes a turn. Re-run `hop claude-hook install` to add it to an existing SessionStart-only install; it's a no-op outside hop and never disrupts Claude.
+- **MCP `until_agent_done` uses that counter when available**: `hopx_agent_turn` captures the session's turn count before sending and treats a counter advance as the authoritative "turn done" — exact completion instead of screen-scraping for a busy footer (which can read a paused agent as idle). When no marker is present (hook not installed, a non-Claude agent, or no local filesystem access) it falls back to the existing busy-line heuristic unchanged, so there's no behavior change without the hook.
+- **Verified submit catches a swallowed Enter**: in `mode:"ui"`, after `hopx_agent_turn` sends your text and presses Enter it re-reads the agent's input box and, if your prompt is still sitting there un-submitted (a known TUI race when the app isn't ready for input), re-sends Enter — up to twice — so a driver never waits forever on a turn that never started. The box is read with a dim-ghost/border-aware scrape (below), so an empty box showing only placeholder text counts as cleared. Reported under `submit` in the result (`verified`, `reason`, `resends`). On by default for UI turns; pass `verify_submit:false` to disable, or tune `verify_submit_retries` / `verify_submit_delay_ms`. No-op (and safe) when no input box is on screen, so it never double-submits to a plain shell.
+- **Composer scrape distinguishes typed text from ghost placeholder**: the MCP now reads a TUI input box straight from the virtual screen, locating it by its box-drawing frame and dropping the dim placeholder text using the per-cell SGR *dim* attribute (rather than stripping `\e[2m` from a string, which is ambiguous when color payloads follow). This is what lets verified-submit tell "my prompt is still in the box" from "the box is empty".
+- **Capture any TUI's scrollback through Hop with `hopx_capture_scrollback`**: the Hop-native counterpart to `hop_read_trajectory` — obtain an alternate-screen TUI's history *the way a user would*, by driving it to scroll up and stitching the rendered frames. It sends a scroll key (default PageUp), waits for the screen to actually redraw (`screenRevision` change), and stitches newly-revealed rows, detecting and excluding the app's fixed footer/composer chrome (so Claude's input box isn't duplicated through the transcript). Restores the live view afterward (PageDown per captured page) and caps output (`max_chars`). Works for any scrollable TUI — including non-Claude agents (codex/gemini) and when no transcript file is reachable. Verified end-to-end: full lossless reconstruction of a 300-line file under `less` (0 gaps, restored to bottom), and a live Claude session (PageUp scrolls, fixed composer not duplicated, view restored). Best-effort and lossy for wrapped/redrawn content — prefer `hop_read_trajectory` when a Claude transcript is available.
+- **Read a Claude session's real history with `hop_read_trajectory`**: the terminal only shows the current frame for an alternate-screen TUI, so the scrolled-off conversation is invisible to a driver. This MCP tool resolves a hop session name to its Claude transcript (`~/.claude/projects/<cwd-encoded>/<sessionId>.jsonl`, via the SessionStart-hook record, falling back to the newest transcript in the project dir — which it flags as ambiguous when several sessions share a cwd) and returns the **actual** turn history. It is **context-safe by design**: it stream-parses the file (a 21 MB / 6900-line transcript reduces in ~70 ms at ~150 MB RSS) and never returns the raw transcript — output is capped (`max_chars`, default 8000) with a truncation hint. The default `digest` mode is a **reduced conversation view** (ported self-contained from the agent-migration tool): per-turn User text + Assistant text + one-line tool-call summaries (`[Bash] …`, `[Read] path`, `[WebSearch] query=…`), with transcript noise dropped (tool-result bodies, thinking, system/hook lines, `<system-reminder>`/`<command-name>`-style injected text) and the most-recent turns kept within budget. Other modes: `summary` (metadata + per-type counts + token totals), `list` (paginated compact records), `get` (one turn by index/uuid), `tail` (last N turns' full text). **Gated by the same per-session agent permission as attaching** — reading a session's history requires `hop_set_agent_permission(name, allowed=true)` (or `hop session permit <name>`); unknown/unverifiable sessions are denied. Reads on the MCP host today, behind a seam so a daemon endpoint can serve it for agent-remote-from-sessions setups later.
+- **Busy-line completion settles before declaring done, and reports a three-state verdict**: on the heuristic path (no Stop-hook marker), the `hopx_agent_turn` busy guard now requires N consecutive idle reads (`settle_checks`, default 2) before calling a turn done — a single idle read can be a lull between an agent's bursts (thinking → tool call), and the settle avoids that stale-idle false "done". The guard's `uiBusyGuard` summary now carries `state: "done" | "busy" | "unknown"` (plus `settledIdle` and a compact `composer` snapshot) so a driver can tell a confirmed completion from a still-working turn from an ambiguous timeout. The turn-counter marker stays authoritative and needs no settle.
+- **`hop session list` shows attached client counts**: each live session now reports how many clients are connected (e.g. `Solstice [TERMINAL, LIVE] · 1 client`, or `· 0 clients` for a live-but-detached session) instead of only whether it's alive. Counts come from the host's per-room client tally; non-live sessions still only appear with `--all`.
+- **`hop` starts a new session by default; `hop attach` reuses one.** Bare `hop` (and `hop new` / `hop --new`) now always start a fresh session instead of reattaching to this directory's session. `hop attach` with no name attaches to an **unattached** session (one with no client connected) — preferring the current directory, else the most recently active — and if every session is already attached it reports "No unattached session" and lists them. `hop attach <name>` and `hop attach all` are unchanged.
+- **Clearer "couldn't reserve a session" note**: when the daemon can't hand out a session atomically, the fallback message now explains it's non-fatal and that a bare `status 200` typically means the running daemon is older than the CLI — with the fix (`hop stop && hop start`, which keeps sessions running). Previously it read as a cryptic "Could not claim session atomically (status 200)".
+- **`hop math '<latex>'`** — render a LaTeX formula in the terminal as a **2D Unicode layout**, dependency-free. The box-layout engine handles stacked fractions, `√` with an overline, big-operator limits stacked over/under, super/subscripts (Unicode glyphs with `^`/`_` fallback), Greek + operator symbols, and combining-mark accents like `\vec`/`\hat`/`\bar`. Reads from an argument or stdin. Inline-image rendering (Kitty/iTerm/Sixel) is deferred until graphics support lands in the web client (xterm.js), since the real payoff is images that render *inside* a shared hop session — until then math is Unicode everywhere.
+
+#### CLI Client
+- **Rename the session from inside it (`Opt+R`)**: type a new name in the status bar (`Enter` to save, `Esc` to cancel). The new name persists to the daemon, so it shows everywhere — the session manager, `hop session list`, and on reattach. (Posts to the local hop daemon's rename API; available wherever a local daemon is reachable.)
+- **You're told when another client reshapes the shared terminal**: with autofit on (the default), a peer's window can resize the shared PTY for everyone. When that happens the status bar shows a `⇄ <name>` indicator (who's driving the current size), and a one-off notice — `<name> resized the terminal to <cols>×<rows>` — explains the reshape so a sudden change of shape (including on connect, when a peer already sized it) isn't a surprise.
+- **Status bar / hints toggles are session-only**: `Opt+B` (status bar) and `Opt+T` (hints) no longer persist to `.hop.json`, so an in-session toggle can't silently become your permanent default. The default is taken from `.hop.json` (`showStatusBar`/`showHints`, both default `true`); toggles affect only the current session and the notice now says so. (Other toggles like mouse capture and sync-size still persist.)
+
+#### Web Client
+- **Restyle to the hop identity**: the web client now shares the CLI bars' palette and language — accent session chip, semantic state dot, and keycap-style find control in a real status-bar footer; mono-led chrome (brand, presence names, session labels); refined light/dark themes; dot-grid join page. The hop session picker got the same treatment, including dark-mode support.
+- **Drawer polish**: quick actions split into two clusters — utility icons (keyboard / share / find) then named actions (Fit / Manage) — and the drawer FAB now defaults to the top-right (clear of the status bar, mirroring the close button) instead of bottom-left. It stays draggable.
+- **Autofit by default + fit on every session load**: the terminal fits the viewport on connect and on each session switch, on every platform. Autofit resizes the shared PTY, so other viewers follow this client; switch to Manual in the drawer to opt out.
+
+#### Server
+- **Plain-shell restore replays the last screen**: on a graceful shutdown the host now persists each room's tail buffer to `<HOP_HOME>/session-buffers/<id>.raw`; `hop restore` seeds a recreated plain-shell session with that buffer plus a dim `──── session restored ────` separator, then starts a fresh shell in the same dir — so reopening a shell session picks up where it left off (claude sessions still resume via `claude --resume`, so they aren't seeded). The buffer is consumed (deleted) on restore so a later normal recreate never replays a stale screen. The first restart after upgrading has no persisted buffers yet (nothing to replay).
+
+### Bug Fixes
+
+#### Session restore
+- **`hop restore` actually restores now (Claude conversations included), from the SessionStart-hook records**: restore built its candidate list from the workspace-scoped session store, which is only populated when a workspace is active — and no workspace is ever activated in normal use, so `restore` found nothing and silently restored zero sessions. It now sources candidates directly from the durable per-session records the SessionStart hook writes (`~/.hop2/claude-sessions/<name>.json` = `{ sessionId, cwd }`), which survive a crash/reboot and carry the exact conversation id. So after a restart, `hop restore` recreates each session in its directory and resumes its Claude conversation with `claude --resume <id>` — no manual capture step. Sessions already live are skipped (idempotent), and `hop restore` now starts the daemon itself if it isn't running, so post-reboot recovery is a single command. `--dry-run` previews the plan. Records are pruned when a session is deleted, so restore never resurrects a session you intentionally closed (and if an unwanted one does come back, deleting it once keeps it gone).
+- **`hopx_agent_turn` no longer runs non-UI input twice**: in `readable_raw` mode (and `auto` resolving to it — i.e. a plain shell or any non-alternate-screen agent), a synchronous turn pre-sent the input and *then* sent it again via the combined send+wait, so a command driven through `hopx_agent_turn` executed twice. The pre-send is now done only for the paths that need it (the `ui` branch and async turns, which return before the combined call); non-UI synchronous turns let the single send+wait do the send. UI and async turns are unchanged.
+
+#### Session manager
+- **Workdir now shows the live directory, not the creation directory**: a session that's both running and saved had its working dir clobbered by the saved definition's cwd when the session list was assembled — so a session you'd `cd`'d into a subdir of (e.g. `~/Code/hop2`) showed its original dir (`~`) in the web/mobile session manager, even though the CLI status bar showed the right one. The live runtime cwd (the room's tracked `liveCwd`) now wins over the saved config cwd.
+
+#### CLI Client
+- **See every shortcut when the hint bar is too narrow (`Opt+?`)**: a full-screen help overlay lists all shortcuts grouped by purpose (`↑↓` scroll, `Esc` close), so keys aren't lost when the window can't show the whole hint bar. The bar now keeps a `⌥? help` entry near the front (so it survives right-edge truncation) and ends with a `…` when there are more hints than fit.
+- **Scroll wheel reaches mouse-aware remotes as a real wheel event (not arrow keys)**: when the remote program had mouse tracking on, clicks/drags were forwarded as mouse events but the wheel was converted to `↑`/`↓` arrow keys — so scrolling in a mouse-aware TUI behaved wrong even in mouse mode. The wheel is now passed through (like clicks) whenever the remote is tracking the mouse; arrow-key emulation is reserved for fullscreen apps that *don't* grab the mouse (a pager, `man`, etc.), and the normal screen still scrolls the local viewport.
+- **Duplicated / lost text during scrolling output (e.g. Claude Code)**: the dirty-line render diff compared screen rows positionally but only forced a full repaint on resize — so when the buffer scrolled (or you panned), rows that shifted could be skipped (lost text) or left behind (duplicated). The renderer now forces a full repaint whenever the buffer scrolls (xterm `onScroll`) or the viewport offset changes, and clears its frame cache on snapshot replay. The in-place diff still applies for typing (no scroll), keeping that fast.
+
+#### Web Client (mobile)
+- **Touch scrolling works again in fullscreen TUIs (Claude Code, vim, less)**: an alternate-screen app has no local scrollback, so the mobile touch handler's `terminal.scrollLines()` was a silent no-op — dragging did nothing once Claude entered fullscreen (and recent Claude versions scroll their own transcript rather than the terminal's buffer). The web client now tracks the remote's alternate-screen state (seeded from the server snapshot, kept live via xterm `?h/?l` CSI handlers for modes 47/1047/1049) and, while it's active, translates a touch-drag into the app's own paging keys — PageUp/PageDown (`\e[5~`/`\e[6~`), which Claude Code, `less`, and `man` all scroll on — instead of the dead local scroll. Drag up pages toward newer output, drag down toward older; momentum is disabled on the alternate screen so a flick can't fire a burst of page keys. Normal-screen scrolling (local viewport + momentum) is unchanged. Verified the alt-screen detection against the real xterm parser (modes flip the flag and the buffer still switches; unrelated modes like cursor-hide/bracketed-paste don't) and the drag→key direction/threshold mapping.
+- **Drawer groups no longer collapse with a long session list**: the drawer is a flex column with a fixed viewport height on mobile, so a long "Switch session" list overflowed and the flex algorithm shrank the Control and Theme/Font/Copy groups (which have `overflow:hidden`) to empty slivers. Children are now pinned to their natural height, so the drawer scrolls instead of squeezing — the settings groups stay visible no matter how many sessions are live.
+- **Mobile controls no longer disappear at narrow widths**: `isMobile` now tracks the viewport instead of being fixed at page load, so resizing a window narrow (or any narrow load) shows the full mobile drawer — keyboard toggle, Find, Touch mode, and the virtual keyboard — matching the CSS breakpoint. Previously a wide-then-narrow window stayed in "desktop mode" and dropped those controls.
+- **Find no longer triggers Safari's auto-zoom**: every focusable field is floored at 16px on mobile, so focusing the find box (or any input) never zooms the page with no way back. The drawer's Find action is now an icon.
+- **Drawer quick actions no longer clip**: buttons are content-width and wrap, so labels like "Manage" are never cut off; keyboard/share/find are compact icon buttons.
+- **Copy is one tidy control** (`Screen | All`) instead of three loose buttons, matching the other drawer rows.
+- **Calmer disconnect**: connecting/reconnecting/disconnected now read in a muted slate instead of alarm orange/red — a dropped connection should feel recoverable. Only a truly ended session shows red.
+- **Haptics**: the key-tap vibration uses the Vibration API on Android/Chromium. (iOS Safari has no web haptic API — Apple removed the `<input switch>` trick in iOS 17.4 — so haptics are a no-op there.)
+
 ## [0.9.0] - 2026-06-12
 
 ### New Features
 
 #### CLI Client
+- **Session panel (Opt+S)**: a file-manager-style overlay — session list on the left, a live screen preview of the highlighted session on the right. `↑`/`↓` (or `j`/`k`) fly through sessions with no perceived latency (previews are fetched from the host and cached), `Enter` switches the live terminal to the selected session, `Esc` closes. The footer shows the selected session's working dir, running program, and viewer count.
 - **Scrollback search (Opt+F)**: incremental search over the buffer; all matches are highlighted (current match bright), `Enter`/`↓` jump to the next match and `↑` to the previous one.
 - **Presence names + take/release control (Opt+C)**: peer names (with typing markers) in the status bar and exclusive-control parity with the web client.
 - **Persistent reconnect indicator**: a banner with the failure reason, countdown to the next retry, and attempt count stays visible while disconnected (CLI and web); the CLI now exits with a clear error if the first ~5 connection attempts never succeed.
@@ -14,12 +69,15 @@
 - **Hints toggle moved to Opt+T** (was `Ctrl+T`), matching the other Opt toggles; `Ctrl+T` now passes through to the remote terminal (readline transpose-chars, fzf, etc.).
 - **Adaptive bar themes**: status/hint bars auto-detect light vs dark terminal backgrounds (OSC 11 query, `$COLORFGBG` fallback) with truecolor palettes; pin with `--theme light|dark|auto` or `{"hay-cli": {"theme": "dark"}}` in `.hop.json`.
 - **Status bar redesign**: semantic state dot at the right edge (green connected / amber reconnecting / red disconnected / purple locked), session name as an accent chip at the left edge, dim cwd, `·` separators, `manual` shown only when autofit is off.
-- **Bigger reattach scrollback**: the server now retains ~2MB of raw output per room for reattach snapshots (was 200KB, which TUI-heavy streams exhausted in a screenful); override with `HAY_SNAPSHOT_BUFFER_BYTES`. Client scrollback raised to 5000 lines (CLI and web).
+- **Much bigger scroll buffer**: client scrollback is now 50000 lines (CLI and web), and the server retains ~20MB of raw output per room for reattach snapshots (override with `HAY_SNAPSHOT_BUFFER_BYTES`). The full snapshot is replayed and parsed on reattach, so this trades memory + reattach-parse time for deeper restored history.
 - **Hint bar redesign**: keycap-style hints (`⌃G detach · ⌥F find …` on macOS) with keys at full strength and labels dim; notices render as toasts (`✓` confirmations, `!` warnings, accent edge for info); the hint line surface is one step fainter than the status line.
 - **Clearer session feedback**: "Created new session" vs "Attached to (N participants)" notice on connect, named control-handoff notices ("alice took control…"), friendlier control-locked rejection with the controller's name, and a reattach hint on detach.
 - **CLI argument validation**: unknown flags and extra positional arguments are rejected with an error instead of silently becoming the room name.
 
 #### Server
+- Every session's PTY env now carries `HOP_SESSION=<room id>`, so a Claude Code SessionStart hook can map a running conversation back to its hop session (enables `hop restore` to resume the exact conversation per session).
+- Room summaries now report the foreground process name (node-pty's process getter, read fresh per summary), live cwd, and last-activity timestamp, so the session manager can show what each session is running, where, and when it was last active.
+- Rooms expose a bounded preview source (size + output tail) for on-demand screen previews in the session manager (`GET /rooms/:id/preview`).
 - Optional `created` flag on `hello` and `by` attribution on `session_ended` (both backwards compatible).
 - Invalid client messages are rejected with the message type and offending field (e.g. `Invalid resize message: rows …`) instead of a bare "Invalid message".
 

package/hay/apps/cli/package.json

@@ -12,8 +12,9 @@
   },
   "dependencies": {
     "hay-shared": "*",
-    "xterm-headless": "^5.3.0",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "xterm-addon-serialize": "^0.11.0",
+    "xterm-headless": "^5.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",