@qvac/harness 0.2.6 → 0.2.8

package/docs/decisions/2026-06-02-kvcache-tool-turns-reenabled.md

@@ -0,0 +1,127 @@
+---
+id: ADR-2026-06-02-kvcache-tool-turns-reenabled
+status: superseded
+introduced_by: PR-QVAC-19770
+supersedes: [ADR-2026-05-29-kvcache-tool-turns]
+superseded_by: [ADR-2026-08-20-kvcache-static-placement]
+---
+
+# KV-cache session is re-enabled for tool-using completions
+
+> **Superseded** by
+> [ADR-2026-08-20-kvcache-static-placement](./2026-08-20-kvcache-static-placement.md):
+> the half of this record that still holds is that `kvCache: 'chat-<id>'` rides
+> every completion. The dynamic-mode half was built on a false premise — the
+> addon's compact-tools anchoring never ran on any shipped model (its arch gate
+> is exact `qwen3`; ours are `qwen35`/`qwen36`), so the coherence this record
+> credits to dynamic mode was never exercised, and the "static never surfaced
+> the tool-call format" claim did not survive re-testing. core-v2 loads static
+> with no sliding window since 2026-08-20; mechanics in
+> `docs/kvcache-reference.md`. The `QVAC_PROMPT_CACHE` kill-switch and
+> `deleteChatPromptCache` described below were core-v1 machinery and do not
+> exist in the current runtime.
+
+## Decision
+
+The `@qvac/sdk` session prompt cache (`completion({ kvCache: "chat-<id>" })`) is
+passed for **all** completions with a chatId — tool-using and tool-free alike —
+gated only by the `QVAC_PROMPT_CACHE` kill-switch. This reverses
+ADR-2026-05-29, which disabled the cache whenever tools were present.
+
+## Context
+
+The prior decision disabled tool-turn caching because the SDK's DYNAMIC cache
+path broke tool-call parsing: it ships a role-based history fragment and trusts
+the addon's tool-chain anchoring, which our reconstructed history did not
+satisfy → `<tool_call>` markup leaked as text. Two things changed:
+
+- Models loaded with `modelConfig.toolsMode: "dynamic"` (QVAC-19660). In
+  dynamic mode the addon anchors tools per-turn (compact-tools), excludes the
+  tool set from the cache config hash, and the fragment slicing keeps
+  multi-round tool turns coherent — including across a model evict/reload.
+  **No longer true as of `@qvac/sdk` 0.18 (QVAC-23936):** the key was removed
+  and the parser rejects it, so static is the only placement. Dynamic was in
+  any case a silent no-op on every arch we ship — the addon gates
+  `tools_compact` on exact-arch `qwen3` while our catalog is `qwen35`/`qwen36` —
+  and the SDK still sliced as-if-dynamic, which made the cache the chat's
+  _memory_ rather than an accelerator: after any cache reset it sent only the
+  last exchange. Under static placement the tool block sits in the addon's
+  protected prefix instead, and 0.18 keeps it out of the primed prefix
+  (QVAC-23251) so the qwen3.5 template no longer raises 'No user query found in
+  messages.'
+- An SDK e2e guard (`kv-cache-tools-dynamic-reuse`, plus a qwen35-dialect
+  variant) verifies a custom-key multi-round tool chain reuses the on-disk cache
+  (`cacheTokens > 0`) and keeps tool calls parseable across an evict/reload.
+
+With the DYNAMIC path proven coherent across reload, the heavyweight
+"reconstruction invalidation / byte-identical history" work the prior ADR
+deferred is unnecessary; divergence is handled with targeted invalidation.
+
+## Consequences
+
+- **Do not pass `toolsMode` at model load.** SDK 0.18 removed the key and its
+  parser rejects an unrecognised one, so passing it fails the load outright and
+  the app parks on the splash. Static placement is the default and the only mode.
+- Dropping a key from `modelConfig` re-keys `modelId`, which is identity-by-config,
+  so expect one cold prime per chat on the first run after such a change.
+- Tool turns reuse the session KV cache: lower TTFT/prefill on multi-round tool
+  turns and follow-ups (manually: round-2 TTFT ~1.1s → ~0.3s; cacheTokens grows
+  monotonically across a conversation).
+- `QVAC_PROMPT_CACHE` (default on; `0`/`false`/`off`) disables all
+  prompt caching as a kill-switch.
+- The per-chat cache is explicitly invalidated on chat delete and agent delete
+  (which cascades to its chats) via `deleteChatPromptCache`, plus a defensive
+  drop on retry (see below). Edit / branch / truncate flows do not exist yet and
+  need no hook.
+- **Why stop / failed / new-message-after-failure need no invalidation.** The
+  cache only ever holds _successful_ turns: the SDK rolls back uncommitted turns
+  on abort (the custom-key path commits only when not aborted and tokens were
+  produced), and failed / canceled / not_delivered replies are excluded from
+  model-visible history (`isModelVisibleMessage`, `qvac-app → core/src/services/common/history.ts`).
+  So a stopped or failed turn leaves neither a committed cache entry nor a
+  visible history row — the reconstructed history and the cached prefix stay
+  aligned, and the next turn (new message or retry) does not slice against a
+  stale prefix. The SDK's own `kv-cache-cancel-then-new-prompt` e2e covers this
+  cancel-then-continue coherence. The **retry** `deleteChatPromptCache` is
+  therefore belt-and-suspenders, not load-bearing: it costs one re-prime on a
+  rare, user-initiated path and removes any dependence on the rollback timing.
+- **Mobile scope.** Mobile now runs the same assistant and harness completion path
+  inside its supervised Bare worklets, so the per-chat cache key reaches the SDK
+  without the retired worker-to-host SDK bridge.
+- `chatPromptCacheKey` is the single source of truth for the `chat-<id>` key
+  shared by the completion path and the invalidation callers.
+- Known SDK limitation: on a multimodal (M-RoPE, `n_pos_per_embd > 1`) model such
+  as Qwen3.5, the SDK's KV sliding-window position shift (`seq_add`/`seq_div` via
+  `trySlidePrefill`) GGML_ASSERT-crashes the worker when the context fills. A
+  standalone SDK repro confirmed this is **independent of `toolsMode` (static and
+  dynamic both crash) and of whether tools are passed**, and is not caused by the
+  prompt cache — it is the sliding window itself, unsupported for multi-pos
+  models. Interim mitigation (separate from the kill-switch): we temporarily
+  stopped setting `n_discarded` at model load so on overflow the SDK took the
+  catchable `CONTEXT_OVERFLOW` path instead of the crashing slide.
+  **Resolved (2026-06-23):** `@qvac/sdk` 0.13.5 (llm-llamacpp 0.24.0) ships
+  M-RoPE/iM-RoPE sliding-context support, so `n_discarded` is set again in
+  `@qvac/sdk → model/model-load-config.ts` and the workbench no longer trims history. See
+  [`2026-06-23-append-only-history.md`](./2026-06-23-append-only-history.md).
+- Regression guards updated: the contract test now asserts `kvCache` IS sent
+  with tools; the spec-fake models dynamic mode (healthy on a tools cache hit);
+  invalidation hooks are covered.
+- **The in-repo suite cannot prove real dynamic-mode coherence.** The spec-fake
+  (`@qvac/sdk → __fixtures__/fake-completion-sdk.ts`) is parameterized to treat dynamic mode
+  as healthy, so the in-repo tests guard against regressing the model load back
+  to static mode and against dropping the `kvCache` key — but they do not prove
+  the SDK's real DYNAMIC path stays coherent against our reconstructed history.
+  That proof lives in the out-of-repo SDK e2e (`kv-cache-tools-dynamic-reuse`
+  and its qwen35 variant), which this repo's CI cannot run.
+
+## When Agents Should Read This
+
+Read this before changing how `kvCache` is passed to `sdk.completion`,
+`toolsMode` at model load, the agentic loop's history construction, transcript
+reconstruction, or the cache invalidation hooks —
+`qvac-app → core/src/services/message/agentic-completion.ts`,
+`qvac-app → core/src/services/model/service.ts`,
+`qvac-app → core/src/services/execution/service.ts`,
+`qvac-app → core/src/services/api/domain-apis.ts`,
+`@qvac/core → lib/assistant.ts`, and
+`lib/capabilities/completion.ts`.

