hexcli 2.8.0__tar.gz → 2.9.0__tar.gz

{hexcli-2.8.0 → hexcli-2.9.0}/.gitignore

@@ -53,3 +53,6 @@ docs/backend_study/data_npu_ab/
 docs/backend_study/_pre_restart/
 tools/backend_bench/.tok_*.txt
 tools/backend_bench/.battery_probe.ps1
+
+# python -m build output
+dist/

{hexcli-2.8.0 → hexcli-2.9.0}/CHANGELOG.md

@@ -6,6 +6,142 @@ the Hexagon NPU, not single-run anecdotes.
 
 ## Unreleased
 
+## 2.9.0 — 2026-09-13
+
+A minor release: `edit_file` and `write_file` behave differently for the
+model, and the launcher hands the agent its package path. Gate: extended
+suite at 5 runs PASS after recheck, uc1 at 6 runs, smoke 10/10, CI green.
+
+- `edit_file` merges the model's change into the file instead of pasting
+  its memory of the file. Multi-turn traces (uc1-t3/t4, 2026-09-13) show
+  the 4B rebuilding lines from the traceback in its history rather than
+  copying them: `for item in data` where the file says `items`, `"average":
+  average` where it says `avg`, a dropped trailing comment. Its
+  `old_string` then sits at 40–95 % similarity while the change it wants is
+  small and clear (`appned` → `append`; add a key to a dict). The old
+  fallback pasted `new_string` over the closest region when similarity was
+  ≥ 95 %, which installed the misremembered names: five of six live uc1-t4
+  runs ended in `NameError: name 'average' is not defined`, put there by the
+  harness, and the model then retried the same line four times. The paste
+  is gone. `protocol_v2._apply_one` now runs a token-level three-way merge
+  between the file's closest region, `old_string` and `new_string`: hunks
+  the model changed are applied where the file agrees with what the model
+  saw, tokens the model misremembered keep the file's text, and a hunk that
+  touches a misremembered token refuses (unless the "change" merely restates
+  what the file already says, which is skipped). Inserted lines are
+  re-indented by the delta between the model's line and the file's; a
+  whitespace run holding a newline never matches one that does not; a
+  replacement that would restate the tokens beside its anchor, grow into a
+  side the model did not see correctly, or carry JSON escapes into a file
+  that has no backslashes, refuses. Every refusal still reports the closest
+  region as before. Replaying the saved traces against the fixtures: of 20
+  distinct failed uc1-t3 edits 5 now apply correctly, 15 still error, 0
+  apply wrongly; of 23 non-exact uc1-t4 attempts 8 apply, 12 refuse, 0
+  produce a harmful file (the first draft produced two syntax errors, from
+  un-shifted indentation and literal `\"` sequences, both now refused or
+  fixed).
+- `edit_file` decodes a double-escaped `old_string`. 58 of 667 saved
+  edit_file calls (38 of them errors) carried `\"` or literal `\n` because
+  the model escaped its JSON arguments twice (agentic-3: `\"name\":
+  \"demo\"` for a file holding `"name": "demo"`). When the raw string is
+  absent from the file and the decoded one is present, both strings are
+  decoded once and the tiers run again. `write_file` does the same for a
+  body that is one line of literal `\n` sequences with no real line break
+  (1 of 389 saved calls), and leaves any body with a real newline alone.
+- Audit of the same bug classes elsewhere: protocol v2's `edit` action
+  shares the applier and gains all of the above; the JSON action parser
+  only tracks escapes to find brace boundaries and never re-escapes; tier 3
+  (indent shift) replaces whole lines and has no trailing-segment case;
+  `run_command` carried one escaped argument in 303 calls and it was a
+  legitimate regex.
+- The edit and write event lines name what landed a non-exact edit
+  (`, transfer match`, `, unescaped match`, `, indent match`; `, unescaped`
+  on a write) so an arm log shows which calls the fallbacks rescued; the
+  model still reads `Edited <path>` / `Wrote <path>`.
+- A checkout's launcher runs the checkout's code. `python -m hexcli.agent`
+  resolves the package from the working directory, then site-packages; the
+  Terminal profile starts in the home directory, so since the 2.8.0
+  packaging the launcher started from `Hex CLI.cmd` was silently running
+  the pip-installed copy (2.7.1 on the owner's machine on 2026-09-13,
+  found when a new input-line feature did not appear) while the checkout
+  sat unused. The launcher now prepends its own package's parent to the
+  child's `PYTHONPATH` (`_agent_env`), a no-op for an installed copy.
+- `run_recheck.cmd` documents that the case list must be quoted: cmd splits
+  an unquoted comma list into arguments, so the first 2026-09-13 recheck ran
+  one case and handed the second case's name to the gate as a baseline path.
+- Live numbers (fresh server per arm, 2026-09-13, a day with under 1 GB
+  free on the 16 GB machine). Smoke 10/10. uc1 at 6 runs: t1 6/6, t2 6/6,
+  t3 5/6 (3/3 on 09-12, 15/24 pooled over earlier arms; the miss called no
+  tool), t4 1/6 (0/3 in every baseline: the first pass ever, on a merged
+  insertion beside the file's own `avg`), t5 0/6, t6 0/6 as before; the
+  merge landed 13 edits across uc1/uc2 that would have errored. uc2 at 3
+  runs: t2 2/3 (the model edited on an explain-only turn; both stray edits
+  refused), the rest 3/3. uc3 at 3 runs, twice: every run invalid on both
+  attempts, the client's 300 s timeout expiring while the server answered
+  429 busy at ~3,200 tokens of context (the 09-12 baseline lost one of
+  three the same way; no HTP hang in the server log), so uc3 has no valid
+  measurement today. Extended suite at 5 runs, seed 20260913: 31/44 pass^5
+  (32/44 on the 2.7.x baseline, 31/41 on 09-05), run-level 162/205 vs
+  165/208, Fisher p=1.0; not one fallback tier fired in those 220 runs (the
+  event-line markers show none), so the suite is a regression check only.
+  Gate RECHECK on agentic-3 (4/5) and self-correct-1 (4/5); recheck at 6
+  runs: self-correct-1 5/6, agentic-3 4/6 (two double-escaped runs, one
+  rescued by the decode, one landing the model's own comma-less JSON, and
+  one old_string hallucinated three times) → gate FAIL; a second agentic-3
+  recheck on a fresh server 6/6 → gate PASS. Ceiling panel: +lint-1
+  3/5→5/5, +trap-4 0/5→1/5, −regression-anchor-1 5/5→4/5 (the model wrote
+  invalid JSON through an exact-match edit). Results:
+  `merge_transfer_r5.json`, `multiturn_uc{1,2,3}_merge_*_20260913.json`,
+  log `merge_transfer.log`; the earlier anchor-only tier's arm is
+  `delta_transfer_r5.json` (gate PASS after recheck, 27/44, superseded).
+
+## 2.8.1 — 2026-09-12
+
+A patch release: nothing model-facing and nothing the launcher hands the
+server changed. Gate: CI green on main; smoke 10/10 on a fresh
+server.
+
+- Installer repairs a Windows Terminal profile whose icon path 2.8.0
+  invalidated. The icon moved into the package (`hexcli/assets/`) that
+  release, but an existing "Hex CLI" profile kept pointing at the old
+  `assets/hexcli.png`; Terminal silently falls back to its own logo on a
+  missing file. `install.ps1` now rewrites a stale `hexcli.png` icon path
+  in a user's own profile with a targeted text edit, leaving the rest of
+  the profile untouched, and the fragment it writes already uses the
+  package path.
+
+- Releases carry the wheel and the source distribution and go to PyPI
+  (`pip install hexcli`): `.github/workflows/publish.yml` runs when a
+  release is published, builds both, attaches them and publishes through
+  PyPI trusted publishing. 2.8.0's files were attached by hand.
+- README rewritten shorter: the PyPI route sits in Install next to the
+  installer, the sample transcript the clips made redundant is gone, the
+  configuration table keeps the keys people change, memory and logs are a
+  short section under Usage, and the clips use absolute links so they
+  render on PyPI, in a two-by-two grid; the edit clip plays faster
+  (23 s, was 32 s). Version and CI badges at the top.
+- Paper and CLAUDE.md current through 2.8.0: the timeline row and the
+  closing state paragraph record the package and the classifier finding,
+  and the milestones table breaks across pages instead of running off
+  one (it had been overflowing page 9).
+- Paper numbers re-audited against the code and the latest results: the
+  window figure shows the 3,696-token server budget and the ~810-token
+  history it leaves instead of the disproven 2,600-token cliff; the
+  headline is 32/44 at pass^5 (LATEST.md) and 35/48 multi-turn; the
+  "9 s per new conversation" figure is retracted as the backend study
+  found; a paragraph carries that study's numbers (15.5 tok/s, 0.8 s warm
+  first token, polling-off power). ARCHITECTURE.md gets the same pass
+  (template in prompts.py, 29 suites, 44 cases, a dated note on the
+  pre-Rewind TTFT section) and the README's suite size reads 44.
+- Paper restructured to six pages: the abstract states the v2.8.0 numbers
+  and the thesis; the runtime lever (KV rewind, the context re-read) is
+  its own section between results and negative results; the status
+  section is one paragraph; the milestones table is one line per row; a
+  positioning paragraph names what the report sits next to; three
+  figures that duplicated prose (chip diagram, prompt anatomy, NPU/CPU
+  bars) are gone and their numbers kept in the text. Every figure in the
+  paper is unchanged from the audit above.
+
 ## 2.8.0 — 2026-09-12
 
 A minor release by RELEASING.md's rule (the launcher moved and its

