hx-cli 0.2.3__tar.gz → 0.2.4__tar.gz

hx_cli-0.2.4/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+.hx/sessions/
+# Not .hx/settings.json: that file is the project's *shared* configuration and
+# is meant to be checked in. What HX writes on your behalf - permission grants
+# and the rest - lives under $HX_HOME/projects/<slug>, outside the checkout
+# entirely, so there is nothing here left to hide.
+snapshot_report.html

{hx_cli-0.2.3 → hx_cli-0.2.4}/CHANGELOG.md

@@ -28,6 +28,90 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.4] - 2026-09-19
+
+### Added
+
+- `/trace [path]`: write the whole session to one self-contained HTML page and
+  open it. The system prompt, the project context, the skills index, every tool
+  schema, every prompt and reply, every thinking block, every tool call beside
+  the result it produced, the per-call token ledger and the files HX changed.
+  Late-injected reminders and compacted turns are included behind a toggle.
+  A session still running traces as it stands, including the turn that just
+  landed. The page follows your system's dark or light setting and a button
+  overrides it; nothing is fetched and nothing is uploaded.
+- `hx trace [SESSION_ID] [PATH]`: the same page for any transcript on the
+  machine, without starting a session. Defaults to the last session in this
+  directory and prints only the path, so `open "$(hx trace)"` works. Either
+  argument may be given alone - a lone one that looks like a path is one.
+- The system prompt and the tool schemas are now written to the transcript on a
+  session's first provider call, so a trace of a finished session can say what
+  the model was told and not only what it said.
+
+### Security
+
+- Permission rules are matched against the path a specifier resolves to, not
+  the text it was written as. `deny: Read(~/.ssh/**)` was got past by asking
+  for `../../.ssh/id_rsa`, or through a symlink planted in the project. The
+  same resolution stops an allow rule leaking: `allow: Edit(src/**)` used to
+  cover `src/../../etc/passwd`.
+- `WebFetch` is matched against every URL it was given rather than the first,
+  so `deny: WebFetch(https://host/**)` is no longer a question of list order.
+  The approval prompt spells the URLs out too; it said `urls=[2 items]`, which
+  answered the only question that mattered with a number.
+- The generated Seatbelt profile no longer grants write access to all of
+  `/private/var/folders` - every user's and every process's temp and cache.
+  `$TMPDIR` was resolved precisely to avoid that, and the profile handed it
+  back on the next line. This user's own container stays writable.
+- `~/.hx/auth.json` is created with mode 0600 rather than narrowed to it after
+  the tokens are written, closing a window at a predictable path where the
+  credential was readable by any local account.
+- The OAuth callback page escapes what the provider sent. An `error` parameter
+  carrying markup ran as HTML on a loopback origin that is otherwise the
+  user's own.
+
+### Fixed
+
+- Slash commands read the session that is in force rather than the one HX
+  opened with. After `/resume`, `/trace` wrote a page of zeros into the empty
+  startup session's directory and `/cost` reported nobody's usage: the command
+  context had captured the session object at startup, and `/resume` rebinds it.
+- A session whose title was the trace template's own data placeholder had the
+  whole payload spliced into the page's `<title>`.
+- A trace labelled an encrypted reasoning block "thinking (signed)", which read
+  as though the page had dropped the rest of it. It now says the text is the
+  provider's summary and the reasoning came back encrypted, and a block that
+  arrived with no summary at all says that rather than rendering an empty box.
+- MCP servers survive a large response. One JSON-RPC message is one line and
+  asyncio's stream limit is 64 KiB, so a tool returning a file did not truncate
+  - it raised out of the read loop and killed the connection for the rest of
+  the session. The limit is now 16 MiB, and overshooting it says so.
+- A tool call is no longer dropped when a stream ends without a `finish_reason`.
+  The arguments were buffered until that field arrived, so a complete call was
+  discarded and the turn reported `end_turn`: the model appeared to stop for no
+  reason, and the tokens were already paid for.
+- The Linux sandbox starts again for anyone with credential *files*. Denied
+  paths were all shadowed with `--tmpfs`, which mounts a directory and aborts
+  bwrap when aimed at a file - and six of them are files, `~/.hx/auth.json`
+  among them. Files are shadowed with `/dev/null` instead. bwrap also starts in
+  the policy's directory rather than whatever `$PWD` happened to hold.
+- `PersistentShell.cwd` follows the shell. It claimed to track it and was in
+  fact the launch directory forever, which meant a background job always
+  started where the session opened rather than where `cd` had left it.
+- A background job no longer leaks its log file descriptor for the life of the
+  session.
+- A record appended while the transcript was being written is no longer
+  dropped. The queue is taken in one step, and a failed write puts its records
+  back rather than losing them.
+- An automatic compaction with nothing to summarise is no longer announced and
+  rerun every turn for the rest of the session. `/compact` still answers either
+  way.
+- `/trace` takes `--no-open`, and never launches a *terminal* browser: with no
+  display, `webbrowser` falls through to lynx or w3m, which opens in the
+  terminal HX is drawing on and takes the session display with it.
+
+---
+
 ## [0.2.3] - 2026-09-18
 
 ### Added