package/docs/decisions/2026-06-23-android-cpu-llm-defaults.md

@@ -0,0 +1,126 @@
+---
+id: ADR-2026-06-23-android-cpu-llm-defaults
+status: active
+introduced_by: PR-691
+supersedes: []
+---
+
+# Android LLM defaults to CPU except Tensor-era Pixels
+
+## Decision
+
+Android LLM inference defaults to CPU with a `q4_0` KV cache, except on
+Tensor-era Google Pixel devices before Pixel 10 where LLM inference defaults
+back to GPU. Pixel 10 and newer remain on CPU.
+
+## Context
+
+Android GPU inference runs on Vulkan, which is unreliable across the fleet:
+Adreno on Snapdragon devices, including many Samsung variants, aborts under the
+LLM workload, and older devices ship buggy drivers. CPU is the only
+consistently stable target.
+
+The earlier Samsung and Pixel 10 CPU special-casing plus stripping the KV-cache
+quantization fields at the host boundary existed only to dodge the Vulkan abort.
+With all inference on CPU that abort path is gone, so a quantized `q4_0` cache
+is safe and lowers memory use.
+
+Pixel 9 profiling later showed that long chat/tool-shaped prompts can collapse
+decode throughput on the SDK CPU path while the GPU path keeps decode TPS
+healthy. Pixel 10 had prior GPU stability issues, so the exception is limited
+to Tensor-era Pixel devices before Pixel 10, including Pixel Tablet and the
+first-generation Pixel Fold. Original Pixel phones are not included in this
+exception.
+
+Core v2 device profiling (2026-07) added two KV-cache facts for the GPU
+exception: a quantized V cache aborts the Adreno backend outright, and a
+quantized K cache forces per-token dequantization onto a slow flash-attention
+path on Mali (Pixel 8 decode dropped from ~10 tps to ~3 tps). The GPU branch
+therefore sends no KV-cache override at all; the SDK default f16/f16 is both
+the stable and the fast profile, matching shipped 0.12. The harness
+additionally clamps cache-type-v to f16 on Android GPU loads as a backstop.
+
+## Consequences
+
+- Embeddings follow the same split, and only on Android: Android devices and
+  every simulator pin `embedDevice: "cpu"`, while iOS devices keep GPU
+  embeddings. That matches the retired Core v1 policy and reflects the failure modes:
+  Adreno/Vulkan aborts outright, whereas a Metal device-lost fault self-heals
+  through the harness escalation in `lib/models/sdk-faults.ts`
+  (reload once, fall back to CPU on a repeat).
+- Do not reintroduce host-boundary KV-cache field stripping; it only made sense
+  for the GPU/Vulkan path.
+- This trades GPU acceleration on most Android devices for reliability and
+  lower memory.
+- Tensor-era Pixel devices before Pixel 10 keep GPU acceleration for LLM
+  completions.
+- Pixel 10 and newer stay on the Android CPU/q4_0 policy.
+- Revisit if the SDK gains a capability probe that can distinguish Vulkan
+  drivers/devices that are safe under load, allowing a selective GPU re-enable.
+
+## Amendment 2026-08-03: the abort attribution is unverified
+
+The Adreno aborts above are attributed to Vulkan, but the app never supplied
+`openclCacheDir` on any load. `@qvac/llm-llamacpp` documents Adreno 700+ as an
+**OpenCL** target, and the OpenCL backend `ggml_abort()`s during init when it
+cannot write its kernel cache, the same symptom this ADR blames on Vulkan. The
+backend that actually ran was never recorded, so which of the two caused the
+aborts is still open.
+
+Three things changed to make it answerable rather than re-litigated:
+
+- `configureSdkStorage` now exports a writable kernel-cache directory, and the
+  harness passes `openclCacheDir` on Android LLM, embedding and transcription
+  loads (`lib/models/opencl-cache.ts`).
+- The KV clamp covers **K as well as V** on Android GPU loads
+  (`adrenoSafeKvCache`). Adreno OpenCL throws on any K type other than
+  `f16`/`f32`/`bf16`, and this ADR's own Mali finding points the same way; only V
+  was clamped before, so an agent row pinning `kvCacheK` reached the load
+  unclamped.
+- `EXPO_PUBLIC_QVAC_ANDROID_LLM_DEVICE` and
+  `EXPO_PUBLIC_QVAC_ANDROID_EMBED_DEVICE` (`"cpu" | "gpu"`) override the Android
+  branches per build, so a device can be retested without a code change. The
+  simulator branch ignores them.
+
+The defaults in this ADR are unchanged and remain in force. Before flipping any
+of them, record on real hardware the `backendDevice` value from
+`hlog('round stats', …)` (the SDK reports `cpu | vulkan | metal | opencl`) plus
+cold and warm `hlog('llm loaded', { loadMs })`. `opencl` means the kernel cache
+is load-bearing and this ADR's attribution needs correcting; `vulkan` means the
+cache dir is inert on this fleet and the CPU pin stands on its original
+reasoning.
+
+## Amendment 2026-09-04: transcription follows the split too
+
+The Consequences above extended the split to embeddings and stopped there, so
+the transcription pool loaded parakeet with a hardcoded `useGPU: true` on every
+device — including the Pixel 10 whose GPU this ADR pins to CPU for the LLM. On
+that hardware the model loads, runs for a time proportional to the clip, and
+returns an empty transcript, so the app reports "contained no detectable
+speech" about a file full of speech. Nothing throws, so the
+`voice gpu load refused, retrying on cpu` fallback added for QVAC-24132 never
+fires: it covers a load that fails, not one that succeeds and produces nothing.
+
+Transcription now takes the same GPU verdict as the LLM, carried on the host
+boundary as `transcriptionDevice` (`"cpu" | "gpu"`) alongside `llmDevice` and
+`embedDevice`, with `EXPO_PUBLIC_QVAC_ANDROID_TRANSCRIPTION_DEVICE` and
+`EXPO_PUBLIC_QVAC_IOS_TRANSCRIPTION_DEVICE` to retest a device per build. An
+absent value still means GPU, so desktop is unaffected. Parakeet allocates its
+weights in one `ggml_backend_alloc_ctx_tensors` call with no partial-offload
+knob, so a GPU this ADR does not trust with the LLM cannot be trusted with it
+either.
+
+Still open: the voice pools have no equivalent of the embedding fault
+escalation in `lib/models/sdk-faults.ts`, so an empty
+transcript from a GPU-loaded model is reported as fact rather than retried on
+CPU. Until that exists, a mis-set device is silent rather than self-healing.
+
+## When Agents Should Read This
+
+Read when changing Android device selection or KV-cache configuration for any
+inference category — LLM, embeddings or transcription — in
+`qvac-app → mobile/lib/android-llm-device.ts`, `qvac-app → mobile/lib/core-v2-harness-config.ts` or
+the pool constructors in `index.ts`, or re-evaluating the
+Android Vulkan/CPU and KV-cache Known Risks. Read the 2026-08-03 amendment
+before treating the Vulkan attribution as settled, and the 2026-09-04 amendment
+before adding a category that loads a model on the GPU.

