@qvac/harness 0.2.5 → 0.2.7

package/docs/decisions/2026-08-20-chat-prompt-prefix-is-stable.md

@@ -0,0 +1,95 @@
+---
+id: ADR-2026-08-20-chat-prompt-prefix-is-stable
+status: active
+introduced_by: PR-1714
+supersedes: []
+---
+
+# A chat's prompt prefix changes only when the user changes something
+
+## Decision
+
+The system prompt and the tool block a chat sends are byte-identical from one turn to the
+next unless the user changed something: agent config, an installed skill, a device tool
+toggle. The runtime never varies them on its own.
+
+`promptPrefixHash` (`lib/capabilities/prompt-prefix.ts`) is the identity of
+that prefix. It rides the harness's per-round `round start` log next to `turns` and `tools`,
+and a harness test asserts consecutive turns of an unchanged agent hash identically while
+enabling a tool moves the hash.
+
+The corollary, where a capability is resolved from more than one input: **one predicate
+answers it for every consumer.** Skill activation is resolved by `skillIsActive`
+(`lib/capabilities/completion.ts`), read both by the active catalog that
+fills the skills section and grants tools, and by the skill loader's per-argument allowlist.
+A skill in one and not the other either hides a capability the model was told about or
+advertises one the loader then refuses.
+
+## Context
+
+The prefix is what the KV cache matches on, so a prefix that moves reprocesses the whole
+chat. That cost is acceptable once, for a change the user made. It is not acceptable per
+turn, and a prefix that moves on its own is usually a capability appearing or disappearing
+rather than a cache problem.
+
+The defect that motivated this: `@mention` activation was resolved from the current turn
+only, so a follow-up turn that named no skill lost the skill, the `skill` tool, and every
+tool the skill granted. `@presentations` built a deck; "edit it to make the background
+orange" reached a model with no way to act. The skills section and two tool definitions
+left the prefix on every such turn, which was observable in the cache numbers and observed
+by nobody.
+
+The second half is the same failure one level down. Activation had two implementations — the
+catalog filter and the loader's allowlist — and repairing only the first would have listed a
+skill in the prompt that the loader answered with `skill not enabled`.
+
+## Alternatives Considered
+
+**Sorting the tool block, or otherwise normalizing the prefix, to absorb variation.** It
+would hide exactly the signal this record exists to expose: KV positions are absolute, so an
+inserted or reordered tool invalidates everything after it whatever we hash. The prefix
+should be stable because nothing varies it, not because the hash forgives variation.
+
+## Consequences
+
+- A change that makes the system prompt or the tool block vary within a chat is a defect,
+  whatever motivates it, and the test says so.
+- A mid-chat `CACHE_INIT` or a `cacheTokens` collapse is now attributable: either the logged
+  prefix moved, and the config change that moved it can be named, or it did not, and the
+  cause is elsewhere.
+- Adding a third consumer of skill activation means extending `SkillActivation`, not
+  re-deriving activation locally.
+- **This record does not decide skill-activation semantics.** SKILL-3 has since been
+  rewritten: an agent is born with every ready skill and a mention grants nothing, so the
+  migration below no longer has a grant to persist. As written at the time,
+  [SKILL-3](../product/skills.md#skill-3) required an `@mention` to enable the skill on the
+  agent — durably, visibly, and removably — and
+  [`qvac-app → docs/plan/tool-safety/p1.md`](../plan/tool-safety/p1.md) §1a-i owns that migration,
+  including moving mention detection out of `completion()` to where the user message is
+  minted. Until it lands, the harness keeps a chat's already-loaded skills active so a
+  follow-up turn does not lose them. That is a runtime repair for the prefix invariant above,
+  not the durable mechanism, and it becomes redundant for the mention path once a mention
+  persists onto `enabledSkills`.
+- **Accepted risk until §1a-i lands: a mention grant is invisible and cannot be revoked.** The
+  only record that the user granted it is the chat transcript, so the Skills UI cannot show it,
+  and removing the skill from the agent (`removeSkillFromAgentLists`, which clears both
+  `enabledSkills` and `installedSkills`) leaves it active in every chat that already loaded it,
+  with the tools it grants, `exec` included. No harness-side signal can fix this: removal clears
+  both lists, so a revoked skill is byte-identical to a never-enabled one, and sending
+  `installedSkills` to the runtime would not distinguish them either. Uninstalling the skill from
+  the _device_ does revoke it everywhere, because the entry then leaves `skillCatalog`.
+- That is a regression in revocability, not just an unbuilt half of SKILL-3. Before, a mention
+  grant was revoked by doing nothing, because it evaporated on the next turn, which is the
+  defect this record exists to fix. Persisting a mention onto the agent is what makes the grant
+  durable _and_ revocable; keeping only the durable half is the interim cost.
+- Not addressed: `historyFromChunks` (`@qvac/core → lib/assistant.ts`) replays only `skill` tool
+  results, so a tool-produced file's `attachmentId` never reaches a later turn. Also not
+  addressed: the `@mention` preload rewrites the last user turn in memory only, so that turn
+  diverges from its persisted form on every later run — a second divergence point downstream
+  of the prefix.
+
+## When Agents Should Read This
+
+Read this before changing what a run puts in the system prompt or the tool list, when adding
+a consumer of skill activation, or when a chat turns out to send a different prefix on
+different turns.

package/docs/decisions/2026-08-20-kvcache-static-placement.md

@@ -0,0 +1,109 @@
+---
+id: ADR-2026-08-20-kvcache-static-placement
+status: active
+introduced_by: PR-1770
+supersedes: [ADR-2026-06-02-kvcache-tool-turns-reenabled]
+---
+
+# Chat models load with static tool placement and no sliding window
+
+## Decision
+
+`model-pool.ts` no longer passes `toolsMode` or `n_discarded` in `modelConfig`
+(static placement in PR-1711, the sliding window in PR-1770).
+Models load with `tools: true` only, which selects the SDK's **static**
+placement — the default, and since SDK 0.18 the only one, because that release
+deletes dynamic mode and rejects the key. The per-turn payload is
+`history.slice(savedCount)`, the unsent tail.
+`kvCache: 'chat-<id>'` stays on every completion, unchanged.
+
+The two removals ship as separate PRs, deliberately: the dynamic-tools defect
+had to reach a release on its own. Each key removal changes `modelConfig`,
+which re-keys the SDK's identity-by-config `modelId`, so every chat
+cold-primes once per removal — one wave per release rather than one wave for
+both. That cost is accepted in exchange for shipping the fix early.
+
+## Context
+
+ADR-2026-06-02 chose `toolsMode: 'dynamic'` on the strength of the addon's
+compact-tools anchoring. The 2026-08-18 investigation
+(`docs/kvcache-reference.md`) established that on every shipped model the addon
+half of that feature never ran: the `tools_compact` gate matches architecture
+`qwen3` exactly, and the catalog is `qwen35`/`qwen36`, so the addon logged
+`tools_compact is not supported … ignoring` on every load while the SDK still
+sliced as-if-dynamic. Consequences, measured:
+
+- the previous answer was duplicated into the KV every warm turn, and the tool
+  block was re-sent with nothing trimming it — three one-line exchanges filled
+  a 2048 window;
+- after any cache reset (deleted `.bin`, `configHash`/`modelId` move, new
+  device) the dynamic slice still sent only the last exchange, so the model
+  silently lost everything older — TTFT unchanged, no error, answer
+  confabulated. Under static placement the same reset costs one proportional
+  prefill and the fact survives (measured: `promptTokens` 16→65, TTFT
+  41→96 ms).
+
+The sliding window fails the same way from the other side, and it fails on the
+shipped stack. **A slide is invisible to the SDK**: the cache session records a
+turn's full message count on success and the next turn sends
+`history.slice(savedCount)`, so nothing observes the addon discarding tokens in
+C++ — the discarded span is gone from the live cache and from the saved `.bin`
+while the app still counts it as sent, and the model silently loses the middle
+of the chat. Not sliding also obsoletes the two slide-time addon bugs we
+reported (the reasoning-span wipe, the single-step prefill slide), and 0 is the
+addon's own documented default, so nothing is being opted out of.
+
+Upstream has since deleted dynamic mode on both sides (SDK `main` rejects the
+`toolsMode` key at parse time; the addon drops `tools_compact` after 0.39.4),
+and the addon team asked (Slack, 2026-08-19) that `n_discarded != 0` never be
+passed because context shifting is dropped in a future addon. That last one is
+guidance about an unreleased version and carries no weight here: the shipped
+0.39.4 documents the knob as live, default 0, with no deprecation note. The
+decision rests on the defect above, which lands today.
+
+## Consequences
+
+- A cold cache now falls back to the full history: chats survive cache resets
+  at TTFT cost instead of silently forgetting.
+- With no sliding window, a full context surfaces `ContextOverflowError`, and
+  the overflow recovery ladder (`lib/context-window.ts`,
+  drop-oldest-turns) becomes effective — under dynamic slicing it was inert.
+  The planned compact flow (MIGRATION, KV cache follow-ups) is its successor.
+- The tool block is **not** in the primed prefix on the SDK we ship (0.18.2;
+  QVAC-23251 landed in 0.17.1) — the prime is the system prompt alone, and the
+  block travels with a turn, written once and skipped thereafter. Its names still
+  join `configHash`, so a tool-set change (a skill activation, an `enabledTools`
+  or `disabledToolsets` edit) re-keys the cache file and costs a cold prime —
+  once per change, since the prefix is otherwise stable for the chat
+  ([2026-08-20-chat-prompt-prefix-is-stable](./2026-08-20-chat-prompt-prefix-is-stable.md)).
+- **Dropping `n_discarded` is what lets that block be skipped at all.** The
+  shipped SDK sets `toolBlockEvictable = (modelConfig.n_discarded ?? 0) > 0`,
+  because with sliding on the addon's discard window opens exactly where the
+  block sits and nothing protects it. So while core-v2 passed the key, the whole
+  tool block was re-sent on every turn — measured ~331 tokens for a 4-tool agent.
+  This is the second present-day reason for the removal, alongside a slide being
+  invisible to the SDK's own `savedCount` accounting.
+- With `n_discarded` at 0 the addon's decode-time slide never engages either: a
+  generation that fits at prefill but crosses `ctx_size` mid-stream cannot
+  slide, and the overflow ladder cannot recover it — the ladder only retries a
+  round that has not yet yielded tokens — so a mid-decode exhaustion ends the
+  turn. Rare (bounded by generation length, not chat length); the compact flow's
+  proactive trigger is the structural answer. That round still fails with the
+  harness's own `CONTEXT_OVERFLOW_MESSAGE` rather than the SDK's text, which
+  names the `modelId` hash and blames the prompt — and which the compaction
+  trigger would not recognise.
+- **Each removal strands the previous cache file, and nothing sweeps it.** The
+  file lives at `{kvCacheDir}/{cacheKey}/{modelId}/{configHash}.bin`, so a
+  `modelId` re-key leaves the old `{modelId}/` directory unreferenced — 21–26 MB
+  at ctx 2048, more at the desktop default. The SDK's retention sweep cannot
+  reach it: eviction plans only keys marked by `markAutoCacheKey`, and the
+  custom-key path (`beginCustom`) never marks, so `chat-<id>` is outside
+  retention permanently and by design (a config revert may revive the file).
+  Pre-existing — every `configHash` move already did this — but two releases in
+  a row now do it to every chat at once. The reclaim is the MIGRATION
+  "Delete on re-key" item, which deletes the whole key directory (every
+  `modelId`/`configHash` under it) on chat deletion and agent re-key; a chat
+  that is never deleted and whose agent is never edited keeps its stale
+  directories until then.
+- One cold prime per chat on first run after the upgrade (the `modelId`
+  re-key) — expected, not a regression.

package/docs/decisions/2026-08-21-vendored-python-wheels.md

@@ -0,0 +1,85 @@
+---
+id: ADR-2026-08-21-vendored-python-wheels
+status: active
+introduced_by: PR-1757
+supersedes: []
+---
+
+# Python packages ship with the app, pinned by hash
+
+## Decision
+
+Every Python distribution a skill declares in `packages` is vendored into the
+app: `wheels/manifest.json` pins each wheel with its sha256,
+`scripts/vendor-python-wheels.mjs` downloads and verifies them at build time,
+and the desktop build copies the tree to `dist/main/python-wheels`. The harness
+receives the directory on argv and installs from it, so a run declaring a pinned
+package makes no network request at all.
+
+Two channels need two mechanisms. Lockfile wheels (micropip, pillow, lxml,
+fonttools, typing-extensions, cryptography and its deps) are copied into
+Pyodide's `packageCacheDir` before the interpreter boots, because `loadPackage`
+reads that directory and nothing else. PyPI wheels (fpdf2, pypdf, openpyxl,
+python-docx, python-pptx and their deps) are staged into the interpreter and
+installed by `emfs:` path with `deps=False`, because the manifest already names
+the whole closure and dependency resolution is the step that would reach PyPI.
+
+## Context
+
+The PDF skill failed on an offline device: `micropip.install` resolves names
+against pypi.org, so `fpdf2` could not be fetched. micropip reports an
+unreachable index as `Can't fetch metadata for 'fpdf2'`, which reads as a wrong
+package name — the model answered it by guessing `fpdf`, `pdf2`, `pdfkit` and
+`reportlab` in turn and never produced a file. Every python-backed skill had the
+same defect, and PyPI wheels were never persisted, so even a device that had
+been online re-downloaded them on the next launch.
+
+Pinning was already the skills' convention for reproducibility. Vendoring the
+pinned set turns that into a supply-chain guarantee: the app cannot install a
+version that was not reviewed, and the runtime makes no PyPI request at all.
+
+Measured cost for the whole set: 17 wheels, 8,314,167 bytes on disk — 1.8 MB of
+PyPI wheels, 3.9 MB of lockfile wheels, and 2.3 MB for the cryptography closure
+the PDF skill's AES flows need. Two macOS DMGs built from the same tree, one with
+the wheels staged and one without, put the shipped cost at **8,245,247 bytes
+(+3.6%)**: 229,209,450 → 237,454,697. Wheels are zip archives, so the DMG's LZFSE
+pass cannot compress them further and the installer grows by very nearly their
+raw size. Against the 24 MB of Pyodide runtime the app already ships, they are the
+cheap part; lxml, long assumed to be the dominant cost, is 1.6 MB.
+
+## Alternatives Considered
+
+- **Point Pyodide's `packageCacheDir` at the read-only vendored tree.** Pyodide
+  writes downloaded wheels into that directory, so an unvendored package would
+  fail on the write rather than on the download, and the online fallback would
+  break. Seeding a writable cache keeps both paths working.
+- **Install the vendored wheels and let micropip resolve the rest.** A partial
+  install pins versions the resolver then has to work around, and it still needs
+  the network for the remainder. The plan is all-or-nothing per request: any
+  unvendored package sends the whole install back to PyPI, dependencies included.
+- **Ship the wheels inside `node_modules/pyodide`.** Its `indexURL` is bypassed
+  the moment `packageCacheDir` is set, and `bun install` would wipe the tree.
+
+## Consequences
+
+- A pin change is two edits and a regeneration: the version in `SKILL.md`, the
+  version in the manifest, then `node scripts/vendor-python-wheels.mjs --update`.
+  The `python-wheels` test suite fails when those disagree, because a silent
+  disagreement reverts that skill to online-only.
+- Bumping Pyodide invalidates the lockfile wheels — they carry its ABI tag. The
+  vendoring script refuses to run when the manifest and `node_modules/pyodide`
+  name different versions.
+- A package no skill declares still installs from PyPI and still needs a
+  connection. micropip reports a missing name and an unreachable index
+  identically, so `packageFetchFailedHint` names both causes and tells the model
+  not to try other spellings, which is the part that ends the loop.
+- Mobile is unchanged: no Pyodide runtime ships there, so no wheels are passed.
+  Vendoring for mobile means shipping the interpreter first.
+- The desktop build needs network access at package time to fill the wheel tree.
+  A hash mismatch fails the build rather than shipping an unreviewed wheel.
+
+## When Agents Should Read This
+
+Read this when changing the Python exec adapter's install path, the vendoring
+script or manifest, the `packages` pins in a skill, the Pyodide dependency, or
+the desktop build steps that stage harness assets.

package/docs/decisions/2026-08-26-exec-is-not-gated-by-skills.md

@@ -0,0 +1,64 @@
+---
+id: ADR-2026-08-26-exec-is-not-gated-by-skills
+status: active
+introduced_by: PR-1854
+supersedes: []
+---
+
+# A skill no longer decides what `exec` may run; approval does
+
+## Decision
+
+`exec` is reachable whenever the agent's Tools settings reach it, and it runs whatever
+command it is given. The two gates that made a skill the source of that permission are
+gone:
+
+- the call-time lock that refused a granted tool until the granting skill's body had
+  been loaded in the same chat, and
+- the per-turn binary allowlist, which built the set of runnable programs out of the
+  `exec(...)` scopes of the active skills and refused everything else.
+
+What remains in front of a command is the sanitizer — one program per call, no
+chaining, pipes, redirection or shell expansion — and the approval prompt, which every
+`exec` write raises unless the agent is in Skip All Approvals.
+
+A skill's `exec(bin)` scope still means something narrower: it names the bin whose
+`cli.schema.json` validates argv and carries the `x-effect: read` annotations that let
+a read run unattended. It no longer decides whether the command may run at all.
+
+## Context
+
+The agent's Tools tab lists Exec as a capability the user switches on, with the hint
+"Lets QV.AC run commands on the device" ([PERM-10](../product/tool-permissions.md#perm-10)).
+That switch writes the tool's name into the agent's allowlist and nothing else. It
+could not add a binary to the allowlist or load a skill body, so switching Exec on left
+`exec` hidden from the model, and a model that reached it anyway got told to load a
+skill it may not have. The user's switch said yes and the gate said no.
+
+Both gates were built when a skill was the only way a tool became available
+(PR-1426 for the lock, and the scope work before it). That premise is what changed.
+
+## Consequences
+
+- **Approval is the boundary.** With no argv schema for an arbitrary bin, `shellEffect`
+  cannot classify a command as a read, so it classifies write and the call prompts. An
+  agent on Skip All Approvals runs shell commands unattended; that mode already carried
+  that meaning for the granted binaries, and now carries it for all of them.
+- **`exec(python)` no longer gates Pyodide.** `language: "python"` runs without any
+  grant. The realm it runs in is unchanged, so
+  [PERM-7](../product/tool-permissions.md#perm-7) is exactly as met, or unmet, as it
+  was; what changed is that reaching it no longer requires a skill. The mitigation is
+  still [tool-safety p3](../plan/tool-safety/p3.md).
+- **The argv schema now reads backwards.** `resolveShellOps` looks the bin up in
+  `grantedOps`, which only active skills fill. With apple-notes on,
+  `osascript -e 'do shell script "id"'` is refused before approval; with it off, the same
+  command sanitizes clean and spawns. Enabling a skill makes `exec` narrower than leaving
+  it off. That is kept deliberately: the schema is how a skill states the shape it expects
+  its own CLI to be called in, and it bounds nothing that running the command directly
+  would not already reach. It stops being defensible the moment anything treats it as a
+  security control.
+- **The model is told the truth.** `exec`'s description no longer promises an allowlist,
+  and a loaded skill's tool note no longer claims its scopes are the only runnable
+  executables.
+- The `skillGated` and `scopeRequired` wire fields survive, reported off, so a build on
+  the other side of the sidecar hop reads both gates as open rather than missing.

package/docs/decisions/2026-08-27-writable-skills-overlay.md

@@ -0,0 +1,56 @@
+---
+id: ADR-2026-08-27-writable-skills-overlay
+status: active
+introduced_by: PR-1857
+supersedes: []
+---
+
+# A user-added skill layers over the bundled base and is trusted only by shadow
+
+Skills load from two roots. The bundled base is the read-only, version-pinned set
+shipped with the app. Over it sits a writable, per-user **overlay** at
+`<sdk-home>/skills`, resolved in `lib/tools/skills/overlay-dir.ts`
+from the `QVAC_CONFIG_PATH` env var that `configureSdkStorage` publishes on both
+runtimes — read via env rather than importing from `assistant`, which would be a
+circular dependency, and needing no new caller argument, so desktop and mobile
+provide it just by configuring storage. `loadSkillCatalog` in
+`lib/tools/skills/catalog.ts` reads both roots and merges them.
+
+## Decision
+
+**The merge key is the folder name, and the overlay wins.** A skill's identity is
+its folder, not its front-matter `name` — because the `skill` tool reads a skill by
+folder path (`/<name>/SKILL.md`, `lib/tools/skill.ts`). Keying the
+catalog on the folder makes the merge key and the on-disk read lookup the same key,
+so they can never disagree. (Keying on `meta.name` did not: an overlay `gmail/`
+declaring `name: pirate` would file itself as a _new_, untrusted `pirate` entry
+while its files still shadowed the trusted base `gmail` at read time — so loading
+`gmail` served the overlay body under the base's grants, bypassing the merge below.
+A divergent `meta.name` is now ignored.) An overlay folder matching a bundled folder
+_shadows_ it; any other folder is a _new_ skill.
+
+**A new overlay skill is untrusted.** A skill's front matter is a grant: loading it
+unlocks tools, widens the credential egress allow-list, and classifies MCP methods
+as reads. A file anyone can drop on disk must not do those things silently. So a
+new overlay skill is excluded from `credentialGrants`
+(`lib/tools/skills/credential-grants.ts`) and from `mcpReadMethods`
+(`catalog.ts`) — it still loads and runs, but its http/exec calls go through the
+normal per-call approval gate, and its declared reads count as writes. This is the
+`origin: 'overlay'` marker, which is local-only and never crosses the wire.
+
+**A shadow overrides instructions, never capability.** Editing a first-party skill
+is the point of the overlay, but the edit must not be able to re-arm it. `mergeOverlay`
+takes the overlay copy's body and display metadata but pins its `allowList`,
+`credentials`, `mcpReads`, and `platform` to the trusted base. So an edit can't add
+an egress host, can't break the skill's auth by dropping a field, and can't claim an
+OS the base doesn't support — and a shadow is _not_ marked `origin: 'overlay'`,
+because its capability surface is the base's.
+
+**An undeclared platform means "here", not "nowhere".** The base treats a skill with
+no `platform` as supported nowhere, because every bundled skill lists its platforms
+explicitly. A user dropping a bare `SKILL.md` (e.g. one from the Claude or Codex
+skills repos) does not know that incantation, and requiring it would mean every
+such skill shows as "not available on this device". So a _new_ overlay skill with no
+declared platform defaults to every platform the app targets; the other gates
+(missing tools, model capability) still apply, so this only lifts the OS gate. This
+is what makes "drop a folder and it works" true.

package/docs/decisions/2026-09-01-skill-operation-manifests.md

@@ -0,0 +1,53 @@
+---
+id: ADR-2026-09-01-skill-operation-manifests
+status: active
+introduced_by: PR-000
+supersedes: []
+---
+
+# A provider write is a compiled skill operation, not a shaping hook in `http_request`
+
+## Decision
+
+A skill declares its write operations in a sibling `operations.json` manifest. The harness compiles
+each entry into a typed tool (`gmail_send`, `gmail_draft`, `calendar_create_meet_event`,
+`calendar_add_meet`) that validates arguments, builds the provider payload, and delegates the call to
+`http_request`. `http_request` itself carries no provider knowledge: the per-host request/response
+shaping registry is removed, and an oversized JSON response is reduced by a generic per-node pruner.
+
+A compiled tool is owned by the skill whose bundled manifest defined it. The tool gate matches on the
+owning skill, not the tool name, so a sibling skill or a writable-overlay skill that declares the same
+name in `tools:` cannot expose it. A writable overlay never contributes operations of its own; editing
+a bundled skill keeps the base manifest's tools, exactly as it keeps the base credentials and
+allow-list.
+
+## Context
+
+Gmail, Calendar, and Docs each needed request shaping (RFC 2822 assembly, base64url, conference
+requests) and response shaping. That knowledge lived inside the generic `http_request` tool as a
+host-keyed registry, so every new provider widened a shared tool, and the model still had to write raw
+URLs and bodies for a write it could not verify.
+
+Shaping also meant the response cap was provider-specific. A provider with no registry entry got a raw
+character slice, which cuts JSON mid-token and drops shallow identifiers the model needs next.
+
+## Alternatives Considered
+
+- **Keep the shaping registry, add a provider per file.** Rejected: provider coupling in a generic
+  tool, and it never gives the model a typed schema for the write.
+- **Let an overlay skill ship its own `operations.json`.** Rejected: a user-editable file would mint a
+  tool with the base skill's credentials — privilege escalation by rename.
+
+## Consequences
+
+- A new provider write is a manifest entry plus a builder, never an `http_request` change.
+- Every operation tool is `externalWrite`, non-auto-approved, and skill-gated; it passes through the
+  same egress guard, private-IP check, and approval path as a raw `http_request`.
+- Response truncation is uniform: parseable JSON in, parseable JSON out, for every host.
+- The manifest describes one HTTP call. Multi-step or paginated flows stay in skill instructions.
+- Revisit if a provider needs a write whose payload cannot be expressed by a named builder.
+
+## When Agents Should Read This
+
+Read this when changing the paths, workflows, runtime boundaries, or platform
+behavior listed for this ADR in `docs/decisions/INDEX.md`.

package/docs/decisions/2026-09-01-usage-breakdown-is-measured.md

@@ -0,0 +1,78 @@
+---
+id: ADR-2026-09-01-usage-breakdown-is-measured
+status: superseded
+introduced_by: PR-1953
+superseded_by: ADR-2026-09-03-usage-breakdown-reported-by-the-harness
+supersedes: []
+---
+
+# The Usage breakdown divides a measured total, it never estimates tokens
+
+## Decision
+
+Only the Usage modal's total is a token count: `cacheTokens` from the turn's SDK
+metrics. Every row below it is that total split by character share, at a
+chars-per-token ratio fitted per chat against the SDK's own count on the first
+turn that reports one. No row converts characters to tokens with a hardcoded
+ratio, and the fit is never recomputed on a later turn.
+
+Two costs the model receives but we do not author are declared as measured
+constants rather than absorbed: the chat template's tool preamble
+(`FRAMING_CHARS_BY_DIALECT`, read through `toolBlockFramingChars`) and one
+exchange's fixed overhead (`TURN_OVERHEAD_TOKENS`, charged to the turn via the
+fit's denominator). Only the first is keyed by dialect — a template either has a
+tool preamble or has none, whereas every template wraps its turns, so declaring
+zero overhead would be further from the truth than Qwen's number is elsewhere.
+
+## Context
+
+The SDK exposes no tokenizer — `@qvac/sdk` 0.18.2 ships tokenization only for
+VLA, whose docs tell consumers to tokenize their own input — so a real count is
+unavailable and `cacheTokens` is the only ground truth.
+
+A single hardcoded ratio cannot work. Measured on Qwen3.5-4B, real density is
+3.17 chars-per-token for a prompt with no tools and 4.23 for a seven-tool
+prompt, because tool schemas are dense JSON and the rest is prose. The retired
+3.5 constant therefore overshot the measured total, and the scaling fallback
+squeezed every row to fit — which is why the rows appeared to grow between turns
+while Conversation collapsed to single digits.
+
+Character counting is also blind to two real costs: the template's own tool
+section, and per-turn role wrappers plus the harness time annotation. Left
+unattributed they are spread across the rows that do have characters, which
+overstated a tool-less agent's System Prompt by 47%.
+
+## Alternatives Considered
+
+- **Better hardcoded ratios per segment.** Rejected: it replaces one invented
+  constant with three, all model-specific, and all silently wrong on a new model.
+- **A two-point fit** using the delta between the first two turns to measure the
+  per-turn cost directly. Correct and constant-free, but it reports nothing until
+  a chat has two turns.
+- **Keying the framing globally rather than by dialect.** Rejected: dialect is
+  the axis the template varies on, and an unmeasured model should declare zero
+  rather than borrow another template's number.
+
+## Consequences
+
+- The rows sum exactly to the measured total on every turn, and the prompt rows
+  hold still across turns of one chat. Both are load-bearing: QA asserts them.
+- Getting a constant wrong is cosmetic. It shifts the split between rows and can
+  never move the total, the sum, or the flatness — so a stale value degrades
+  silently, and only a real-model measurement can catch it.
+- The estimator must keep mirroring the production selection functions
+  (`permittedTools`, `enabledTools`, `skillIsActive`); a drift test pins this.
+- The fit's numerator must keep pace with what the cache holds. Tool calls and
+  their output are re-sent and counted; generated `thinking` is not, and
+  `cacheTokens` excludes it (measured: 408 generated tokens against 162 reported).
+- Re-measure a constant by diffing the addon's `PROMPT_SEND` dump against
+  `systemPromptChars` + `toolsChars`. Drive it from `@qvac/core → examples/chat-tui.mjs`
+  over a pty with `QVAC_STORAGE` pointed at a scratch dir, and read `N ctx` from
+  the footer.
+- Revisit if the SDK ever exposes a token-count or prompt-render op: that would
+  retire the fit and both constants.
+
+## When Agents Should Read This
+
+Read this when changing the paths, workflows, runtime boundaries, or platform
+behavior listed for this ADR in `docs/decisions/INDEX.md`.