@@ -481,7 +565,8 @@ 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.3...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.4...HEAD
+[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
 [0.2.2]: https://github.com/aletisunil/hx/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/aletisunil/hx/compare/v0.2.0...v0.2.1

hx_cli-0.2.3/README.md → hx_cli-0.2.4/PKG-INFO

@@ -1,3 +1,42 @@
+Metadata-Version: 2.5
+Name: hx-cli
+Version: 0.2.4
+Summary: HX - an agent harness for the terminal
+Project-URL: Homepage, https://hx.sunilaleti.dev
+Project-URL: Documentation, https://hx.sunilaleti.dev
+Project-URL: Source, https://github.com/aletisunil/hx
+Project-URL: Issues, https://github.com/aletisunil/hx/issues
+Author: Sunil Aleti
+License: MIT
+Keywords: agent,cli,coding-agent,llm,openrouter,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pygments>=2.17
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: truststore>=0.10
+Requires-Dist: wcwidth>=0.2.13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pyte>=0.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pygments; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: symbols
+Requires-Dist: tree-sitter-language-pack>=0.7; extra == 'symbols'
+Requires-Dist: tree-sitter>=0.23; extra == 'symbols'
+Description-Content-Type: text/markdown
+
 # HX
 
 An agent harness for the terminal. Python core, its own terminal renderer,
@@ -260,6 +299,9 @@ hx -p "explain this repo"   # headless: streams to stdout, tool activity to stde
 hx resume                   # resume the last session here
 hx resume <session-id>      # resume a specific one
 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
+hx trace <id> out.html      # a specific session, to a path you choose
 hx --model openai/gpt-5     # override the model for one run
 hx --mode plan              # start read-only
 hx --cwd ../other-project   # run against a different directory
@@ -407,6 +449,7 @@ than being silently resolved.
 | `/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 |
 | `/copy` | copy the last reply to the clipboard |
+| `/trace [path]` | write the whole session to a self-contained HTML page |
 | `/fullscreen [on\|off]` | take the whole window, with the prompt pinned to the bottom |
 | `/mouse [on\|off]` | mouse reporting, and with it your terminal's own text selection |
 | `/init` | generate an `AGENTS.md` for the project |
@@ -652,6 +695,7 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `~/.hx/system-prompt.md` | your system prompt, replacing the built-in one |
 | `~/.hx/system-prompt-append.md` | text appended to whichever prompt is in force |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
+| `~/.hx/sessions/<id>/trace.html` | where `/trace` writes, unless you name a path |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
 | `~/.hx/projects/<project>/settings.local.json` | this machine's settings for one project - where "always allow" lands |
 | `./.hx/settings.json` | project settings, checked in if you like — read by HX, never written |
@@ -735,6 +779,79 @@ rest to the session directory, and hands the model that path to grep.
 
 ---
 
+## Tracing a session
+
+`/trace` writes everything that happened to one self-contained HTML file and
+opens it in a browser:
+
+```
+/trace                      # ~/.hx/sessions/<id>/trace.html
+/trace ~/Desktop/bug.html   # somewhere you choose
+```
+
+Everything means everything. The system prompt, the project context, the skills
+index, every tool schema as the provider received it, every prompt, every
+reply, every thinking block, every tool call next to the result it produced,
+the per-call token ledger, and the files HX changed. Late-injected reminders
+and compacted turns are in there too, behind a toggle that says how many there
+are — a trace that hides the reminders and the superseded turns is not a trace
+of the session that ran.
+
+Nothing is summarised and nothing is prettified. Assistant text is shown as it
+arrived, backticks and all, because a trace exists to answer "what actually
+went through" and a rendered version of that is a different document. Long tool
+results are folded rather than truncated, with the character count on the fold.
+
+**Thinking, where the provider allows it.** How much of a model's reasoning HX
+ever sees is the provider's decision, not HX's. Anthropic's models return the
+thinking itself. The Responses API - the OpenAI and Codex routes - returns a
+one-line summary in plaintext and the reasoning encrypted, to be replayed on
+the next call and read by nobody, HX included. A trace labels which of the two
+it is holding, because a one-line thinking block is otherwise indistinguishable
+from a trace that dropped the rest.
+
+A running session traces as it stands right now, including the turn that just
+landed. The page says so, because a trace of a live session is a snapshot.
+
+**Reading it.** Long tool results are folded and the reference panels - the
+prompt, the schemas, the ledger - start shut, so the transcript is what you
+land on. "Expand all" opens the whole page, panels included, and turns into
+"Collapse all". A session with no turns yet opens its panels on its own, since
+there is nothing else to read.
+
+**Dark or light.** The page follows your system by default and a button in the
+corner overrides it, remembered per browser. No stylesheet is fetched to do it.
+
+**Nothing is uploaded and nothing is fetched.** The payload, the stylesheet and
+the script all live in the file, so it opens offline, renders the same a year
+later, and a trace of a private repository stays as private as the directory
+you wrote it into. The embedded payload is also the machine-readable trace: it
+is JSON, in a `<script id="trace-data">` element, and `/trace` is the only way
+HX will ever put your transcript anywhere but `~/.hx`.
+
+From outside a session, on any transcript on the machine:
+
+```sh
+hx trace                        # the last session in this directory
+hx trace 20260918-214743-b5b8f9 # one by id
+hx trace ~/somewhere.html       # the last session, to a path you choose
+hx trace <id> ~/somewhere.html  # both, to a path or a directory
+open "$(hx trace)"              # the path is all that goes to stdout
+```
+
+`hx trace` reads the transcript and runs nothing, so it works on a session that
+ended months ago and on one another terminal has open right now.
+
+**What a trace can be missing.** The prompt and the tool schemas are written to
+the transcript on the session's first provider call — the first moment the tool
+registry has settled, because MCP servers connect after the loop is built. A
+session traced before that call, or one recorded by a version of HX older than
+this feature, has the transcript but not the prompt, and the page leaves those
+panels out rather than guessing. `/trace` inside a live session fills them in
+from the loop either way.
+
+---
+
 ## Reading and editing code
 
 **Line anchors.** `Read` labels every line with a short content hash:

hx_cli-0.2.3/PKG-INFO → hx_cli-0.2.4/README.md

@@ -1,40 +1,3 @@
-Metadata-Version: 2.5
-Name: hx-cli
-Version: 0.2.3
-Summary: HX - an agent harness for the terminal
-Project-URL: Homepage, https://github.com/aletisunil/hx
-Project-URL: Issues, https://github.com/aletisunil/hx/issues
-Author: Sunil Aleti
-License: MIT
-Keywords: agent,cli,coding-agent,llm,openrouter,tui
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.11
-Requires-Dist: httpx>=0.27
-Requires-Dist: markdown-it-py>=3.0
-Requires-Dist: pydantic>=2.7
-Requires-Dist: pygments>=2.17
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: truststore>=0.10
-Requires-Dist: wcwidth>=0.2.13
-Provides-Extra: dev
-Requires-Dist: mypy>=1.11; extra == 'dev'
-Requires-Dist: pyte>=0.8; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest-cov>=5.0; extra == 'dev'
-Requires-Dist: pytest>=8.2; extra == 'dev'
-Requires-Dist: ruff>=0.6; extra == 'dev'
-Requires-Dist: types-pygments; extra == 'dev'
-Requires-Dist: types-pyyaml; extra == 'dev'
-Provides-Extra: symbols
-Requires-Dist: tree-sitter-language-pack>=0.7; extra == 'symbols'
-Requires-Dist: tree-sitter>=0.23; extra == 'symbols'
-Description-Content-Type: text/markdown
-
 # HX
 
 An agent harness for the terminal. Python core, its own terminal renderer,
@@ -297,6 +260,9 @@ hx -p "explain this repo"   # headless: streams to stdout, tool activity to stde
 hx resume                   # resume the last session here
 hx resume <session-id>      # resume a specific one
 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
+hx trace <id> out.html      # a specific session, to a path you choose
 hx --model openai/gpt-5     # override the model for one run
 hx --mode plan              # start read-only
 hx --cwd ../other-project   # run against a different directory
@@ -444,6 +410,7 @@ than being silently resolved.
 | `/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 |
 | `/copy` | copy the last reply to the clipboard |
+| `/trace [path]` | write the whole session to a self-contained HTML page |
 | `/fullscreen [on\|off]` | take the whole window, with the prompt pinned to the bottom |
 | `/mouse [on\|off]` | mouse reporting, and with it your terminal's own text selection |
 | `/init` | generate an `AGENTS.md` for the project |
@@ -689,6 +656,7 @@ files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 | `~/.hx/system-prompt.md` | your system prompt, replacing the built-in one |
 | `~/.hx/system-prompt-append.md` | text appended to whichever prompt is in force |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
+| `~/.hx/sessions/<id>/trace.html` | where `/trace` writes, unless you name a path |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
 | `~/.hx/projects/<project>/settings.local.json` | this machine's settings for one project - where "always allow" lands |
 | `./.hx/settings.json` | project settings, checked in if you like — read by HX, never written |
@@ -772,6 +740,79 @@ rest to the session directory, and hands the model that path to grep.
 
 ---
 
+## Tracing a session
+
+`/trace` writes everything that happened to one self-contained HTML file and
+opens it in a browser:
+
+```
+/trace                      # ~/.hx/sessions/<id>/trace.html
+/trace ~/Desktop/bug.html   # somewhere you choose
+```
+
+Everything means everything. The system prompt, the project context, the skills
+index, every tool schema as the provider received it, every prompt, every
+reply, every thinking block, every tool call next to the result it produced,
+the per-call token ledger, and the files HX changed. Late-injected reminders
+and compacted turns are in there too, behind a toggle that says how many there
+are — a trace that hides the reminders and the superseded turns is not a trace
+of the session that ran.
+
+Nothing is summarised and nothing is prettified. Assistant text is shown as it
+arrived, backticks and all, because a trace exists to answer "what actually
+went through" and a rendered version of that is a different document. Long tool
+results are folded rather than truncated, with the character count on the fold.
+
+**Thinking, where the provider allows it.** How much of a model's reasoning HX
+ever sees is the provider's decision, not HX's. Anthropic's models return the
+thinking itself. The Responses API - the OpenAI and Codex routes - returns a
+one-line summary in plaintext and the reasoning encrypted, to be replayed on
+the next call and read by nobody, HX included. A trace labels which of the two
+it is holding, because a one-line thinking block is otherwise indistinguishable
+from a trace that dropped the rest.
+
+A running session traces as it stands right now, including the turn that just
+landed. The page says so, because a trace of a live session is a snapshot.
+
+**Reading it.** Long tool results are folded and the reference panels - the
+prompt, the schemas, the ledger - start shut, so the transcript is what you
+land on. "Expand all" opens the whole page, panels included, and turns into
+"Collapse all". A session with no turns yet opens its panels on its own, since
+there is nothing else to read.
+
+**Dark or light.** The page follows your system by default and a button in the
+corner overrides it, remembered per browser. No stylesheet is fetched to do it.
+
+**Nothing is uploaded and nothing is fetched.** The payload, the stylesheet and
+the script all live in the file, so it opens offline, renders the same a year
+later, and a trace of a private repository stays as private as the directory
+you wrote it into. The embedded payload is also the machine-readable trace: it
+is JSON, in a `<script id="trace-data">` element, and `/trace` is the only way
+HX will ever put your transcript anywhere but `~/.hx`.
+
+From outside a session, on any transcript on the machine:
+
+```sh
+hx trace                        # the last session in this directory
+hx trace 20260918-214743-b5b8f9 # one by id
+hx trace ~/somewhere.html       # the last session, to a path you choose
+hx trace <id> ~/somewhere.html  # both, to a path or a directory
+open "$(hx trace)"              # the path is all that goes to stdout
+```
+
+`hx trace` reads the transcript and runs nothing, so it works on a session that
+ended months ago and on one another terminal has open right now.
+
+**What a trace can be missing.** The prompt and the tool schemas are written to
+the transcript on the session's first provider call — the first moment the tool
+registry has settled, because MCP servers connect after the loop is built. A
+session traced before that call, or one recorded by a version of HX older than
+this feature, has the transcript but not the prompt, and the page leaves those
+panels out rather than guessing. `/trace` inside a live session fills them in
+from the loop either way.
+
+---
+
 ## Reading and editing code
 
 **Line anchors.** `Read` labels every line with a short content hash:

{hx_cli-0.2.3 → hx_cli-0.2.4}/pyproject.toml

@@ -60,7 +60,9 @@ dev = [
 hx = "hx.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/aletisunil/hx"
+Homepage = "https://hx.sunilaleti.dev"
+Documentation = "https://hx.sunilaleti.dev"
+Source = "https://github.com/aletisunil/hx"
 Issues = "https://github.com/aletisunil/hx/issues"
 
 # The version lives in the package, not here - three hand-maintained copies

{hx_cli-0.2.3 → hx_cli-0.2.4}/src/hx/__init__.py

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

{hx_cli-0.2.3 → hx_cli-0.2.4}/src/hx/auth/oauth/callback.py

@@ -12,6 +12,7 @@ where the browser reaches the host by another address.
 from __future__ import annotations
 
 import asyncio
+import html
 import os
 import threading
 from dataclasses import dataclass
@@ -49,7 +50,18 @@ p{{margin:0;color:#9aa4b2}}
 
 
 def _page(title: str, body: str, *, ok: bool) -> bytes:
-    return _PAGE.format(title=title, body=body, colour="#7ee787" if ok else "#ff7b72").encode()
+    """Render the one page this server serves.
+
+    Both fields are escaped: ``body`` carries the provider's ``error``
+    parameter, which arrives from the network and is under nobody's control
+    here. Interpolated raw, ``?error=<img src=x onerror=...>`` executed on an
+    origin that is otherwise this machine's own.
+    """
+    return _PAGE.format(
+        title=html.escape(title),
+        body=html.escape(body),
+        colour="#7ee787" if ok else "#ff7b72",
+    ).encode()
 
 
 class _Handler(BaseHTTPRequestHandler):

{hx_cli-0.2.3 → hx_cli-0.2.4}/src/hx/auth/store.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
 import time
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field, replace
@@ -172,9 +173,22 @@ class AuthStore:
         path.parent.mkdir(parents=True, exist_ok=True)
         payload = {pid: cred.to_json() for pid, cred in sorted(data.items())}
 
+        # Created 0600, not chmod'd to it afterwards. The file is opened at
+        # whatever the umask allows and only narrowed once the tokens are
+        # already in it, which leaves a window - at a path anyone can predict -
+        # where the credential is world-readable. Passing the mode to `open`
+        # closes it: there is no instant at which the descriptor exists and the
+        # permissions are wrong.
         tmp = path.with_suffix(".json.tmp")
-        tmp.write_text(json.dumps(payload, indent=2))
-        # Restrict before the rename so the token is never briefly world-readable.
+        descriptor = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                handle.write(json.dumps(payload, indent=2))
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+        # O_CREAT leaves an existing file's mode alone, so a store written by
+        # an older HX is narrowed here rather than keeping its old permissions.
         tmp.chmod(0o600)
         tmp.replace(path)
 

{hx_cli-0.2.3 → hx_cli-0.2.4}/src/hx/cli.py

@@ -4,6 +4,7 @@
 ``hx -p "..."``        print mode: run one prompt headless, stream to stdout
 ``hx resume [id]``     resume a session
 ``hx prompt``          print the resolved system prompt
+``hx trace [id]``      write a session to a self-contained HTML page
 ``hx mcp ...``         manage MCP servers
 ``hx docs [section]``  print the shipped manual
 ``hx changelog [ver]`` print what shipped in each version
@@ -35,6 +36,8 @@ Usage:
   hx -p, --print PROMPT     Run one prompt headlessly and print the result
   hx resume [SESSION_ID]    Resume a previous session
   hx prompt                 Print the system prompt this directory would use
+  hx trace [SESSION_ID] [PATH]
+                            Write a session to a self-contained HTML trace
   hx mcp list|add|remove    Manage MCP servers
   hx auth [set|clear]       Show or change the OpenRouter API key
   hx docs [SECTION|--all]   Print the manual, or one section of it
@@ -97,6 +100,8 @@ def _dispatch(args: list[str]) -> int:
         return run_auth_command(list(parsed.rest))
     if parsed.command == "prompt":
         return run_prompt_command(parsed)
+    if parsed.command == "trace":
+        return run_trace_command(parsed)
     if parsed.command == "docs":
         return run_docs_command(list(parsed.rest))
     if parsed.command == "changelog":
@@ -162,7 +167,7 @@ def parse_args(args: list[str]) -> ParsedArgs:
 
     if positional:
         head, *tail = positional
-        if head in {"resume", "prompt", "mcp", "upgrade", "auth"}:
+        if head in {"resume", "prompt", "trace", "mcp", "upgrade", "auth"}:
             parsed.command = head
             parsed.rest = tuple(tail)
             if head == "resume" and tail:
@@ -704,6 +709,81 @@ def run_prompt_command(parsed: ParsedArgs) -> int:
     return 0
 
 
+def _looks_like_a_path(arg: str) -> bool:
+    """Whether a lone ``hx trace`` argument is a destination, not a session id.
+
+    Session ids are ``20260918-215601-7608a6b0``: no separator, no extension,
+    no leading ``~`` or ``.``. Anything wearing one of those is somewhere the
+    user wants the file, and reading it as an id produces ``no session
+    '/Users/you/bug.html'`` - an error about the wrong thing entirely.
+    """
+    return (
+        "/" in arg or os.sep in arg or arg.startswith(("~", ".")) or arg.lower().endswith(".html")
+    )
+
+
+def run_trace_command(parsed: ParsedArgs) -> int:
+    """``hx trace [SESSION_ID] [PATH]`` - write a session out as one HTML page.
+
+    Reads the transcript rather than running anything, so it works on a session
+    that ended months ago and on one another terminal has open right now. A
+    live session traced this way is current as of its last flush, which is
+    every message; ``/trace`` inside that session is the one that also catches
+    the usage of a turn still in flight.
+
+    Either argument may be given alone. A lone one that looks like a path is
+    one, so ``hx trace ~/bug.html`` means what ``/trace ~/bug.html`` means
+    inside a session rather than hunting for a session by that name.
+    """
+    from hx.core.session import SessionNotFound, latest_session, load_session
+    from hx.trace import TRACE_FILENAME, build_trace, default_trace_path, write_trace
+
+    rest = list(parsed.rest)
+    cwd = (parsed.cwd or Path.cwd()).resolve()
+
+    target: str | None = None
+    session_id: str | None = None
+    if len(rest) > 1:
+        session_id, target = rest[0], rest[1]
+    elif rest:
+        if _looks_like_a_path(rest[0]):
+            target = rest[0]
+        else:
+            session_id = rest[0]
+
+    if session_id is None:
+        latest = latest_session(cwd)
+        if latest is None:
+            print(f"error: no sessions recorded for {cwd}", file=sys.stderr)
+            return 1
+        session_id = latest.session_id
+
+    try:
+        session = load_session(session_id)
+    except SessionNotFound:
+        print(f"error: no session {session_id!r}", file=sys.stderr)
+        return 1
+
+    destination = default_trace_path(session)
+    if target is not None:
+        # Relative paths stay relative to the shell, not to ``--cwd``: that flag
+        # picks the project to trace, and a shell user typing ``out.html`` means
+        # the directory they are standing in.
+        destination = Path(target).expanduser()
+        if destination.is_dir():
+            destination = destination / TRACE_FILENAME
+
+    try:
+        written = write_trace(build_trace(session), destination)
+    except OSError as exc:
+        print(f"error: could not write the trace: {exc}", file=sys.stderr)
+        return 1
+
+    # The path on stdout alone, so `open "$(hx trace)"` works.
+    print(written)
+    return 0
+
+
 def run_docs_command(args: list[str]) -> int:
     """``hx docs [SECTION|--all]`` - the manual that shipped with this version.