package/docs/decisions/2026-07-29-assistant-owned-storage-layout.md

@@ -0,0 +1,88 @@
+---
+id: ADR-2026-07-29-assistant-owned-storage-layout
+status: active
+introduced_by: PR-000
+supersedes: []
+---
+
+# Assistant-owned storage separates shared models from private KV
+
+## Decision
+
+The assistant owns the Desktop and Mobile storage layout. Hosts pass a release
+environment plus optional root/model overrides; they do not construct assistant
+or SDK subpaths.
+
+Models stay at the SDK's canonical shared location on every platform:
+
+```text
+~/.qvac/models/             SDK-wide model and asset cache
+```
+
+(Snap uses `$SNAP_USER_COMMON` as the home base, i.e.
+`$SNAP_USER_COMMON/.qvac/models`.) This deliberately matches the `@qvac/sdk`
+default (`getDefaultCacheDir → $HOME/.qvac/models`) so a standalone SDK, a CLI, or
+another QVAC product on the same machine reuses one downloaded model cache rather
+than each re-downloading multi-GB assets. Because of that sharing requirement
+models are **not** moved under `XDG_DATA_HOME` — the host may still relocate them
+explicitly via `QVAC_MODEL_CACHE_PATH` / the `models` override.
+
+The assistant **image cache** resolves via `bare-storage.persistent()` —
+`qvac/image-cache` under the OS data tier on every platform (`$XDG_DATA_HOME` on
+Linux, `~/Library/Application Support` on macOS, `%APPDATA%` on Windows; Flatpak
+`~/.var/app/<id>/data`). It stays in the _data_ tier (not `ephemeral()`/cache)
+because the assistant sweeps it itself (`imageCacheMaxBytes`/`imageCacheMaxAgeMs`
+→ `sweepImageCache`), so it does not rely on OS cache eviction.
+
+Private state is rooted at the platform persistent-data directory returned by
+`bare-storage` (or `SNAP_USER_COMMON` for Snap):
+
+```text
+qvac/{prod|staging|dev}/
+├── assistant/               private application state
+└── sdk-home/               private SDK runtime home, registry, and KV cache
+```
+
+The assistant writes an SDK JSON config with `cacheDirectory` pointing at the
+canonical models directory and uses the SDK's supported home override to assign
+each app/channel a private `sdk-home`. The SDK continues to derive its own
+KV-cache subpath; Workbench does not duplicate that SDK implementation detail.
+
+On Mobile, Delete All Data asks the live assistant harness to call the SDK's
+`deleteCache({ all: true })` operation before stopping Core, then removes only
+the `assistant` directory. A failed or unsupported KV-cache operation aborts the
+reset so Workbench does not report permanent deletion while conversation-derived
+cache remains. The host never deletes `sdk-home` directly, preserving SDK
+registry metadata alongside the shared model assets.
+
+The channel that home override rides on is per-runtime, not per-process. Off
+bare-kit it is `env[SNAP_USER_COMMON]`, which is also the key `resolveStorage`
+reads as the platform root; on bare-kit it is `Bare.argv[0]`, which `@qvac/sdk`
+prefers over `HOME_DIR` and resolves lazily. Bare-kit worklets share one OS
+`environ`, so a host that runs two of them — mobile runs the assistant and the
+harness side by side — would have each `configureSdkStorage` redefine the root
+the other's `resolveStorage` is about to read. Argv is copied into each
+runtime, so the write cannot leave the worklet that made it.
+
+Desktop `--storage`, `--tmp`, and `QVAC_STORAGE_PATH` replace only the private
+root. `QVAC_MODEL_CACHE_PATH` is a separate override for hermetic tests and
+other explicit host requirements. Mobile applies the same relative layout, but
+OS app-ID sandboxes naturally prevent sharing across Development, Staging, and
+Production installations.
+
+## Consequences
+
+- Desktop apps and release channels reuse downloaded model assets without
+  sharing conversations, meshes, runtime locks, or KV caches.
+- Mobile app reset clears every SDK KV cache through the harness and deletes
+  private assistant state while leaving shared models and SDK registry metadata
+  intact.
+- Existing `~/.qvac/models` downloads continue to be used on every platform —
+  models are unchanged and stay aligned with the SDK default. The assistant
+  **image cache** moved from `~/.qvac-assistant/image-cache` to
+  `bare-storage.persistent()` (`qvac/image-cache`, data tier) — a greenfield
+  change with no migration of prior cache data. Legacy global KV and app-data
+  directories are not migrated or deleted.
+- SDK cache layout changes remain owned by the SDK: Core supplies the supported
+  model-cache and home overrides and invokes SDK cache deletion without
+  reproducing the KV subpath.

