@qvac/harness 0.2.7 → 0.2.9

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`.

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

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

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

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

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

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

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

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

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