@qvac/harness 0.2.6 → 0.2.7

package/docs/decisions/2026-08-17-harness-hook-pipeline.md

@@ -0,0 +1,84 @@
+---
+id: ADR-2026-08-17-harness-hook-pipeline
+status: active
+introduced_by: PR-000
+supersedes: []
+---
+
+# Harness hooks fold a whole round before any call runs, and fail closed
+
+## Decision
+
+`assistant-harness` exposes four hook phases — `runStart`, `preToolCall`, `postToolCall`,
+`runEnd` — registered in a single process-wide array (`harnessHooks`) and driven by
+`HookPipeline` from inside `completion()`. Hooks receive a deep JSON clone of their payload and
+influence the run only through what they return: new `args` for a pre-hook, a new `result` for a
+post-hook, or a `HookRejection` (`{ error, guidance: true }`).
+
+Two ordering rules are durable:
+
+- **Pre-hooks fold the whole round before any call in that round executes.** The assistant turn
+  written to history replays the folded calls, so history can never disagree with what ran.
+- **Post-hooks fire only after a real `tool.execute()`.** Refused, denied, invalid, guarded,
+  capped, and unknown calls never reach a post-hook.
+
+A pre-hook may also _repair_ a call: the `args` it returns replace the model's own, and the
+payload carries the tool's declared `parameters` so the repair is schema-driven rather than
+per-tool. `ArgRepairHook` is registered first for that reason — it decodes a structured parameter
+a small model handed over as text (fenced, newline-broken, or missing its outer closer) before
+approval, the activity log, and `execute()` read the call, so all three see the same canonical
+args and the tool itself keeps a strict reader.
+
+Failure is closed, not fatal. A throwing tool hook becomes model-facing guidance and the loop
+continues; a throwing `runStart`/`runEnd` hook is logged and ignored, because run authorization
+lives in the policy layer, not here.
+
+## Context
+
+Tool calls already pass through validation, the trusted-source guard, effect classification, and
+the approval memo. Extending any of those for cross-cutting concerns (redaction, arg rewriting,
+telemetry, per-tool filtering) would have meant editing the gate chain for every new concern.
+
+The round-level fold exists because the assistant turn is written to history once, before the
+calls run. Folding per call would let a pre-hook mutate arg N after the turn already recorded the
+model's original wrapper — history and execution would diverge, and the model would be trained by
+its own record to re-emit the un-mutated form.
+
+Deep cloning exists because payloads are the run's live objects: model-emitted args, history-bound
+results, the message list. A hook that mutates one in place would leak into the run without
+returning anything, which makes the "influence only through return values" contract unenforceable.
+Payloads are JSON-domain, so a `JSON.parse(JSON.stringify(...))` round-trip severs every reference;
+non-JSON values (`undefined`, functions, `BigInt`, cycles) pass through as-is rather than
+withholding output that already ran.
+
+## Alternatives Considered
+
+- **Per-call fold (pre(N) after post(N-1)).** Rejected: it desynchronizes the assistant turn from
+  what executes. Accepted cost of the round fold is that pre-hooks fire for calls a later gate
+  (skill lock, search cap, abort) never runs.
+- **Hooks that throw abort the run.** Rejected: a buggy third-party hook would become a run-level
+  denial of service. Failing closed on the _call_ keeps the run recoverable.
+- **In-place mutation of the live payload.** Rejected: no way to distinguish a deliberate change
+  from an accidental one, and no way to reject a hook's edit.
+- **Structured-clone / a clone library.** Rejected: payloads are already JSON-domain; a dependency
+  buys nothing a `JSON` round-trip does not.
+
+## Consequences
+
+- A new hook phase must state whether it fires before or after execution, and post-phase hooks
+  must never fire for a call that did not execute.
+- Rejection wording must never match the SDK wedge patterns in `models/sdk-faults.ts` — those mark
+  a dead native context for eviction, not guidance for the model. A post-hook rejection says the
+  tool already executed, so the model does not retry a side effect.
+- With no hook registered a run pays nothing, not even a payload clone. Keep that: `harnessHooks`
+  is empty by default.
+- Registration is a process-wide array with no ordering, priority, or per-agent scoping. That is
+  deliberate and should be revisited only when a real consumer needs it.
+- Hooks cannot bypass approval, the trusted-source guard, or the denial memo — those gates run on
+  the folded args, after the hook.
+
+## When Agents Should Read This
+
+Read this when changing the paths listed for this ADR in `docs/decisions/INDEX.md` — the tool loop
+in `capabilities/completion.ts`, anything under `lib/hooks/`, or any new gate that must order
+itself against the fold.

package/docs/decisions/2026-08-17-harness-outbound-egress-guard.md