package/docs/decisions/2026-08-04-sidecar-orphan-reaping.md

@@ -0,0 +1,79 @@
+---
+id: ADR-2026-08-04-sidecar-orphan-reaping
+status: active
+introduced_by: PR-1382
+supersedes: []
+---
+
+# The host reaps the sidecar's process group; the harness cannot reap itself
+
+## Decision
+
+When the assistant sidecar exits, the desktop host kills the sidecar's whole process group.
+The sidecar is spawned detached (`qvac-app → desktop/electron/assistant.ts`), so it leads its own group
+and every harness it spawns stays in that group; killing the group on the exit edge reaps the
+strays and can reach nothing else.
+
+This is POSIX-only, and so is the bug. On Windows the kernel already ties the tree together:
+libuv assigns every non-detached child to a Job Object created with `KILL_ON_JOB_CLOSE`
+("so windows will kill it when the parent process dies" — libuv's own comment), and
+`bare-subprocess` is a thin `uv_spawn` binding that sets `UV_PROCESS_DETACHED` only when asked.
+The sidecar and the harness are both spawned non-detached there, so killing the sidecar kills
+the harness at kernel level, mid-inference included. Verified empirically on a real Windows
+machine: sidecar killed mid-generation, both bare processes died, nothing lingered.
+
+The harness does not try to detect its own orphaning.
+
+## Context
+
+The harness holds gigabytes of loaded model weights. Stow's stop signal is pipe EOF, and a
+sidecar killed outright (SIGKILL, OOM) never runs the ordered teardown that bounds its child —
+so on POSIX the harness reparents to init and holds that memory until the machine reboots.
+
+A manual `kill -9` is only the cleanest way to reproduce it. The same state follows from an
+`abort()` or segfault in one of the sidecar's native addons (SQLite, the vector extension,
+ffmpeg image normalization), from the kernel OOM killer picking the sidecar instead of the
+harness, or from a developer killing a hung app.
+
+## Alternatives Considered
+
+An in-process watchdog in the harness (poll `os.ppid()`, exit on reparent) was implemented and
+reverted. The shipped bundle did contain the call, unref'd intervals do fire under bare, and
+`os.ppid()` is a live `getppid()` that reflects reparenting — yet a harness orphaned for minutes
+never exited. A harness parked in a native SDK call is not running JS at all, so no _JS-level_
+mechanism can survive it, whatever signal it watches.
+
+A native parent-death watcher would survive it, since it does not need the JS thread:
+`WaitForSingleObject` on the parent handle, `PR_SET_PDEATHSIG` on Linux, kqueue `NOTE_EXIT` on
+macOS. All require native work in bare, so the host-side reap was preferred.
+
+## Consequences
+
+- The host is the only place that can bound the harness on abrupt sidecar death. The reap must
+  stay wired for every sidecar spawned, whether or not a renderer ever adopted it.
+- The `detached: process.platform !== "win32"` split is load-bearing in both directions. POSIX
+  needs the detach or the group kill has nothing to aim at; Windows needs the non-detach or
+  libuv skips the job assignment and the kernel tie is lost. Setting `detached: true` on Windows
+  would create there the very bug this reap fixes on POSIX.
+- Keep the harness in the sidecar's group — never spawn it detached, on any platform. On POSIX
+  a detached harness leaves the sidecar's group and silently escapes this reap (no error, no
+  failing test unless the real-process test in
+  `qvac-app → desktop/test/electron/assistant-sidecar-orphan.test.ts` is kept); on Windows it leaves the
+  sidecar's job and escapes the kernel cascade the same way.
+- Prefer the group over a pid on POSIX. The harness's own children (exec and shell tools) are in
+  the group too; killing the harness pid alone leaves them orphaned.
+- The win32 branch of `forceKillAssistantSidecarTree` (`taskkill /T` on the sidecar) matters for
+  the clean-stop escalation, where the sidecar is alive but will not unwind; on the exit edge it
+  is a post-mortem no-op — the job object has already done the work.
+- Not solved on POSIX: the host dying abruptly while the sidecar is itself blocked in a native
+  call. Then the sidecar cannot act on its own pipe EOF and nothing alive can reap either
+  process. A sweep for stray harnesses at startup is the remedy if that shows up in practice.
+  (Windows is covered even here: the host's death closes its job handle and the cascade takes
+  the whole tree.)
+- `killStowChildren()` (`bare-supervisor/stow`) still covers a clean host exit; this covers the
+  abrupt sidecar death it cannot see.
+
+## 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-11-pyodide-worker-thread.md