{hexcli-2.8.0 → hexcli-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hexcli
-Version: 2.8.0
+Version: 2.9.0
 Summary: Local Hexagon NPU terminal agent for Snapdragon X Elite Windows ARM64
 Project-URL: Homepage, https://github.com/NathanL15/Hex-CLI
 Project-URL: Repository, https://github.com/NathanL15/Hex-CLI
@@ -27,61 +27,37 @@ Description-Content-Type: text/markdown
 
 # Hex CLI
 
+[![PyPI](https://img.shields.io/pypi/v/hexcli)](https://pypi.org/project/hexcli/)
+[![CI](https://github.com/NathanL15/Hex-CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/NathanL15/Hex-CLI/actions/workflows/ci.yml)
+
 Hex CLI is a coding agent for the Windows terminal, similar to aider or
 Claude Code, that runs a local model on the Snapdragon Hexagon NPU. It reads
 and edits files, runs commands, and checks its own work. The model is
 Qwen3-4B, served by [npurun](https://github.com/bpbonker/npurun). After
 setup it works offline.
 
-**Ask something.** The answer streams in, markdown and all, above an input
-box that stays on the last rows.
-
-![A question answered in bullet points](docs/gifs/ask.gif)
-
-**Ask about the machine.** Live state comes from a real command, shown as
-it runs.
-
-![The CPU name read with a PowerShell command](docs/gifs/machine.gif)
-
-**Change code.** Every file change prints a diff; when you ask for the
-tests, they run; `/diff` shows the turn's changes and `/undo` takes them
-back, files included.
-
-![A docstring added, the tests run, then undone](docs/gifs/edit.gif)
-
-**Nothing destructive runs unasked.** Commands are classified before they
-run; a delete asks first.
-
-![A delete command waits for a y/N before running](docs/gifs/safety.gif)
-
-```
-> the median calc in processor.py is wrong for even-length lists, fix it
-
-◆ read_file
-▸ [read] processor.py  (lines 1-40 of 40)
-
-◆ edit_file
-▸ [edit] processor.py  (+2 lines)
-~ processor.py  (+3 −1)
-@@ -12,4 +12,6 @@
--    return sorted(data)[len(data) // 2]
-+    mid = len(data) // 2
-+    if len(data) % 2 == 0:
-+        return (sorted(data)[mid - 1] + sorted(data)[mid]) / 2
-
-◆ run_code
-
-Fixed: even-length lists now average the two middle values. The test file
-prints 3.5 for [1, 2, 5, 6].
-
-──────────────────────────────────────────────────────────────────
-> ask, or / for commands
-──────────────────────────────────────────────────────────────────
-context ◔ 21%   npu 0%   mem 12.5/15.6 GB              ~\proj (main)
-```
-
-Your messages sit on a light band, the input box and status line stay on
-the last rows, and the answer streams in above them.
+<table>
+<tr>
+<td width="50%" valign="top">
+<b>Ask something.</b> The answer streams in, markdown and all, above an input box that stays on the last rows.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/ask.gif" alt="A question answered in bullet points" width="100%">
+</td>
+<td width="50%" valign="top">
+<b>Ask about the machine.</b> Live state comes from a real command, shown as it runs.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/machine.gif" alt="The CPU name read with a PowerShell command" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<b>Change code.</b> Every file change prints a diff; when you ask for the tests, they run; <code>/diff</code> shows the turn's changes and <code>/undo</code> takes them back, files included.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/edit.gif" alt="A docstring added, the tests run, then undone" width="100%">
+</td>
+<td width="50%" valign="top">
+<b>Nothing destructive runs unasked.</b> Commands are classified before they run; a delete asks first.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/safety.gif" alt="A delete command waits for a y/N before running" width="100%">
+</td>
+</tr>
+</table>
 
 ## Requirements
 
@@ -93,33 +69,42 @@ Tested on a Snapdragon X Elite. It will not run on x86 machines or on Macs.
 
 ## Install
 
+The installer does everything the machine allows:
+
 ```powershell
 git clone https://github.com/NathanL15/Hex-CLI
 cd Hex-CLI
 .\install.ps1
 ```
 
-The installer checks the machine, installs the package (`pip install .`,
-which gives you the `hex` and `hexcli` commands), downloads npurun, the
-model and the small embedding model that semantic memory uses, and runs
-`--doctor` when it finishes. It skips steps that are already done, so run
-it again after fixing anything it reports. Everything it writes for you
-lives in `~\.shellai`.
-
-It cannot download the QAIRT SDK for you, because Qualcomm does not allow
-redistribution. It prints instructions for that step and picks the SDK up on
-the next run. See [Setup by hand](#setup-by-hand) if you want to do the
-steps yourself.
-
-The Start Menu shortcut opens Hex in Windows Terminal when it is installed,
-through a "Hex CLI" profile the installer registers. It starts in your home
-folder; `/cwd <path>` moves into a project, whose `AGENTS.md` then applies. Text selection, copy
-and paste work there as in any other tab. Without Windows Terminal the
-shortcut uses the classic console, where drag-select is off because Hex
-disables QuickEdit (a click would otherwise freeze output); use the window
-menu's Edit, Mark to copy there. To have `hex` itself open in Windows
-Terminal from any shell, set it as the default terminal in its Settings,
-Startup.
+It checks the machine, installs the package, downloads npurun, the model
+and the small embedding model that memory uses, and runs `--doctor` when it
+finishes. It skips steps that are already done, so run it again after
+fixing anything it reports. Everything it writes for you lives in
+`~\.shellai`.
+
+The one thing it cannot download is the QAIRT SDK, because Qualcomm does
+not allow redistribution. It prints the instructions for that step and
+picks the SDK up on the next run.
+
+Or install from PyPI. The package is the same one the installer uses; you
+install the SDK yourself and the rest downloads itself:
+
+```powershell
+pip install hexcli       # the hex and hexcli commands
+hexcli --update          # downloads npurun
+hex                      # the first run downloads the model, about 2.5 GB
+```
+
+`hexcli --doctor` lists what is still missing and the command that fixes
+each item. Every [release](https://github.com/NathanL15/Hex-CLI/releases)
+also carries the wheel and the source distribution.
+
+The Start Menu shortcut opens Hex in Windows Terminal, through a profile
+the installer registers, starting in your home folder; `/cwd <path>` moves
+into a project. Without Windows Terminal it uses the classic console, where
+drag-select is off because Hex disables QuickEdit (a click would otherwise
+freeze output); use the window menu's Edit, Mark to copy there.
 
 ## Usage
 
@@ -133,14 +118,11 @@ hexcli --doctor                      # check the install
 hexcli --update                      # refresh npurun (and pull the source in a checkout)
 ```
 
-In a checkout without the package installed, `python launcher.py` and
-`python -m hexcli.agent` are the same two commands.
-
 Piped input is added to the request as context, or used as the request if
-there is no argument. Long input is trimmed to fit the context window.
-When stdout is not a terminal the answer is printed alone, with no
-progress text, so `hexcli "..." > answer.txt` and `hexcli "..." | clip`
-work.
+there is no argument. When stdout is not a terminal the answer is printed
+alone, so `hexcli "..." > answer.txt` and `hexcli "..." | clip` work. In a
+checkout without the package installed, `python launcher.py` and
+`python -m hexcli.agent` are the same two commands.
 
 ### Commands
 
@@ -165,10 +147,10 @@ work.
 | `/doctor` | check the install |
 | `Esc` | cancel the running step |
 
-You can add your own commands. Put a `.md` file in `.shellai/commands/` in
-the project, or `~/.shellai/commands/` for all projects, and `/<filename>`
-sends its content as the prompt. `$ARGUMENTS` in the file is replaced with
-whatever follows the command.
+You can add your own. Put a `.md` file in `.shellai/commands/` in the
+project, or `~/.shellai/commands/` for all projects, and `/<filename>`
+sends its content as the prompt, with `$ARGUMENTS` replaced by whatever
+follows the command:
 
 ```powershell
 # .shellai/commands/review.md contains: Review $ARGUMENTS for bugs and style issues.
@@ -188,21 +170,15 @@ whatever follows the command.
 | `Ctrl+V` | paste a block. Nothing is sent until you press Enter |
 | `Shift+Enter` | new line inside the entry |
 | `\` then `Enter` | continue on a new line |
-| `Ctrl+Plus` `Ctrl+Minus` | text size in the classic console |
 
-History is saved in `~/.shellai/input_history`. When stdin is not a
-terminal the agent falls back to plain `input()`, so pipes and CI work.
-
-The input box stays on the last rows of the window, and the conversation
-scrolls up above it. The status line under it
-shows how full the context is, the NPU load (the counter behind Task
-Manager's NPU graph), memory in use, and the working directory and branch.
-Set `status_bar` to `false` for the old inline prompt.
+The status line under the input box shows how full the context is, the
+NPU load, memory in use, and the working directory and branch. Set
+`status_bar` to `false` for a plain inline prompt.
 
 ### Project instructions
 
 If a project has an `AGENTS.md`, the agent reads it every turn. Keep it
-under about 1,200 characters. The model has a 4K token context and your
+under about 1,200 characters: the model has a 4K token context and your
 request has to fit in there too.
 
 ### Tools
@@ -213,9 +189,19 @@ request has to fit in there too.
 for the full signatures.
 
 `edit_file` tries an exact match first, then a whitespace-tolerant match,
-then a close match if there is exactly one. If the match is ambiguous it
-returns an error rather than guessing. `read_file` reads large files in
-pages. Every file change prints a diff and can be reverted with `/undo`.
+then a close match if there is exactly one; an ambiguous match returns an
+error rather than a guess. `read_file` reads large files in pages. Every
+file change prints a diff and can be reverted with `/undo`.
+
+### Memory and logs
+
+Memory is two local stores, one per project and one global, built on
+MiniLM embeddings. When idle, the agent condenses recent turns into short
+notes that later prompts include; `/memory` shows what is stored.
+
+Each session is written to `~/.shellai/chatlog/` as a JSONL file: every
+request, every message sent to the model, every reply with its latency,
+every tool call with its output. Secrets in the config are redacted.
 
 ## Safety
 
@@ -223,18 +209,16 @@ Commands are classified before they run:
 
 | Level | Examples | Behaviour |
 |---|---|---|
-| destructive | `Remove-Item`, `git reset --hard`, `format-*`, `iex` | asks first |
+| destructive | `Remove-Item`, `git reset --hard`, `Format-Volume`, `iex` | asks first |
 | sensitive | ssh/gpg/aws keys, hosts file, registry hives, credential stores, `-EncodedCommand` | asks first, denied when non-interactive |
 | safe | `Get-*`, `ls`, `git status` | runs |
 | caution | anything else | runs |
 
 File writes stay inside the working directory unless you widen the scope
 with `workspace_write_allow`. Reads can go anywhere. Key and credential
-paths are blocked for all file tools.
-
-`fetch_url` is the only tool that touches the network. It asks before every
-fetch, and is refused when non-interactive. Set `network_access` to
-`"deny"` to remove the tool or `"allow"` to skip the prompt.
+paths are blocked for all file tools. `fetch_url` is the only tool that
+touches the network; it asks before every fetch and is refused when
+non-interactive.
 
 Each classified command is appended to `.shellai/audit.log`. Text inside
 files and tool output is treated as data, not instructions. A 4B model does
@@ -244,45 +228,20 @@ doing so.
 ## Configuration
 
 Config is optional. `~\.shellai\shellai.json` and `.shellai/config.json`
-in a project are merged over the defaults, so you only need to write the
-keys you change. `shellai.example.json` lists every key with its default,
-and `/setup` writes the file for you.
+in a project are merged over the defaults, so you only write the keys you
+change. The ones people change:
 
 | Key | Default | Effect |
 |---|---|---|
 | `max_agent_steps` | `15` | tool calls per turn |
-| `live_streaming` | `true` | show the answer as it arrives |
-| `rich_input` | `true` | history, Tab completion, multi-line paste |
-| `side_padding` | `2` | left margin in columns |
-| `status_bar` | `true` | input box and status line at the bottom |
-| `user_highlight` | `true` | light band behind your messages in the transcript |
 | `show_diffs` | `true` | print a diff after each file change |
+| `status_bar` | `true` | input box and status line at the bottom |
 | `workspace_write_scope` | `true` | keep writes inside the working directory |
-| `autopilot_confirm_sensitive` | `true` | ask before touching keys and credentials |
-| `network_access` | `"ask"` | `"deny"` or `"allow"` |
-| `require_verification` | `true` | ask the agent to check its own edits |
-| `prompt_split` | `true` | answer plain questions without the tool loop |
-| `escalation_local_model` | `""` | a larger local model to consult when stuck |
+| `network_access` | `"ask"` | `"deny"` removes `fetch_url`, `"allow"` skips the prompt |
 | `memory_enabled` | `true` | semantic memory |
-| `chat_log_enabled` | `true` | write full session logs |
-| `protocol` | `"v1"` | `"v2"` is experimental |
 
-## Logs and memory
-
-Each session is written to `~/.shellai/chatlog/` as a JSONL file: every
-request, every message sent to the model, every reply with its latency,
-every tool call with its output. Secrets in the config are redacted.
-`/stats` prints the path of the current file.
-
-```powershell
-python tools/chatlog_report.py                  # summary across all sessions
-python tools/chatlog_report.py --last           # replay the most recent session
-python tools/chatlog_report.py --session 1a2b   # replay one session by id prefix
-```
-
-Memory is two local stores, one per project and one global, built on MiniLM
-embeddings. When idle, the agent condenses recent turns into short notes
-that are included in later prompts. `/memory` shows what is stored.
+`shellai.example.json` lists every key with its default, and `/setup`
+writes the file for you.
 
 ## Setup by hand
 
@@ -291,7 +250,7 @@ These are the steps `install.ps1` performs. `--doctor` checks each one.
 **1. The package**
 
 ```powershell
-pip install .        # from the checkout: the hex and hexcli commands, numpy, onnxruntime
+pip install hexcli   # or, from the checkout: pip install .
 ```
 
 `ruff` is optional and enables the `lint_code` tool.
@@ -313,22 +272,26 @@ setx ADSP_LIBRARY_PATH "C:\Qualcomm\AIStack\QAIRT_2.50.0\lib\hexagon-v73\unsigne
 If `ADSP_LIBRARY_PATH` is missing, npurun crashes with
 `STATUS_STACK_BUFFER_OVERRUN`.
 
-**3. npurun and a model**
-
-The NPU server is a fork of npurun, at
-[NathanL15/npurun](https://github.com/NathanL15/npurun) on the
-`hexcli-fork` branch. Each release there has a prebuilt `npurun-arm64.exe`.
-Hex CLI expects one specific build, set by `REQUIRED_NPURUN` in
-`hexcli/launcher.py`. `--doctor` fails on an older build and `--update`
-replaces it (the download goes to `~\.shellai\bin`).
+**3. npurun and the model**
 
-To build from source, use the fork. It has the prompt cache rewind, usage
-reporting, exact `max_tokens`, and request watchdog that Hex CLI relies on.
+The NPU server is a fork of npurun at
+[NathanL15/npurun](https://github.com/NathanL15/npurun), branch
+`hexcli-fork`, with a prebuilt `npurun-arm64.exe` on each release. Hex CLI
+expects one specific build, set by `REQUIRED_NPURUN` in
+`hexcli/launcher.py`; `hexcli --update` downloads it to `~\.shellai\bin`
+and `--doctor` fails on an older one. The fork adds the prompt cache
+rewind, usage reporting, exact `max_tokens` and the request watchdog that
+Hex CLI relies on, so upstream npurun will not do. To build it yourself:
 
 ```powershell
 git clone -b hexcli-fork https://github.com/NathanL15/npurun
 cd npurun
 cmd /c "scripts\dev-shell-local.bat cargo install --path crates\npurun-cli"
+```
+
+The model downloads on the first `hex` run, or by hand:
+
+```powershell
 npurun pull qwen3-4b-instruct-2507      # about 2.5 GB
 ```
 
@@ -357,7 +320,7 @@ curl -L -o ~\.shellai\onnx\tokenizer.json https://huggingface.co/sentence-transf
 
 ## Development
 
-CI runs `ruff` and 25 offline test suites against a mock backend, so no NPU
+CI runs `ruff` and 29 offline test suites against a mock backend, so no NPU
 is needed for those:
 
 ```powershell
@@ -369,14 +332,15 @@ python evals/test_lineedit.py
 
 The live evals need the NPU server. They check what the model actually did,
 by looking at the filesystem and the answer, and run each case several
-times because the model is not deterministic.
+times because the model is not deterministic:
 
 ```powershell
 python evals/cases_smoke.py                        # quick check
-python evals/cases_extended.py --runs 3            # 41 cases
+python evals/cases_extended.py --runs 3            # 44 cases
 python evals/cases_multiturn.py --runs 3 --think-time 15
 python evals/compare.py <before.json> <after.json>
 python evals/gate.py --baseline <base.json> <candidate.json>
+python tools/chatlog_report.py --last             # replay the most recent session
 ```
 
 Restart the NPU server before each suite. After an hour or two of steady