@@ -0,0 +1,176 @@
+---
+id: ADR-2026-08-17-harness-outbound-egress-guard
+status: active
+introduced_by: PR-QVAC-23689
+supersedes: []
+---
+
+# Harness tool egress and spawn environments are allowlists, not filters
+
+## Decision
+
+Every outbound URL a harness tool reaches — `http_request` and `mcp_call`, on the
+first request and on each redirect hop — passes `resolveOutboundUrl`
+(`lib/tools/url-guard.ts`) before a socket opens. The guard
+rejects loopback, RFC1918, CGNAT, link-local, cloud-metadata hosts and their IPv6
+equivalents through `lib/tools/private-ip.ts`, and rejects a
+hostname whose resolved addresses land in those ranges. `private-ip.ts`
+default-denies any address it cannot positively classify as global unicast.
+
+The check splits along the hook boundary from
+ADR-2026-08-17-harness-hook-pipeline. The model-supplied URL gets a
+synchronous literal-host check from `checkOutboundHost`
+(`lib/tools/url-guard.ts`), run by `EgressGuardHook`
+(`lib/hooks/built-in/egress.ts`), a `preToolCall` hook
+shipped by default in `harnessHooks`
+(`lib/hooks/registry.ts`) so every host gets it without
+registering anything; a rejected call never executes and the rejection
+reaches the model as guidance. The hook does not resolve DNS — it only
+catches a literal blocked host (an IP or bracketed IPv6 literal in the URL
+itself). Resolving the hostname and pinning the connection to the addresses
+the guard approved happens in the tool, which needs those addresses anyway to
+connect: each tool runs `resolveOutboundUrl` itself with a `resolveHost`
+defaulting to `lib/dns-lookup.ts`, so a tool constructed
+directly (bypassing the pipeline) is still guarded. `resolveOutboundUrl`
+returns both the verdict and the resolved address set, which the tool then
+pins the connection to. `http_request` re-runs the
+check on every redirect hop, which only exists mid-execution after the hook
+has fired; `mcp_call` runs it before any credential resolves, so a blocked
+host never gets a token minted for it.
+
+On Node, `lib/no-redirect-fetch-node.ts` pins the connection
+to the addresses the guard already approved: it passes them to `http`/`https`
+request's `lookup` callback, which connects only to those addresses and
+rejects private results. On Bare, `lib/no-redirect-fetch-bare.ts`
+does not pin — the fetch agent carries a validating `lookup` hook
+(`lib/validating-lookup.ts`) that re-resolves through the
+same validation, plus a `createConnection` wrapper that re-checks literal-IP
+hosts, so the address it connects to is validated but not necessarily the one
+the guard first approved. That gap is the residual rebinding window on Bare;
+a rebind into a private range is still caught, just by a second resolve
+instead of by reusing the first one.
+
+A spawned child receives an environment built by adding to an allowlist, never by
+subtracting from `process.env`. `EXEC_ENV_ALLOWLIST` in
+`lib/helpers/spawn-path.ts` is `PATH`, `HOME`, the temp-dir
+trio, locale, `TZ`, `USER`, `LOGNAME`, the proxy and CA-bundle variables a
+granted binary needs to reach the network at all behind a corporate proxy, plus
+a per-platform set for the Obsidian launchers. Nothing else — no `SSH_*`, no
+`AWS_*`, no host tokens — crosses into a child.
+
+The same fail-closed shape covers the two remaining tool inputs that name a host
+resource. `exec`'s shell `workdir` resolves through `resolveKey` against the
+granted `roots`, and with no roots granted it is refused outright rather than
+passed to `spawn`. Skill loading is gated by `SkillCatalogGuardHook`
+(`lib/hooks/built-in/skill-catalog.ts`), shipped by default
+in `harnessHooks` alongside `EgressGuardHook`; a host that loads a catalog
+passes it to the constructor so `name` resolves against the advertised
+catalog, keeping the loadable set equal to the set the model was shown. The
+`skill` tool itself reads through a `Localdrive` rooted at `skillsDir`, which
+refuses traversal and absolute names regardless of the hook.
+
+A grant names what a tool may reach; a deny root names what no grant can reach, and
+deny wins. `resolveKey` (`lib/tools/fs/scope.ts`) resolves every
+path against the granted `roots` and then against `deniedRoots`, which the host
+passes and the model cannot influence. Both sides are canonicalized through
+`realpath` before comparison — once per resolution, not once per path segment — so
+a symlink, an uncanonical root, or a `..` walk cannot step around the deny root.
+The walking tools (`file_glob`, `grep`) drop denied paths as they enumerate,
+because a listing must not name what a read may not open. The desktop sidecar and
+the mobile worklet both derive the deny root from the storage layout the host
+already passes (ADR-2026-07-29-assistant-owned-storage-layout), so the app's own
+`credentials.vault`, `vault.key` and plaintext config database sit outside every
+grant without a new host argument.
+
+## Context
+
+`qvac-app → docs/tool-review-checklist.md` carried SSRF as an unchecked placeholder — "port
+v1 `private-ip.ts`" — while `http_request` and `mcp_call` shipped in desktop and
+mobile builds. Both are model-driven: the URL, the redirect target, the `workdir`
+and the skill name all come from generated arguments, so any host reachable from
+the device was reachable by a prompt. Cloud metadata endpoints and a developer's
+own loopback services are the valuable targets, and both are one plain hostname
+away.
+
+An allowlist rather than a denylist for the spawn environment follows from the
+same reasoning applied to a different axis. A denylist has to enumerate every
+secret-bearing variable a host might set, and loses the moment a new tool
+convention appears. The allowlist only has to enumerate what the pinned binaries
+actually need to run, which is short and changes rarely.
+
+## Alternatives Considered
+
+**Check only the literal URL, and skip DNS resolution.** Cheap, and it stops
+`http://127.0.0.1/`. It does not stop a hostname with an `A` record pointing at
+`127.0.0.1`, which is the standard way this is exploited. Resolving is the
+point of the guard as a whole — the hook's literal check is a fast early
+reject, but the tool must still resolve the hostname and check the resolved
+addresses before it connects, since it is the tool that ends up holding those
+addresses.
+
+**Make `resolveHost` a required option.** Rejected: every existing construction
+site would have to pass it, and the one that forgets ships a tool with no guard.
+Defaulting it means the unsafe configuration cannot be expressed by omission.
+
+**Put the initial-URL check only in the hook pipeline, not in each tool.**
+Tempting once the pipeline landed: the guard is exactly the cross-cutting
+per-tool gate the pipeline exists for, a rejection there reaches the model as
+guidance without the call executing, and one hook covers every URL-bearing tool
+instead of each tool re-implementing the same preamble. `EgressGuardHook` ships
+by default in `harnessHooks` (`lib/hooks/registry.ts`), so
+every host gets the model-facing guidance without registering anything — but
+the tools still keep their own check, because a tool can be constructed
+directly and called outside the hook pipeline, and that construction site must
+stay guarded on its own. A host that needs to drop the hook builds its own
+hook list instead of using `harnessHooks`; the tool-level check still holds
+either way.
+
+**Rely on the redirect-following code to re-enter the guard implicitly.** Rejected
+— redirect handling lives in shared helpers that do not own the resolver, so the
+hop check is written explicitly at each hop instead. A guard that only runs on the
+first URL is bypassed by any open redirect.
+
+**Filter `process.env` by pattern (drop anything matching `*TOKEN*`, `*KEY*`).**
+Rejected: it reads as security while depending on naming discipline in software we
+do not control.
+
+**Rely on the fs grants alone, and trust hosts not to grant a directory that
+contains the vault.** Rejected: the natural grant on desktop and mobile _is_ the
+user's home or the app sandbox, and both contain the storage root. A boundary that
+holds only while every host picks a narrow grant is not a boundary.
+
+## Consequences
+
+- A new URL-bearing tool must run `resolveOutboundUrl` itself, on its own target
+  and on any URL it derives mid-execution (redirects, discovery), and should be
+  added to `EgressGuardHook`'s tool match so the refusal reaches the model
+  as guidance. A tool that opens its own socket is outside the boundary and the
+  review checklist should catch it.
+- A new host embedding the harness gets `EgressGuardHook` and
+  `SkillCatalogGuardHook` by default through `harnessHooks`; registration is
+  optional, not required. A host that needs to drop one builds its own hook
+  list instead of using `harnessHooks`. Dropping the egress hook costs
+  the guidance, not the gate; dropping the catalog hook leaves skill loading
+  bounded only by the `skill` tool's `Localdrive` root, so the loadable set is
+  the whole skills directory rather than the advertised catalog.
+- New entries in `EXEC_ENV_ALLOWLIST` need a stated reason — the file's comments
+  say what each existing entry is load-bearing for, and `PATH` in particular is
+  what makes the exec binary allowlist resolvable.
+- The Node fetch path pins each request to the address set returned by the
+  egress check. A direct use of the low-level Node fetch adapter without a
+  supplied address set performs its own validating lookup before connecting.
+- A new fs-shaped tool takes `deniedRoots` and resolves through `resolveKey`; one
+  that walks the tree must also drop denied entries while enumerating, not only
+  refuse the eventual read. A new host embedding the harness must pass the deny
+  root — omitting it hands the vault to whatever else it grants.
+- `workdir` on a device with no granted directories is an error, not a silent
+  fallback to the process cwd. That is intended, and the error text says to use
+  absolute paths instead.
+- Revisit if the harness ever needs to reach a private address deliberately — a
+  self-hosted MCP server on a LAN, say. That needs an explicit per-device grant,
+  not a hole in `private-ip.ts`.
+
+## 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-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.