loadouts 0.2.5 → 0.4.0

package/docs/authoring.md

@@ -26,10 +26,13 @@ targets:
     mode: subagent
     steps: 8
     color: accent
-    permission:
-      bash:
-        "*": ask
-        "git diff*": allow
+    permissions:
+      - action: shell
+        resource: "*"
+        effect: ask
+      - action: shell
+        resource: "git diff *"
+        effect: allow
 
   cursor:
     is_background: false
@@ -219,7 +222,7 @@ include:
 
 ---
 
-## OpenCode Config And Plugins
+## OpenCode Config, Commands, And Plugins
 
 OpenCode-specific artifacts live under `.loadouts/opencode/` and only render when included in a loadout that targets `opencode`.
 
@@ -228,34 +231,86 @@ OpenCode-specific artifacts live under `.loadouts/opencode/` and only render whe
 // .loadouts/opencode/opencode.jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-wakatime"]
+  "plugins": ["opencode-wakatime"]
 }
 ```
 
 Project scope renders this to `opencode.jsonc`. Global scope renders it to `~/.config/opencode/opencode.jsonc`. This is whole-file ownership; if you do not include this artifact, loadouts does not touch your OpenCode config file.
 
+**Slash commands:**
+```md
+<!-- .loadouts/opencode/commands/loadouts.md -->
+# /loadouts
+
+Arguments: `$ARGUMENTS`
+```
+
+Project scope renders this to `.opencode/commands/loadouts.md`. Global scope renders it to `~/.config/opencode/commands/loadouts.md`.
+
 **Local plugins:**
 ```ts
 // .loadouts/opencode/plugins/notify.ts
