[dtump]

Important

DRAFT — do not merge yet. OpenCode 2.x needs to stabilize first. This PR is parked until the validation checklist below passes. The project stays on 1.x (main) in the meantime.

What

Upgrades the image from OpenCode 1.x (opencode-ai@1.18.16) to OpenCode 2.2.0. OpenCode 2.x is published as @opencode/cli — opencode-ai is frozen at 1.x — so the Dockerfile install and the update_pins.py tool registry switch package names. The --ignore-scripts + explicit postinstall.mjs install pattern is unchanged (v2 package has the same shape; postinstall re-reviewed per the Dockerfile's standing note).

Changes

• Dockerfile / update_pins.py: opencode-ai → @opencode/cli; pin OPENCODE_VERSION=2.2.0
• Drop OPENCODE_EXPERIMENTAL_AGENT_TEAMS=1 (no such variable in OpenCode 1.x ≥ 1.19 or 2.x); keep OPENCODE_DISABLE_AUTOUPDATE=1 (still honoured in v2) and IS_SANDBOX=1 (legacy HOST_UID=0 net)
• opencode --version now prints opencode v2.2.0 — CI pin-match assertion updated
• entrypoint.sh: the /root chown walk also filters No such file or directory — OpenCode 2's background service keeps transient files (flock lock dirs, service.json, SQLite sidecars) on the shared volume, and a concurrent container's start can race their removal
• Routine soak-gated refresh of the other pins (openspec 1.14.3, pnpm 11→12, uv 0.13.5, glab 1.124.0, awscli 2.38.4)
• fix(ci): ignore hadolint DL3003 for the tmux source build — pre-existing failure (every main push red since 2026-08-10)
• OpenSpec: new change upgrade-opencode-v2 (validated, synced, archived); its deltas rewrite host-config-parity + persistent-session-storage (still Claude-flavoured after the fork migration) to OpenCode 2 reality; six implemented-but-unfinished pre-rename changes archived without syncing their stale/superseded deltas

User impact

• Seamless: config locations, opencode.docker.json seed, host config mounts, and wrapper flags (--auto, --continue, --session, …) are unchanged; a v1-schema opencode.json is accepted and normalised in memory; provider credentials carry over (v2 imports auth.json)
• Breaking: v1 conversation history does not migrate (fresh SQLite DB; only credentials import); OpenCode 2 runs a per-user background service whose stale registration self-heals on the next run (verified)

Verified so far (on this branch)

• Unit tests (56), npm audit signatures for @opencode/cli@2.2.0 + @fission-ai/openspec@1.14.3 + pnpm@12.15.0 (registry signatures + attestations), openspec validate (change + 8 specs)
• Host: docker build + opencode --version → opencode v2.2.0, smoke cell (warm volume + settings seed), background-service stale-registration recovery against warm volumes
• CI on this branch: MCVS-PR-validation green after conventional retitle; hadolint fixed; shellcheck/unit tests green

⚠️ Must be checked / validated before this is merged

1. Upstream service stability — blocking. Reproduced in our container: constant "Restarting service…" from the managed background service. Root-caused in our logs to a registration-slot stampede — 18× managed service registration replaced; shutting down within ~85s, 19 serve --service spawns in one day. Upstream: [service]: managed service stalls, watchdog recovery loses sessions (404 "session not found"), restart stampede races the service slot (2.0.25 vs 2.0.26) anomalyco/opencode#54181 (open, severity:high — "managed service stalls, watchdog recovery loses sessions, restart stampede races the service slot"). Our trigger was concurrent containers sharing opencode-root, but the stall half of the issue can hit a single instance. Gate: wait for an upstream fix, or validate a single-instance 2.x session over several real workdays with zero restart loops.
2. "tool bash is not available" errors. v2 renamed the bash tool to shell and ships no alias. Seen when prompt content references bash; also plausible as a model-prior effect (Mistral Large 4) because a custom agent's Markdown body replaces the built-in system prompt that names the tools (model-request.ts:110). Gate: sweep host config + workspace content for bash tool references; A/B built-in vs custom agent; confirm the errors stop.
3. Related open upstream issues producing similar "tool not available" symptoms — re-test at merge time: #59993 (tool catalog empty after location reload), #51949 (agent reports no tools after auto-compaction), #60014 (code-mode catalog omits built-ins), #52054 (http_proxy without no_proxy loops), #55937 ($HOME watcher starves the event loop).
4. Concurrent containers: v2's single-slot service registration races across containers sharing the volumes (the stampede above). Until #54181 is fixed upstream, validate the guidance: one container per volume set; --ephemeral for second sessions; --standalone as a per-run alternative.
5. Re-pin at merge time: run uv run update_pins.py (no override) so the pin is the newest soaked 2.x — 2.2.0 soaks 2026-11-03, and by merge time a newer 2.x will likely be eligible. This also turns the CI soak audit green (it is red until then — the only expected red job on this branch).
6. Full CI matrix green at merge time: the Docker build job (version smoke + 10-cell smoke matrix) is currently skipped while the soak audit is red; all jobs (Validate, Docker build, General, MCVS-PR-validation) must pass before merge.
7. Host-side validation to re-run at merge time: docker build, opencode --version → opencode v2.2.x, the full smoke/smoke.sh matrix, the gh-proxy integration test (tests/gh-proxy-integration.sh), and a config-parity spot check (agents/commands/skills/AGENTS.md discovery + v1-schema seed normalisation).

Follow-ups (separate, intentionally not in this PR)

• Spec modernisation for the remaining Claude-flavoured specs (cli-help, package-managers, external-cli-tools, multi-workspace-mounts) — recover coverage from the archived deltas
• Check divergence from upstream schubergphilis/claude-docker
• Cleanup: inert prompts/ + statusline-command.sh mounts, --resume help example (should be --continue)
• 3 open manual verification tasks in 2 archived changes (openspec 3.3 — done; git-overlay 5.3 — pending a host run)
• Upstream issues worth filing: tool-name repair/alias for model-emitted legacy names (bash→shell); custom-agent system prompt replacing the tool-listing prompt