@qvac/harness 0.8.6 → 0.8.8

package/CHANGELOG.md

@@ -8,96 +8,346 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ## [Unreleased]
 
+## [0.8.8] - 2026-10-15
+
+### Added
+
+- A skill's manifest may declare `display_name`, the `@` handle users see and
+  type, as one word (letters, digits, `-` or `_`); a `display_name` that is
+  not one word is ignored. The Word and Excel skills are shown as Documents
+  and Spreadsheets, and their folder names are trademarks, so a host needs a
+  handle other than the name. Once the word skill's manifest declares
+  `display_name: Documents`, `@documents` resolves it, and `@word` still does,
+  so an app that sends the folder name keeps working. The catalog entry and
+  the `skills` wire carry `displayName`, a customized copy of a skill keeps
+  the shipped one, and `skillMentionHandle` gives a host the same rule the
+  harness matches on. The folder name stays the skill's key everywhere else.
+  (#469)
+
+### Fixed
+
+- A replayed tool call keeps its markup when history is rendered from scratch.
+  Every assistant turn lost its tool-call markup on the way in, so a retry,
+  compaction, a dropped chat cache, an overflow candidate or another device
+  showed the model an empty assistant turn followed by a result answering
+  nothing. Only an assistant turn that no tool result follows is stripped now,
+  which still keeps markup leaked into a final answer out of the prompt. (#402)
+- A web search the harness runs for "search the web" now ends on the same
+  continuation nudge as a search the model makes. Without it, the round after
+  the search often failed on Qwen3.5-9B with thinking on instead of answering.
+  (#486)
+- An identical call to a read tool that already succeeded this turn is
+  answered with a note pointing at the earlier result instead of running
+  again, and counts as a strike. A small model could repeat the same call
+  hundreds of times in one round until the context filled. Any other tool
+  that runs clears the memo, and a round is cut to its first 16 calls. (#377)
+- Asking the `skill` tool for a file a loaded skill does not have returns
+  guidance listing its real files instead of an error, so the app no longer
+  shows a failed tool call for it. A file asked of an unknown skill returns
+  `skill not found`. (#383)
+
+## [0.8.7] - 2026-10-12
+
+### Added
+
+- A skill's manifest may declare `env`, the variables its `exec` commands run
+  with. The child process env is an allowlist, so this is the only way a
+  skill's binary sees a setting of its own. The value `${session}` expands to
+  the chat the run belongs to, which lets a long-lived tool such as a browser
+  daemon keep one instance per chat; a run with no session drops that variable.
+  An overlay skill keeps the base skill's `env`, so an edit never widens what
+  a command can reach. `completion()` takes an optional `session`, in process
+  and over hrpc, and falls back to the first segment of `cacheKey`. (#341)
+
+  ```yaml
+  metadata:
+    env:
+      AGENT_BROWSER_SESSION: '${session}'
+      AGENT_BROWSER_HEADED: '1'
+  ```
+
+- A verb in a skill's `cli.schema.json` may carry `x-max-output-chars`, the
+  most output `exec` returns for that command. The ceiling wins over the
+  model's own `maxOutputChars`, the truncation note says which limit applied,
+  and a schema whose cap is not a positive integer fails to load. Page
+  snapshots and other verbose read verbs stay inside the context this way.
+  (#342)
+
+- The `browser` skill ships with `@qvac/skills` 0.1.14: an agent drives a
+  Chromium through the `agent-browser` CLI, scoped to `exec(agent-browser)`,
+  with one browser session per chat. (#405)
+
+- A chat model's context climbs as far as the device and the SDK allow when
+  neither the agent nor the host sets one: 262,144, then 131,072, then 65,536,
+  before the default. The device class caps the climb, the trained window from
+  the weight's GGUF header bounds it, and each rung must pass `assessModelFit`
+  with its own config. The choice is kept per pool key for the life of the
+  process. See the
+  [decision record](https://github.com/tetherto/qvac-harness/blob/v0.8.7/docs/decisions/2026-10-08-the-device-class-sets-how-far-the-context-climbs.md).
+  (#382)
+
+### Changed
+
+- **Breaking for hosts:** a skill named with `@` or in prose now reaches the
+  model as a `skill` call, its result and the continuation nudge right after the
+  request, exactly the round a load the model makes itself leaves, instead of
+  being written into the user's message. The user's turn is sent as typed and
+  the run stays on the chat's KV cache key, so its rounds and the turn after it
+  read the cached prefix; the child key 0.8.6 ran these turns under (#305) and
+  its delete are gone. The host must replay each run's turns as it sent them
+  (`@qvac/core` does from 0.7.0, tetherto/qvac-core#338): a host that collapses
+  a run to its request and answer leaves the cache's message count stale, and
+  the next turn's whole history is appended to the cache again. Because the body
+  is replayed as sent, an edit to the skill reaches such a chat on its next
+  mention of the skill, not on the next turn.
+
+- `bare-stow` 0.1.7, with the patches it made stale dropped. (#396)
+- `lunte` 1.8.6 and `lunte-plugin-qvac` 0.2.0. (#397)
+
+### Fixed
+
+- **Breaking:** a skill switched off on the agent can no longer be used. Naming
+  it with `@` or in prose loads nothing and unlocks nothing, and a chat that
+  loaded it earlier loses it as soon as it is switched off (QVAC-25357).
+  `skillIsActive` reads the agent's `enabledSkills` alone, and
+  `SkillActivation` drops its `mention` and `loadedSkills` fields. A host that
+  relied on a mention to grant a skill must enable it on the agent first. (#338)
+- A round that says nothing and calls nothing is re-asked on a history that
+  keeps that round's turn. The re-ask used to resend the history without it,
+  which the SDK, having cached the turn, read as stale: it sent the whole
+  history again and the addon appended it to the KV cache. (#403)
+- A model loaded by hand when nothing else is in memory is no longer refused,
+  even when its estimate is above the memory cap. Beside another model a
+  manual load is still refused, so it never piles a second model into memory.
+  (#394)
+
+- When llama.cpp overruns its grammar mid-round and a complete
+  `<function=…></function>` call has already streamed, the round ends on that
+  text and markup recovery runs the call, instead of the turn failing with
+  "Unexpected empty grammar stack". The held-back prose is flushed before any
+  rethrow, and the inference inspector reports the recovered round as
+  `completed` with the grammar error as its `reason`. (#370)
+
+- `@mention`s, the implicit skill preload and the explicit web-search check
+  read the turn as the user typed it (`CompletionContext.said`, carried in the
+  start frame's existing payload), so a host that rewrites the stored turn no
+  longer hides a mention. Hosts that do not send `said` behave as before.
+  (#372)
+
+- Office files keep their pictures off the text: in a deck a picture fills an
+  empty placeholder, sits below the text when there is room, and otherwise
+  takes the right half; an op aimed at a slide a later `addSlide` creates is
+  refused rather than moved. In a workbook `addImage` without a `cell` lands
+  beside the data, as `addChart` does, and a second picture or chart stacks
+  below the first. A nested op is named as its own entry in a tool error, and
+  the tool result says when an attached image went unused. (#406)
+
+### Removed
+
+- **Breaking:** `skillPreloadMessage` (`lib/tools/skills/mention.ts`) and
+  `withoutSkillLoadTurns` (`lib/capabilities/tool-turns.ts`). Nothing writes a
+  skill body into the user's message any more, so no earlier load turn has to
+  be dropped to keep the two from contradicting each other.
+- `CompletionSdk.deleteCache`. Nothing calls it now that the child key (#305)
+  and the chat-cache drop after a model-loaded skill (#373, reverted in #400)
+  are gone.
+
 ## [0.8.6] - 2026-10-08
 
 ### Added
 
-- `setModelMemoryCap(percent)` lets loaded models fill that share of the
-  device's memory budget, so chat models a request loaded stay loaded beside
-  each other while they fit, and a chat switching between them loads neither
-  again. A load that would not fit unloads idle models one at a time: image and
-  music models first, then embedding, speech and transcription models, then
-  chat models a request loaded, then those loaded by hand, least recently used
-  first. Each load is sized by `assessModelFit`, and `list()` rows of loaded
-  models carry the estimate as `memoryBytes`; `memoryUsage()` answers their
-  total. A manual `loadModel` of any kind never unloads another model. `0`, a mobile device, and a host
-  that never sets a cap keep one chat model a request loaded, as before
-  (QVAC-25735). (#358)
+- `setModelMemoryCap(percent)` keeps several models loaded side by side. Loaded
+  models may fill that share of the device's memory budget, so chat models a
+  request loaded stay loaded while they fit, and a chat switching between them
+  loads neither again.
+
+  A load that would not fit unloads idle models one at a time, least recently
+  used first within each group: image and music models first, then embedding,
+  speech and transcription models, then chat models a request loaded, then
+  those loaded by hand. A manual `loadModel` of any kind never unloads another
+  model.
+
+  Each load is sized by `assessModelFit`. `list()` rows of loaded models carry
+  the estimate as `memoryBytes`, and `memoryUsage()` answers their total. `0`,
+  a mobile device, and a host that never sets a cap keep one chat model a
+  request loaded, as before (QVAC-25735). See
+  [Keeping several models in memory](https://github.com/tetherto/qvac-harness/blob/v0.8.6/README.md#keeping-several-models-in-memory)
+  and the
+  [decision record](https://github.com/tetherto/qvac-harness/blob/v0.8.6/docs/decisions/2026-10-07-loaded-models-share-a-memory-budget.md).
+
+  ```js
+  await harness.setModelMemoryCap(85)
+
+  const { usedBytes } = await harness.memoryUsage()
+  const loaded = (await harness.list({ cachedOnly: true })).filter((m) => m.isLoaded)
+  // each loaded row carries memoryBytes, the estimate its load was sized by
+  ```
+
+  (#358)
+
 - `setDownloadsAllowed({ allowed })`, in process and over hrpc, lets a host hold
-  model downloads. While downloads are not allowed, a load whose model is not on
-  the device emits a `model` event with `status: 'held'` and the model's
-  download name and `addon`, then waits. It goes ahead once a `download()` puts
-  the model on the device or downloads are allowed again; aborting the caller's
-  signal ends it with `AbortedError`, and a wait that ends without loading
-  reports `error` with `message: 'aborted'`. This covers the image, music and translation
+  model downloads, for example while a phone is on cellular, so a request
+  cannot pull several GB without asking. Downloads are allowed by default, and
+  `download()` itself is never held: it is how the host fetches a held model
+  once the user approves.
+
+  While downloads are not allowed, a load whose model is not on the device
+  emits a `model` event with `status: 'held'`, the model's download name and
+  its `addon`, then waits. It goes ahead once a `download()` puts the model on
+  the device or downloads are allowed again. Aborting the caller's signal ends
+  it with `AbortedError`, and a wait that ends without loading reports `error`
+  with `message: 'aborted'`. This covers the image, music and translation
   runtimes and every pooled load (chat, embedding, speech, transcription).
-  `download()` is never held, and downloads are allowed by default. Over hrpc,
-  every model event frame now carries an `addon` field, which is `null` unless
-  the event is `held` or the `error` that ends a held wait. (#340)
+
+  Over hrpc, every model event frame now carries an `addon` field, which is
+  `null` unless the event is `held` or the `error` that ends a held wait. See
+  [Holding model downloads](https://github.com/tetherto/qvac-harness/blob/v0.8.6/README.md#holding-model-downloads)
+  and the
+  [decision record](https://github.com/tetherto/qvac-harness/blob/v0.8.6/docs/decisions/2026-10-07-a-load-waits-for-a-download-the-host-holds.md).
+
+  ```js
+  await harness.setDownloadsAllowed({ allowed: false })
+
+  harness.on('model', (state) => {
+    if (state.status === 'held') askToDownload(state.model, state.addon)
+  })
+
+  // later, once the user agrees
+  await harness.setDownloadsAllowed({ allowed: true })
+  ```
+
+  (#340)
+
 - Ternary Bonsai 2 27B joins the curated catalog in two builds,
   `Ternary-Bonsai-2-27B-PQ2_0` (7.2 GB) and `Ternary-Bonsai-2-27B-PTQ1_0`
   (5.9 GB), each with its vision projection. Both sit in the `high` tier, by
-  their memory footprint rather than their parameter count. As a Qwen3.8-27B
-  fine-tune whose name the SDK's dialect router does not recognise, it parses
-  tool calls as `qwen35`; a catalog entry can now name its tool dialect. (#303)
+  their memory footprint rather than their parameter count.
+
+  It is a Qwen3.8-27B fine-tune whose name the SDK's dialect router does not
+  recognise, so it parses tool calls as `qwen35`; a catalog entry can now name
+  its tool dialect.
+
+  ```js
+  import { BONSAI_2_27B_PTQ1 } from '@qvac/harness/model-catalog'
+
+  await harness.loadModel({ model: BONSAI_2_27B_PTQ1, agent: { ctxSize: 8192 } })
+  ```
+
+  (#303)
 
 ### Changed
 
 - `@qvac/sdk` and `@qvac/inference` 0.21.0, with `@qvac/llm-llamacpp` 0.55.0.
-  `@qvac/model-fit` leaves the native graph, and `@qvac/fabric` now ships its
-  prebuilds as per-platform packages (`@qvac/fabric-<os>-<cpu>`), so a host
-  that packages the addons exempts those names from any install age gate.
-  The fit check passes the model's source to the SDK's new `loadModel`-shaped
+  A host that packages the addons exempts `@qvac/fabric-<os>-<cpu>` from any
+  install age gate: `@qvac/fabric` now ships its prebuilds as those
+  per-platform packages. `@qvac/model-fit` leaves the native graph. The fit
+  check passes the model's source to the SDK's new `loadModel`-shaped
   `assessModelFit` input. (#302)
-- Transcription streams long audio to the model in 300 s segments instead of
-  decoding the whole clip first, so peak memory no longer grows with the clip's
-  length (a 3.8 h clip peaked at about 0.9 GB above baseline, down from 1.8
-  GB). Clips under 60 s are transcribed as before. (#291)
+- Transcribing long audio no longer needs memory in proportion to its length.
+  It streams the audio to the model in 300 s segments instead of decoding the
+  whole clip first: a 3.8 h clip peaked at about 0.9 GB above baseline, down
+  from 1.8 GB. Clips under 60 s are transcribed as before. (#291)
 
 ### Fixed
 
-- A run that preloads a skill (`@skill`, or a skill named in prose) caches its
-  prompt under a child of the chat's key for the length of the run, instead of
-  prefilling the whole prompt on every round of a tool loop. The child key is
-  deleted when the run ends. (#305)
+- A run that preloads a skill (`@skill`, or a skill named in prose) no longer
+  prefills the whole prompt on every round of a tool loop. It caches its prompt
+  under a child of the chat's key for the length of the run, and the child key
+  is deleted when the run ends. (#305)
 
 ## [0.8.5] - 2026-10-06
 
 ### Added
 
-- Skill-gated `pptx`, `docx` and `xlsx` tools on the office engine. A call takes
-  an `attachmentId` (or `create` options), `ops` that name engine methods with
-  named arguments, and an `output` file name; with an `attachmentId` alone it
-  returns the file's contents. The first failing op saves nothing and returns
-  the engine's error. An edit is never saved under the attached file's own
-  name. Saving the same file again in one turn answers with the one already
-  attached, and a changed file under that name is refused. The one-line answer
-  comes back as `reply`. These are the tools the presentations, word and excel
-  skills in `@qvac/skills` 0.1.12 call. (#286)
+- The model can now read, edit and create PowerPoint, Word and Excel files
+  without Python, on Bare and Node: skill-gated `pptx`, `docx` and `xlsx`
+  tools on the office engine. These are the tools the presentations, word and
+  excel skills in `@qvac/skills` 0.1.12 call.
+
+  A call takes an `attachmentId` (or `create` options), `ops` that name engine
+  methods with named arguments, and an `output` file name; with an
+  `attachmentId` alone it returns the file's contents. The first failing op
+  saves nothing and returns the engine's error.
+
+  An edit is never saved under the attached file's own name. Saving the same
+  file again in one turn answers with the one already attached, and a changed
+  file under that name is refused. The one-line answer comes back as `reply`.
+  See the
+  [office engine](https://github.com/tetherto/qvac-harness/blob/v0.8.5/lib/office/engine/README.md)
+  for the methods an op can name.
+
+  ```js
+  // the arguments a model passes to the pptx tool
+  {
+    create: { title: 'Q3 review' },
+    ops: [{ op: 'addSlide', title: 'Revenue', body: 'Up 12% on Q2' }],
+    output: 'q3-review.pptx'
+  }
+  ```
+
+  (#286)
 
 ### Changed
 
 - **Breaking:** `@qvac/skills` is now 0.1.12, whose office and pdf skills run on
   the `pptx`, `docx`, `xlsx` and `pdf` tools instead of Python. A host that
   passes its own `skillsDir` needs 0.1.12 as well: older office skills import
-  Python libraries this release no longer ships. (#286)
-- `extractOfficeText` and `extractDocxText` read .docx, .xlsx and .pptx in
-  process on the engine instead of starting Pyodide, and read at most 1M cells
+  Python libraries this release no longer ships. A host on the bundled skills
+  has nothing to do.
+
+  ```sh
+  # a host whose own skillsDir comes from @qvac/skills
+  # before
+  npm install @qvac/skills@0.1.11
+  # after
+  npm install @qvac/skills@0.1.12
+  ```
+
+  (#286)
+
+- `extractOfficeText` and `extractDocxText` no longer start Pyodide: they read
+  .docx, .xlsx and .pptx in process on the engine, and read at most 1M cells
   across a workbook. Extracted workbook booleans read `true`/`false` instead of
   `True`/`False`. `closeOfficeWorker` and `closeDocxWorker` remain as no-ops.
   (#286)
 - `exec` refuses Python that imports `pptx`, `docx` or `openpyxl`, or declares
-  their packages, before it runs, and names the tool (or the skill that grants
-  it) to use instead. (#287)
+  their packages, before it runs. The refusal names the tool (or the skill
+  that grants it) to use instead, so the model moves to the office tools
+  rather than trying to install the package. (#287)
 - **Breaking:** Python run through `exec` asks for approval like any other
-  write, including a run that only builds a new PDF. (#289)
+  write, including a run that only builds a new PDF. Those runs used to
+  skip `approve`; now the user is asked. The `pdf` tool, which builds PDFs now,
+  counts as a read and does not ask.
+
+  ```js
+  // before: exec running Python that only built a new PDF skipped approve
+  // after: it reaches approve as a write, like any other Python run
+  const context = {
+    model,
+    agent,
+    messages,
+    approve: async ({ name, effect }) => (effect === 'write' ? askUser(name) : true)
+  }
+  ```
+
+  (#289)
 
 ### Removed
 
 - **Breaking:** the vendored Python wheels for python-pptx, python-docx,
   openpyxl, fpdf2 and pypdf, and their dependencies. Only micropip is still
   seeded; any other package installs from PyPI, which sandbox mode refuses.
-  Use the office and `pdf` tools. (#286, #289)
+  Use the office and `pdf` tools.
+
+  ```js
+  // before: exec built a PDF offline with the vendored fpdf2
+  { language: 'python', command: 'from fpdf import FPDF\n...', outputs: ['report.pdf'] }
+  // after: the pdf tool builds it
+  { action: 'create', markdown: '# Report\n...', output: 'report.pdf' }
+  ```
+
+  (#286, #289)
+
 - The `exec` guidance written for python-pptx, python-docx and fpdf2 code:
   their error hints and source checks, and the shrink-to-fit pass on saved
   decks. (#288, #289)
@@ -106,42 +356,64 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ### Added
 
-- A skill-gated `pdf` tool on `bare-pdfium` 1.6.0. With an `attachmentId` and
-  no `action` it reads a PDF: the page count, each page's text and the form
-  fields. With an `action` it saves a new file named `output` and attaches it:
-  `create` from Markdown (chat images placed with `![caption](attachmentId)`),
-  `merge`, `split`, `rotate`, `watermark`, `fill`, `encrypt`, `decrypt` and
-  `text`. Errors name what exists, a locked PDF takes its password on any
-  action, and the one-line answer comes back as `reply`. On Node it reports
-  that the device cannot open PDFs. The pdf skill in the next `@qvac/skills`
-  release uses it instead of Python. (#256)
-- An office engine in `lib/office/engine/` that reads, edits and creates `.pptx`,
-  `.docx` and `.xlsx` files in TypeScript on Bare and Node, so office editing no
-  longer needs Python and can run on mobile. It keeps untouched parts byte for
-  byte, fails with a `DocsError` whose code names the problem, and moves Excel
-  references when rows and columns change. It adds `@xmldom/xmldom`, makes
-  `bare-zlib` a direct dependency and maps `#zlib` to `bare-zlib` or `zlib`.
+- The model can read, create and change PDFs without Python: a skill-gated
+  `pdf` tool on `bare-pdfium` 1.6.0. The pdf skill in the next `@qvac/skills`
+  release uses it instead of Python. On Node it reports that the device cannot
+  open PDFs.
+
+  With an `attachmentId` and no `action` it reads a PDF: the page count, each
+  page's text and the form fields. With an `action` it saves a new file named
+  `output` and attaches it: `create` from Markdown (chat images placed with
+  `![caption](attachmentId)`), `merge`, `split`, `rotate`, `watermark`, `fill`,
+  `encrypt`, `decrypt` and `text`.
+
+  Errors name what exists, a locked PDF takes its password on any action, and
+  the one-line answer comes back as `reply`.
+
+  ```js
+  // the arguments a model passes to the pdf tool
+  { attachmentId, action: 'rotate', degrees: 90, pages: [2], output: 'scan-rotated.pdf' }
+  ```
+
+  (#256)
+
+- An office engine in `lib/office/engine/` reads, edits and creates `.pptx`,
+  `.docx` and `.xlsx` files in TypeScript on Bare and Node, so office editing
+  no longer needs Python and can run on mobile. It is internal in this release:
+  the tools that drive it come in 0.8.5.
+
+  It keeps untouched parts byte for byte, fails with a `DocsError` whose code
+  names the problem, and moves Excel references when rows and columns change.
+  It adds `@xmldom/xmldom`, makes `bare-zlib` a direct dependency and maps
+  `#zlib` to `bare-zlib` or `zlib`. See the
+  [engine's README](https://github.com/tetherto/qvac-harness/blob/v0.8.0/lib/office/engine/README.md)
+  and the
+  [decision record](https://github.com/tetherto/qvac-harness/blob/v0.8.0/docs/decisions/2026-09-28-office-files-are-edited-by-the-harness-engine.md).
+  (#150)
 
 ### Fixed
 
-- Qwen3.5-family models: a tool call that ran goes back into the chat history
-  in the Qwen3.5 template's own format (`<tool_call>` wrapper, one line per tag,
-  string values as written) instead of a compact `<function=…>` line. A model
-  several calls into a turn copied the compact form, the tool grammar rejected
-  it, and the run ended in "This didn't finish". Models with another tool format
-  (e.g. MedPsy) still get a format that is not their own, until the SDK accepts
-  structured tool calls in history. (QVAC-23092, #146)
-- A skill loaded with a `file` it does not have, before its instructions were
-  loaded, now returns those instructions with a line naming the files it has,
-  so the skill counts as loaded and its skill-gated tools appear. Before, a
-  one-file skill answered that the model already had its instructions, and its
-  tools stayed hidden. (#257)
-- After a tool attaches a file, the loop tells the model the file is shown and
-  to answer, allows one more tool round, then writes the answer in a tool-less
-  round. Small models no longer keep calling tools on their own output until
-  the round cap. (#258)
-- `exec`: a `$` before a digit, a space or punctuation in a shell command is
-  escaped instead of rejected, so text like `$1,299` runs on the first try. Real
+- Qwen3.5-family models no longer stall several tool calls into a turn. A tool
+  call that ran goes back into the chat history in the Qwen3.5 template's own
+  format (`<tool_call>` wrapper, one line per tag, string values as written)
+  instead of a compact `<function=…>` line.
+
+  A model several calls into a turn copied the compact form, the tool grammar
+  rejected it, and the run ended in "This didn't finish". Models with another
+  tool format (e.g. MedPsy) still get a format that is not their own, until
+  the SDK accepts structured tool calls in history. (QVAC-23092, #146)
+
+- A skill's gated tools now appear when the model first asks the skill for a
+  file it does not have. Loaded with such a `file` before its instructions were
+  loaded, the skill returns those instructions with a line naming the files it
+  has, so it counts as loaded. Before, a one-file skill answered that the model
+  already had its instructions, and its tools stayed hidden. (#257)
+- Small models no longer keep calling tools on their own output until the round
+  cap. After a tool attaches a file, the loop tells the model the file is shown
+  and to answer, allows one more tool round, then writes the answer in a
+  tool-less round. (#258)
+- `exec`: text like `$1,299` in a shell command runs on the first try. A `$`
+  before a digit, a space or punctuation is escaped instead of rejected. Real
   shell expansion is still refused, now with a hint to single-quote the text.
   (#208)
 
@@ -149,223 +421,419 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ### Added
 
-- A tool result may carry `answer: true` beside its `content` to end the turn
-  with that content as the reply, without another round through the model.
-  The `tool-result` event still fires. `weather_lookup` uses it for an
-  ambiguous or unknown place: the question that lists the namesakes, or the
-  not-found line, is the reply.
+- A tool can now end the turn with its own answer. A tool result may carry
+  `answer: true` beside a non-empty `content`, and that content becomes the
+  reply without another round through the model. The `tool-result` event still
+  fires.
+
+  `weather_lookup` uses it for an ambiguous or unknown place: the question that
+  lists the namesakes, or the not-found line, is the reply.
+
+  ```js
+  const harness = new Harness({
+    tools: [
+      {
+        name: 'store_hours',
+        description: 'Opening hours of the store',
+        parameters: { type: 'object', properties: {} },
+        toolset: null,
+        effect: () => 'read',
+        execute: async () => ({ content: 'Open 9 to 5, Monday to Saturday.', answer: true })
+      }
+    ]
+  })
+  ```
+
+  (#153)
 
 ### Fixed
 
-- `weather_lookup` finds the place before it asks for the weather. It looks the
-  city up on Open-Meteo's geocoder, `geocoding-api.open-meteo.com`, a new
-  outbound host, and asks wttr.in for the forecast at the coordinates of the
-  place it picked, which leads the report. A bare "Nassau" now reports Nassau,
-  Bahamas. It used to ask wttr.in by name, whose own geocoder put it in
-  Westbury, New York. A name that places of a similar size share, such as
-  Springfield, gets a question listing up to four of them instead of a
-  forecast: any namesake with a tenth of the largest one's population counts.
-  A country or state in the request picks among them. When the geocoder is
-  blocked, slow or failing, or knows no such place, the lookup asks wttr.in by
-  name, as before. The resource label names both hosts.
+- `weather_lookup` reports the place that was asked about: a bare "Nassau" now
+  reports Nassau, Bahamas. It used to ask wttr.in by name, whose own geocoder
+  put it in Westbury, New York.
+
+  It now finds the place before it asks for the weather. It looks the city up
+  on Open-Meteo's geocoder, `geocoding-api.open-meteo.com`, a new outbound
+  host, and asks wttr.in for the forecast at the coordinates of the place it
+  picked, which leads the report. The resource label names both hosts.
+
+  A name that places of a similar size share, such as Springfield, gets a
+  question listing up to four of them instead of a forecast: any namesake with
+  a tenth of the largest one's population counts. A country or state in the
+  request picks among them. When the geocoder is blocked, slow or failing, or
+  knows no such place, the lookup asks wttr.in by name, as before. See the
+  [decision record](https://github.com/tetherto/qvac-harness/blob/v0.7.3/docs/decisions/2026-09-16-a-lookup-reports-the-place-it-resolved.md).
+  (#153)
 
 ## [0.7.2] - 2026-10-01
 
 ### Added
 
-- `web_fetch` attaches a plain-text file (.txt, .csv, .json…) to the chat
-  besides returning its text, so the user can open or save it and `exec` can
-  stage it to read past the returned text. The result carries its
-  `attachmentId`, `fileName` and `byteLength`. A body cut at the fetch cap is
-  not attached, and a host that cannot store files gets the text alone, as
-  with page images. (#147, #148)
+- A plain-text file `web_fetch` fetched (.txt, .csv, .json…) is now attached
+  to the chat besides its text being returned, so the user can open or save
+  it and `exec` can stage it to read past the returned text. The result
+  carries its `attachmentId`, `fileName` and `byteLength`.
+
+  A body cut at the fetch cap is not attached, and a host that cannot store
+  files gets the text alone, as with page images.
+
+  ```js
+  for await (const event of harness.completion(context)) {
+    if (event.type === 'tool-result' && event.name === 'web_fetch') {
+      const { attachmentId, fileName, byteLength } = event.result
+      // attachmentId is undefined when nothing was attached
+    }
+  }
+  ```
+
+  (#147, #148)
 
 ### Changed
 
 - Speech sounds cleaner on desktops. Devices on the `mid` profile and up now
   speak with Supertonic 3 FP16 (`Supertonic3-FP16`, 207 MB) instead of Q8_0
   (127 MB), at 16 inference steps instead of 5, which removes the artifacts
-  the 5-step output had. Synthesis takes about 2.7× as long, still around 7×
-  faster than real time on an M-series Mac. Phones (`low`) and `tiny` devices
-  keep Q4_0 at 5 steps. A host that prefetches `infraModelsFor` downloads the
-  FP16 model once; `Supertonic3-Q8_0` stays in the catalog, and now also runs
-  at 16 steps when a host asks for it by name. (#149)
+  the 5-step output had.
+
+  Synthesis takes about 2.7× as long, still around 7× faster than real time on
+  an M-series Mac. Phones (`low`) and `tiny` devices keep Q4_0 at 5 steps.
+
+  A host that prefetches `infraModelsFor` downloads the FP16 model once;
+  `Supertonic3-Q8_0` stays in the catalog, and now also runs at 16 steps when a
+  host asks for it by name.
+
+  ```js
+  import { defaultTtsModelName } from '@qvac/harness/model-defaults'
+
+  defaultTtsModelName('mid') // 'Supertonic3-FP16', was 'Supertonic3-Q8_0'
+  ```
+
+  (#149)
 
 ## [0.7.1] - 2026-09-30
 
 ### Added
 
-- `list()` rows carry `isLoading`: true from the moment a load of that model
-  starts, whoever asked for it, until it is ready or the load fails. It is read
-  off the pool, so a host shows a model as loading without counting loads
-  itself. A model loading again under other settings while a copy of it is
-  resident reads `isLoaded` and `isLoading` both true. Chat models read it
-  today: image, music and translation models load for each generation, and
-  speech, transcription and embedding pools key by source, so those rows read
-  `false` for now. An optional field on the wire; a row from an older harness
-  reads `false`. (#143)
+- A host can show a model as loading without counting loads itself. `list()`
+  rows carry `isLoading`: true from the moment a load of that model starts,
+  whoever asked for it (a request, `warmModel` or `loadModel`), until it is
+  ready or the load fails. It is read off the pool.
+
+  A model loading again under other settings while a copy of it is resident
+  reads `isLoaded` and `isLoading` both true. Chat models read it today. Image,
+  music and translation models load for each generation, and speech,
+  transcription and embedding pools key by source, so those rows read `false`
+  for now. It is an optional field on the wire; a row from an older harness
+  reads `false`. See
+  [Load and unload a model](https://github.com/tetherto/qvac-harness/blob/v0.7.1/README.md#load-and-unload-a-model).
 
   ```js
   const loading = (await harness.list({ cachedOnly: true })).filter((row) => row.isLoading)
   ```
 
+  (#143)
+
 ### Changed
 
-- The `model` event carries `catalogChanged` at every edge a `list()` re-read
-  would show: the `loading` that starts a load and the `ready` or `error` that
-  ends it, beside `unloaded`. Progress ticks still do not. A host that re-reads
-  the list on `catalogChanged` sees a model turn loading, then loaded, with no
-  bookkeeping of its own. The served event stream never drops a frame that
-  carries it, so two `ready` frames of one model under two keys both cross. (#143)
+- A host that re-reads `list()` on `catalogChanged` sees a model turn loading,
+  then loaded, with no bookkeeping of its own. The `model` event carries
+  `catalogChanged` at every edge a re-read would show: the `loading` that
+  starts a load and the `ready` or `error` that ends it, beside `unloaded`.
+  Progress ticks still do not.
+
+  The served event stream never drops a frame that carries it, so two `ready`
+  frames of one model under two keys both cross.
+
+  ```js
+  harness.on('model', async (state) => {
+    if (state.catalogChanged) render(await harness.list({ cachedOnly: true }))
+  })
+  ```
+
+  (#143)
+
 - `ModelInfo` requires `isLoading`, and `listModels`, `customModelRows` and
   `mergeCustomRows` return `CatalogRow`, the row before the pools are asked. A
-  typed fake `list()` adds the field. (#143)
+  typed fake `list()` adds the field.
+
+  ```js
+  // before
+  list: async () => [{ ...row, isLoaded: false }]
+
+  // after
+  list: async () => [{ ...row, isLoaded: false, isLoading: false }]
+  ```
+
+  (#143)
+
 - A custom model's row reads `isLoaded` only once its load has landed; it used
   to read `true` from the first attempt. (#143)
 
 ### Fixed
 
-- A load that ends without the model in memory emits `model` with `error` and
-  the reason: it failed, or a suspend or close cancelled it. It used to end in
-  silence, so a host could not tell a failed load from one still running. The
-  `error` also refreshes the cached `isCached`, since a load may have downloaded
-  the weights before it failed. (#143)
+- A host can tell a failed load from one still running. A load that ends
+  without the model in memory emits `model` with `error` and the reason in
+  `message`: it failed, or a suspend or close cancelled it. It used to end in
+  silence. The `error` also refreshes the cached `isCached`, since a load may
+  have downloaded the weights before it failed. (#143)
 
 ## [0.7.0] - 2026-09-29
 
 ### Added
 
-- `list()` rows carry `taskType`, what the model is for: `llm`, `embeddings`,
-  `speech-to-text`, `text-to-speech`, `image-generation`, `audio-generation`,
-  `translation`, `text-recognition` or `other`. It is decided from the addon in
-  one place, `lib/models/model-task.ts`, on each side of the wire rather than
-  sent over it. `ModelTaskType` is exported, and grows the four new values a
-  preview never returns. (#140)
+- A host can tell what each model is for without keeping its own table.
+  `list()` rows carry `taskType`: `llm`, `embeddings`, `speech-to-text`,
+  `text-to-speech`, `image-generation`, `audio-generation`, `translation`,
+  `text-recognition` or `other`.
+
+  It is decided from the addon in one place, `lib/models/model-task.ts`, on
+  each side of the wire rather than sent over it. `ModelTaskType` is exported,
+  and grows the four new values a preview never returns.
+
+  ```js
+  const rows = await harness.list({ cachedOnly: true })
+  const transcribers = rows.filter((row) => row.taskType === 'speech-to-text')
+  ```
+
+  (#140)
 
-- `modelsForAgent(agent, host)` lists every model an agent runs on a device,
+- `modelsForAgent(agent, host)` answers which models an agent runs on a device,
   each with its `use`: the chat model, clamped by `runnableModelName`, then the
   image and music models its skills need. A host deciding what to download, or
   which agents a model delete affects, asks this instead of working it out.
-  `runnableModelName(requested, host)` and `isMobilePlatform(platform)` move here
-  from `@qvac/core`: on a phone a pick above the device's profile runs as its
-  recommended model. Whether the host is a phone is the required `mobile` on
-  `HostCapability`, which `capability()` now reports, so its answer passes
-  straight in; a host built by hand has to say. Both functions are on the
-  browser-safe `@qvac/harness/model-catalog` entry too. (#141)
+
+  `runnableModelName(requested, host)` and `isMobilePlatform(platform)` move
+  here from `@qvac/core`: on a phone, a pick above the device's profile runs as
+  its recommended model. Whether the host is a phone is the required `mobile`
+  on `HostCapability`, which `capability()` now reports, so its answer passes
+  straight in; a host built by hand has to say. `runnableModelName` and
+  `isMobilePlatform` are on the browser-safe `@qvac/harness/model-catalog`
+  entry too.
 
   ```js
-  const chat = modelsForAgent(agent, await harness.capability()).find((m) => m.use === 'chat')
+  import { modelsForAgent, QWEN_35_9B } from '@qvac/harness'
+
+  const agent = {
+    modelName: QWEN_35_9B,
+    installedSkills: ['image-generation'],
+    skillsScope: 'all'
+  }
+  const models = modelsForAgent(agent, await harness.capability())
+  // [{ name, addon: 'llm', use: 'chat' }, { name, addon, use: 'image' }]
+  ```
+
+  ```js
+  import { runnableModelName, QWEN_35_4B, QWEN_35_9B } from '@qvac/harness/model-catalog'
+
+  const host = { capabilityProfile: 'mid', recommendedModelName: QWEN_35_4B, mobile: true }
+  runnableModelName(QWEN_35_9B, host) // QWEN_35_4B
+  ```
+
+  (#141)
+
+- `capability()` answers `mobile`, whether the harness runs on a phone, read
+  off the platform it probes. It rides `capability-response` as an optional
+  field; a response from an older harness reads as `false`.
+
+  ```js
+  const { mobile } = await harness.capability()
   ```
 
-- `capability()` answers `mobile`, whether the harness runs on a phone, read off
-  the platform it probes. It rides `capability-response` as an optional field;
-  a response from an older harness reads as `false`. (#141)
+  (#141)
+
+- A host no longer needs to know what `modelChoice` means in an agent's
+  `generate_music` tool settings. `musicModelChoiceFrom(settings)` reads the
+  music model pick out of them, and `isMusicModelChoice` is exported beside it.
+
+  ```js
+  import { musicModelChoiceFrom } from '@qvac/harness/music-catalog'
+
+  musicModelChoiceFrom({ modelChoice: 'turbo-hq' }) // 'turbo-hq'
+  musicModelChoiceFrom({}) // undefined
+  ```
 
-- `musicModelChoiceFrom(settings)` reads the music model pick out of an agent's
-  `generate_music` tool settings, so a host no longer knows what `modelChoice`
-  means there. `isMusicModelChoice` is exported beside it. (#141)
+  (#141)
 
 ### Changed
 
-- **Breaking:** the package no longer publishes a prebuilt sidecar:
+- **Breaking:** the package no longer publishes a prebuilt sidecar.
   `dist/harness.bundle`, `dist/harness.cjs`, `dist/prebuilds-manifest.json` and
   the `./dist/harness.cjs` export are gone. A host stows
   `worker/harness-sidecar.mjs` itself, as desktop and mobile already do, or
-  spawns `worker/stow-entry.mjs` straight from its install. (#127)
-- **Breaking:** a stowed harness runs python in a worker rather than in-process.
-  A host that stows the harness stops deferring `pyodide`, keeps
-  `QVAC_PYODIDE_CACHE_DIR` writable, no longer stages a separate worker bundle,
-  and ships what stow offloads beside the bundle, which now includes pyodide's
-  wasm, stdlib and lock file and the vendored wheels. A target that embeds
-  assets instead of offloading them cannot run python, since `fs` cannot read
-  inside a bundle. (#127)
-- A bundle of the package root carries neither pyodide nor the vendored wheels.
-  Only an entry that runs python, the exec tool or `@qvac/harness/docx` and
-  `/office`, pulls them in. (#127)
+  spawns `worker/stow-entry.mjs` straight from its install. See
+  [The published package](https://github.com/tetherto/qvac-harness/blob/v0.7.0/README.md#the-published-package)
+  and [Spawning](https://github.com/tetherto/qvac-harness/blob/v0.7.0/README.md#spawning).
+
+  ```js
+  // before
+  const harness = require('@qvac/harness/dist/harness.cjs')
+  const { ipc, sidecar, exit } = await harness.start(args)
+
+  // after
+  import { spawnHarness } from '@qvac/harness'
+
+  const harness = spawnHarness({
+    entry: require.resolve('@qvac/harness/worker/stow-entry.mjs'),
+    sdkStorage
+  })
+  ```
+
+  (#127)
+
+- **Breaking:** a stowed harness runs python in a worker rather than
+  in-process. A host that stows the harness:
+
+  - stops deferring `pyodide`
+  - keeps `QVAC_PYODIDE_CACHE_DIR` writable
+  - no longer stages a separate worker bundle
+  - ships what stow offloads beside the bundle, which now includes pyodide's
+    wasm, stdlib and lock file and the vendored wheels
+
+  A target that embeds assets instead of offloading them cannot run python,
+  since `fs` cannot read inside a bundle. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.7.0/docs/decisions/2026-09-25-the-python-worker-runs-on-bare-worker.md).
+  (#127)
+
+- A bundle of the package root carries neither pyodide nor the vendored
+  wheels. Only an entry that runs python pulls them in: the exec tool, or
+  `@qvac/harness/docx` and `/office`. (#127)
 - `SandboxHook` no longer checks `packages`. The exec tool refuses an install
   the vendored wheels do not hold in full in sandbox mode, whether declared in
   `packages` or on a pip line, with the same message as before. (#127)
 - The vendored wheels are the `#pyodide-wheels` directory asset on Bare;
   `QVAC_PYTHON_WHEELS_DIR` still overrides it. (#127)
 - The python worker and the in-process deadline are spawned through
-  `worker_threads`, which the package maps to `bare-worker`;
+  `worker_threads`, which the package maps to `bare-worker`.
   `#pyodide-worker-spawn` is gone. (#127)
-- **Breaking:** `engines.bare` is `>=1.34.0`, so Bare refuses to load the
-  package on older runtimes. `bare-runtime` is pinned to 1.34.0 and
-  `bare-sidecar` to 0.5.7 (Bare 1.34.0) across the tree, `bare-supervisor`'s copy
-  included, with `bare-thread` at least 1.2.7 and `bare-module` 7.1.0 for
-  `bare-worker`'s copy. (#127)
+- **Breaking:** Bare refuses to load the package on runtimes older than 1.34.0:
+  `engines.bare` is `>=1.34.0`. `bare-runtime` is pinned to 1.34.0 and
+  `bare-sidecar` to 0.5.7 (Bare 1.34.0) across the tree, `bare-supervisor`'s
+  copy included, with `bare-thread` at least 1.2.7 and `bare-module` 7.1.0 for
+  `bare-worker`'s copy. A host upgrades its Bare to 1.34.0 or later. (#127)
 - `bare-module` is no longer a dependency or an override, and
-  `bare-module-traverse` is overridden to 2.5.8: earlier versions drop the
+  `bare-module-traverse` is overridden to `~2.5.8`: earlier versions drop the
   `asset` condition on `bare-sidecar`'s binary, and a stowed harness then fails
   to boot on Bare 1.33 and later. (#127)
 - `skillModelsForAgent` rows carry `use`, `image` or `music`, so a caller can
-  tell which skill a model is for without looking the name up in the catalogs. (#141)
-- `CapabilityInfo` has a required `mobile`, so a `HarnessContract` whose
-  `capability()` builds its own answer, a test stub included, returns it too. (#141)
+  tell which skill a model is for without looking the name up in the catalogs.
+  (#141)
+- `CapabilityInfo` has a required `mobile`. A `HarnessContract` whose
+  `capability()` builds its own answer, a test stub included, returns it too.
+
+  ```js
+  // before
+  capability: async () => ({ capabilityProfile: 'mid', recommendedModelName: QWEN_35_4B })
+
+  // after
+  capability: async () => ({
+    capabilityProfile: 'mid',
+    recommendedModelName: QWEN_35_4B,
+    mobile: false
+  })
+  ```
+
+  (#141)
 
 ### Removed
 
-- **Breaking:** `bareRuntime` is no longer exported from `./lib/tools/exec.ts`.
-  It is at `./lib/tools/exec/bare-runtime.ts`, so the package root no longer
-  loads the exec tool to reach it. (#127)
-- **Breaking:** `QVAC_PYODIDE_TEST_LOADER`: tests point
-  `QVAC_PYODIDE_WORKER_ENTRY` at an entry that serves their fake interpreter. (#127)
+- **Breaking:** `bareRuntime` is no longer exported from `./lib/tools/exec.ts`,
+  so the package root no longer loads the exec tool to reach it. It is at
+  `./lib/tools/exec/bare-runtime.ts`.
+
+  ```js
+  // before
+  import { bareRuntime } from '@qvac/harness/lib/tools/exec.ts'
+
+  // after
+  import { bareRuntime } from '@qvac/harness/lib/tools/exec/bare-runtime.ts'
+  ```
+
+  (#127)
+
+- **Breaking:** `QVAC_PYODIDE_TEST_LOADER` is gone. A test points
+  `QVAC_PYODIDE_WORKER_ENTRY` at an entry that serves its fake interpreter.
+
+  ```sh
+  # before
+  QVAC_PYODIDE_TEST_LOADER=/path/to/fake-loader.js
+  # after
+  QVAC_PYODIDE_WORKER_ENTRY=/path/to/fake-worker-entry.js
+  ```
+
+  (#127)
 
 ### Fixed
 
-- Python runs start on Bare 1.34, whose threads cannot read a module off disk,
-  including in a stowed harness. The worker is spawned through `worker_threads`,
-  which the package maps to `bare-worker` on Bare, pyodide is handed its asm
-  module as `createPyodideModule`, and the files pyodide reads are named as
-  assets, so a bundler carries them beside the bundle. (#127)
+- Python runs start on Bare 1.34, including in a stowed harness. Threads there
+  cannot read a module off disk, so the worker is spawned through
+  `worker_threads`, which the package maps to `bare-worker` on Bare. Pyodide is
+  handed its asm module as `createPyodideModule`, and the files pyodide reads
+  are named as assets, so a bundler carries them beside the bundle. (#127)
 
 ## [0.6.0] - 2026-09-28
 
 ### Added
 
-- `loadModel({ model, agent })` loads a downloaded chat, embedding, speech or
-  transcription model ahead of use, under the key a request for it would load
-  under, so the first request finds it loaded. `unloadModel({ model })` unloads
-  every copy of a model once the requests holding it finish, and says whether it
-  could. Image and music models load for each generation and are refused. A load
-  or an unload counts as a call in flight for `setModelIdleTimeout`, and one that
-  lands during an idle unload waits for it. Also on the wire as `load-model` and
-  `unload-model`. (#133)
+- A host can load a model before anyone asks for it, and unload it on demand.
+  `loadModel({ model, agent })` loads a downloaded chat, embedding, speech or
+  transcription model under the key a request for it would load under, so the
+  first request finds it loaded. Pass the agent a chat model will run for: its
+  context size and KV cache types are part of that key.
+
+  `unloadModel({ model })` unloads every copy of a model once the requests
+  holding it finish, and says whether it could. Image and music models load for
+  each generation and are refused.
+
+  A load or an unload counts as a call in flight for `setModelIdleTimeout`, and
+  one that lands during an idle unload waits for it. Both are on the wire as
+  `load-model` and `unload-model`. See
+  [Load and unload a model](https://github.com/tetherto/qvac-harness/blob/v0.6.0/README.md#load-and-unload-a-model).
 
   ```js
+  import { QWEN_35_4B } from '@qvac/harness'
+
   const { loaded } = await harness.loadModel({ model: QWEN_35_4B, agent: { ctxSize: 8192 } })
   const { unloaded } = await harness.unloadModel({ model: QWEN_35_4B })
   ```
 
-- A chat model loaded with `loadModel` is pinned: it does not count against
-  `completionModelCap`, so several stay loaded at once and a request for
-  another model leaves them in place. A manual load never unloads another model
-  to fit; it returns `{ loaded: false, reason: 'memory' }` when the SDK's
-  `assessModelFit` says it would not fit beside what is loaded. A request always
-  gets its model: pinned models no reply is using give way oldest first when it would not fit,
-  and a request or a manual load for a model under other settings replaces its idle copy. Image and
-  music generation and an idle unload still clear every idle chat model. (#134)
+  (#133)
+
+- Several chat models can stay loaded at once. A chat model loaded with
+  `loadModel` is pinned: it does not count against `completionModelCap`, and a
+  request for another model leaves it in place.
+
+  A manual load never unloads another model to fit. It returns
+  `{ loaded: false, reason: 'memory' }` when the SDK's `assessModelFit` says it
+  would not fit beside what is loaded, so the host unloads one first. A request
+  always gets its model: when it would not fit, pinned models no reply is using
+  give way oldest first. A request or a manual load for a model under other
+  settings replaces its idle copy. Image and music generation and an idle
+  unload still clear every idle chat model, pinned or not. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.6.0/docs/decisions/2026-09-25-a-model-loaded-ahead-of-use-lands-where-its-request-looks.md).
 
   ```js
+  import { QWEN_35_9B } from '@qvac/harness'
+
   const { loaded, reason } = await harness.loadModel({ model: QWEN_35_9B })
   if (reason === 'memory') showNotice('Unload a model first')
   ```
 
+  (#134)
+
 ### Changed
 
-- A model loading or unloading in any pool emits `model` with `catalogChanged`,
-  not only a chat model, so `list()` reports a fresh `isLoaded` for embedding,
-  speech and transcription models too. (#133)
-- Speech, transcription and embedding requests key their pool entry by the
-  model's registry src however the caller names it, so a model named once by
-  its catalog name and once by its src is one copy in memory. (#133)
+- `list()` reports a fresh `isLoaded` for embedding, speech and transcription
+  models, not only chat models. A model loading or unloading in any pool now
+  emits `model` with `catalogChanged`. (#133)
+- A speech, transcription or embedding model named once by its catalog name and
+  once by its src is one copy in memory. Those requests key their pool entry by
+  the model's registry src however the caller names it. (#133)
 
 ### Fixed
 
 - A chat model loads when the host passes no `llmDevice`. 0.5.0 sent `device`,
   `gpu_layers`, `main-gpu` and `openclCacheDir` to the SDK as `undefined`,
-  which the SDK spreads over its defaults: with no device the load failed with
+  which the SDK spreads over its defaults. With no device the load failed with
   "must specify a device: 'gpu' or 'cpu'", and with a device but no
   `llmGpuLayers` the default of 99 GPU layers was lost. Unset fields are left
   out again. (#137)
@@ -374,25 +842,39 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ### Added
 
-- `setModelIdleTimeout(ms)` frees memory once the device has been idle that
-  long: with no `completion`, `invoke`, `embed`, `transcribe`, `speak`,
+- `setModelIdleTimeout(ms)` frees memory on a device that has sat idle that
+  long. With no `completion`, `invoke`, `embed`, `transcribe`, `speak`,
   `speakStream` or `warmModel` call in flight, every idle resident model is
-  unloaded, including the image, music and translation runtimes. The next call
-  loads what it needs again. `0`, the default, is Never, and arms no timer. A
-  turn waiting on a tool or an approval between rounds counts as busy, so it
-  keeps its model. Also on the wire as `set-model-idle-timeout`. (#131)
+  unloaded, including the image, music and translation runtimes, and the next
+  call loads what it needs again.
+
+  The clock is device-wide: any call resets it, whichever model it uses. `0`,
+  the default, is Never and arms no timer. A turn waiting on a tool or an
+  approval between rounds counts as busy, so it keeps its model. The call is on
+  an in-process `Harness`, on the `RemoteHarness` client, and on the wire as
+  `set-model-idle-timeout`. See
+  [Freeing memory when idle](https://github.com/tetherto/qvac-harness/blob/v0.5.0/README.md#freeing-memory-when-idle)
+  and
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.5.0/docs/decisions/2026-09-25-idle-unload-is-opt-in-and-device-wide.md).
 
   ```js
-  await harness.setModelIdleTimeout(30 * 60_000)
+  await harness.setModelIdleTimeout(30 * 60_000) // 0 turns it off
   ```
 
+  (#131)
+
 - `setCustomModels` entries take an optional `label`, the name the user gave
-  the model, and `list()` rows carry it as `label`. The tool-call format is
-  matched against the label as well as the file name, so a custom model
-  registered under an opaque id still gets its family's format. (#124)
+  the model, and `list()` rows carry it back as `label`.
+
+  The label also picks the tool-call format: the model family (Qwen, Gemma,
+  LFM and so on) is matched against the label as well as the file name, with
+  spaces read as hyphens, so a custom model registered under an opaque id
+  still gets its family's format. (#124)
 
 - `setCustomModels` entries take an optional `contextLength`, the model's
-  trained window. (#124)
+  trained window, which caps the context it loads with by default (see
+  Changed). Pass the preview's `contextLength` straight through. See
+  [Register the set](https://github.com/tetherto/qvac-harness/blob/v0.5.0/README.md#register-the-set).
 
   ```js
   await harness.setCustomModels([
@@ -403,23 +885,39 @@ While the major version is `0`, a breaking change bumps the minor version.
       contextLength: preview.contextLength
     }
   ])
+
+  const [row] = (await harness.list({ type: 'llm' })).filter(
+    (model) => model.name === 'custom-7f3a'
+  )
+  row.label // 'Gemma 4 E4B'
   ```
 
+  (#124)
+
 ### Changed
 
 - A custom model loads with a context of the smaller of 51,200 tokens and its
-  trained `contextLength`, instead of the default. An asked-for context size
+  trained `contextLength`, where it always took 51,200 before. A model trained
+  on 40,960 tokens now loads with 40,960. A context size the caller asks for
   still wins. (#124)
 
 ### Fixed
 
 - `previewModelSource` takes a direct link to one shard of a split `.gguf` as
-  the whole set: `src` is the first part, `sizeBytes` adds up every part, and
-  the label names the count, as in `model.gguf (3 parts)`. A missing part
-  refuses with `not-found` or `unreachable`. (#124)
-
-- `isCached` reports a sharded custom download once every shard is on disk,
-  and `deleteModel` removes all of its shards. (#124)
+  the whole set. `src` is the first part, which holds the metadata, and
+  `sizeBytes` adds up every part, so `isCached` can match the finished
+  download. Every part is checked with a `HEAD` request, and a missing part
+  refuses with `not-found` or `unreachable`, naming the part. See
+  [Preview a source before adding it](https://github.com/tetherto/qvac-harness/blob/v0.5.0/README.md#preview-a-source-before-adding-it).
+  (#124)
+
+- `isCached` reports a sharded custom download once every shard is on disk in
+  the folder the SDK keeps them in; it always read false before. `deleteModel`
+  removes all of its shards, where it left them behind. See
+  [List them](https://github.com/tetherto/qvac-harness/blob/v0.5.0/README.md#list-them)
+  and
+  [Delete a download](https://github.com/tetherto/qvac-harness/blob/v0.5.0/README.md#delete-a-download).
+  (#124)
 
 ## [0.4.0] - 2026-09-24
 
@@ -428,27 +926,48 @@ While the major version is `0`, a breaking change bumps the minor version.
 - `previewModelSource({ src, mmprojSrc })` checks a Hugging Face link, a direct
   `.gguf` link or a local path before a host adds it as a custom model. It
   reads the Hugging Face metadata and the file's GGUF header, never the whole
-  model. The answer is a file to register (`src`, `sizeBytes`,
-  `contextLength`, `architecture`, `sizeLabel`, `taskType`, `license`, `fit`
-  and `fitReasons`), a list of `files` to pick from for a repo that holds
-  several, or `ok: false` with a `refusal` code and a `reason` to show. It is
-  served on the `RemoteHarness` client and on an in-process `Harness`, and its
-  types are exported from the package root. (#121)
+  model.
+
+  The answer is one of three:
+
+  - a file to register: `ok: true` with `src`, `sizeBytes`, `contextLength`,
+    `architecture`, `sizeLabel`, `taskType`, `license`, `fit` and
+    `fitReasons`;
+  - a choice: `ok: true` with a list of `files` and no `src`, for a repo that
+    holds several weights;
+  - a refusal: `ok: false` with a `refusal` code and a `reason` to show.
+
+  It is served on the `RemoteHarness` client and on an in-process `Harness`,
+  and its types (`ModelSourcePreview`, `ModelSourceFile`,
+  `ModelSourceRefusal`, `ModelFitVerdict`, `PreviewModelSourceContext`) are
+  exported from the package root. See
+  [Preview a source before adding it](https://github.com/tetherto/qvac-harness/blob/v0.4.0/README.md#preview-a-source-before-adding-it)
+  and
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.4.0/docs/decisions/2026-09-22-a-model-source-is-previewed-before-it-is-added.md).
 
   ```js
   const preview = await harness.previewModelSource({ src: link })
 
   if (!preview.ok) return showError(preview.reason)
-  if (!preview.src) return pickOneOf(preview.files) // then preview files[i].src
-  if (preview.taskType !== 'llm') return showError('Only an llm runs as a custom model')
+  if (!preview.src) return pickOneOf(preview.files) // preview the pick next
+  if (preview.taskType !== 'llm') {
+    return showError('Only an llm runs as a custom model')
+  }
   ```
 
-- `setCustomModels` entries take `taskType` and `expectedSize`, and `list()`
-  returns the registered custom models after the catalog rows, with
-  `registrySource: 'custom'`, `isLoaded`, and an `isCached` that is false
-  until every file is on disk and, when `expectedSize` is set, adds up to it.
   (#121)
 
+- `setCustomModels` entries take `taskType` and `expectedSize`, and `list()`
+  returns the registered custom models after the catalog rows, under the same
+  `type` and `cachedOnly` filters.
+
+  A custom row has `registrySource: 'custom'` and `isLoaded`. Its `isCached`
+  is false until every file is on disk and, when `expectedSize` is set, their
+  sizes add up to it, so a partial download is not cached. See
+  [Register the set](https://github.com/tetherto/qvac-harness/blob/v0.4.0/README.md#register-the-set)
+  and
+  [List them](https://github.com/tetherto/qvac-harness/blob/v0.4.0/README.md#list-them).
+
   ```js
   await harness.setCustomModels([
     {
@@ -464,56 +983,90 @@ While the major version is `0`, a breaking change bumps the minor version.
   const custom = models.filter((model) => model.registrySource === 'custom')
   ```
 
+  (#121)
+
 - A `modelsDir` Harness option says where downloads live, so `list()` and
   `deleteModel` can find a custom model's files. The spawned sidecar sets it
-  from its SDK storage; an in-process `Harness` has to pass it. (#121)
+  from its SDK storage; an in-process `Harness` has to pass it. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.4.0/docs/decisions/2026-09-24-a-custom-download-is-found-at-the-sdk-cache-path.md).
 
   ```js
   const harness = new Harness({ modelsDir })
   ```
 
+  (#121)
+
 ### Changed
 
-- `deleteModel(name)` removes the weight and projection a custom model
-  downloaded, where it used to remove nothing. It never touches a local path
-  the user pointed at, and the model stays registered, listed as not cached.
-  (#121)
+- `deleteModel(name)` frees the disk a custom model's download took: it
+  removes the weight and projection the model downloaded, where it used to
+  remove nothing.
+
+  It never touches a local path the user pointed at, since those are the
+  user's files. The model stays registered and lists as not cached, ready to
+  download again. See
+  [Delete a download](https://github.com/tetherto/qvac-harness/blob/v0.4.0/README.md#delete-a-download).
 
   ```js
   const { removed, freedBytes } = await harness.deleteModel('nanbeige-3b')
   ```
 
+  (#121)
+
 - A custom model name resolves only where an `llm` is loaded, never for
-  another task, and a `setCustomModels` entry whose `taskType` is anything
-  other than `llm` is not registered. An entry without `taskType` is an `llm`,
-  as before. (#121)
+  another task. A `setCustomModels` entry whose `taskType` is anything other
+  than `llm` is not registered. An entry without `taskType` is an `llm`, as
+  before, so a host that registers only text models changes nothing. (#121)
 
 ### Fixed
 
-- A turn that preloads a skill with `@skill`, or names an active skill in its
-  prompt, no longer caches the inlined SKILL.md body under the chat's KV key.
-  Each such turn left about 7k tokens stranded in the cache, until a later turn
-  overflowed the context window and failed. (#120)
+- A chat no longer fails with a context overflow after turns that load a
+  skill up front. A turn that preloads a skill with `@skill`, or names an
+  active skill in its prompt, used to cache the inlined SKILL.md body under
+  the chat's KV key. Each such turn left about 7k tokens stranded in the
+  cache, until a later turn overflowed the context window and failed. (#120)
 
 ## [0.3.3] - 2026-09-24
 
 ### Changed
 
-- `@qvac/sdk` and `@qvac/inference` 0.20.0. Some addons now ship their
-  prebuilds as per-platform packages (`@qvac/<addon>-<os>-<cpu>`, for
-  `audiogen-ggml` 0.4 and `tts-ggml` 0.9), which the addon names in its
-  `#host-addon` import map, and `@qvac/model-fit` and `@qvac/fabric` join the
-  native graph as deferred addons. A host that packages the addons resolves
-  prebuilds through that map, and exempts the new package names from any
-  install age gate: bun skips a blocked optional dependency without a word,
-  and the prebuild goes missing. (#85)
+- `@qvac/sdk` and `@qvac/inference` 0.20.0. A host that packages the addons
+  has packaging work to do.
+
+  Some addons now ship their prebuilds as per-platform packages
+  (`@qvac/<addon>-<os>-<cpu>`, for `asr-ggml` 0.5, `audiogen-ggml` 0.4 and
+  `tts-ggml` 0.9), which the addon names in its `#host-addon` import map, and
+  `@qvac/model-fit` and `@qvac/fabric` join the native graph as deferred
+  addons. The harness no longer pins `@qvac/asr-ggml` and lets the SDK resolve
+  it.
+
+  A host that packages the addons resolves prebuilds through that map, and
+  exempts the new package names from any install age gate: bun skips a blocked
+  optional dependency without a word, and the prebuild goes missing. See
+  [The published package](https://github.com/tetherto/qvac-harness/blob/v0.3.3/README.md#the-published-package).
+
+  ```toml
+  # bunfig.toml, for each host the app ships to
+  [install]
+  minimumReleaseAgeExcludes = [
+    "@qvac/model-fit",
+    "@qvac/asr-ggml-darwin-arm64",
+    "@qvac/audiogen-ggml-darwin-arm64",
+    "@qvac/tts-ggml-darwin-arm64"
+  ]
+  ```
+
+  (#85)
+
 - A user message with several images reaches the SDK as one turn again. The
   per-image split added for QVAC-24156 is gone, since SDK 0.20 carries the
   upstream fix (llama.cpp #27348) and equal-size still images no longer merge
-  as video frames and abort the encode. This release must not be paired with
-  SDK 0.19, where that crash comes back. `<key>-vision-history-v1` cache
-  directories left by the split are no longer read, and clearing all caches
-  removes them. (#116)
+  as video frames and abort the encode.
+
+  This release must not be paired with SDK 0.19, where that crash comes back.
+  `<key>-vision-history-v1` cache directories left by the split are no longer
+  read, and clearing all caches removes them. (#116)
+
 - `@qvac/skills` 0.1.9. The diagrams skill carries every recipe inline, so a 2B
   model no longer loops on loading a reference file it cannot name. The excel
   skill routes a chat image to create rather than edit, the Google OAuth routes
@@ -531,16 +1084,21 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ### Changed
 
-- A networked Python run's approval label leads with the hosts its source names
-  in a URL, as `python · network: www.youtube.com …`, or says
+- A person approving a networked Python run now sees where it will connect,
+  and any other host is asked about as the run reaches it.
+
+  The approval label leads with the hosts the source names in a URL, as
+  `python · network: www.youtube.com …`, or says
   `network: no host named in the code`. On an approved run those hosts, and
-  their `www.` form, are reached without asking; a subdomain is not. Any other
-  host, such as a CDN a library fans out to, a redirect or a URL built at
-  runtime, pauses the run and is asked about through the completion's
+  their `www.` form, are reached without asking; a subdomain is not.
+
+  Any other host, such as a CDN a library fans out to, a redirect or a URL
+  built at runtime, pauses the run and is asked about through the completion's
   `askUser` before its name is looked up. A host allowed once stays allowed
   for that run, and silence past a minute counts as a no. A host that does not
   wire `askUser` refuses every unnamed host, and a skip-all run asks nothing.
-  (#109)
+  See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.2/docs/decisions/2026-09-22-python-reaches-the-network-through-the-guarded-fetch.md).
 
   ```js
   for await (const event of harness.completion({
@@ -555,52 +1113,85 @@ While the major version is `0`, a breaking change bumps the minor version.
   }
   ```
 
+  (#109)
+
 ### Fixed
 
-- A timed-out Python run spun at full CPU until the process was killed when
-  Pyodide had no worker thread, as for a stowed bundle whose host does not set
-  `QVAC_PYODIDE_WORKER_ENTRY`. It is now interrupted at the deadline, rejects
-  with `Command timed out after <ms>ms`, and the interpreter keeps its state. A
+- A timed-out Python run no longer spins at full CPU until the process is
+  killed when Pyodide has no worker thread, as for a stowed bundle whose host
+  does not set `QVAC_PYODIDE_WORKER_ENTRY`.
+
+  It is now interrupted at the deadline, rejects with
+  `Command timed out after <ms>ms`, and the interpreter keeps its state. A
   blocking call such as a long `time.sleep` still sees the interrupt only once
-  it returns. (#104)
-- A timed-out Python run on the worker thread could miss its SIGINT, so the
-  worker was killed after the grace window along with the interpreter's state.
-  The interrupt is resent every 100 ms until the run settles. (#112)
-- A Python run that failed partway through a save attached the half-written
-  file, and each failing retry attached another copy under the same name. A
-  non-zero exit now attaches nothing and reports every declared output in
-  `missingOutputs`. (#110)
+  it returns. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.2/docs/decisions/2026-08-11-pyodide-worker-thread.md).
+  (#104)
+
+- A timed-out Python run on the worker thread keeps its interpreter state. It
+  could miss its SIGINT, so the worker was killed after the grace window along
+  with the interpreter's state. The interrupt is now resent every 100 ms until
+  the run settles. (#112)
+
+- A Python run that fails no longer attaches a broken file. A run that failed
+  partway through a save attached the half-written file, and each failing
+  retry attached another copy under the same name. A non-zero exit now
+  attaches nothing and reports every declared output in `missingOutputs`, so
+  the retry writes it again. (#110)
 
 ### Security
 
 - Python in `exec` reached the network whenever the runtime allowed it,
   including a call that auto-ran as a read with no approval prompt, so a
   document build that loads an image from a URL could reach the web without
-  anyone seeing it. The network now opens only to a call a person approved or
-  that skip-all let through, and sandbox mode stays offline. 0.3.1 is affected.
+  anyone seeing it.
+
+  The network now opens only to a call a person approved or that skip-all let
+  through, and sandbox mode stays offline. 0.3.1 is affected; upgrade from it.
+  See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.2/docs/decisions/2026-09-22-python-reaches-the-network-through-the-guarded-fetch.md).
   (#108)
 
 ## [0.3.1] - 2026-09-23
 
 ### Added
 
-- Python in `exec` reaches the network on Bare: `urllib`, `http.client` and
-  what is built on them, yt-dlp included, work unchanged, and `requests` works
-  through urllib3's emscripten backend. Every request goes through the guarded
-  fetch the web tools use, so each hop is checked before it is sent,
-  credentials do not follow a redirect to another origin, and a response is
-  capped at 100 MB. Where the global `fetch` is not the guarded one, as on
-  Node, Python stays offline, and sandbox mode keeps it offline everywhere. A
-  Python run may now declare `.mp4`, `.webm`, `.m4a` and `.mp3` outputs, each
-  checked by its file signature. (#94)
-- `SkillOAuthConfig.verify`, parsed from a skill manifest's
-  `setup.routes[].oauth.verify` and carried over the wire, so a host can probe a
-  fresh token before saving it. A probe is an https `url` on the same site as
-  the route's `tokenUrl`, an optional `GET` or `POST` `method` and JSON `body`,
-  and `reject` rules. A rule matches a listed `status`, or a 2xx JSON body whose
-  `field` is not `notEqual`, and its `error` names the rejection. A probe that
-  breaks these rules is dropped and the route kept. `SkillOAuthVerify` and
-  `SkillOAuthVerifyRule` are exported. (#105)
+- Python in `exec` reaches the network on Bare. `urllib`, `http.client` and
+  what is built on them, yt-dlp included, work unchanged, and `requests`
+  works through urllib3's emscripten backend.
+
+  Every request goes through the guarded fetch the web tools use: each hop is
+  checked before it is sent, credentials do not follow a redirect to another
+  origin, and a response is capped at 100 MB. Where the global `fetch` is not
+  the guarded one, as on Node, Python stays offline, and `sandboxMode` keeps
+  it offline everywhere. A Python run may now declare `.mp4`, `.webm`, `.m4a`
+  and `.mp3` outputs, each checked by its file signature. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.1/docs/decisions/2026-09-22-python-reaches-the-network-through-the-guarded-fetch.md).
+  (#94)
+
+  ```js
+  // exec arguments a model can now send on Bare
+  {
+    language: 'python',
+    command:
+      "import urllib.request\n" +
+      "urllib.request.urlretrieve('https://example.com/talk.mp3', 'talk.mp3')",
+    outputs: ['talk.mp3']
+  }
+  ```
+
+- A host can probe a fresh OAuth token before saving it.
+  `SkillOAuthConfig.verify` is parsed from a skill manifest's
+  `setup.routes[].oauth.verify` and carried over the wire;
+  `SkillOAuthVerify` and `SkillOAuthVerifyRule` are exported. The harness
+  only parses the probe; the host runs it.
+
+  A probe is an https `url` on the same site as the route's `tokenUrl`, an
+  optional `GET` or `POST` `method` and JSON `body`, and `reject` rules. A
+  rule matches a listed `status`, or a 2xx JSON body whose `field` is not
+  `notEqual` (a rule with both needs both), and its `error` names the
+  rejection. A probe that breaks these rules is dropped and the route kept.
+  (#105)
 
   ```js
   const skills = await harness.skills()
@@ -615,63 +1206,95 @@ While the major version is `0`, a breaking change bumps the minor version.
   ```
 
 - A skill operation may name `response.decode` to turn a provider's JSON body
-  into a compact shape before the model sees it, starting with
-  `gmail-message`: the ids and labels, the From, To, Subject, Date, Message-ID
-  and References headers, the snippet, and the body as text, capped at 4000
-  characters. A `gmail-get` request builder joins it. A manifest naming both
-  `pick` and `decode`, or a builder or decoder this harness does not have, is
-  rejected. (#69)
+  into a compact shape before the model sees it. The first decoder is
+  `gmail-message`: the ids and labels, the From, To, Subject, Date,
+  Message-ID and References headers, the snippet, and the body as text,
+  capped at 4000 characters. A `gmail-get` request builder goes with it.
+
+  A manifest naming both `pick` and `decode`, or a builder or decoder this
+  harness does not have, is rejected. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.1/docs/decisions/2026-09-01-skill-operation-manifests.md).
+  (#69)
+
+  ```js
+  // an operation in a skill's operations.json (gmail, @qvac/skills 0.1.7)
+  {
+    tool: 'gmail_get',
+    request: {
+      method: 'GET',
+      url: 'https://gmail.googleapis.com/gmail/v1/users/me/messages/{id}',
+      query: { metadataHeaders: 'Subject,From,To,Date,Message-ID,References' },
+      builder: 'gmail-get'
+    },
+    response: { decode: 'gmail-message' }
+  }
+  ```
 
 ### Changed
 
-- A compiled skill operation whose HTTP method is `GET`, `HEAD` or `OPTIONS` is
-  a read: it auto-runs without an approval prompt, like the same request through
-  `http_request`, and takes no `intent` argument. MCP operations and every other
-  method are still writes that ask. (#69)
-- `@qvac/skills` 0.1.7, now pinned exactly: Gmail reads a message with
+- A compiled skill operation whose HTTP method is `GET`, `HEAD` or `OPTIONS`
+  now runs without an approval prompt. It is a read, like the same request
+  through `http_request`, and takes no `intent` argument. MCP operations and
+  every other method are still writes that ask. (#69)
+- `@qvac/skills` 0.1.7, now pinned exactly. Gmail reads a message with
   `gmail_get` instead of telling the model to decode base64, which needs this
   release's decoder, and Asana rejects a non-MCP app at connect time through
   a `verify` probe. (#105)
 
 ### Fixed
 
-- A malformed `<tool_call>` left its JSON arguments in the reply. The whole span
-  is now stripped, and an unclosed one is stripped to the end of the text.
-  (#100)
+- A malformed `<tool_call>` left its JSON arguments in the reply. The whole
+  span is now stripped, and an unclosed one is stripped to the end of the
+  text. (#100)
 - A misspelt, placeholder or repeated `skill` load returned an error the model
   retried until the turn ran out. A placeholder or the skill's own name now
-  reads the body, a near miss of one of its files loads that file, and a repeat
-  is acknowledged without re-reading it. (#101)
+  reads the body, a near miss of one of its files loads that file, and a
+  repeat is acknowledged without re-reading it. (#101)
 - When the model reached for `pip` or a video tool on the shell path, it was
   only told what the path is not, and retried the same call. Each refusal now
   names the call that works, such as `packages: ["requests"]` with the pin a
-  vendored package installs offline under. A missing import names the package
-  that provides it, and `python -c`, a heredoc or bare Python source runs as
-  Python instead of being sent back for a `language` argument. (#71)
+  vendored package installs offline under.
+
+  A missing import names the package that provides it, and `python -c`, a
+  heredoc or bare Python source runs as Python instead of being sent back for
+  a `language` argument. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.1/docs/decisions/2026-09-21-exec-names-the-call-that-works.md).
+  (#71)
 
 ## [0.3.0] - 2026-09-23
 
 ### Added
 
-- A `translate` capability for `invoke`: it translates text without loading an
-  LLM. The language pair picks the route before anything loads. English and
-  one of nine European languages go through the TranslatePsy-EuroNano packs,
-  the other 43 languages Bergamot serves go through their per-pair models
-  (pivoting through English when neither side is English), and 16 languages
-  Bergamot has no model for go through TranslatePsy-AfriSLM, named by ISO 639-1
-  or FLORES-200 code. An omitted `from` is detected from the text, except for
-  the AfriSLM languages, which need it named. The `tool-result` carries the
-  text, the pair and the `engine` that answered. (#76)
+- A `translate` capability for `invoke`: text translation without loading an
+  LLM. The language pair picks the route before anything loads:
+
+  - English and one of nine European languages go through the
+    TranslatePsy-EuroNano packs.
+  - The other 43 languages Bergamot serves go through their per-pair models,
+    pivoting through English when neither side is English.
+  - 16 languages Bergamot has no model for go through TranslatePsy-AfriSLM,
+    named by ISO 639-1 or FLORES-200 code.
+
+  An omitted `from` is detected from the text, except for the AfriSLM
+  languages, which need it named. The `tool-result` carries the text, the pair
+  and the `engine` that answered (`nmt`, `slm`, or `none` when the text is
+  already in the target language). A pair no route serves, or a source that
+  cannot be detected, comes back as `result.error`. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.0/docs/decisions/2026-09-21-translation-pivots-through-english.md).
+  (#76)
 
   ```js
   for await (const event of harness.invoke({
     capability: 'translate',
     args: { text: 'The weather is nice today.', to: 'de' }
   })) {
-    if (event.type === 'tool-result') show(event.result.text)
+    if (event.type === 'tool-result') {
+      if (event.result.error) showError(event.result.error)
+      else show(event.result.text)
+    }
     if (event.type === 'error') showError(event.message)
   }
-  // result: { text, from, to: 'de', engine: 'nmt', pivoted: false }
+  // result: { text, from: 'en', to: 'de', engine: 'nmt', pivoted: false }
   ```
 
 - `translationPlanFor`, `NMT_TO_ENGLISH`, `NMT_FROM_ENGLISH`,
@@ -688,18 +1311,23 @@ While the major version is `0`, a breaking change bumps the minor version.
   if ('error' in plan) showError(plan.error)
   ```
 
-- `enhance: 'never' | 'auto'` on `invoke`. With `'auto'`, an image prompt is
-  rewritten by a model already resident on the device, and never triggers a
-  load: with nothing resident, or a rewrite that fails, the run goes direct.
+- `enhance: 'never' | 'auto'` on `invoke`, for the `image` capability. With
+  `'auto'`, the prompt is rewritten by a model already resident on the
+  device, and never triggers a load: with nothing resident, or a rewrite that
+  fails, the run goes direct. Omitting `enhance` behaves as `'never'`, which
+  passes the arguments through untouched.
+
   `metrics` reports the `route` taken (`direct` or `enhanced`), the
-  `routeModel` used and the tokens the rewrite spent. Omitting `enhance`
-  behaves as `'never'`, which passes the arguments through untouched. (#77)
+  `routeModel` used and the tokens the rewrite spent. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.3.0/docs/decisions/2026-09-21-a-caller-states-constraints-not-mechanisms.md).
+  (#77)
 
   ```js
   for await (const event of harness.invoke({
     capability: 'image',
     args: { prompt: 'funny meme' },
-    enhance: 'auto'
+    enhance: 'auto',
+    attach
   })) {
     if (event.type === 'metrics') log(event.route, event.routeModel)
   }
@@ -707,33 +1335,56 @@ While the major version is `0`, a breaking change bumps the minor version.
 
 ### Changed
 
-- The bundle defers `@qvac/translation-nmtcpp` like the other inference
-  addons, so `prebuilds-manifest.json` now names its prebuilds and a host that
-  assembles them beside the bundle has to include it. It is already a
-  dependency of `@qvac/sdk`. (#76)
+- A host that assembles the native prebuilds beside the bundle now has to
+  include `@qvac/translation-nmtcpp`. The bundle defers it like the other
+  inference addons, so `prebuilds-manifest.json` names its prebuilds. It is
+  already a dependency of `@qvac/sdk`, so it is in the host's
+  `node_modules`. See
+  [The published package](https://github.com/tetherto/qvac-harness/blob/v0.3.0/README.md#the-published-package).
+  (#76)
 
 ## [0.2.12] - 2026-09-22
 
+The first published release with the 0.2.11 changes (`invoke`,
+`detectLanguage`, `SkillOAuthConfig`), plus the fix below.
+
 ### Fixed
 
-- Sandbox mode refused every `exec` call that installs packages, which broke
-  the pdf, presentations, word and excel skills. A request whose packages are
-  all vendored now installs from the shipped wheels; one that would fall back
-  to PyPI is still refused. (#91)
+- The pdf, presentations, word and excel skills work again under
+  `sandboxMode`. Sandbox mode refused every `exec` call that installs
+  packages, including installs that never leave the device.
+
+  A request whose packages are all vendored, each pinned to the version the
+  shipped wheels carry, now installs from those wheels. One unvendored
+  package, an unpinned version, or a host that ships no wheels would fall
+  back to PyPI, and is still refused. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.2.12/docs/decisions/2026-09-21-sandbox-mode-no-network.md#consequences).
+  (#91)
 
 ## [0.2.11] - 2026-09-22
 
 Tagged but never published to npm; these changes first shipped in 0.2.12.
+Install 0.2.12 or later to get them.
 
 ### Added
 
 - `invoke({ capability, args })` runs one capability on its own, with no
   model, no dispatch and no approval callback: the caller already decided.
-  `image` is the first capability. It is a frame on the existing `completion`
-  stream, so it takes the same `attach`, `progress` and abort signal and emits
-  the same `tool-call`, `tool-result`, `metrics`, `error` and `aborted` events.
-  `metrics` reports `totalTokens: 0`. It is on `Harness` and `RemoteHarness`
-  alike, and optional on `HarnessContract`. (#74)
+  `image` is the first capability, and `CAPABILITIES` and `isCapability` list
+  and check the names.
+
+  It is a frame on the existing `completion` stream, so it takes the same
+  `attach`, `progress` and abort signal, and emits the same `tool-call`,
+  `tool-result`, `metrics`, `error` and `aborted` events. `metrics` reports
+  `totalTokens: 0`. An optional `agent` supplies the image defaults (model,
+  steps, size). A failure inside the tool, such as a missing `attach`, comes
+  back as `result.error` on the `tool-result`; the `error` event is for a
+  capability the device lacks or a tool that threw.
+
+  It is on `Harness` and `RemoteHarness` alike, and optional on
+  `HarnessContract`. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.2.11/docs/decisions/2026-09-21-a-run-that-loads-no-model.md).
+  (#74)
 
   ```js
   for await (const event of harness.invoke({
@@ -743,14 +1394,20 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
     progress,
     signal
   })) {
-    if (event.type === 'tool-result') showImage(event.result)
+    if (event.type === 'tool-result') {
+      // { attachmentId, fileName, byteLength, width, height } or { error }
+      if (event.result.error) showError(event.result.error)
+      else showImage(event.result.attachmentId)
+    }
     if (event.type === 'error') showError(event.message)
   }
   ```
 
-- `detectLanguage({ text, topK })`, served over hrpc as `detect-language` and
-  on `RemoteHarness`: language detection with no model to load. Without
-  `topK`, or with 1, it answers with the single best match and no
+- `detectLanguage({ text, topK })`: language detection with no model to load.
+  It is on `Harness`, served over hrpc as `detect-language`, and on
+  `RemoteHarness`.
+
+  Without `topK`, or with 1, it answers with the single best match and no
   probability. Above that it returns ranked candidates with their
   probabilities, best first, and may return fewer than asked. Text it cannot
   place answers `und`. (#75)
@@ -763,15 +1420,31 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   // [{ code, language, probability }, ...]
   ```
 
-- `SkillOAuthConfig` on `SkillSetupRoute.oauth`, parsed from a skill
-  manifest's `setup.routes[].oauth` and carried over the wire, so a host can
-  run a skill's OAuth setup from its manifest instead of its own provider
-  table. A route missing `stateKey`, `authUrl`, `tokenUrl` or `tokenAuth`
-  carries no `oauth`. (#88)
+- A host can run a skill's OAuth setup from its manifest instead of its own
+  provider table. `SkillSetupRoute.oauth` carries a `SkillOAuthConfig` parsed
+  from `setup.routes[].oauth` and sent over the wire, and `SkillOAuthConfig`
+  is exported.
+
+  `stateKey`, an https `authUrl` and `tokenUrl`, and `tokenAuth`
+  (`pkce-only`, `secret-in-body` or `secret-in-basic`) are required; an
+  `oauth` route without a valid config is dropped. `extraAuthParams` may not
+  override the parameters the flow owns, such as `redirect_uri` or `state`.
+  (#88)
+
+  ```js
+  const skills = await harness.skills()
+  const route = skills
+    .find((skill) => skill.name === 'spotify')
+    ?.setup?.routes?.find((r) => r.kind === 'oauth')
+
+  // { stateKey, authUrl, tokenUrl, scopes, tokenAuth,
+  //   extraAuthParams?, registrationEndpoint?, port?, sharedIosSession? }
+  const oauth = route?.oauth
+  ```
 
 ### Changed
 
-- `@qvac/skills` 0.1.6: the eight OAuth skills declare their setup routes'
+- `@qvac/skills` `^0.1.6`: the eight OAuth skills declare their setup routes'
   OAuth config, the Spotify skill always makes the play call after a search,
   and the weather skill looks the place up with `weather_lookup`. (#88)
 
@@ -788,11 +1461,17 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Added
 
-- `sandboxMode` agent option: an agent with no network access. It withholds
-  every tool that reaches the network (the web search, HTTP request and MCP
-  toolsets, including skill operations over HTTP or MCP), not just web search.
+- `sandboxMode` agent option: an agent that cannot reach the network. Set it
+  on the agent and every network tool is withheld before the model sees the
+  catalog: the web search, HTTP request and MCP toolsets, including skill
+  operations compiled over HTTP or MCP, not just web search.
+
   `exec` stays, but refuses package installs and well-known network commands
-  such as `curl`, `git` and `npm`. That is a guard, not an OS-level sandbox.
+  such as `curl`, `git` and `npm`. That is a name-list guard, not an OS-level
+  sandbox: another binary, or Python calling `pyfetch`, can still open a
+  socket. The six toolset switches stay independent; this is the one knob
+  that means "no network". See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.2.10/docs/decisions/2026-09-21-sandbox-mode-no-network.md).
   (#73)
 
   ```js
@@ -805,12 +1484,17 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   }
   ```
 
-- `@qvac/harness/office`: XLSX and PPTX text extraction for Knowledge beside
-  DOCX, through the same bundled Python worker. It keeps sheet names, column
-  positions, cached formula values, slide text, grouped shapes and tables;
-  speaker notes, images and charts are left out. The format comes from the
-  file extension, with `mimeType` as the fallback. `@qvac/harness/docx` is
-  unchanged. (#83)
+- `@qvac/harness/office`: XLSX and PPTX text extraction for Knowledge, beside
+  DOCX, through the same bundled Python worker. `extractOfficeText` picks the
+  format from the file extension, with `mimeType` as the fallback.
+
+  XLSX keeps sheet names, column positions, cached formula values (formula
+  text where there is no cached value). PPTX keeps slide text, grouped shapes
+  and tables in slide order; speaker notes, images and charts are left out.
+  Legacy XLS and PPT are not supported. `@qvac/harness/docx` is unchanged and
+  shares the worker. See
+  [Office extraction](https://github.com/tetherto/qvac-harness/blob/v0.2.10/README.md#office-extraction)
+  for the cache and wheel paths a host sets. (#83)
 
   ```js
   import { extractOfficeText, closeOfficeWorker } from '@qvac/harness/office'
@@ -822,43 +1506,57 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Fixed
 
-- A small model could loop on the same failing tool call, up to the round
-  cap. A call that already failed this turn with the same arguments is now
+- A small model no longer loops on the same failing tool call up to the round
+  cap. A call that already failed this turn with the same arguments is
   answered from its first result without running again, until a later round
-  succeeds. Three such answers end the turn's tool rounds. A failure that may
-  pass on retry, such as a timeout, a 5xx, 408 or 429, still runs again, and
-  the tools that can fail that way now say so in a `code` or `status` field on
-  their result. (#78)
-- A guessed `auth.tokenCredentialKey` on `http_request` or `mcp_call` was
-  refused with an error claiming the skill was not loaded. It now resolves to
-  the one connected credential allowed for that URL, and when none is
-  connected the error says so and tells the user to connect it in Skills.
-  (#72)
+  succeeds. Three such answers end the turn's tool rounds; the tool set is
+  never changed, so the prompt cache is kept.
+
+  A failure that may pass on retry, such as a timeout, a 5xx, 408 or 429,
+  still runs again, and the tools that can fail that way now say so in a
+  `code` or `status` field on their result. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.2.10/docs/decisions/2026-09-21-a-failed-call-is-answered-from-its-own-result.md).
+  (#78)
+
+- A guessed `auth.tokenCredentialKey` on `http_request` or `mcp_call` now
+  works instead of failing with an error claiming the skill was not loaded.
+  It resolves to the one connected credential allowed for that URL. When
+  none is connected, the error says so and tells the user to connect it in
+  Skills. (#72)
 
 ## [0.2.9] - 2026-09-22
 
 ### Added
 
-- `captureInferenceCalls` on a completion's context: each round then emits an
-  `inference-call` event with the exact payload it is about to send (model,
-  messages, tools, generation params, cache key and prompt prefix), and an
-  `inference-sent` event once it ends, with the tokens it spent, its `outcome`
-  (`completed`, `overflowed` or `failed`) and, on the bundled patched SDK, the
-  slice of `messages` the KV cache let through. An attempt the overflow ladder
-  rejected is still recorded, with its `droppedTurns`. Off unless asked for,
-  since every record carries a whole prompt. The flag and both events are new on
-  the hrpc wire, so the host and the spawned harness both need 0.2.9. (#51)
+- A host can record exactly what each inference round sent. Set
+  `captureInferenceCalls` on a completion's context, and each round emits an
+  `inference-call` event with the payload it is about to send: model,
+  messages, tools, generation params, cache key and prompt prefix.
+
+  An `inference-sent` event follows once the round ends, with the tokens it
+  spent, its `outcome` (`completed`, `overflowed` or `failed`) and, on the
+  bundled patched SDK, the slice of `messages` the KV cache let through. An
+  attempt the overflow ladder rejected is still recorded, with its
+  `droppedTurns`. See
+  [What actually gets sent](https://github.com/tetherto/qvac-harness/blob/v0.2.9/docs/kvcache-reference.md#what-actually-gets-sent).
+
+  Off unless asked for, since every record carries a whole prompt. The flag
+  and both events are new on the hrpc wire, so the host and the spawned
+  harness both need 0.2.9. (#51)
 
   ```js
-  for await (const event of harness.completion({ model, messages, captureInferenceCalls: true })) {
-    if (event.type === 'inference-call') record(event.call.round, event.call.messages)
-    if (event.type === 'inference-sent') settle(event.round, event.outcome, event.tokens)
+  const context = { model, agent, messages, captureInferenceCalls: true }
+  for await (const event of harness.completion(context)) {
+    if (event.type === 'inference-call') record(event.call)
+    if (event.type === 'inference-sent') settle(event.round, event.outcome)
   }
   ```
 
-- The `metrics` event carries the last round's `stopReason`, and leaves it out
-  when the SDK reports none. A turn cut off by the context window ends cleanly
-  with `stopReason: 'length'`, so a host can tell it from a complete answer.
+- A host can tell a cut-off answer from a complete one. The `metrics` event
+  carries the last round's `stopReason`, and leaves it out when the SDK
+  reports none. A turn cut off by the context window ends cleanly with
+  `stopReason: 'length'`. See
+  [Compaction](https://github.com/tetherto/qvac-harness/blob/v0.2.9/docs/kvcache-reference.md#compaction).
   (#62)
 
   ```js
@@ -875,15 +1573,21 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 ### Added
 
 - `weather_lookup`, a tool that looks weather up on wttr.in by `location` and
-  leads its report with the place the service actually resolved. When that
-  place disagrees with the country or state the user named, it refuses instead
-  of reporting the weather of wherever the geocoder landed: a nonexistent town
-  no longer gets a forecast, and a bare "Rome" the service places in Togo says
-  so. It is offered only once the weather skill is loaded, needs no approval,
-  and the `http-request` toolset switch turns it off. The spawned sidecar
-  registers it; an in-process host adds it to its tools. (#52)
+  leads its report with the place the service actually resolved.
+
+  When that place disagrees with the country or state the user named, it
+  refuses instead of reporting the weather of wherever the geocoder landed: a
+  nonexistent town no longer gets a forecast, and a bare "Rome" the service
+  places in Togo says so.
+
+  It is offered only once the weather skill is loaded, needs no approval, and
+  the `http-request` toolset switch turns it off. The spawned sidecar registers
+  it; an in-process host adds it to its tools. See
+  [the decision record](https://github.com/tetherto/qvac-harness/blob/v0.2.8/docs/decisions/2026-09-16-a-lookup-reports-the-place-it-resolved.md).
+  (#52)
 
   ```js
+  import { Harness } from '@qvac/harness'
   import { createWeatherLookupTool } from '@qvac/harness/lib/tools/weather-lookup.ts'
 
   const harness = new Harness({ tools: [...tools, createWeatherLookupTool()] })
@@ -898,20 +1602,25 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   the version. (#55)
 
   ```js
-  // 0.2.7
+  // before
+  import { currentReleaseLine } from '@qvac/harness/schema/release-tags'
   const line = currentReleaseLine(root) // '0.2'
 
-  // 0.2.8
+  // after
+  import { currentReleaseVersion } from '@qvac/harness/schema/release-tags'
   const version = currentReleaseVersion(root) // Version 0.2.8
   const line = `${version.major}.${version.minor}`
   ```
 
-- `previousReleaseTags` from the same module now counts the newest shipped tag
-  on the line being built as a baseline, not only older lines, so a schema
-  change is checked against the build users are running. Only tags newer than
-  the package version are left out. A host that regenerates its `spec/`
-  against it re-derives hyperschema's version counters once, so expect one
-  regeneration commit after upgrading. (#55, #58)
+- A schema change is now checked against the build users are running.
+  `previousReleaseTags` from the same module counts the newest shipped tag on
+  the line being built as a baseline, not only older lines; only tags newer
+  than the package version are left out.
+
+  A host that regenerates its `spec/` against it re-derives hyperschema's
+  version counters once, so expect one regeneration commit after upgrading.
+  (#55, #58)
+
 - `@qvac/skills` 0.1.4: the Apple Notes create-note operation no longer
   renames a note after creating it, which failed on iCloud accounts and left
   duplicate notes behind. (#48)
@@ -920,14 +1629,17 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Added
 
-- `@qvac/harness/docx`: `extractDocxText` pulls a DOCX file's text for
-  Knowledge with the bundled Python runtime, keeping paragraphs and tables in
-  document order, one row per line with cells joined by `' | '`. It takes up to
-  20 MiB and only the shipped wheels, never a network install. Set
-  `QVAC_PYODIDE_CACHE_DIR` to a writable directory first, so the worker seeds
-  its cache from those wheels and works offline. A bundled host also sets
-  `QVAC_PYODIDE_WORKER_ENTRY` and `QVAC_PYTHON_WHEELS_DIR` to its staged
-  worker and wheels. (#46)
+- `@qvac/harness/docx`: `extractDocxText` gives Knowledge a DOCX file's text,
+  pulled with the bundled Python runtime. Paragraphs and tables keep document
+  order, one table row per line with cells joined by `' | '`.
+
+  It takes up to 20 MiB and only the shipped wheels, never a network install.
+  Set `QVAC_PYODIDE_CACHE_DIR` to a writable directory first, so the worker
+  seeds its cache from those wheels and works offline. A bundled host also
+  sets `QVAC_PYODIDE_WORKER_ENTRY` and `QVAC_PYTHON_WHEELS_DIR` to its staged
+  worker and wheels. See
+  [DOCX extraction](https://github.com/tetherto/qvac-harness/blob/v0.2.7/README.md#docx-extraction).
+  (#46)
 
   ```js
   import { extractDocxText, closeDocxWorker } from '@qvac/harness/docx'
@@ -959,36 +1671,45 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   })
   ```
 
-- `writeClient` and `writeCapabilities` from `@qvac/harness/schema/generate`
-  take an options argument whose `optionalRequests` names the request types a
-  caller may omit: the generated client sends `{}` for them and the generated
-  capability types mark the input optional. Left out, only `@assistant/empty`
-  is optional, as before. A set you pass replaces that default, so include it
-  if you still want it. `writeClient` still takes an export name as a string.
-  (#44)
+- A caller can declare which hrpc requests may be omitted. `writeClient` and
+  `writeCapabilities` from `@qvac/harness/schema/generate` take an options
+  argument whose `optionalRequests` names those request types: the generated
+  client sends `{}` for them, and the generated capability types mark the input
+  optional.
+
+  Left out, only `@assistant/empty` is optional, as before. A set you pass
+  replaces that default, so include it if you still want it. `writeClient`
+  still takes an export name as a string. (#44)
 
   ```js
   import { writeClient, writeCapabilities } from '@qvac/harness/schema/generate'
 
   const optionalRequests = new Set(['@assistant/empty', '@assistant/mesh-scope'])
-  writeClient(builder, 'spec/calls.js', { exportName: 'engineClient', optionalRequests })
+  writeClient(builder, 'spec/calls.js', {
+    exportName: 'engineClient',
+    optionalRequests
+  })
   writeCapabilities(builder, 'spec/capabilities.d.ts', { optionalRequests })
   ```
 
 ### Changed
 
-- A completion that needs a different model no longer loads it beside one a
-  live run is holding. It waits for that run to release its model, for up to
-  five minutes, and then loads anyway rather than failing. A `warmModel` call
-  waits two seconds at most, and skips the warm if no room was made. (#41)
+- Switching models no longer stacks a second one in memory beside a live run.
+  A completion that needs a different model waits for that run to release its
+  model, for up to five minutes, and then loads anyway rather than failing.
+
+  A `warmModel` call waits two seconds at most, and skips the warm if no room
+  was made. (#41)
 
 ## [0.2.5] - 2026-09-14
 
 ### Added
 
-- A `gpuStats` option on `spawnHarness`, `harnessChild` and `HarnessOptions`.
-  A host that already has the GPU reading passes it, and the harness skips its
-  own probe. Left out, the harness probes for itself. (#36)
+- A host that already has the GPU reading can hand it over: a `gpuStats`
+  option on `spawnHarness`, `harnessChild` and `HarnessOptions`, and the
+  harness skips its own probe. Left out, the harness probes for itself. It
+  takes the `bare-gpu-info` shape: `memory.totalBytes` and `gpu.devices`, each
+  with a `name` and `videoMemoryBytes`. (#36)
 
   ```js
   import { spawnHarness } from '@qvac/harness/lib/spawn.ts'
@@ -998,54 +1719,72 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
     sdkStorage,
     gpuStats: {
       memory: { totalBytes: os.totalmem() },
-      gpu: { devices: [{ name: 'NVIDIA RTX 4070', videoMemoryBytes: 12884901888 }] }
+      gpu: {
+        devices: [{ name: 'NVIDIA RTX 4070', videoMemoryBytes: 12884901888 }]
+      }
     }
   })
   ```
 
 ### Fixed
 
-- On a Linux snap the harness exited about a second after `open`, and the
-  supervisor respawned it in a loop: the boot-time capability probe created a
-  second GPU-info instance beside the SDK's own. On Linux and Windows under
-  Bare, GPUs are now enumerated in a short-lived child process, which gives up
-  after 5 seconds and reports no GPU. (#36)
-- On Windows, asking for an image after a presentation left the chat stuck on
-  "Loading … into memory". Pyodide's boot opened the process streams from the
-  Python worker thread, which blocked the image-model loader's progress. Boot
-  now never touches them; a run's own output capture is unchanged. (#34)
+- The harness stays up on a Linux snap. It exited about a second after `open`,
+  and the supervisor respawned it in a loop: the boot-time capability probe
+  created a second GPU-info instance beside the SDK's own.
+
+  On Linux and Windows under Bare, GPUs are now enumerated in a short-lived
+  child process, which gives up after 5 seconds and reports no GPU. (#36)
+
+- On Windows, asking for an image after a presentation no longer leaves the
+  chat stuck on "Loading … into memory". Pyodide's boot opened the process
+  streams from the Python worker thread, which blocked the image-model loader's
+  progress. Boot now never touches them; a run's own output capture is
+  unchanged. (#34)
 
 ## [0.2.4] - 2026-09-12
 
 ### Added
 
-- `@qvac/harness/worker/stow-entry.mjs`: the sidecar entry, published so a
-  host running from inside `node_modules` spawns the engine without the
-  prebuilt bundle. Every native addon then resolves beside the JS that calls
-  it, from one install. With the bundle, the addons come from the host's own
-  install, and a version skew there hangs the child on boot rather than
-  throwing: `@qvac/core` 0.1.2 shipped that way. The bundle stays published
-  for a host that relocates the code out of `node_modules`. (#31)
+- `@qvac/harness/worker/stow-entry.mjs`: a sidecar entry a host running from
+  inside `node_modules` spawns directly, without the prebuilt bundle. Every
+  native addon then resolves beside the JS that calls it, from one install.
+
+  With the bundle, the addons come from the host's own install, and a version
+  skew there hangs the child on boot rather than throwing: `@qvac/core` 0.1.2
+  shipped that way. The bundle stays published for a host that relocates the
+  code out of `node_modules`. (#31)
 
   ```js
   import { harnessChild } from '@qvac/harness/lib/spawn.ts'
 
   const entry = new URL(import.meta.resolve('@qvac/harness/worker/stow-entry.mjs')).pathname
-  const spec = harnessChild(entry, { runner, skillsDir, wheelsDir, sdkStorage: storage.sdk })
+  const spec = harnessChild(entry, {
+    runner,
+    skillsDir,
+    wheelsDir,
+    sdkStorage: storage.sdk
+  })
   ```
 
 ## [0.2.3] - 2026-09-12
 
 ### Added
 
-- `schema/generate` emits `writeStream` on the generated `HandlerFrames`, so a
-  duplex handler's frames type without a local widening. (#29)
+- A duplex handler's frames now type without a local widening:
+  `schema/generate` emits `writeStream` on the generated `HandlerFrames`.
+  (#29)
+
+  ```js
+  // in a generated spec, a duplex handler can watch its write side close
+  frames.writeStream?.on('close', onClose)
+  ```
 
 ### Changed
 
-- On Android and iOS, `resolveStorage` keeps models under the app's own
-  persistent root instead of the device HOME, which an app cannot write.
-  Desktop and Snap are unchanged, and `overrides.models` still wins. (#29)
+- Models download on Android and iOS. `resolveStorage` keeps them under the
+  app's own persistent root there, instead of the device HOME, which an app
+  cannot write. Desktop and Snap are unchanged, and `overrides.models` still
+  wins. (#29)
 
   ```js
   import { resolveStorage } from '@qvac/harness/storage'
@@ -1057,37 +1796,41 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Fixed
 
-- Every `./lib/tools/*` subpath is published. The tarball listed only the ones
-  `qvac-core` imports, so the mobile worklet's file tools (`file-glob`, `grep`,
-  `read-files`, `create-documents`, `edit-documents`, `fs/scope`) failed with
-  `PACKAGE_PATH_NOT_EXPORTED`. 0.1.1 to 0.2.2 are affected. (#29)
+- The mobile worklet's file tools load again. Every `./lib/tools/*` subpath is
+  published now; the tarball listed only the ones `qvac-core` imports, so
+  `file-glob`, `grep`, `read-files`, `create-documents`, `edit-documents` and
+  `fs/scope` failed with `PACKAGE_PATH_NOT_EXPORTED`. 0.1.1 to 0.2.2 are
+  affected. (#29)
 
 ## [0.2.2] - 2026-09-11
 
 ### Fixed
 
-- A stale lockfile entry gave `@qvac/sdk` its own nested `@qvac/inference`
-  0.19.1, beside the patched 0.19.0 the harness pins. The bundle is built from
-  the pinned copy alone again. (#27)
+- The engine bundle runs on the patched `@qvac/inference` 0.19.0 the harness
+  pins, and nothing else. A stale lockfile entry had given `@qvac/sdk` its own
+  nested `@qvac/inference` 0.19.1 beside it. A packaging fix with no API
+  change. (#27)
 
 ## [0.2.1] - 2026-09-11
 
 ### Fixed
 
-- The generated wire spec in 0.2.0 stamped the fields it added (`downloaded`
-  on a download event and as a model status, and `kvCacheKey`) with schema
-  version 7, the version 0.1.2 already shipped. They are version 8 now, so the
-  spec matches the schema it is built from. (#25)
+- The generated wire spec matches the schema it is built from again. 0.2.0
+  stamped the fields it added (`downloaded` on a download event and as a model
+  status, and `kvCacheKey`) with schema version 7, the version 0.1.2 already
+  shipped. They are version 8 now. Only the generated spec changed; no API
+  change. (#25)
 
 ## [0.2.0] - 2026-09-11
 
 ### Added
 
-- `deleteKvCache(kvCacheKey)` deletes one chat's KV cache, every file kept
-  under that key, where `clearKvCache()` deletes them all. It is safe on a key
-  still in use: the next turn under it primes from scratch. It rides a new
-  `delete-kv-cache` hrpc route, and resolves with `{ status }` like
-  `clearKvCache`. (#22)
+- `deleteKvCache(kvCacheKey)` deletes one chat's KV cache: every file kept
+  under that key. `clearKvCache()` still deletes them all.
+
+  It is safe on a key still in use: the next turn under it primes from scratch.
+  It rides a new `delete-kv-cache` hrpc route, and resolves with `{ status }`
+  like `clearKvCache`. (#22)
 
   ```js
   // the cacheKey the chat's completions ran under
@@ -1095,11 +1838,13 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   if (result.status !== 'success') log(result.error)
   ```
 
-- A download's `complete` event carries `downloaded`, `true` when bytes were
-  fetched and `false` when the model was already on disk. An image model's
-  `model` events report `loading` rather than `downloading` when it is cached,
-  and a new `downloaded` status once a fetched one has loaded, so a host that
-  switches over `status` has one more case. (#22)
+- A host can tell a fresh download from a model already on disk. A download's
+  `complete` event carries `downloaded`: `true` when bytes were fetched,
+  `false` when the model was already there.
+
+  An image model's `model` events report `loading` rather than `downloading`
+  when it is cached, and a new `downloaded` status once a fetched one has
+  loaded, so a host that switches over `status` has one more case. (#22)
 
   ```js
   for await (const event of harness.download({ model })) {
@@ -1111,28 +1856,63 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   })
   ```
 
-- `ToolDefinition.prompt`: an optional compact `description` and `parameters`
-  the model is shown in place of the full ones, which still validate the call.
-  `exec` and `skill` ship one, so every turn spends less of the prompt on
-  their schemas. (#22)
-- `CONTEXT_OVERFLOW_MESSAGE` is exported, the message a turn fails with when
-  it does not fit the model's context window, so a host can tell that failure
-  apart and compact the chat. (#22)
+- `ToolDefinition.prompt` lets a tool show the model a shorter schema: an
+  optional compact `description` and `parameters` sent in place of the full
+  ones, which still validate the call. `exec` and `skill` ship one, so every
+  turn spends less of the prompt on their schemas. (#22)
+
+  ```js
+  const lookup = {
+    name: 'lookup',
+    description: 'Look a record up by its id, and return ...',
+    parameters: {
+      type: 'object',
+      properties: { id: { type: 'string', description: 'The record id ...' } },
+      required: ['id']
+    },
+    // what the model sees; the full schema above still validates the call
+    prompt: {
+      description: 'Look a record up by id.',
+      parameters: {
+        type: 'object',
+        properties: { id: { type: 'string' } },
+        required: ['id']
+      }
+    },
+    toolset: null,
+    effect: () => 'read',
+    execute: async ({ id }) => find(id)
+  }
+  ```
+
+- `CONTEXT_OVERFLOW_MESSAGE` is exported: the message a turn fails with when it
+  does not fit the model's context window. A host can tell that failure apart
+  and compact the chat. (#22)
 
   ```js
   import { CONTEXT_OVERFLOW_MESSAGE } from '@qvac/harness'
+
+  if (event.type === 'error' && event.message === CONTEXT_OVERFLOW_MESSAGE) {
+    compact(chat)
+  }
   ```
 
 - With `QVAC_HARNESS_LOG=1`, each turn logs `sdk tool definitions`: the tool
   schemas it sent, largest first, with each one's size and the skill that
   granted it. (#22)
 
+  ```sh
+  QVAC_HARNESS_LOG=1 bare host.js
+  ```
+
 ### Changed
 
 - `@qvac/sdk` 0.19.0, pinned exactly. Under Bare the SDK is now served by
   `@qvac/inference` 0.19.0, through a new `#sdk` import alias.
-  `@qvac/audiogen-ggml` joins the deferred addons, so `prebuilds-manifest.json`
-  names it and the host provides it too. (#22)
+
+  `@qvac/audiogen-ggml` joins the deferred addons, so
+  `prebuilds-manifest.json` names it and the host provides it too. (#22)
+
 - Image and music generation schemas reach the model once their skill's
   instructions are loaded, not as soon as the skill is enabled. Loading the
   skill unlocks them within the same turn, at the cost of one cache re-prime
@@ -1147,10 +1927,11 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Fixed
 
-- `@qvac/harness/sdk-storage` and `@qvac/harness/sdk-config-loader` failed to
-  resolve under Bare with `MODULE_NOT_FOUND`: the tarball carried only the Node
-  loader behind `#sdk-config-loader`, so `configureSdkStorage()` could not run
-  on Bare. Both loaders ship now. 0.1.1 is affected. (#20)
+- `configureSdkStorage()` runs under Bare again.
+  `@qvac/harness/sdk-storage` and `@qvac/harness/sdk-config-loader` failed to
+  resolve there with `MODULE_NOT_FOUND`, because the tarball carried only the
+  Node loader behind `#sdk-config-loader`. Both loaders ship now. 0.1.1 is
+  affected. (#20)
 
   ```js
   // Bare: loads again, nothing else changes
@@ -1161,13 +1942,15 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Added
 
-- The library surface ships compiled: `dist-lib/` carries JavaScript and a
-  `.d.ts` for every export, so `@qvac/harness` and its subpaths import from
-  npm under plain Node or Bare, with no TypeScript source or type-stripping
-  loader. Export keys are unchanged, `.ts`-suffixed deep paths included, so a
-  host that took the library from the repository switches to the package
-  without editing a specifier. Of `./lib/tools/*`, only the paths `qvac-core`
-  imports are published. (#18)
+- `@qvac/harness` and its subpaths now import from npm under plain Node or
+  Bare, with no TypeScript source or type-stripping loader. The library surface
+  ships compiled: `dist-lib/` carries JavaScript and a `.d.ts` for every
+  export.
+
+  Export keys are unchanged, `.ts`-suffixed deep paths included, so a host that
+  took the library from the repository switches to the package without editing
+  a specifier. Of `./lib/tools/*`, only the paths `qvac-core` imports are
+  published. (#18)
 
   ```js
   import { harnessChild, spawnHarness } from '@qvac/harness/lib/spawn.ts'
@@ -1178,13 +1961,18 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
 
 ### Added
 
-- First release of the QVAC engine as `@qvac/harness`. The tarball is the
-  prebuilt `dist/harness.bundle`, one bundle for every platform, and the
-  generated `dist/harness.cjs` a host requires to spawn it as a bare-sidecar
-  process. It spawns and does not import: the export map points at library
+- First release of the QVAC engine as `@qvac/harness`. A host gets the
+  prebuilt engine, `dist/harness.bundle` (one bundle for every platform), and
+  the generated `dist/harness.cjs` it requires to spawn that bundle as a
+  bare-sidecar process.
+
+  The package spawns; it does not import. Its export map points at library
   source the tarball leaves out, so a host takes `spawnHarness`,
   `harnessChild` and the transport from the repository until a compiled
-  surface ships. (#13)
+  surface ships. See
+  [The npm artifact spawns; it does not import](https://github.com/tetherto/qvac-harness/blob/v0.1.0/README.md#the-npm-artifact-spawns-it-does-not-import)
+  and [Spawning](https://github.com/tetherto/qvac-harness/blob/v0.1.0/README.md#spawning).
+  (#13)
 
   ```js
   const harness = require('@qvac/harness/dist/harness.cjs')
@@ -1192,17 +1980,20 @@ Tagged but never published to npm; these changes first shipped in 0.2.12.
   const { ipc, sidecar, exit } = await harness.start(args)
   ```
 
-- `dist/prebuilds-manifest.json` names every native prebuild directory the
-  bundle defers, keyed by its path relative to the bundle. The host assembles
-  those beside the bundle from its own `node_modules`, and installs the
-  `@qvac` inference addons and `pyodide` alongside. (#13)
+- `dist/prebuilds-manifest.json` tells a host which native prebuilds to supply.
+  It names every prebuild directory the bundle defers, keyed by its path
+  relative to the bundle. The host assembles those beside the bundle from its
+  own `node_modules`, and installs the `@qvac` inference addons and `pyodide`
+  alongside. (#13)
 - Skills come from `@qvac/skills` 0.1.2, a content-addressed bundle the
   harness materializes at runtime. The Python wheels the tool runtime installs
   ship in `wheels/`, each pinned by hash in `wheels/manifest.json`. (#13, #15)
-- GPU stats are read through `bare-gpu-info`, so every dependency installs from
-  the public npm registry. (#12)
+- Every dependency installs from the public npm registry: GPU stats are read
+  through `bare-gpu-info`. (#12)
 
-[Unreleased]: https://github.com/tetherto/qvac-harness/compare/v0.8.6...HEAD
+[Unreleased]: https://github.com/tetherto/qvac-harness/compare/v0.8.8...HEAD
+[0.8.8]: https://github.com/tetherto/qvac-harness/compare/v0.8.7...v0.8.8
+[0.8.7]: https://github.com/tetherto/qvac-harness/compare/v0.8.6...v0.8.7
 [0.8.6]: https://github.com/tetherto/qvac-harness/compare/v0.8.5...v0.8.6
 [0.8.5]: https://github.com/tetherto/qvac-harness/compare/v0.8.0...v0.8.5
 [0.8.0]: https://github.com/tetherto/qvac-harness/compare/v0.7.3...v0.8.0