hx-cli 0.2.5__tar.gz → 0.2.7__tar.gz

{hx_cli-0.2.5 → hx_cli-0.2.7}/.github/workflows/ci.yml

@@ -36,8 +36,21 @@ jobs:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v3
       - run: uv sync --extra dev --python ${{ matrix.python }}
+      # bubblewrap, so the Linux sandbox tests run instead of skipping. Ubuntu
+      # 24.04 confines unprivileged user namespaces with AppArmor, which bwrap
+      # needs; the runner is throwaway, so lift that rather than ship a profile.
+      - if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update && sudo apt-get install -y bubblewrap
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
       # `live` needs an API key and real spend, so it never runs in CI.
       - run: uv run pytest -m "not live"
+      # What every end-to-end test saw, screen by screen - pass or fail.
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-report-${{ matrix.os }}-${{ matrix.python }}
+          path: e2e-report/
 
   install-script:
     runs-on: ubuntu-latest

{hx_cli-0.2.5 → hx_cli-0.2.7}/.gitignore

@@ -17,3 +17,4 @@ htmlcov/
 # and the rest - lives under $HX_HOME/projects/<slug>, outside the checkout
 # entirely, so there is nothing here left to hide.
 snapshot_report.html
+e2e-report/

{hx_cli-0.2.5 → hx_cli-0.2.7}/CHANGELOG.md

@@ -7,7 +7,7 @@ wheel, `hx changelog` prints it, and a session can answer "what's new?" or
 "which version added web search?" from it rather than from a guess. `hx docs`
 prints the manual next to it.
 
-The rules, enforced by `tests/test_docs.py` so a release cannot forget them:
+The rules, enforced by `tests/e2e/test_cli.py` so a release cannot forget them:
 
 - Every released version has a `## [x.y.z] - YYYY-MM-DD` section here, and the
   version in `src/hx/__init__.py` always has one. Bumping the version without
