@qvac/harness 0.2.8 → 0.2.9

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

@@ -1,126 +0,0 @@
----
-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

@@ -1,88 +0,0 @@
----
-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

@@ -1,79 +0,0 @@
----
-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

@@ -1,68 +0,0 @@
----
-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

@@ -1,84 +0,0 @@
----
-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

@@ -1,176 +0,0 @@
----
-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`.