@@ -0,0 +1,68 @@
+---
+id: ADR-2026-08-11-pyodide-worker-thread
+status: active
+introduced_by: PR-1524
+supersedes: []
+---
+
+# Pyodide runs in a worker thread with a shared interrupt buffer
+
+## Decision
+
+The harness executes python (Pyodide, CPython on WebAssembly) in a dedicated
+worker thread — `Bare.Thread` + `bare-channel` on Bare, `worker_threads` on
+Node — never on the harness thread. Cancellation goes through a 1-byte
+`SharedArrayBuffer` registered with `pyodide.setInterruptBuffer()`: the host
+writes SIGINT, CPython raises `KeyboardInterrupt` at the next bytecode
+boundary, and the interpreter survives for the next run. A run that ignores
+the interrupt past a grace window gets the worker killed and respawned.
+
+## Context
+
+`runPython` is synchronous inside Pyodide, so on the harness thread a busy
+script froze every tool and chat turn, and timeout/abort could only settle
+before or after a run. An interrupt can only be delivered from another thread
+(the blocked thread cannot run JS), so shared memory plus a second thread is
+the minimal correct shape. Two Bare constraints shaped the implementation:
+
+- `Bare.Thread.terminate()` is honored at a safepoint only. It cannot stop a
+  busy-spinning thread, and `join()` on one blocks forever — so on Bare a
+  wedged worker is abandoned (never joined), while Node's `terminate()`
+  genuinely kills. Joining a healthy worker is only safe after its channel end
+  has closed (`drainAndReap`), because the channel teardown itself needs the
+  host's event loop.
+- A fresh thread's module loader reads plain files only. Spawning a thread
+  whose entry lives inside a stowed `.bundle` aborts the whole process, but a
+  `.bundle` path _as the entry itself_ boots fine. Every stowed harness —
+  desktop (dev and packaged) and mobile — must therefore stage the worker as
+  its own bundle and name it via `QVAC_PYODIDE_WORKER_ENTRY`; until a host
+  sets it, a bundled harness falls back to the pre-worker in-process path
+  rather than crash, so the worker only runs under the harness test suites.
+
+## Alternatives Considered
+
+- **In-process with a watchdog thread writing the interrupt buffer**: keeps
+  the harness thread blocked during runs and cannot serve a user abort (the
+  event loop that would receive it is the blocked one).
+- **Subprocess CPython**: no wasm sandbox, not portable to mobile (iOS forbids
+  spawning processes).
+
+## Consequences
+
+- The worker thread is an availability boundary, not a security boundary:
+  python can still reach the worker realm's globals via `from js import …`, so
+  a python grant keeps shell-level trust (see `scope.ts`).
+- Anything that changes worker/entry module paths must keep the
+  bundled-harness fallback and the `QVAC_PYODIDE_WORKER_ENTRY` override
+  working, or every bundled host crashes on the first python run.
+- The in-process path survives for injected test loaders only; fakes cannot
+  cross a thread boundary. Worker transport tests load a fake interpreter
+  inside the thread via `QVAC_PYODIDE_TEST_LOADER`.
+- Revisit if Bare threads gain forced termination, or when the packaging
+  pipeline ships the staged worker bundle (the fallback then becomes dead
+  code).
+
+## 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-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.