@@ -28,6 +28,113 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.7] - 2026-09-27
+
+### Added
+
+- `HX_OPENROUTER_BASE_URL` points the OpenRouter route at any OpenAI-compatible
+  endpoint - a gateway, a recording proxy.
+- Pressing `esc` on a running turn leaves an "Interrupted" line in the transcript,
+  so a reply cut off mid-sentence no longer reads as a finished one.
+- A paste over 10 lines or 1000 characters shows in the prompt as
+  `[Pasted text #1 +40 lines]` and is sent in full; the token moves and deletes
+  as one character, and survives history recall and `ctrl+k`/`ctrl+y`.
+- `\` then `enter` inserts a newline in any terminal, including Apple's Terminal
+  and tmux without extended keys, where `shift+enter` cannot be told from `enter`. `\\` then
+  `enter` sends a message that ends in a backslash.
+
+### Fixed
+
+- `shift+enter` inserts a newline instead of sending the message in kitty, Ghostty,
+  WezTerm, iTerm2 and tmux (with `extended-keys on`): HX now asks the terminal for
+  the kitty keyboard protocol, falling back to xterm's modifyOtherKeys, and hands
+  it back on exit, `ctrl+z` and `/fullscreen`. `ctrl+shift+z` (redo) works there too.
+- `shift+enter` also inserts a newline on macOS in terminals that send it as a
+  plain `enter` (VS Code's, Apple's Terminal) or as `option+enter` (the Claude
+  desktop app's terminal panel): HX asks macOS which modifiers are held when the
+  key arrives. A real `option+enter` still steers, an `enter` hard on the heels of
+  a shifted character (`?` then `enter`) still sends, and `HX_MODIFIER_PROBE=0`
+  turns the check off.
+- A multi-line paste keeps its line breaks. Terminals send them as carriage
+  returns, which HX was deleting, so a pasted table arrived as one long line.
+- Lines typed with `shift+enter` stay separate lines in the transcript instead of
+  being joined into one paragraph.
+- On macOS the sandbox now refuses *writes* to credential paths (`~/.ssh`,
+  `~/.aws`, `~/.hx/auth.json`, ...) as well as reads, so a session opened in your
+  home directory cannot plant an `authorized_keys` entry.
+- On Linux the same holds for a credential path that does not exist yet: a
+  session opened in your home directory with no `~/.ssh` could create one and
+  plant an `authorized_keys` on the host. HX now creates such a path, empty and
+  private (`0700` for a directory, `0600` for a file), and mounts a read-only
+  shadow over it. Existing credential directories are shadowed read-only too, so
+  a write fails with "Read-only file system" instead of vanishing.
+- Shell commands the model runs show their output in the transcript again - the
+  last lines, with `ctrl+o` for the rest - instead of only "Took 12ms".
+- `/context` no longer fails with "'UsageLedger' object has no attribute
+  'total_tokens'"; it lists what fills the window.
+- `/copy` copies the last reply and says how it was copied, instead of failing.
+- `/theme light` reports "Theme: light" rather than "Theme: None".
+- `/compact` on a short session says only that there is nothing to compact, no
+  longer followed by a "Compacting…" that never finishes; a compaction that
+  saves nothing still reports that it finished, and the context gauge keeps
+  counting the system prompt afterwards.
+- `/help` lines its key descriptions up however long a binding is, and a long
+  row in `/agents`, `/cost` or any other command output wraps under its own
+  column instead of at the left edge.
+- The "always allow" option on an approval names where the rule is really
+  saved (`~/.hx`), and the answered approval shows a file relative to the
+  project rather than as an absolute path.
+- `/permissions` no longer says the same thing twice.
+
+---
+
+## [0.2.6] - 2026-09-23
+
+### Added
+
+- Sign in to remote MCP servers over OAuth. A server that asks for it -
+  Atlassian's `https://mcp.atlassian.com/v2/mcp`, for one - shows as needing
+  sign-in; `/mcp login <server>` or `hx mcp login <server>` opens the browser
+  and the tools arrive without a restart. Tokens refresh on their own;
+  `/mcp logout <server>` forgets them. `"oauth": {"clientId": ...}` in
+  `mcp.json` covers servers without client registration.
+- MCP servers that change their tool list mid-session have the new list
+  swapped in, whether they announce it in a reply or on their own stream.
+- `hx mcp add NAME --url URL --header "Name: value"` saves headers, such as an
+  API token, with the server.
+- `/mcp reconnect <server>` restarts one server without restarting HX.
+- `/resume` always offers a list to switch to: this directory's sessions
+  first, then every other directory's, each row naming where it lives.
+  Picking one from elsewhere restarts HX in that directory on it, with the
+  same `--mode` and `--model`. The session already open is no longer listed,
+  and the list is no longer cut at 20.
+
+### Fixed
+
+- `/resume` said "No previous sessions in this directory" in a fresh
+  directory, or inside a session resumed from another one, instead of
+  listing anything.
+- `hx resume <id>` ran the session in whatever directory you typed it in,
+  not the one it was recorded in, so its paths and tool calls pointed at the
+  wrong project.
+- `hx mcp add NAME --url URL`, `--user`, and server arguments like `npx -y`
+  were refused as unknown options, so none of them could be run.
+- `hx mcp add` dropped headers from the entry it wrote.
+- A remote MCP server that expires its session is initialized again instead
+  of failing every call until HX restarts.
+- A multi-line shell command no longer breaks the screen. Its approval shows
+  one row per line, the tool call shows the first line and `+N lines`
+  (`ctrl+o` shows the rest), and the approval options and prompt are no longer
+  drawn several times over.
+- `/resume` from inside a resumed session showed the resumed conversation
+  pushed off the top of the screen, leaving only the "Resumed" notice.
+- A session title with a line break in it no longer splits its row in the
+  `/resume` picker.
+- Started in your home directory, the status bar named it `~/.`; it now reads
+  `~`.
+
+---
+
 ## [0.2.5] - 2026-09-23
 
 ### Added
@@ -592,7 +699,9 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.5...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.7...HEAD
+[0.2.7]: https://github.com/aletisunil/hx/compare/v0.2.6...v0.2.7
+[0.2.6]: https://github.com/aletisunil/hx/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/aletisunil/hx/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/aletisunil/hx/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/aletisunil/hx/compare/v0.2.2...v0.2.3