-import type { Plugin } from "@opencode-ai/plugin";
-
-export const Notify: Plugin = async ({ $ }) => ({
-  "session.idle": async () => {
-    await $`osascript -e 'display notification "Session completed" with title "opencode"`;
+export default {
+  id: "notify",
+  async setup(ctx) {
+    // register hooks here
   },
-});
+};
 ```
 
-Project scope renders this to `.opencode/plugins/notify.ts`. Global scope renders it to `~/.config/opencode/plugins/notify.ts`.
+Project scope renders this to `.opencode/plugins/notify.ts`. Global scope renders it to `~/.config/opencode/plugins/notify.ts`. A bare local server plugin file cannot resolve `@opencode/plugin` (local plugin directories do not install dependencies); reference it by path from `opencode.json(c)` `plugins`, or publish a package.
 
 **Include in a loadout:**
 ```yaml
 include:
   - opencode/opencode.jsonc
+  - opencode/commands/loadouts.md
   - opencode/plugins/notify.ts
 ```
 
-NPM plugins belong in the managed `opencode.json(c)` `plugin` array. Local plugin source files belong in `.loadouts/opencode/plugins/`.
+NPM packages belong in the managed `opencode.json(c)` `plugins` array. Local plugin source files belong in `.loadouts/opencode/plugins/`.
+
+**TUI plugins:**
+
+OpenCode V2 CLI plugins are a `./tui` module of a plugin directory, loaded alongside the server entry. The TUI host supplies `@opencode/plugin/tui`, `@opentui/solid`, and `solid-js`, so local TUI sources need no install. They are useful for user-facing UI that should not be added to chat or model-visible prompt context.
+
+**Local plugin directories** (kind `opencode-plugin-dir`) render every file in the directory:
+
+```yaml
+include:
+  - opencode/plugins/loadouts
+```
+
+The bundled `opencode-runtime` loadout renders a working package-directory example to `plugins/loadouts/` — see `loadouts docs runtime`.
+
+```tsx
+// .loadouts/opencode/plugins/status-popup/tui.tsx
+/** @jsxImportSource @opentui/solid */
+
+import { Plugin } from "@opencode/plugin/tui";
+
+export default Plugin.define({
+  id: "status-popup.tui",
+  setup(context) {
+    context.keymap.layer(() => ({
+      commands: [
+        {
+          id: "status_popup_open",
+          title: "Open status popup",
+          palette: true,
+          slash: { name: "status-popup" },
+          run() {
+            context.ui.dialog.set({ size: "medium" });
+            context.ui.dialog.show(() => <box border paddingLeft={2}>TUI-only popup</box>);
+          },
+        },
+      ],
+    }));
+  },
+});
+```
+
+The server entry (`index.ts` with `{ id, setup }`) sits beside this file in the same directory.
 
 ---
 

package/docs/commands.md

@@ -52,12 +52,36 @@ Compile a runtime bundle for inspection (no filesystem activation). Defaults to
 loadouts runtime                     # Compile default loadout
 loadouts runtime base backend        # Compile multiple loadouts
 loadouts runtime base --tool cursor  # Target a different tool
+loadouts runtime base -l             # Force local/project scope
+loadouts runtime base -g             # Force global scope
 loadouts runtime base --json         # Output RuntimeBundle JSON only
 loadouts runtime base --system-block # Output renderRuntimeSystemBlock(bundle) only
 ```
 
 See `docs/runtime.md` for architecture, OpenCode-first integration flow, and per-tool capability flags.
 
+### `loadouts session <status|equip|unequip|list>`
+Manage durable equipment on one OpenCode V2 session without filesystem activation.
+```bash
+loadouts session list
+loadouts session status --session ses_...
+loadouts session equip backend --session ses_... -p
+loadouts session equip caveman --session ses_... -g
+loadouts session unequip --session ses_...
+```
+Omit `--session` to target the most recently updated root session at the current
+directory. `-g`/`-p` select the loadout source scope. All subcommands accept `--json`.
+The running service is discovered automatically and is never started by this command.
+
+### `loadouts tui`
+Open the standalone dashboard (Node 22.19+). Use `[` / `]` for All/Global/Project
+tabs and `h` / `l` or `Tab` to change sections. Row actions infer their filesystem
+scope. Press `S` to target a running OpenCode conversation, then `m` to switch
+filesystem/session mode. See [dashboard navigation](runtime.md#opencode-dashboard).
+The embedded OpenCode dashboard
+opens with `/loadouts` or `ctrl+l`; `/loadouts equip <names…> [-g|-p]`,
+`/loadouts unequip`, `/loadouts status`, and `/loadouts quick` run client-side.
+
 ### `loadouts diff [name]`
 Preview what would change if a loadout were applied.
 ```bash

package/docs/compatibility.md

@@ -4,13 +4,13 @@ Current built-in rendering targets for canonical artifacts.
 
 ## Artifact Paths (Project Scope)
 
-| Tool | Rule | Skill | Agent | Instruction |
-|------|------|-------|-------|-------------|
-| Claude Code | `.claude/rules/<name>.md` | `.claude/skills/<name>/` | `.claude/agents/<name>.md` | `CLAUDE.md` (generated wrapper to `AGENTS.md`) |
-| Cursor | `.cursor/rules/<name>.mdc` | `.cursor/skills/<name>/` | `.cursor/agents/<name>.md` | `AGENTS.md` |
-| OpenCode | `.opencode/rules/<name>.md` | `.opencode/skills/<name>/` | `.opencode/agents/<name>.md` | `AGENTS.md` |
-| Codex | - (no rule target) | `.agents/skills/<name>/` | `.codex/agents/<name>.toml` | `AGENTS.md` |
-| Pi | - (no native rule target) | `.pi/skills/<name>/` | - | `AGENTS.md` |
+| Tool | Rule | Skill | Agent | Instruction | Extra Artifacts |
+|------|------|-------|-------|-------------|-----------------|
+| Claude Code | `.claude/rules/<name>.md` | `.claude/skills/<name>/` | `.claude/agents/<name>.md` | `CLAUDE.md` (generated wrapper to `AGENTS.md`) | - |
+| Cursor | `.cursor/rules/<name>.mdc` | `.cursor/skills/<name>/` | `.cursor/agents/<name>.md` | `AGENTS.md` | - |
+| OpenCode | `.opencode/rules/<name>.md` | `.opencode/skills/<name>/` | `.opencode/agents/<name>.md` | `AGENTS.md` | `.opencode/commands/<name>.md`, `.opencode/plugins/<name>.{ts,tsx,js}`, `~/.config/opencode/cli.json(c)` (global-only), `opencode.json(c)` |
+| Codex | - (no rule target) | `.agents/skills/<name>/` | `.codex/agents/<name>.toml` | `AGENTS.md` | - |
+| Pi | - (no native rule target) | `.pi/skills/<name>/` | - | `AGENTS.md` | - |
 
 Global scope uses each tool's configured global base path. Instruction files may render to home-level `AGENTS.md` or `CLAUDE.md` paths depending on the tool.
 
@@ -24,7 +24,7 @@ Rendered aliases for compatibility:
 
 - Cursor/OpenCode rules: `paths` is mirrored to `globs`.
 - Cursor/OpenCode rules: `activation` is mirrored to `alwaysApply` (`always -> true`, `scoped -> false`).
-- OpenCode skills: `model-invocable` is mirrored to `disable-model-invocation` (inverted boolean).
+- OpenCode skills: `model-invocable` is mirrored to `metadata["opencode/autoinvoke"]` (same boolean, not inverted — OpenCode V2 has no `disable-model-invocation` field).
 - Agent overlays are rendered into each harness' native frontmatter. Codex agents are generated as TOML with the Markdown body mapped to `developer_instructions`.
 
 Transforms add aliases when canonical fields are present and alias fields are not already set.

package/docs/concepts.md

@@ -79,7 +79,9 @@ include:
 | `prompt` | file | Slash command templates |
 | `extension` | directory | Runtime code extensions |
 | `theme` | file | UI theme configuration |
+| `opencode-command` | file | OpenCode slash command markdown |
 | `opencode-config` | file | Whole-file OpenCode runtime configuration |
+| `opencode-cli-config` | file | Whole-file OpenCode CLI configuration (global-only) |
 | `opencode-plugin` | file | Local OpenCode plugin modules |
 
 ## Supported Tools
@@ -88,9 +90,9 @@ include:
 |------|-------|--------|--------|--------------|-----------------|
 | Claude Code | `.claude/rules/*.md` | `.claude/skills/` | `.claude/agents/*.md` | `CLAUDE.md` | — |
 | Cursor | `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/*.md` | `AGENTS.md` | — |
-| OpenCode | `.opencode/rules/*.md` | `.opencode/skills/` | `.opencode/agents/*.md` | `AGENTS.md` | `opencode.json(c)`, `.opencode/plugins/` |
+| OpenCode | `.opencode/rules/*.md` | `.opencode/skills/` | `.opencode/agents/*.md` | `AGENTS.md` | `opencode.json(c)`, `~/.config/opencode/cli.json(c)` (global-only), `.opencode/plugins/`, `.opencode/commands/*.md` |
 | Codex | — | `.agents/skills/` | `.codex/agents/*.toml` | `AGENTS.md` | — |
-| Pi | `.pi/rules/*.md` | `.pi/skills/` | — | `AGENTS.md` | `.pi/extensions/`, `.pi/themes/` |
+| Pi | — | `.pi/skills/` | — | `AGENTS.md` | `.pi/prompts/*.md`, `.pi/extensions/`, `.pi/themes/` |
 
 ## Sources (Cross-Project Config)
 

package/docs/opencode-v2-probes.md

@@ -0,0 +1,253 @@
+# OpenCode V2 probes — P3/P4/P5/P6 source evidence
+
+Status: **source-verified pass** (2026-09-14). Answers the open probes in
+`plans/OPENCODE-V2-RUNTIME.md` §4. Every claim below was read out of exact
+sources; nothing is inferred from docs or memory. No live TUI/service was
+started or modified.
+
+Version sources used (in preference order — the shared scratch under
+`/private/var/folders/hh/y90cz08d14j4nl2l8nncn7bh0000gn/T/opencode` had several
+ghosted/symlinked `node_modules` dirs, so tarball and git-tag sources were
+preferred over loose scratch files):
+
+- **opencode source, tag `v2.0.3`** — fetched raw from
+  `github.com/sst/opencode` (redirects to `anomalyco/opencode`); core files
+  also present as extracts in scratch `src/` (names prefixed
+  `core_*` = `packages/core/src/...`).
+- **`@opencode/plugin@2.0.3`** — extracted tarball, scratch
+  `plugin-2.0.3/package/dist/` (its `package.json` pins deps:
+  `@opencode/{ai,client,protocol,schema,util}@2.0.3`, peer
+  `@opentui/{core,solid} >=0.5.10`, `solid-js >=1.9.0`).
+- **`@opencode/util@2.0.3`**, **`@opencode/ai@2.0.3`** — extracted tarballs
+  (scratch `util203-*`, `ai-2.0.3/package`).
+- **`@opentui/solid@0.5.11` + `@opentui/core@0.5.11`** — `npm pack`ed into
+  scratch `p3-tui/` this session.
+- **Version correction for the plan:** opencode v2.0.3's root `package.json`
+  catalog pins `@opentui/{core,keymap,solid} = 0.5.10` and `solid-js =
+  1.9.15` — **not** `@opentui/*@0.5.11` as the plan header states. 0.5.11 is
+  what `@opencode/plugin@2.0.3`'s peer range permits, but upstream v2.0.3
+  builds and ships against 0.5.10.
+
+Throughout: **SV** = source verified (file+line read); **LT** = live tested
+(this pass did none); **LT\*** = live-tested in a prior session (cited, not
+re-run).
+
+---
+
+## P4 — Global `AGENTS.md` discovery candidates
+
+**Question:** does V2 read `~/.config/opencode/AGENTS.md` or `~/AGENTS.md` as
+the global instruction file?
+
+**Answer (SV):** Global scope reads **only `~/.config/opencode/AGENTS.md`**
+(XDG config dir; `OPENCODE_CONFIG_DIR` honored). `~/AGENTS.md` is **not** a
+global candidate — but it is *not* dead either: it is picked up by the
+**project ancestor walk** for any session whose location sits under `$HOME`.
+
+Evidence, `packages/core/src/config/plugin/instruction.ts` (scratch
+`src/core_config_plugin_instruction.ts`):
+
+- L34–37: `start = location.directory` (session cwd ref), `root =
+  location.project.directory`, `home = global.home`, and
+  `globalFile = join(global.config, "AGENTS.md")`.
+- L36: `const stop = FSUtil.contains(home, start) ? home : root` — the
+  ancestor walk extends to `$HOME` whenever the location is under it.
+- L43–50: candidates = `[globalFile]` (only when `discovery.global`, L44) plus
+  `ancestorDirectories(start, stop).map(dir => join(dir, "AGENTS.md"))`
+  (L46–48). `$HOME` itself is the last element of that walk, so `~/AGENTS.md`
+  is a watched candidate for under-home locations.
+- L62–66: `globalSource` reads **only** `globalFile`.
+- L68–75: `projectSource` = `fs.up({ targets: ["AGENTS.md"], start, stop })`.
+- `fs.up` is inclusive of `stop` (`@opencode/util@2.0.3`
+  `dist/fs-util.js` L94–114: target checked at `current` before the
+  `stop === current` break), and `FSUtil.contains` is inclusive
+  (`dist/fs-util.js` L206–209) — so a project rooted at `~` still checks
+  `~/AGENTS.md`.
+- Defaults: `project` and `global` discovery are both on unless configured off
+  (`src/core_instruction-discovery.ts` L99–100: `options?.project !== false`,
+  `options?.global !== false`).
+- `global.config` = `<XDG_CONFIG_HOME || ~/.config>/opencode`
+  (`@opencode/util@2.0.3` `dist/global-roots.js` L6–9 + `roots()`), overridden
+  by `OPENCODE_CONFIG_DIR` (`src/util_global.ts` L79).
+
+**Consequence for Loadouts:** the P4 fear is already neutralized in current
+`src/builtins/tools/opencode.ts` — L9 sets the tool base to
+`~/.config/opencode` and L32–36 render global instructions to
+`{base}/AGENTS.md` with a comment citing exactly this core file. The plan §4's
+premise ("renders global instructions to `{home}/AGENTS.md`") is stale for the
+current source. Remaining nuance worth a comment in the tool spec: a file at
+`~/AGENTS.md` would *also* be discovered — as **project-scope** instructions —
+for every project under `$HOME`, so we must never render global instructions
+there.
+
+---
+
+## P5 — Is `ui.router.current()` reactive in Solid computations?
+
+**Question:** can the dashboard/EQUIPPED bar track session switches via
+`ui.router.current()`?
+
+**Answer (SV, not live-tested):** **Yes — at property granularity.**
+`current()` returns the underlying `solid-js/store` proxy. It is reactive when
+its *properties* (`type`, `sessionID`, `name`, `data`) are read inside a
+computation; the call itself reads no signal, so `const r =
+ui.router.current()` followed by property reads later still tracks, but
+treating the returned object as an opaque "snapshot" (e.g. storing it and
+comparing by reference) will not update.
+
+Evidence:
+
+- `packages/tui/src/context/route.tsx` (v2.0.3): L29–35 the route context is
+  `createStore<Route>(...)`; L37–43 `navigate` = `setStore(reconcile(route))`
+  (fine-grained per-property notifications, including key removal when
+  switching `session` → `plugin`); L38–39 `get data() { return store }`.
+- `packages/tui/src/plugin/api.tsx` (v2.0.3, also scratch
+  `p3p5p6-src/api.tsx`): L59 `route: useRoute()` in the plugin host; L176–178
+  `current() { return host.route.data }` — a direct store hand-off, no
+  signal/memo wrapper.
+- The host app itself relies on exactly this pattern: `packages/tui/src/app.tsx`
+  (v2.0.3) reads `route.data.type` / `route.data.sessionID` inside
+  `createEffect`s (terminal-title effect, session-environment effect), so
+  property-level tracking is the intended contract.
+- Published d.ts (`plugin-2.0.3/package/dist/tui/context.d.ts`): L399–403
+  `router.current(): Route` carries **no** "Reactive when read in a Solid
+  computation" doc comment — unlike `panel.current()` (L411–415) and
+  `tabs.list()` (L420) which do. The doc-comment asymmetry is a trap; the
+  implementation is reactive all the same. Worth a note in our plugin code.
+
+---
+
+## P3 — TUI loader: local plugin dir import host injection
+
+**Question:** does a local plugin *dir* without `node_modules` resolve
+`@opencode/plugin/tui` + `@opentui/solid` in the TUI?
+
+**Answer (SV):** **Yes, on Bun** (the TUI runtime). The TUI host installs a
+process-wide Bun loader plugin *before* any plugin source is imported, which
+rewrites those bare specifiers to host-provided virtual modules. **On Node,
+there is no injection** (plugins must be precompiled). The prior empirical
+result that the **server** loader has no such injection for local dirs
+(LT\*, prior session) stands unchanged — server and TUI have different
+loaders.
+
+Evidence chain:
+
+1. **Host installs injection at startup** — `packages/tui/src/plugin/context.tsx`
+   (v2.0.3) L24: `import "#runtime-plugin-support"`, mapped by
+   `packages/tui/package.json` `imports` to
+   `src/plugin/runtime-plugin-support.bun.ts` under the `bun` condition
+   (default/`node` maps to `.node.ts`, which is a single comment: "Node loads
+   precompiled plugins without it").
+2. **What is injected** — `runtime-plugin-support.bun.ts` (scratch
+   `p3p5p6-src/`, L1–8) calls `ensureRuntimePluginSupport({ additional: {
+   "@opencode/plugin/tui": { Plugin, PluginContextProvider, usePlugin } } })`.
+3. **Injection mechanism** — `@opentui/solid@0.5.11`
+   `scripts/runtime-plugin-support-configure.js`: default injected modules =
+   `@opentui/solid`, `@opentui/solid/components`, `@opentui/solid/jsx-runtime`,
+   `@opentui/solid/jsx-dev-runtime`, `solid-js`, `solid-js/store` (plus core
+   `@opentui/core` / `@opentui/core/testing`); then
+   `registerBunPlugin(createRuntimePlugin({ core, additional: modules, rewrite }))`
+   and `ensureSolidTransformPlugin({ moduleName:
+   runtimeModuleIdForSpecifier("@opentui/solid"), resolvePath })`. The Node
+   variant (`scripts/runtime-plugin-support.node.js`) throws
+   `"@opentui/solid/runtime-plugin-support is Bun-only…"`.
+4. **Rewrite semantics** — `@opentui/core@0.5.11` `dist/runtime-plugin.js`
+   (header comment + L43/L68): matching imports are rewritten to virtual
+   `opentui:runtime-module:<encodeURIComponent(specifier)>` ids; **non-`node_modules` source files
+   (i.e. our plugin's files) get a dedicated rewrite loader immediately**;
+   `node_modules` ESM is recursively prescanned and only rewritten when it
+   transitively imports a runtime module. The configure-provided `resolvePath`
+   maps any specifier present in the module map (including the additional
+   `@opencode/plugin/tui`) to its virtual id and returns `null` for everything
+   else (normal resolution).
+5. **`solid-js/dist/solid.js` role** — three exact facts: (a) `@opentui/solid@0.5.11`
+   `index.js` (package root) L103/205/210 etc. imports `solid-js/dist/solid.js`
+   **directly** — the host's reactive runtime is pinned to the universal
+   bundle, bypassing export conditions; (b) `scripts/solid-plugin.js`
+   onLoad-swaps `node_modules/solid-js/dist/server.js` → `solid.js` (and
+   `solid-js/store/dist/server.js` → `store.js`), so any node_modules dep in a
+   plugin graph that resolves solid's server condition gets the same runtime;
+   (c) `scripts/solid-transform.js` L20–28 exports
+   `resolveNodeSolidRuntimeImport` mapping bare `solid-js` →
+   `solid-js/dist/solid.js`, `solid-js/store` → `solid-js/store/dist/store.js`
+   — exported helper; no caller found inside the two published tarballs. For
+   **plugin source files**, bare `solid-js` does not go down any of these
+   paths: it is in the virtual-module map (`defaultRuntimeModules`), so it
+   resolves to the host's module instance, and babel `babel-preset-solid`
+   compiles JSX with `moduleName` = the virtual `@opentui/solid` id,
+   `generate: "universal"`.
+6. **Local dir graph loading** — `packages/tui/src/plugin/discovery.ts`
+   (v2.0.3) L22–49: `discoverPluginTargets` returns **directories only** under
+   `<globalConfig>/plugins/` and `<project>/.opencode/plugins/`.
+   `packages/tui/src/plugin/context.tsx` `resolvePlugin`: local targets →
+   `sources.read(entrypoint)` → `@opencode/plugin@2.0.3` `dist/source.js`
+   (`createPluginSources`: digest-cached, file-tracked) → `dist/source.bun.js`
+   `prepareSource`: scans the local graph with `Bun.Transpiler.scan`
+   (**skips `node_modules`**, tracks files for hot reload), then `load: () =>
+   Host.load(entrypoint)`; `dist/host.js`: local dir entry resolution is
+   **file-convention** — `tui` → `path.resolve(dir, "tui")`, `server` →
+   `<dir>/server` or `<dir>/index`, `rpc` → `<dir>/rpc` (package.json
+   `exports` only matter for named package targets); `load` = `importModule`
+   → `@opencode/util@2.0.3` `dist/runtime/import.bun.js`: plain dynamic
+   `import()` + `Bun.resolveSync` — i.e. the graph flows through Bun's native
+   loader, where the plugins from steps 3–4 are registered. Single *file*
+   local targets are skipped by the TUI reconcile and reach the TUI via the
+   server's plugin list (`source.type === "local"` → `path.dirname`), which
+   matches the plan's "single files are dropped by the loader" **V**.
+
+**Conclusion for distribution path 1 (local dir, dotfiles):** viable for the
+TUI entry without any `node_modules` — `@opencode/plugin/tui`,
+`@opentui/solid`, and `solid-js` all resolve via host injection on Bun. The
+dir needs `tui.{ts,tsx,js}` (+ optional `server.*`, `rpc.*`) at its root; a
+`package.json` `exports` map is unnecessary for local dirs (it only affects
+npm-package targets). Server entry of the same dir still hits the confirmed
+missing-deps wall (LT\*) — a TUI-only dir plugin is safe; a dir whose server
+entry imports unresolvable packages is not.
+
+---
+
+## P6 — `CacheHint` fields and semantics in `@opencode/ai`
+
+**Question:** exact shape of `SystemPart.cache` and what it does downstream.
+
+**Answer (SV):**
+
+- **Shape** — `@opencode/ai@2.0.3` `dist/schema/options.d.ts` L135–140:
+  `CacheHint = { type: "ephemeral" | "persistent"; ttlSeconds?: number }`.
+  `dist/schema/messages.d.ts` L1–23: `systemPartSchema = { type: "text",
+  text: string, cache?: CacheHint, metadata?: Record<string, unknown> }` with
+  `SystemPart.make(text)` convenience. (`CachePolicy` at
+  `options.d.ts` L141–155 — request-level `"auto" | "none" | {tools, system,
+  messages, ttlSeconds}` — is a separate, per-request concept.)
+- **Anthropic lowering** — `dist/protocols/anthropic-messages.js`:
+  L335–341 documents a hard cap of **4 `cache_control` breakpoints per
+  request** across `tools`+`system`+`messages`; beyond the cap markers are
+  **counted (`breakpoints.dropped`) and silently dropped** (L346–351).
+  L343–352: both hint types (`ephemeral` and `persistent`) lower to
+  `cache_control: { type: "ephemeral" }`; `ttlBucket(ttlSeconds) === "1h"`
+  adds `ttl: "1h"`, else the wire TTL is omitted (provider default 5m).
+  System parts each get their own `cache_control` when present (L924–930).
+- **TTL bucket** — `dist/protocols/utils/cache.js` L5:
+  `ttlBucket = ttlSeconds !== undefined && ttlSeconds >= 3600 ? "1h" :
+  undefined`. So `ttlSeconds >= 3600` → 1h bucket; anything else (including
+  omitted) → default 5m. Same mapping used by openrouter
+  (`dist/providers/openrouter.js` L8, L57) and bedrock
+  (`dist/protocols/utils/bedrock-cache.js` L47).
+- **OpenAI-family** — `dist/protocols/openai-chat.js` L293–294: within a
+  message only the **last** cache-bearing part gets the breakpoint
+  (`findLast`); system parts are marked individually when any system part
+  carries a cache (L344–351).
+- **`persistent` vs `ephemeral`:** no behavioral divergence found in any
+  lowering path — every consumer gates on
+  `type !== "ephemeral" && type !== "persistent"` and then uses only
+  `ttlSeconds`. Treat `type` as an accepted-but-inert discriminator today.
+- **Baseline:** opencode core sets **no** cache hints on its own
+  instruction/context system parts (no `cache` usage in
+  `packages/core/src/session/{context,instructions,instruction-entry}.ts` or
+  `packages/core/src/instructions/index.ts` — instructions render as plain
+  strings, `src/core_instructions_index.ts` L165–189). A `cache`-carrying part
+  injected by our phase-3 context hook would therefore consume one of the 4
+  breakpoints fresh. Practical guidance for the plan's "use `cache`" note:
+  one hint on our single injected block is safe; never hint per-artifact
+  (breakpoint cap), and `ttlSeconds: 3600` only makes sense for long sessions
+  where the 1h Anthropic cache price is worth it.

package/docs/opencode-v2-runtime.md

@@ -0,0 +1,129 @@
+# OpenCode V2 Runtime
+
+Implemented against **OpenCode 2.0.3**, `@opencode/client@2.0.3`,
+`@opencode/plugin@2.0.3`, OpenTUI 0.5.11, and the host's Solid 1.9.15.
+Verified 2026-09-14. See [runtime.md](runtime.md) for usage and
+[the implementation plan](../plans/OPENCODE-V2-RUNTIME.md) for the original scope.
+The [beta investigation](archive/opencode-v2-runtime-beta-18707.md) is archived.
+
+## Three equip layers
+
+| Layer | Storage | Applies to |
+|---|---|---|
+| Global | `~/.config/loadouts/.state.json` and rendered tool files | Every location |
+| Project | `.loadouts/.state.json` and rendered tool files | Sessions in the project |
+| Session | OpenCode instruction entries and session permission rules | One session ID |
+
+Global/project outputs use OpenCode's native hot reload. Session equips do not
+write tool configuration or the filesystem activation manifests.
+
+## Implementation
+
+- `src/integrations/opencode/session.ts`: `SessionActivator`, persisted manifest,
+  entry size preflight, permission ownership, in-process serialization, rollback.
+- `src/integrations/opencode/delta.ts`: resolver-backed compilation minus intact
+  managed OpenCode outputs. Full skill selection survives delta exclusion.
+- `src/integrations/opencode/client.ts`: authenticated service discovery; never
+  starts a service during normal use. Reports version mismatches.
+- `src/tui/core/`: shared `EquipLayer`, reducer, controller and `ViewSpec`.
+- `src/tui/hosts/opencode/`: package-dir server/TUI entries and RPC contract.
+- `src/tui/skins/opentui/`: embedded renderer. Standalone/Pi use pi-tui.
+
+The TUI plugin calls the generated client supplied by OpenCode. `/loadouts` is
+registered in its client-side keymap; dashboard commands never become prompts.
+Router data captures the originating session ID. The footer uses reactive slot
+session IDs and native instruction/permission events, with no cache-file IPC.
+
+## Verified probes
+
+| Probe | Result |
+|---|---|
+| P1: session skill deny | **Live:** blocks the permission path but does **not** remove the skill advertisement. The server context hook filters denied `<skill>` blocks. Two sessions with opposite gates produced opposite advertisements. |
+| P2: instruction entries | **Live:** first entry appears after `AGENTS.md` in the system instruction part; a replacement produces a native “supersedes” update in messages on the next turn. The original system prefix is retained — this is future-turn supersession, not history rewriting. A control session had no entry. |
+| P3: local package dependencies | **Live:** local server package dirs do not install/resolve `@opencode/plugin` merely because it is declared in package.json. Server libraries are bundled. TUI host aliases resolve bare `@opencode/plugin/tui`, `@opentui/solid`, and `solid-js`; rewriting Solid to `solid-js/dist/solid.js` fails. |
+| P4: global instructions | Source: `{global.config}/AGENTS.md`. The built-in renderer now writes `{base}/AGENTS.md`, normally `~/.config/opencode/AGENTS.md`. |
+| P5: router reactivity | Dashboard target is explicitly captured in route data; footer receives reactive slot props. See [source evidence](opencode-v2-probes.md). |
+| P6: cache hint | See [source evidence](opencode-v2-probes.md). Entries use the server's native caching/supersession behavior. No unmeasured cache-cost warning is shown. |
+
+Source locations and remaining distinctions between source verification and live
+observation are recorded in [opencode-v2-probes.md](opencode-v2-probes.md).
+
+## Persistence and ownership
+
+One instruction entry per nonempty loadout delta uses a readable, collision-safe
+`loadouts.bundle.<slug>-<hash>` key. `loadouts.manifest` records names, source scope,
+fingerprint, keys, selected skills, prior/applied permission rules and selections.
+Keys satisfy `^[a-z0-9][a-z0-9._-]*$`. Each JSON-serialized UTF-8 value is checked
+against the server's **256 KiB per-entry** limit before any mutation.
+
+Permission replacement appends denies for unselected catalog skills to the prior
+session rules. It never adds an allow that could override an agent's deny. The
+activator waits for plugin activation before reading the initial catalog.
+Unequip restores prior permissions only when the current rules still match those
+Loadouts applied; external edits are preserved and reported. Unrelated instruction
+entries are preserved. Re-equips remove obsolete owned keys.
+
+Agent/model declarations are applied per session. Existing explicit selections
+are restored on unequip unless subsequently changed externally. V2 has no API to
+clear an explicit selection back to an implicit default; if there was no explicit
+prior selection, the selected value remains after unequip.
+
+Partial HTTP failures trigger rollback of entries, permissions and known previous
+selections. An incomplete rollback is surfaced explicitly. Operations on one
+session are serialized within a process. **The V2 APIs provide neither an atomic
+multi-resource transaction nor compare-and-swap:** a process crash or simultaneous
+mutations by different clients can interrupt or race an equip. Inspect session
+status/entries/rules before recovering such a session. A model step can observe
+intermediate state if equip overlaps that step; the completed equip governs the
+next step.
+
+## Server enhancements
+
+The package server entry filters skill advertisements by session permission
+rules. It indexes loadout skills via `skill.transform`, preserving existing
+catalog IDs, and advertises selected off-disk skills per session. Those additions
+are location-wide catalog entries, with automatic invocation disabled by default.
+The manifest remains authoritative for off-disk advertisement selection.
+
+Headless `/loadouts equip`, auto-equip via
+`loadouts.yaml: opencode.defaultSession`, and typed RPC share the activator.
+In 2.0.3, `Plugin.Context.session` lacks instruction-entry methods, so these
+optional server operations discover the managed local service. They require that
+service; the HTTP/TUI session activation path itself uses the connected client.
+Without managed-service discovery, ordinary instruction entries and on-disk
+permission filtering still work, and off-disk skills remain path references.
+
+The deny list and virtual catalog are snapshots at equip/plugin load respectively.
+Re-equip after changing skill membership; reload the plugin to index newly added
+off-disk loadouts. Global/project filesystem skill changes remain native hot reload.
+
+## Build and verify
+
+```sh
+npm run build
+npm run lint
+npm test
+node scripts/opencode-session-e2e.mjs
+OPENCODE_E2E_MODEL=provider/model node scripts/opencode-session-e2e.mjs --prompts
+node scripts/opencode-session-restart-e2e.mjs
+```
+
+The first E2E harness creates and removes its own two sessions. `--prompts`
+adds three model turns to verify the outgoing skill advertisements and instruction
+supersession. The restart harness uses separate XDG config/state/data/cache roots
+and stops only the service it created. Neither restarts the shared working service.
+
+The OpenCode build uses Solid's **universal Babel transform**. Its host-owned
+runtime imports stay external; the server implementation is self-contained.
+Standalone still needs Node 22.19+ for pi-tui. OpenTUI requires Bun or Node 26.4+
+with experimental FFI, and is only used inside OpenCode.
+
+## V2 gotchas retained
+
+- `instructions` in `opencode.json` is accepted but unresolved. Render instructions
+  to `AGENTS.md`; never depend on that array.
+- `POST …/skill` works on 2.0.3; the archived beta's failure is obsolete.
+- Documentation uses `/api/experimental/session/…` for some operations while the
+  installed 2.0.3 API uses `/api/session/…`. Always use the pinned generated client.
+- Native instruction updates retain earlier context with supersession notices.
+  Unequip changes future turns; it does not erase information the model has seen.