Generic per-harness cache pre-warm before sandboxing (first-launch plugin/dep fetch fails through omac's proxy; opencode is the first concrete case)

[nhuelstng]

Problem (general)

Any harness that fetches something from the network on its first launch — a plugin, a provider package, model metadata, a runtime component — breaks the first time it runs under omac start in a new workdir, because:

1. Authenticated proxy not traversed. omac injects HTTP_PROXY/HTTPS_PROXY=http://omac:<token>@127.0.0.1:<port> and forces all egress through its filtering proxy. Installers/fetchers that don't send the proxy's basic-auth credentials fail silently — no net DENY line, because the request never becomes an allowed connection. --allow-domain on the registry does not help; it is not a filesystem grant issue either.
2. Per-workdir cache. The tool cache is PreparePersistent(DomainWorkdir, …) → ~/.cache/omac/sha256(\"v1:workdir:\"+canonical-workdir), and omac start/serve inject XDG_CACHE_HOME=<scope>/xdg (internal/toolcache/cache.go, internal/cli/start.go). So the cache is per-workdir: every new project folder starts cold and re-hits the failing fetch. A one-time global warm does not help.

The harness works fine outside omac (direct fetch), but fails on the first omac start in any workdir the user has not already warmed. Since we cannot know in advance which folder the user will start omac in, a manual/install-time pre-warm of one workdir is not a reliable fix.

First concrete case: OpenCode @tngtech/opencode-skainet

OpenCode config declares plugin: [\"@tngtech/opencode-skainet@latest\"]; on startup it uses Bun's package installer to fetch the plugin, then loads it to register the skainet provider. Inside the sandbox the install fails (per above), so the provider is never registered:

ProviderModelNotFoundError: Model not found: skainet/zai-org/GLM-5.2

(surfaced as a generic UnknownError / Unexpected server error).

Reproduce

XDG_CACHE_HOME=$(mktemp -d)/xdg \
  omac sandbox run --profile tng-default --allow-domain chat.model.tngtech.com \
    --allow-env XDG_CACHE_HOME --write <config> --write <cache> \
    -- opencode run \"hello\"
# -> ProviderModelNotFoundError: Model not found: skainet/...

The cache dir is deterministic, so pre-warming a known workdir works and afterwards omac start there runs offline (verified) — but only for that one folder.

Other harnesses have analogous first-launch fetches (provider packages, model metadata, runtime components) that will hit the same wall; the fix should not be opencode-specific.

Proposed fix — a generic, harness-agnostic pre-warm

A per-harness declared warm step that omac runs in the prepared tool-cache scope, with direct network, before entering the sandbox. omac already prepares the toolcache scope (PreparePersistent) ahead of launch; run the harness's declared warm command against that scope first, then sandbox. Harness-agnostic: each harness (opencode, codex, copilot, future) declares its own warm command (e.g. opencode → opencode models); omac just runs whatever the active harness declares. One-time per workdir, automatic, no user action.

Alternatives (also harness-agnostic):

• Proxy-aware fetch — make installs traverse omac's authenticated proxy (or have the proxy accept them), so no warm is needed at all.
• Shared cache domain — let plugin/dep packages live in a cross-workdir shared cache so one warm covers every workdir.

Context

Found via the omac-tng-installer e2e suite (test/e2e), which reports OpenCode as a documented SKIP (known limitation) against a cold per-workdir cache rather than masking it with a same-workdir pre-warm. Claude Code, Codex, and the skainet/taia proxies all pass.

[nhuelstng]

make it optional (you only need to be able to do it rarely)

[nhuelstng]

alternative: make an omac prewarm that just lets all dependencies update

[nhuelstng]

currently it seems like it is not needed

[Retr0MrWave]

Reproduced #155's concrete case end-to-end — but the mechanism is not proxy traversal, and half the premise is stale post-#144.

Setup: omac built from main (26ff8e3), Linux/bwrap, opencode 1.17.16, ~/.config/opencode/opencode.json declaring plugin: ["@tngtech/opencode-skainet@latest"].

host:            opencode models | grep -c '^skainet'   → 13
omac start:      omac start opencode -- models          → 71 models, 0 skainet

1. The installer does traverse the proxy. This issue states the fetch "fail[s] silently — no net DENY line, because the request never becomes an allowed connection". The run log says otherwise:

28 × ALLOW registry.npmjs.org:443 (allow_domain)

npm reached the registry fine and got an honest 404. The plugin is on an internal registry, and the @tngtech scope→registry mapping lives in ~/.npmrc, which is a baseline protected path (internal/sandboxprofile/baseline.go:51). Masked inside the sandbox → npm asks the public registry:

$ omac sandbox run -- npm view @tngtech/opencode-skainet version
npm error 404 Not Found - GET https://registry.npmjs.org/@tngtech%2fopencode-skainet
$ npm view @tngtech/opencode-skainet version     # host
1.0.3

The omac-scoped package dir is created but left empty — no package.json, no node_modules:
~/.cache/omac/<digest>/xdg/opencode/packages/@tngtech/opencode-skainet@latest/

In the failing run, tng-artifacts.int.tngtech.com was never contacted at all.

2. A/B confirms it. Same cold XDG_CACHE_HOME, same profile, only difference filesystem.read: ["~/.npmrc"] + filesystem.override_deny: ["~/.npmrc"] + allow_domain: tng-artifacts.int.tngtech.com:

control: total=71  skainet=0    (only ALLOW registry.npmjs.org)
fixed:   total=79  skainet=13   → installs @tngtech/opencode-skainet 1.0.3
         ALLOW tng-artifacts.int.tngtech.com:443 (allow_domain)
         ALLOW chat.model.tngtech.com:443 (allow_domain)

(The non-skainet count drops 71→66 because the plugin sets disabled_providers: ["opencode"].)

So for this case a pre-warm would work by accident — it warms outside the sandbox where ~/.npmrc is readable. The credential/config-visibility axis (#150) is the actual cause here, and a pre-warm would mask it rather than fix it.

3. The per-workdir premise is stale. #144 moved the default cache scope to global (omac start -cache-scope defaults to global; toolcache.DescribeShared), so a warm is no longer per-folder. What remains is subtler: the omac scope is a different cache from the host's, and opencode writes a generated package.json + lockfile per spec dir, so @latest is frozen at first resolution. This host's July copy still pins 0.13.0 while npm view says 1.0.3:

~/.cache/opencode/packages/@tngtech/opencode-skainet@latest/package.json
  → { "dependencies": { "@tngtech/opencode-skainet": "0.13.0" } }   # 2026-07-09

That's why the reporter in #241 saw no effect from host-side --force reinstalls and cache purges: none of those paths are what the sandbox reads. omac cache clear is the only reset.

4. One more grant gap for the pre-warm design. The plugin caches its model list at XDG_STATE_HOME || ~/.local/state + opencode-skainet/models/<provider>-<sha1(baseURL)>.json (verified in 1.0.3 dist/config/cache.js). omac grants ~/.local/state/opencode but not ~/.local/state/opencode-skainet (internal/config/harness.go:253-258), and toolcache.Environment redirects XDG_CACHE_HOME but not XDG_STATE_HOME (internal/toolcache/cache.go:118). So even a warmed plugin can't read or write its cache inside the sandbox. Any pre-warm that only warms XDG_CACHE_HOME won't cover plugin state under $XDG_STATE_HOME/<plugin-name>/.

Real-world sighting: #241. Related: #150 (the actual root cause here), and #257 for the prompt-latency race this run also exposed.

[Retr0MrWave]

Re-scoped against #259, with data. The premise of this issue no longer
holds, and the remedy it proposes would mask the cause rather than fix it.

The opencode case is not a pre-warm problem. As reported in this thread
earlier: the installer traverses the proxy fine (28 × ALLOW registry.npmjs.org:443) and gets an honest 404, because the @tngtech
scope→registry mapping lives in a protected ~/.npmrc. #259 fixes that
inside the sandbox. A pre-warm would have "worked" only by warming outside
the sandbox, where the file is readable — i.e. by routing around the actual
defect.

The per-workdir premise is stale. #144 made the default cache scope
global (omac start -cache-scope defaults to global,
toolcache.DescribeShared), so a warm is no longer per-folder.

What genuinely remains is a grant gap, not a warm step. The plugin
already has its own cache; the sandbox just cannot see it. Measured on
Linux/bwrap with #259's projection enabled and discovery blocked:

~/.local/state/opencode-skainet granted     -> 14 models (from the cache)
not granted (omac's built-in default)       ->  0 models

So the offline/cold path this issue cares about is already solved by the
plugin — omac only has to stop hiding the cache. Generalized: any opencode
plugin that keeps state under $XDG_STATE_HOME/<plugin-name>/ is invisible
to the sandbox, because toolcache.Environment redirects XDG_CACHE_HOME
but not XDG_STATE_HOME (internal/toolcache/cache.go:118) and the harness
grants name only opencode itself.

Proposal

• Re-title this issue around plugin state visibility rather than
  cache pre-warm.
• Document that a profile must grant its plugins' state dirs, and note
  the $XDG_STATE_HOME/<plugin-name> convention. Zero code, unblocks
  users today.
• Decide whether omac should derive those paths itself. It could read
  opencode's plugin: [...] config and map package → state dir, but the
  package name is not reliably the plugin's own PLUGIN_NAME
  (@tngtech/opencode-skainet → opencode-skainet happens to match).
  Hardcoding a plugin name into the harness registry would violate the
  harness-agnostic rule in AGENTS.md, so this needs a deliberate call.
• Keep a generic per-harness warm step only if some other harness
  still needs one; the opencode case no longer motivates it.

Refs #259, #241.