{hx_cli-0.2.5 → hx_cli-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.5
+Version: 0.2.7
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -299,7 +299,7 @@ hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
 hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 hx resume                   # resume the last session here
-hx resume <session-id>      # resume a specific one
+hx resume <session-id>      # resume a specific one, in the directory it was recorded in
 hx prompt                   # print the system prompt this directory would use
 hx trace                    # write the last session here to an HTML page
 hx trace out.html           # the same, to a path you choose
@@ -311,6 +311,8 @@ hx --no-sandbox             # disable OS sandboxing (rules still apply)
 hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
+hx mcp login <server>       # sign in to a remote MCP server in the browser
+hx mcp logout <server>      # forget a remote MCP server's sign-in
 hx auth [set|clear]         # manage the OpenRouter key
 hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
@@ -348,7 +350,7 @@ allowlist it if you would rather not be asked:
 ```
 
 `CHANGELOG.md` lists what each version added, and a release cannot skip it:
-`tests/test_docs.py` fails when `__version__` has no section (see
+`tests/e2e/test_cli.py` fails when `__version__` has no section (see
 [Releasing](#releasing)).
 
 ### Keys
@@ -360,7 +362,7 @@ be rebound (see [Keybindings](#keybindings)).
 | Key | Does |
 |---|---|
 | `enter` | send |
-| `ctrl+j` | newline (also `shift+enter`) |
+| `shift+enter` | newline (also `ctrl+j`; in a terminal that cannot send `shift+enter`, end the line with `\` and press `enter`) |
 | `esc` | interrupt the current turn |
 | `ctrl+c` | copy the selected text; with nothing selected, clear the prompt (twice on an empty prompt exits) |
 | `ctrl+d` | exit, when the prompt is empty |
@@ -478,14 +480,14 @@ than being silently resolved.
 | `/cost` | tokens, cache savings, spend |
 | `/compact [focus]` | summarise older turns now |
 | `/clear` | fresh session, same directory |
-| `/resume` | reopen a previous session, listed by name |
+| `/resume` | switch to another session - this directory's first, then the rest |
 | `/rewind` | go back to an earlier prompt, restoring the files HX changed |
 | `/title [text]` | show or set this session's name |
 | `/prompt` | the system prompt this session is running with |
 | `/todos` | show the current plan |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
-| `/mcp` | server status |
+| `/mcp [login\|logout\|reconnect <server>]` | server status, and signing in to remote servers |
 | `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
@@ -662,8 +664,11 @@ merge: it is read per layer, and only from your own settings. See
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
 `HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_GIT_NOTICES`,
 `HX_THEME`, `HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state, `HX_TAVILY_API_KEY`
-for web search, and `HX_CA_BUNDLE` / `HX_SSL_NO_VERIFY` for TLS (see
-[Credentials](#credentials)).
+for web search, `HX_CA_BUNDLE` / `HX_SSL_NO_VERIFY` for TLS (see
+[Credentials](#credentials)), and `HX_OPENROUTER_BASE_URL` to point the OpenRouter
+route at another OpenAI-compatible endpoint - a gateway, or a recording proxy.
+`HX_MODIFIER_PROBE=0` stops HX asking macOS whether shift is held when an
+`enter` arrives (see [Keys](#keys)).
 
 ### The system prompt
 
@@ -701,6 +706,13 @@ if you want a cheaper model for it — and it is counted in `/cost` like any oth
 If the call fails the session is still named, from your first message. `/title
 <text>` renames it.
 
+`/resume` lists every session except the one you are in: this directory's
+first, then other directories', each row naming where it lives. A session from
+this directory is swapped in place. One from elsewhere belongs to that
+directory - its sandbox, permission rules, prompt and tools - so HX restarts
+itself there with `hx resume <id>`, keeping options like `--mode` and
+`--model`.
+
 ### Themes
 
 A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
@@ -765,7 +777,8 @@ confidence prompts rather than passing.
 **An OS sandbox** wraps command execution: Seatbelt on macOS, bubblewrap on
 Linux. The filesystem is readable, writes are confined to the project and the
 temp dir, credential paths (`~/.ssh`, `~/.aws`, and HX's own `auth.json`) are
-unreadable, and outbound network is off. If neither backend is present the
+unreadable and unwritable - even inside the project, and even before they
+exist - and outbound network is off. If neither backend is present the
 status bar says `no-sandbox` rather than implying protection that is not there.
 
 Modes cycle with shift+tab: `plan` (read-only — mutating tools are not even
@@ -996,10 +1009,41 @@ construction.
 }
 ```
 
-Or `hx mcp add local python server.py`. Tools arrive namespaced
+Or `hx mcp add local python server.py`, or
+`hx mcp add remote --url https://example.com/mcp`. Tools arrive namespaced
 `mcp__<server>__<tool>` in a deterministic order. Servers connect concurrently
 with a per-server timeout; one that is broken or slow logs a warning and is
-dropped rather than taking the session with it.
+dropped rather than taking the session with it. A server that changes its tool
+list mid-session (`notifications/tools/list_changed`) has the new list swapped
+in without a restart.
+
+A remote server that asks for sign-in - Atlassian's, for one - is signed in to
+over OAuth, with nothing to configure:
+
+```json
+{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }
+```
+
+It shows as needing sign-in until you run `/mcp login atlassian` in a session
+or `hx mcp login atlassian` in a shell. That opens the browser, and the tools
+arrive as soon as you approve - no restart. HX follows the MCP authorization
+spec: it finds the authorization server from the server's metadata, registers
+itself as a client, signs in with PKCE, and keeps the token in `~/.hx/auth.json`
+(mode 0600), refreshing it before it expires and again if the server rejects
+it. Over SSH, paste the final redirect URL into the prompt instead.
+`/mcp logout atlassian` forgets it.
+
+A server that does not offer client registration needs a client you register
+with it yourself, and anything else about the sign-in can be pinned the same
+way:
+
+```json
+"oauth": { "clientId": "...", "clientSecret": "...", "scope": "read write", "callbackPort": 33418 }
+```
+
+To send a token of your own instead - an API key - give the server an
+`Authorization` header, and OAuth stays out of the way:
+`hx mcp add jira --url https://mcp.atlassian.com/v2/mcp --header "Authorization: Basic <base64 email:token>"`.
 
 **Hooks** are shell commands HX runs at named points in a turn. Four events:
 `PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.
@@ -1077,6 +1121,23 @@ uv run mypy                  # strict
 uv run hx                    # run from the checkout
 ```
 
+The suite is end-to-end. Each test in `tests/e2e/` starts the installed `hx`
+binary - on a real pseudo-terminal for the TUI, or as a plain subprocess for
+print mode and the other commands - in a private `$HOME` and `$HX_HOME`, and
+points it at a local OpenRouter stand-in with `HX_OPENROUTER_BASE_URL`.
+Everything between the keyboard and the socket is the shipped code; only the
+model's replies are scripted. The screen is read back through a VT emulator,
+so assertions are on the cells a terminal shows, not on the bytes HX meant to
+write.
+
+Every run writes `e2e-report/`: `index.html` shows each test's outcome and
+every screen it checked, rendered in colour, and one text file per screen lets
+two runs be compared with `diff -r`. CI uploads it from every test job as an
+`e2e-report-*` artifact. Set `HX_E2E_REPORT` to write it somewhere else.
+
+Tests that need the OS sandbox are skipped where there is no backend
+(`sandbox-exec` on macOS, `bwrap` on Linux).
+
 Tests marked `live` hit a real API. The OpenRouter ones cost money:
 
 ```sh
@@ -1093,17 +1154,7 @@ uv run pytest -m live tests/test_live_devin.py
 
 They are the only place the wire formats, streaming, tool use and a genuine
 cache hit are proven against a real service; everything else runs against the
-scripted provider.
-
-Tests marked `sandbox` exercise the real OS sandbox and are skipped where no
-backend exists.
-
-The TUI has SVG layout snapshots. Read the diff before accepting a change to
-them - they exist to catch a frame that quietly lost a row:
-
-```sh
-uv run pytest tests/tui/test_snapshots.py --snapshot-update
-```
+stand-in.
 
 ### Layout
 
@@ -1112,7 +1163,7 @@ src/hx/
   cli.py config.py paths.py frontmatter.py git.py
   core/         loop, context assembly, compaction, late injection, sessions, usage
   auth/         credential store, OAuth flows, per-route resolution
-  providers/    OpenRouter, Codex, Devin, the model catalogue, a scripted provider for tests
+  providers/    OpenRouter, Codex, Devin, the model catalogue
   tools/        Bash, Read, Write, Edit, Glob, Grep, Symbols, TodoWrite, Task,
                 WebSearch, WebFetch, line anchors, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
@@ -1149,12 +1200,12 @@ Each release:
 # 1. move CHANGELOG.md's [Unreleased] entries under the new version, dated,
 #    and leave a fresh empty [Unreleased] behind
 # 2. bump __version__ in src/hx/__init__.py
-# 3. uv run pytest tests/test_docs.py     # the version must have a section
+# 3. uv run pytest tests/e2e/test_cli.py  # the version must have a section
 git commit -am "release: X.Y.Z"
 git tag v$(uv run hx --version | cut -d' ' -f2) && git push origin main --tags
 ```
 
-Step 1 is not optional and is not a convention: `tests/test_docs.py` fails the
+Step 1 is not optional and is not a convention: `tests/e2e/test_cli.py` fails the
 whole suite when `__version__` has no `CHANGELOG.md` section, so a release that
 skips it cannot get past CI to the `publish` job. The file ships inside the
 wheel and `hx changelog` prints it, so a version with no section there reaches

{hx_cli-0.2.5 → hx_cli-0.2.7}/README.md

@@ -259,7 +259,7 @@ hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
 hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 hx resume                   # resume the last session here
-hx resume <session-id>      # resume a specific one
+hx resume <session-id>      # resume a specific one, in the directory it was recorded in
 hx prompt                   # print the system prompt this directory would use
 hx trace                    # write the last session here to an HTML page
 hx trace out.html           # the same, to a path you choose
@@ -271,6 +271,8 @@ hx --no-sandbox             # disable OS sandboxing (rules still apply)
 hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
+hx mcp login <server>       # sign in to a remote MCP server in the browser
+hx mcp logout <server>      # forget a remote MCP server's sign-in
 hx auth [set|clear]         # manage the OpenRouter key
 hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
@@ -308,7 +310,7 @@ allowlist it if you would rather not be asked:
 ```
 
 `CHANGELOG.md` lists what each version added, and a release cannot skip it:
-`tests/test_docs.py` fails when `__version__` has no section (see
+`tests/e2e/test_cli.py` fails when `__version__` has no section (see
 [Releasing](#releasing)).
 
 ### Keys
@@ -320,7 +322,7 @@ be rebound (see [Keybindings](#keybindings)).
 | Key | Does |
 |---|---|
 | `enter` | send |
-| `ctrl+j` | newline (also `shift+enter`) |
+| `shift+enter` | newline (also `ctrl+j`; in a terminal that cannot send `shift+enter`, end the line with `\` and press `enter`) |
 | `esc` | interrupt the current turn |
 | `ctrl+c` | copy the selected text; with nothing selected, clear the prompt (twice on an empty prompt exits) |
 | `ctrl+d` | exit, when the prompt is empty |
@@ -438,14 +440,14 @@ than being silently resolved.
 | `/cost` | tokens, cache savings, spend |
 | `/compact [focus]` | summarise older turns now |
 | `/clear` | fresh session, same directory |
-| `/resume` | reopen a previous session, listed by name |
+| `/resume` | switch to another session - this directory's first, then the rest |
 | `/rewind` | go back to an earlier prompt, restoring the files HX changed |
 | `/title [text]` | show or set this session's name |
 | `/prompt` | the system prompt this session is running with |
 | `/todos` | show the current plan |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
-| `/mcp` | server status |
+| `/mcp [login\|logout\|reconnect <server>]` | server status, and signing in to remote servers |
 | `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
@@ -622,8 +624,11 @@ merge: it is read per layer, and only from your own settings. See
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
 `HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_GIT_NOTICES`,
 `HX_THEME`, `HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state, `HX_TAVILY_API_KEY`
-for web search, and `HX_CA_BUNDLE` / `HX_SSL_NO_VERIFY` for TLS (see
-[Credentials](#credentials)).
+for web search, `HX_CA_BUNDLE` / `HX_SSL_NO_VERIFY` for TLS (see
+[Credentials](#credentials)), and `HX_OPENROUTER_BASE_URL` to point the OpenRouter
+route at another OpenAI-compatible endpoint - a gateway, or a recording proxy.
+`HX_MODIFIER_PROBE=0` stops HX asking macOS whether shift is held when an
+`enter` arrives (see [Keys](#keys)).
 
 ### The system prompt
 
@@ -661,6 +666,13 @@ if you want a cheaper model for it — and it is counted in `/cost` like any oth
 If the call fails the session is still named, from your first message. `/title
 <text>` renames it.
 
+`/resume` lists every session except the one you are in: this directory's
+first, then other directories', each row naming where it lives. A session from
+this directory is swapped in place. One from elsewhere belongs to that
+directory - its sandbox, permission rules, prompt and tools - so HX restarts
+itself there with `hx resume <id>`, keeping options like `--mode` and
+`--model`.
+
 ### Themes
 
 A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
@@ -725,7 +737,8 @@ confidence prompts rather than passing.
 **An OS sandbox** wraps command execution: Seatbelt on macOS, bubblewrap on
 Linux. The filesystem is readable, writes are confined to the project and the
 temp dir, credential paths (`~/.ssh`, `~/.aws`, and HX's own `auth.json`) are
-unreadable, and outbound network is off. If neither backend is present the
+unreadable and unwritable - even inside the project, and even before they
+exist - and outbound network is off. If neither backend is present the
 status bar says `no-sandbox` rather than implying protection that is not there.
 
 Modes cycle with shift+tab: `plan` (read-only — mutating tools are not even
@@ -956,10 +969,41 @@ construction.
 }
 ```
 
-Or `hx mcp add local python server.py`. Tools arrive namespaced
+Or `hx mcp add local python server.py`, or
+`hx mcp add remote --url https://example.com/mcp`. Tools arrive namespaced
 `mcp__<server>__<tool>` in a deterministic order. Servers connect concurrently
 with a per-server timeout; one that is broken or slow logs a warning and is
-dropped rather than taking the session with it.
+dropped rather than taking the session with it. A server that changes its tool
+list mid-session (`notifications/tools/list_changed`) has the new list swapped
+in without a restart.
+
+A remote server that asks for sign-in - Atlassian's, for one - is signed in to
+over OAuth, with nothing to configure:
+
+```json
+{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }
+```
+
+It shows as needing sign-in until you run `/mcp login atlassian` in a session
+or `hx mcp login atlassian` in a shell. That opens the browser, and the tools
+arrive as soon as you approve - no restart. HX follows the MCP authorization
+spec: it finds the authorization server from the server's metadata, registers
+itself as a client, signs in with PKCE, and keeps the token in `~/.hx/auth.json`
+(mode 0600), refreshing it before it expires and again if the server rejects
+it. Over SSH, paste the final redirect URL into the prompt instead.
+`/mcp logout atlassian` forgets it.
+
+A server that does not offer client registration needs a client you register
+with it yourself, and anything else about the sign-in can be pinned the same
+way:
+
+```json
+"oauth": { "clientId": "...", "clientSecret": "...", "scope": "read write", "callbackPort": 33418 }
+```
+
+To send a token of your own instead - an API key - give the server an
+`Authorization` header, and OAuth stays out of the way:
+`hx mcp add jira --url https://mcp.atlassian.com/v2/mcp --header "Authorization: Basic <base64 email:token>"`.
 
 **Hooks** are shell commands HX runs at named points in a turn. Four events:
 `PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.
@@ -1037,6 +1081,23 @@ uv run mypy                  # strict
 uv run hx                    # run from the checkout
 ```
 
+The suite is end-to-end. Each test in `tests/e2e/` starts the installed `hx`
+binary - on a real pseudo-terminal for the TUI, or as a plain subprocess for
+print mode and the other commands - in a private `$HOME` and `$HX_HOME`, and
+points it at a local OpenRouter stand-in with `HX_OPENROUTER_BASE_URL`.
+Everything between the keyboard and the socket is the shipped code; only the
+model's replies are scripted. The screen is read back through a VT emulator,
+so assertions are on the cells a terminal shows, not on the bytes HX meant to
+write.
+
+Every run writes `e2e-report/`: `index.html` shows each test's outcome and
+every screen it checked, rendered in colour, and one text file per screen lets
+two runs be compared with `diff -r`. CI uploads it from every test job as an
+`e2e-report-*` artifact. Set `HX_E2E_REPORT` to write it somewhere else.
+
+Tests that need the OS sandbox are skipped where there is no backend
+(`sandbox-exec` on macOS, `bwrap` on Linux).
+
 Tests marked `live` hit a real API. The OpenRouter ones cost money:
 
 ```sh
@@ -1053,17 +1114,7 @@ uv run pytest -m live tests/test_live_devin.py
 
 They are the only place the wire formats, streaming, tool use and a genuine
 cache hit are proven against a real service; everything else runs against the
-scripted provider.
-
-Tests marked `sandbox` exercise the real OS sandbox and are skipped where no
-backend exists.
-
-The TUI has SVG layout snapshots. Read the diff before accepting a change to
-them - they exist to catch a frame that quietly lost a row:
-
-```sh
-uv run pytest tests/tui/test_snapshots.py --snapshot-update
-```
+stand-in.
 
 ### Layout
 
@@ -1072,7 +1123,7 @@ src/hx/
   cli.py config.py paths.py frontmatter.py git.py
   core/         loop, context assembly, compaction, late injection, sessions, usage
   auth/         credential store, OAuth flows, per-route resolution
-  providers/    OpenRouter, Codex, Devin, the model catalogue, a scripted provider for tests
+  providers/    OpenRouter, Codex, Devin, the model catalogue
   tools/        Bash, Read, Write, Edit, Glob, Grep, Symbols, TodoWrite, Task,
                 WebSearch, WebFetch, line anchors, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
@@ -1109,12 +1160,12 @@ Each release:
 # 1. move CHANGELOG.md's [Unreleased] entries under the new version, dated,
 #    and leave a fresh empty [Unreleased] behind
 # 2. bump __version__ in src/hx/__init__.py
-# 3. uv run pytest tests/test_docs.py     # the version must have a section
+# 3. uv run pytest tests/e2e/test_cli.py  # the version must have a section
 git commit -am "release: X.Y.Z"
 git tag v$(uv run hx --version | cut -d' ' -f2) && git push origin main --tags
 ```
 
-Step 1 is not optional and is not a convention: `tests/test_docs.py` fails the
+Step 1 is not optional and is not a convention: `tests/e2e/test_cli.py` fails the
 whole suite when `__version__` has no `CHANGELOG.md` section, so a release that
 skips it cannot get past CI to the `publish` job. The file ships inside the
 wheel and `hx changelog` prints it, so a version with no section there reaches

{hx_cli-0.2.5 → hx_cli-0.2.7}/pyproject.toml

@@ -124,5 +124,5 @@ asyncio_mode = "auto"
 addopts = "-q --strict-markers -m 'not live'"
 markers = [
   "live: hits a real API (OpenRouter, or Tavily for the web search tools)",
-  "sandbox: requires sandbox-exec (macOS) or bwrap (Linux)",
+  "e2e: drives the installed hx binary against a local OpenRouter stand-in",
 ]

{hx_cli-0.2.5 → hx_cli-0.2.7}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.5"
+__version__ = "0.2.7"
 
 __all__ = ["__version__"]