@openchambery/web 1.19.22-beta.1 → 2.0.0-beta.3

package/server/lib/opencode/DOCUMENTATION.md

@@ -11,8 +11,10 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, forces `OPENCHAMBER_RUNTIME=web` unless already `ssh-remote` (so `dev:server` cannot inherit a leftover desktop env and host a relay, while SSH-managed remotes may), parses CLI options, and starts server bootstrap.
 - `packages/web/server/lib/opencode/routes.js`: OpenCode/provider settings and auth-related route registration.
 - `packages/web/server/lib/opencode/lifecycle.js`: OpenCode process lifecycle runtime (startup, restart, readiness, health monitoring). Managed child env inherits the user shell environment unchanged; experimental flags such as `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` follow the user's own environment and are never injected by OpenChamber.
+- `packages/web/server/lib/opencode/v1-migration-gate.js`: pure V1→v2 migration admission gate (`GET /api/experimental/migration/v1` → whether transcript may be fetched).
 - `packages/web/server/lib/opencode/managed-capabilities-runtime.js`: managed-child scheduled-task resources, config injection, rotating bridge identity, and bridge authorization.
 - `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.
+- `packages/web/server/lib/opencode/ensure-cli.js`: detect local `opencode` version and install the pinned official V2 into the OpenChamber data dir when missing or too old. Never uses a packaged/bundled binary.
 - `packages/web/server/lib/opencode/env-config.js`: OpenCode-related environment variable parsing and validation (host/port/hostname).
 - `packages/web/server/lib/opencode/hmr-state-runtime.js`: HMR-persistent runtime state initialization, auth-state bootstrap, and HMR sync helpers.
 - `packages/web/server/lib/opencode/bootstrap-runtime.js`: base app bootstrap runtime for status/auth/tts/notification/OpenChamber route wiring.
@@ -25,7 +27,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/core-routes.js`: server status/system routes, auth/access guard routes, and settings utility route registration.
 - `packages/web/server/lib/opencode/shutdown-runtime.js`: graceful shutdown orchestration runtime for watcher/session/terminal/process/server teardown.
 - `packages/web/server/lib/opencode/server-startup-runtime.js`: server listen/startup flow and process/signal handler orchestration runtime.
-- `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset/SPA fallback route registration and manifest route wiring.
+- `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset/SPA fallback route registration and manifest route wiring. The SPA fallback sends `index.html` relative to `root`, so deep links keep working when the install lives under a dot directory.
 - `packages/web/server/lib/opencode/feature-routes-runtime.js`: feature route composition runtime for dynamic import-backed config/skill/provider route registration.
 - `packages/web/server/lib/conversations/`: combined create-session-and-prompt orchestration (OpenChamber-owned, registered before generic proxy).
 - `packages/web/server/lib/session-turn-pages/`: turn-window session message pagination (`GET /api/openchamber/sessions/:sessionID/messages`), anchor reconcile (`GET .../messages/reconcile`), Changes L2/L3 (`GET .../changes`), and exact message L1 projection (`GET /api/session/:sessionID/message/:messageID`); loops official OpenCode `session.messages` for turn pages and head→anchor gap recovery with continuation/budgets/`resetRequired`; all registered before generic proxy. L1 first-packet / SSE / exact-message paths keep `summary.diffs` as a slim `{ file, status?, additions, deletions }` list plus additive `diffCount`/`hasDiffs` (patch bodies stay on L3). See `session-turn-pages/DOCUMENTATION.md`.
@@ -83,8 +85,11 @@ This module provides OpenCode server integration utilities for the web server ru
   - `GET /api/config/opencode-resolution`
   - `GET /api/behavior/agents-md`: returns an authoritative empty document only when the file is absent (`ENOENT`); permission and I/O failures return HTTP 500.
   - `PUT /api/behavior/agents-md`
-  - `POST /api/opencode/upgrade` (proxies OpenCode `POST /global/upgrade` with a required semantic version `target`, then restarts managed OpenCode so the new binary is active)
-  - `GET /api/opencode/upgrade-status`
+  - `POST /api/opencode/upgrade` (ticket 12): installs the pinned/target `@opencode/cli` into the **owned cache** at `~/.config/openchamber/opencode-cli/<version>/`. Managed owned-cache processes restart on that binary; official shared services use that exact binary's `service restart`, then adopt its registration again. Success requires a fresh running-serve version probe and runtime contract verification. Arbitrary external servers, private processes using global CLI, and private bundled binaries return HTTP 409; user installs are never overwritten. Concurrent upgrades are single-flight (`operation` state). Active sessions require `confirmActiveTasks`/`force`. Failure preserves cached binaries, restores the previous binary selection, and reports the failed phase; it does not claim the old process was restored. Shared-service recovery can subsequently re-ensure the registered service.
+  - `GET /api/opencode/upgrade-status`: returns `currentVersion`/`serveVersion`/`cliVersion`, `targetVersion`/`latestVersion` (pin), `supplySource`, `ownership`, `canManage`, `management`, `guidance`, `contract`, and `operation`. Official shared services report `ownership: 'shared-service'`, `processOwnership: 'shared'`, and `canManage: true`. `available` is true only when `canManage` and target > current; unmanaged global/external runtimes report `available: null` plus manual guidance.
+  - `GET /api/opencode/contract` (ticket 11): runtime contract admission for the **running serve** (not health alone). Dimensions: reachable / authenticated / protocolCompatible / executionAllowed / capabilities / migration / CLI↔serve mismatch. Floor `2.0.12` (acceptable OpenCode 2.x at or above); below-min 2.x and 1.x block execution with upgrade guidance; no upper version cap.
+  - `GET /api/opencode/health`: probes managed OpenCode `GET /api/info` (Basic auth, 4s timeout). `healthy` is reachability/version shape via `evaluateOpenCodeHealthBody` (admits official 2.x `ServerInfo` and classic `{ healthy: true, version }`; rejects 1.x / missing / `healthy: false`). Response also includes `executionAllowed`, `protocolCompatible`, and `contract` so clients do not treat health success as full execution semantics. Upstream non-OK responses pass through status with `{ healthy: false, error, contract }`; transport failures return HTTP 503.
+  - `GET /api/opencode/version`: serve + CLI versions, mismatch flag, and contract snapshot
   - `POST /api/opencode/directory`
   - `GET /api/provider/:providerId/source`
   - `DELETE /api/provider/:providerId/auth`
@@ -112,26 +117,74 @@ This module provides OpenCode server integration utilities for the web server ru
   membership — that remains a UI-side authoritative pull fused with directory
   `/session/status`.
 
+## Public exports (opencode2-pin.js)
+- `PINNED_OPENCODE2_VERSION`: exact desktop/runtime pin (never 1.x).
+- `OPENCODE2_NPM_PACKAGE`: `@opencode/cli` (global install that ships the official `opencode` v2 binary; not 1.x `opencode-ai`).
+- `parseOpenCode2VersionOutput(stdout)` / `compareOpenCode2Versions(left, right)` / `isOpenCode2VersionAtLeast(version, minimum)`: CLI `--version` parse and pin comparison.
+- `openCode2BinaryName(platform)` / `npmPackageForOpenCode2(platform, arch)`: staged binary name `opencode` (`opencode.exe` on Windows) and official platform package `@opencode/cli-<os>-<arch>[-baseline]`.
+- `isOpenCode1xVersion(value)` / `isAcceptableOpenCode2HealthVersion(value)` / `evaluateOpenCodeHealthBody(body)`: health admission accepts only 2.x. 1.x, `0.x` pre-2 binaries, and missing/unknown versions are rejected even when `healthy: true`.
+- `resolveOpenCode2UpgradeTarget(target)` / `rejectOpenCode1xUpgradeTarget(target)`: upgrade targets default to the pin and refuse 1.x.
+
+## Public exports (runtime-contract.js)
+- Ticket 11 pure admission matrix. `RUNTIME_CONTRACT_MIN_VERIFIED` (`2.0.12`) is the documented 2.x floor; capabilities include `core.protocol`, `session.prompt`, `session.queuedInput`, `session.background`, `session.generationFallback`, `migration.v1Read`.
+- `evaluateRuntimeContract(input)`: separate reachable / auth / protocol / execution / migration / CLI↔serve mismatch reasons for UI and diagnostics. **`executionAllowed` requires acceptable OpenCode 2.x at or above the floor** (`versionBand === 'verified'`).
+- `formatRuntimeContractBlockedError(contract)` / `runtimeContractExecutionBlockedBody(contract)`: user-facing upgrade guidance on HTTP 409 execution blocks (below-min / 1.x), not raw JSON dumps.
+- `isRuntimeContractExecutionPath` / `isRuntimeContractDiagnosticPath` / `isRuntimeContractStopPath` / `shouldBlockRuntimeContractExecution` / `createRevokedRuntimeContract`: proxy + Host transport gate helpers. **Execution paths require `executionAllowed === true` on the current contract**; null/pending/false all block (no silent bypass). Unit/DI factories may pass `{ allowMissingContract: true }` only when no lifecycle is wired. Interrupt/abort and reads stay available when execution is limited. Health success is not full execution semantics.
+
+## Public exports (server-opencode-fetch.js)
+- Host transport boundary so queue / goal / scheduled / assistants / session-title cannot bypass the proxy write gate.
+- `configureServerOpenCodeFetchGate(getter, options?)` / `createServerOpenCodeFetch` / `wrapFetchWithRuntimeContractGate`: shared admission; `makeOpenCodeV2Client` always wraps fetch with the gate. Production must not set `allowMissingContract`.
+
+## Public exports (owned-runtime-upgrade.js)
+- Ticket 12 ownership model: `classifyRuntimeOwnership` separates process ownership (external vs managed) from binary ownership (owned-cache / global-cli / bundled / env / settings). External serve using an owned file stays external; managed process using a global file stays global-cli.
+- `buildUpgradeStatusSnapshot` / `evaluateOwnedUpgradeResult` / `createUpgradeOperationState` / `resolveOwnedCacheBinaryPath`.
+
+## Public exports (ensure-cli.js)
+- `ensurePinnedOpenCode2Cli({ discoveredPath, pin, autoInstall, install, readVersion })`: reuse any discovered acceptable 2.x CLI (official name `opencode`). Install the pin into `~/.config/openchamber/opencode-cli/<pin>/opencode` only when nothing usable is installed. `OPENCHAMBER_OPENCODE2_AUTO_INSTALL=0` disables download (`OPENCODE_CLI_MISSING`).
+- `installPinnedOpenCode2Cli(options)`: download `@opencode/cli-<os>-<arch>@pin`, extract, copy as `opencode`, chmod, verify `--version`.
+- `installedOpenCode2BinaryPath(version)` / `readOpenCode2BinaryVersion(path)` / `isOpenCode2AutoInstallEnabled()`.
+
+## Public exports (v1-migration-gate.js)
+- `OPENCODE_V1_MIGRATION_PATH`: `/api/experimental/migration/v1`.
+- `V1_MIGRATION_USER_NOTICE`: user-visible backfill notes (reuse message ids; in-progress tools become interrupted; V1 subtasks omitted from v2).
+- `evaluateV1MigrationGate(input)`: pure function. Accepts migration JSON (`{ status }`), an HTTP envelope (`{ httpStatus|status, body }`), or a transport failure (`{ error }`). Returns `{ admitTranscript, phase, progress?, error?, userNotice? }`. `required` / `running` / `error` / network failure → `admitTranscript: false`. `completed` or HTTP 404 (no V1 library) → `true`. Unknown or empty bodies fail closed and are never treated as an empty-list success.
+- `fetchV1MigrationGate({ url, headers, signal, fetchImpl })`: GET-only status poll used by lifecycle.
+
 ## Public exports (lifecycle.js)
-- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration.
+- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration. Bootstrap reuses a healthy v2 `opencode serve` when present; otherwise starts managed `opencode serve`. Before managed spawn, `ensurePinnedOpenCode2CliEnv()` detects the local CLI version and installs the pinned official V2 when missing or too old (skipped for external skip-start). Startup accepts both `server listening on http://127.0.0.1:PORT` and the legacy `opencode server listening on …` line. Readiness/health probes `GET /api/info` first, then `/global/health`, with Basic auth (username `opencode`). A body is admitted only when `evaluateOpenCodeHealthBody` accepts the version (rejects 1.x and missing/unknown). After health ok, `startOpenCode` / `waitForOpenCodeReady` poll `GET /api/experimental/migration/v1` (no POST; backfill is owned by opencode2). Each readiness attempt uses one abort timer that covers **both** health and migration so a hung migration cannot outrun the per-attempt budget. External instances are a read-only mount: restart/refresh only re-probe health + V1 migration (never kill, spawn, clear port, or flip `isExternalOpenCode`); health monitoring skips them; upgrade routes return 409. After readiness admits, lifecycle warms recent directories via optional `getWarmupDirectories` (sequential best-effort `GET /api/session?directory=&limit=1`). External skip-start / auto-detect attach leave `isOpenCodeReady` false until the gate admits. `isOpenCodeReady` means transcript may be fetched only when the gate admits (`completed`, or no V1 library such as HTTP 404). `required` / `running` / `error` keep the ready gate closed; `error` is retried. The last gate result is stored on `state.v1Migration` and published on the OpenChamber `/health` snapshot so UI can render `phase` and running `progress` (`label` / `numerator` / `denominator`) plus `userNotice` (reuse message ids; in-progress tools become interrupted; V1 subtasks do not appear in v2).
+- Shared official service (default for Web and Electron hosts, including mobile clients connected to those hosts): when `sharedService` is injected and neither an OpenCode port nor host is configured, bootstrap runs `opencode service start` before HMR/private-process reuse or any port-4096 probe. It attaches to the registered stable-channel service, adopts its password/base URL/port, and marks it external for shutdown. Closing OpenChamber leaves that service running; no managed capabilities (scheduled-task plugin, bridge token, `v2-plugin-host-shim`) are injected. Attach failure clears URL/port/password, reports an unavailable integration and permits explicit retry, without silently spawning a private server. Explicit host/port and shared-service opt-out retain their existing behavior; VS Code retains its extension-owned sidecar lifecycle.
+- While attached, ordinary `restartOpenCode()` re-runs `service start` and adopts the latest registration before re-probing; a failed ensure propagates instead of probing stale credentials as success. Upgrade-only `restartOpenCode({ binaryPath })` bypasses settings rediscovery and runs the verified target's `service restart`. Configuration refresh uses `POST /api/location/reload` instead of process replacement (returns `{ reloaded: true, external: true }`). Health monitoring uses registration-PID liveness. Normal attachment/recovery does not version-pin or downgrade a healthy registered service; explicit in-app upgrade is the version-replacement operation.
 - Returned API:
   - `startOpenCode()`
   - `restartOpenCode()`
+  - `isSharedOpenCodeService()`: true while attached to the shared official service.
   - `waitForOpenCodeReady(timeoutMs?, intervalMs?)`
   - `waitForAgentPresence(agentName, timeoutMs?, intervalMs?)`
   - `refreshOpenCodeAfterConfigChange(reason, options?)`
   - `bootstrapOpenCodeAtStartup()`
   - `retryOpenCodeStartup()`
   - `startHealthMonitoring(healthCheckIntervalMs)`
-  - `waitForPortRelease(port, timeoutMs, hostname?)`
-  - `killProcessOnPort(port)`
+  - `waitForPortRelease(port, timeoutMs, hostname?)`: probe-only; reports whether the listener freed without killing occupants.
+  - `killProcessOnPort(port, ownedPid?)`: legacy helper retained for tests/compat; force-signals only an explicit owned pid/process group when `ownedPid` is provided. Restart and graceful shutdown **do not** call it after `child.close()` (close owns escalation; a second kill of a captured pid risks recycling). Never mass-kills by port via `lsof`.
+
+## Public exports (shared-service.js)
+- Discovery and start of the official `opencode serve --service` background service shared with official Desktop/TUI (one process, one database, so providers and plugins stay in sync across clients).
+- `resolveSharedServiceRegistrationPath(env?, homeDir?)`: `${XDG_STATE_HOME || ~/.local/state}/opencode/service.json` (stable channels only).
+- `isSharedServiceEnabled(env?)`: on by default; `OPENCHAMBER_OPENCODE_SHARED_SERVICE=0|false|off` opts out.
+- `parseSharedServiceRegistration(text)` / `readSharedServiceRegistration({ file, fsLike })`: `{ origin, port, pid, password, version }` or `null`; missing/malformed files are absent, never a service.
+- `buildSharedServiceStartEnv(env)`: strips `OPENCHAMBER_*`, `OPENCODE_SERVER_PASSWORD`, and `OPENCODE_PASSWORD` so the long-lived service never inherits OpenChamber credentials.
+- `startSharedOpenCodeService({ binary, args, env, spawnImpl, timeoutMs, replace })`: runs `<binary> [...args] service start`, or `service restart` for explicit `replace: true`; rejects with the stderr tail on non-zero exit or timeout. The launcher has hidden Windows console and does not own the detached service lifetime.
+- `isProcessAlive(pid)`, `createSharedOpenCodeService({ envLike, fsLike, spawnImpl })`: the lifecycle dependency (`start`, `readRegistration`, `buildStartEnv`).
+- `shared-service.integration.test.js` is opt-in via `OPENCHAMBER_TEST_OPENCODE_BINARY`; it isolates HOME/XDG/config/database and verifies launcher exit survival, PID reuse, explicit replacement and authenticated health, then stops only its isolated service.
 
 ## Public exports (env-runtime.js)
-- `createOpenCodeEnvRuntime(dependencies)`: creates runtime that owns OpenCode CLI environment and binary discovery state.
+- `createOpenCodeEnvRuntime(dependencies)`: creates runtime that owns OpenCode CLI environment and binary discovery state. Discovery order: settings/env, then PATH `opencode`, then known install locations, then a previously installed pin under the OpenChamber data dir. Automatic discovery and bundled resources use only `opencode` (`opencode.exe` on Windows); 1.x binaries are skipped by `--version`, not by basename. `resolveOpencodeCliPath()` never prefers a packaged/bundled Electron extraResource. Managed startup calls `ensurePinnedOpenCode2CliEnv()` and installs the pin only when no usable 2.x CLI exists; if pin install fails (or auto-install is disabled), it may last-resort to a 2.x binary under `OPENCHAMBER_BUNDLED_OPENCODE_CLI_DIR` or `process.resourcesPath/opencode-cli` (source `bundled`). Explicit `OPENCODE_BINARY` that reports 1.x fails closed with `OPENCODE_BINARY_INVALID`. Bootstrap reuses a healthy v2 `opencode serve` on port 4096 when present; otherwise it starts generic `opencode serve`.
+- VS Code keeps a copied sidecar (`packages/vscode/src/opencode-sidecar.ts`) with the same invariants: discovery order may differ (no Electron bundled fallback), but reject list, listening lines, health path order (`/api/health` then `/global/health`), `{ healthy: true }`, and Basic username `opencode` must stay aligned. Changing one copy requires changing the other.
 - Returned API:
   - `applyLoginShellEnvSnapshot()`
   - `getLoginShellEnvSnapshot()`
   - `ensureOpencodeCliEnv()`
+  - `ensurePinnedOpenCode2CliEnv()`
   - `applyOpencodeBinaryFromSettings()`
   - `resolveOpencodeCliPath()`
   - `resolveManagedOpenCodeLaunchSpec(opencodePath)`: resolves the effective managed OpenCode launch target, unwrapping Windows package-manager shims to a direct native binary or explicit runtime+script when possible.
@@ -141,11 +194,12 @@ This module provides OpenCode server integration utilities for the web server ru
   - `isExecutable(filePath)`
   - `searchPathFor(binaryName)`
   - `clearResolvedOpenCodeBinary()`
+  - `forceResolvedOpenCodeBinary(path, source?)`: pin managed launch to an explicit binary (owned-cache upgrade) so restart does not rediscover a global CLI
 
 ## Public exports (managed-capabilities-runtime.js)
 - `createManagedCapabilitiesRuntime(dependencies?)`: returns resource publishing, bridge-origin, child-environment, identity, and bridge-authorization APIs for managed OpenCode only.
 - `mergeManagedOpenCodeConfig({ configContent, pluginUrl, instructionsUrl })`: merges injected plugin/instructions URLs with stable deduplication.
-- Managed child config injects the plugin as a file URL and instructions as an absolute filesystem path. Capability identity validates the current managed PID and its liveness before HMR reuse or bridge authorization.
+- Managed child config injects the scheduled-task plugin as a file URL and instructions as an absolute filesystem path, then appends the `v2-plugin-host-shim` directory. OpenCode 2.0.12 has no `ctx.catalog`; that shim re-invokes catalog-based user plugins against `provider.transform`. Capability identity validates the current managed PID and its liveness before HMR reuse or bridge authorization.
 - `bootstrap-runtime.js` forwards managed bridge authorization to the API auth gate. The reserved bridge path accepts only the current managed-child capability and returns HTTP 403 before UI, tunnel, or client authentication for every other request. `feature-routes-runtime.js` registers the managed scheduled-task bridge before generic OpenCode proxy composition.
 - Capability resources use an application-version and source-content SHA-256 fingerprint directory. The bridge token is a managed OpenCode process capability: every plugin loaded into that process belongs to the trusted-code boundary. External OpenCode receives no managed capability injection or bridge authorization.
 
@@ -175,7 +229,7 @@ This module provides OpenCode server integration utilities for the web server ru
 ## Public exports (network-runtime.js)
 - `createOpenCodeNetworkRuntime(dependencies)`: creates runtime for OpenCode network and URL concerns.
 - Returned API:
-  - `waitForReady(url, timeoutMs?)`
+  - `waitForReady(url, timeoutMs?)`: probes `GET /api/health` then `/global/health` with `getOpenCodeAuthHeaders()`; `{ healthy: true }` is ready.
   - `normalizeApiPrefix(prefix)`
   - `setDetectedOpenCodeApiPrefix()`
   - `buildOpenCodeUrl(path, prefixOverride?)`
@@ -233,11 +287,36 @@ This module provides OpenCode server integration utilities for the web server ru
   - `resolveProjectDirectory(req)`
   - `resolveOptionalProjectDirectory(req)`
 
+## V2 configuration persistence and activation
+
+Agent, Command, MCP, Plugin and Skill mutation routes write their existing local
+configuration paths and return `{ success: true, requiresReload: false,
+application: 'watch' }` (skill install retains its `ok` result). They do not call
+the process lifecycle or `location.reload`. V2 Config watchers and plugin/domain
+reconciliation apply watched changes; frontend domain events refresh catalogs.
+The receipt means **persisted**, not confirmed activation. A remote external
+OpenCode with a different filesystem cannot see Host-local writes merely because
+the write succeeded; restarting that server does not transfer those files either.
+
+Raw global `opencode` config saves no longer request a restart. Opaque plugin-owned
+JSON targets retain `requiresManualRestart: true` because OpenCode's config watcher
+does not guarantee those plugins reload their private configuration. Explicit UI
+configuration reload uses official SDK `location.reload`. The historical
+`/api/config/reload` host/bridge endpoint remains reserved for existing process
+startup/recovery/binary-change callers, not ordinary Settings mutations.
+
+`config-hot-reload.integration.test.js` is opt-in via
+`OPENCHAMBER_TEST_OPENCODE_BINARY=<absolute-v2-cli>`. It starts a separate loopback
+server with isolated HOME/XDG/config/database, checks global command changes,
+plugin disable/re-enable, credentials and MCP config changes without reload or
+restart, then terminates only its own child and removes its temporary files.
+It makes no model requests and never reads real user credentials.
+
 ## Public exports (config-entity-routes.js)
 - `registerConfigEntityRoutes(app, dependencies)`: registers configuration entity routes:
-  - `GET /api/config/catalog/providers` resolves the request project directory, calls OpenCode's SDK `config.providers`, and returns schema version `1` with an allowlisted provider/model catalog. The route is available through the shared web host used by Web, Electron, hosted mobile, and Capacitor mobile, before generic OpenCode proxy handling.
-  - Provider catalog responses include only provider `id`, `name`, and safe models. Safe models include `id`, `name`, fixed text/audio/image/video/pdf capability modalities, bounded cost/limit fields, `release_date`, and variant names with `{}` values. Identifiers are bounded to 512 characters, display names to 1024, release dates to 64, numeric values to absolute 1e9, and catalog collections to 200 providers, 500 models per provider, and 100 defaults or variants. Provider credentials/configuration and unallowlisted model fields stay server-side. Malformed catalog roots and SDK error envelopes return HTTP 502. `partial: true` is structural only: provider/model/default truncation, dropped providers/models/defaults, or truncated variant dictionaries. Soft allowlist stripping of optional metadata (unknown modalities, non-boolean capability flags, out-of-range cost/limit numbers, empty/null/invalid `release_date`) keeps valid models and must not set `partial: true`, or UI refresh retains a stale complete snapshot after OpenCode provider updates.
-  - Agents: `/api/config/agents/:name` and `/api/config/agents/:name/config`
+  - `GET /api/config/catalog/providers` resolves the request project directory, composes official v2 `provider.list` + `model.list` (+ `model.default`), and returns schema version `1` with an allowlisted provider/model catalog. Catalog model ids and defaults use `ModelInfo.id` (the external generate/session id). `ModelInfo.modelID` is an internal field and is not the catalog key. The route is available through the shared web host used by Web, Electron, hosted mobile, and Capacitor mobile, before generic OpenCode proxy handling.
+  - Provider catalog responses include only provider `id`, `name`, and safe models. Safe models include `id`, `name`, fixed text/audio/image/video/pdf capability modalities, bounded cost/limit fields, `release_date`, and variant names with `{}` values. v2 `ModelInfo.variants` is an array of `{ id, settings?, headers?, body? }`; projection keeps ids in array order as empty-object keys and drops request payloads. v2 `capabilities.tools` maps to `toolcall`, and `input`/`output` modality name arrays map to boolean maps. v2 `cost` tier arrays keep the untiered base price. Identifiers are bounded to 512 characters, display names to 1024, release dates to 64, numeric values to absolute 1e9, and catalog collections to 200 providers, 500 models per provider, and 100 defaults or variants. Provider credentials/configuration and unallowlisted model fields stay server-side. Malformed catalog roots and SDK error envelopes return HTTP 502. `partial: true` is structural only: provider/model/default truncation, dropped providers/models/defaults, or truncated variant dictionaries. Soft allowlist stripping of optional metadata (unknown modalities, non-boolean capability flags, out-of-range cost/limit numbers, empty/null/invalid `release_date`, invalid variant ids) keeps valid models and must not set `partial: true`, or UI refresh retains a stale complete snapshot after OpenCode provider updates. The same input shapes are accepted by the VS Code projector and `packages/ui/src/lib/configCatalogParser.ts`.
+  - Agents: `/api/config/agents/:name` and `/api/config/agents/:name/config`. A `native` create or update writes only the fields in that object into the selected user or project markdown file. `scope` chooses the file. `confirmDrop` removes fields the current format cannot represent; every other field already in the file stays unchanged.
   - Commands: batched metadata via `POST /api/config/commands/metadata`; `{ catalog: true }` returns the compact autocomplete catalog without templates, plus CRUD at `/api/config/commands/:name`
   - Global raw configs: `GET /api/config/global` discovers existing config targets; `GET/PUT /api/config/global/:target` reads and writes `opencode`, `oh-my-opencode-slim`, and `oh-my-openagent` JSON or JSONC files
   - MCP servers: `/api/config/mcp` and `/api/config/mcp/:name`
@@ -259,6 +338,7 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
   - `getOpenCodeAuthHeaders()`
   - `isOpenCodeConnectionSecure()`
   - `ensureLocalOpenCodeServerPassword(options?)`
+  - `adoptOpenCodeServerPassword(password, source)`: adopts a password owned by another process (the shared official service registration); `null` clears it on attach rollback.
 
 ## Public exports (core-routes.js)
 - `registerServerStatusRoutes(app, dependencies)`: registers status/system endpoints:
@@ -313,9 +393,13 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
   - `setupProxy(app)`
 
 ## Public exports (shutdown-runtime.js)
-- `createGracefulShutdownRuntime(dependencies)`: creates graceful shutdown runtime for managed OpenCode and web server teardown sequencing.
+- `createGracefulShutdownRuntime(dependencies)`: creates graceful shutdown runtime for managed OpenCode and web server teardown sequencing. Stops managed OpenCode only via `openCodeProcess.close()` (that handle owns SIGTERM→SIGKILL). After close, `waitForPortRelease(port, 5000)` probes whether the listener freed — never re-kills a pre-captured numeric pid (recycle hazard) and never mass-kills by port. When `forceCloseConnections: true`, after `server.close()` it runs `forceCloseHttpServerConnections` (`closeAllConnections` plus destroy of tracked upgraded sockets) so the HTTP close callback can fire without waiting `SHUTDOWN_TIMEOUT` on leftover WS/SSE.
 - Returned API:
-  - `gracefulShutdown(options?)`: accepts `forceCloseConnections: true` for runtimes that close remaining HTTP connections after initiating server close.
+  - `gracefulShutdown(options?)`: accepts `forceCloseConnections: true` for runtimes that close remaining HTTP connections after initiating server close (including upgraded sockets tracked by `attachHttpServerConnectionTracker`).
+
+## Public exports (http-server-connections.js)
+- `attachHttpServerConnectionTracker(server)`: tracks sockets from the server's `connection` event (covers later upgrades). Returns `{ getOpenSocketCount, destroyRemainingSockets, dispose }`.
+- `forceCloseHttpServerConnections(server)`: `closeAllConnections` then destroys remaining tracked sockets; returns `{ destroyedTracked }`. Only the owning server's sockets — never an external server.
 
 ## Public exports (server-startup-runtime.js)
 - `createServerStartupRuntime(dependencies)`: creates runtime for server bind/listen and process handler wiring.
@@ -370,6 +454,8 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
   - `POST /api/projects/:projectId/icon/discover`
 
 ## Public exports (skill-routes.js)
+
+The V2 skill catalog uses `id` as the existing OpenChamber `name` invocation key and `path` as the file location. Frontmatter `name` is a display label, never an invocation key. Local fallback discovery uses the same path-derived ID, so live and local entries deduplicate correctly. Web, Electron and mobile share this route; VS Code mirrors the projection through `skill.list` in its extension host. Upstream failures remain errors rather than empty successful catalogs.
 - `registerSkillRoutes(app, dependencies)`: registers skills-related routes:
   - Skills config CRUD and metadata under `/api/config/skills*`; `summary=true` returns compact autocomplete fields without skill content or sources
   - Skills catalog listing/source pagination, scan, and install routes
@@ -382,9 +468,10 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
   - SSE forwarders: `GET /api/global/event`, `GET /api/event` (optional `includeReasoning=false` parse-filters reasoning events on the Host send path; param never forwarded upstream; enabled path remains byte passthrough)
   - Official session.messages list: `GET /api/session/:sessionID/message` (optional `includeReasoning=false` strips reasoning parts; exact message GET is owned by session-turn-pages)
   - Session message forwarder: `POST /api/session/:sessionId/message`
-  - Generic `/api/*` forwarding with hop-by-hop header filtering
+  - Generic `/api/*` forwarding with hop-by-hop header filtering. v2 upstream routes live under `/api` (`@opencode-ai/protocol`); the proxy restores that prefix after Express strips the `/api` mount. Forwarding `/agent` (v1 root) hits the v2 Web UI HTML fallback.
   - Windows `/session` merge fallback path behavior
-  - OpenCode readiness gate for proxied `/api` requests
+  - OpenCode readiness gate for proxied `/api` requests: process warmup still uses `OPEN_CODE_READY_GRACE_MS`; `state.v1Migration.admitTranscript !== true` holds with no grace until the gate admits or the client cancels, so a `running` migration past 12s cannot `next()` an empty session list through as success
+  - Runtime contract execution gate (ticket 11): mutating session/turn paths require **current-instance** `executionAllowed === true` (null/pending/false → HTTP 409 `RUNTIME_CONTRACT_EXECUTION_BLOCKED`). The gate runs before readiness hold and **again after hold** so a stale permit cannot forward once the new instance is incompatible. Lifecycle **revokes** the permit (generation bump + pending contract) on start/restart; async health probes only publish when their generation still matches. Diagnostic GET health/info/migration paths, ordinary reads, and **interrupt/abort (stop-task)** stay available. Host background clients share the same gate via `server-opencode-fetch` / gated `makeOpenCodeV2Client`.
 
 ## Public exports (watcher.js)
 - `createOpenCodeWatcherRuntime(dependencies)`: creates global event watcher runtime backed by the shared upstream SSE reader.

package/server/lib/opencode/agent-document.d.ts

@@ -0,0 +1,28 @@
+export class DropConfirmationRequired extends Error {
+  code: 'drop-confirmation';
+  dropped: Array<{ key: string; reason: string }>;
+  constructor(dropped: Array<{ key: string; reason: string }>);
+}
+
+export function inspectAgentConfig(config: unknown): {
+  legacy: boolean;
+  dropped: Array<{ key: string; reason: string }>;
+};
+
+export function convertAgentConfig(config: unknown): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+  legacy: boolean;
+  dropped: Array<{ key: string; reason: string }>;
+};
+
+export function applyNativePatch(
+  current: { frontmatter: Record<string, unknown>; body: string },
+  patch: Record<string, unknown>,
+): { frontmatter: Record<string, unknown>; body: string };
+
+export function writeAgentDocument(
+  existing: { frontmatter?: Record<string, unknown>; body?: string },
+  patch: Record<string, unknown>,
+  confirmDrop: boolean,
+): { frontmatter: Record<string, unknown>; body: string };

package/server/lib/opencode/agent-document.js

@@ -0,0 +1,280 @@
+/**
+ * OpenCode v2 agent markdown.
+ *
+ * A file is native only when every frontmatter key is a current agent field.
+ * Any older key makes the loader migrate the whole file, and native keys in
+ * that file are then treated as request body. Saving therefore rewrites the
+ * whole file as native markdown. Fields the runtime does not apply are reported
+ * and kept until the caller confirms they can be dropped.
+ */
+
+const NATIVE_KEYS = new Set([
+  'model',
+  'variant',
+  'request',
+  'system',
+  'description',
+  'mode',
+  'hidden',
+  'color',
+  'steps',
+  'disabled',
+  'permissions',
+]);
+
+const ACTION_RENAMES = {
+  bash: 'shell',
+  task: 'subagent',
+  write: 'edit',
+  patch: 'edit',
+};
+
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+const PROMPT_FILE = /^\{file:.+\}$/i;
+const EFFECTS = new Set(['allow', 'ask', 'deny']);
+
+export class DropConfirmationRequired extends Error {
+  /**
+   * @param {Array<{ key: string, reason: string }>} dropped
+   */
+  constructor(dropped) {
+    super('Drop confirmation required');
+    this.code = 'drop-confirmation';
+    this.dropped = dropped;
+  }
+}
+
+const isEffect = (value) => typeof value === 'string' && EFFECTS.has(value);
+
+const renameAction = (action) => ACTION_RENAMES[action] || action;
+
+/**
+ * @param {unknown} config
+ * @returns {{ legacy: boolean, dropped: Array<{ key: string, reason: string }> }}
+ */
+export function inspectAgentConfig(config) {
+  const source = config && typeof config === 'object' && !Array.isArray(config) ? config : {};
+  /** @type {Array<{ key: string, reason: string }>} */
+  const dropped = [];
+  const keys = Object.keys(source);
+
+  for (const key of keys) {
+    if (key === 'temperature' || key === 'top_p') {
+      dropped.push({ key, reason: 'generation' });
+      continue;
+    }
+    if (key === 'options' && source.options && typeof source.options === 'object' && Object.keys(source.options).length > 0) {
+      dropped.push({ key, reason: 'unknown' });
+      continue;
+    }
+    if (key === 'prompt' && typeof source.prompt === 'string' && PROMPT_FILE.test(source.prompt.trim())) {
+      dropped.push({ key, reason: 'prompt-file' });
+      continue;
+    }
+    if (key === 'color' && source.color != null && source.color !== '' && !HEX_COLOR.test(String(source.color))) {
+      dropped.push({ key, reason: 'color' });
+      continue;
+    }
+    if (key === 'variant' && (typeof source.model !== 'string' || source.model.length === 0)) {
+      dropped.push({ key, reason: 'variant' });
+      continue;
+    }
+    if (!NATIVE_KEYS.has(key) && !isConvertibleKey(key)) {
+      dropped.push({ key, reason: 'unknown' });
+    }
+  }
+
+  const legacy = keys.some((key) => !NATIVE_KEYS.has(key)) || dropped.length > 0;
+  return { legacy, dropped };
+}
+
+const isConvertibleKey = (key) => (
+  key === 'prompt'
+  || key === 'tools'
+  || key === 'disable'
+  || key === 'maxSteps'
+  || key === 'permission'
+  || key === 'name'
+  || key === 'options'
+);
+
+/**
+ * @param {unknown} config
+ * @returns {{ frontmatter: Record<string, unknown>, body: string, legacy: boolean, dropped: Array<{ key: string, reason: string }> }}
+ */
+export function convertAgentConfig(config) {
+  const source = config && typeof config === 'object' && !Array.isArray(config) ? { ...config } : {};
+  const inspection = inspectAgentConfig(source);
+  /** @type {Record<string, unknown>} */
+  const frontmatter = {};
+
+  if (typeof source.description === 'string' && source.description.trim()) {
+    frontmatter.description = source.description;
+  }
+  if (source.mode === 'primary' || source.mode === 'subagent' || source.mode === 'all') {
+    frontmatter.mode = source.mode;
+  }
+
+  const model = encodeModel(source.model, source.variant);
+  if (model) frontmatter.model = model;
+
+  if (source.hidden === true) frontmatter.hidden = true;
+  if (source.disabled === true || source.disable === true) frontmatter.disabled = true;
+  if (typeof source.color === 'string' && HEX_COLOR.test(source.color)) frontmatter.color = source.color;
+
+  const steps = positiveInt(source.steps) ?? positiveInt(source.maxSteps);
+  if (steps !== undefined) frontmatter.steps = steps;
+
+  if (isRequest(source.request)) frontmatter.request = source.request;
+
+  const permissions = normalizePermissions(source.permissions ?? source.permission, source.tools);
+  if (permissions.length > 0) frontmatter.permissions = permissions;
+
+  const body = readSystem(source);
+  return { frontmatter, body, legacy: inspection.legacy, dropped: inspection.dropped };
+}
+
+/**
+ * @param {{ frontmatter: Record<string, unknown>, body: string }} current
+ * @param {Record<string, unknown>} patch
+ */
+export function applyNativePatch(current, patch) {
+  const frontmatter = { ...current.frontmatter };
+  let body = current.body;
+  const changes = patch && typeof patch === 'object' ? patch : {};
+  for (const [key, value] of Object.entries(changes)) {
+    if (value === undefined || key === 'name' || key === 'scope' || key === 'confirmDrop') continue;
+    if (key === 'system') {
+      body = value === null ? '' : String(value);
+      delete frontmatter.system;
+      continue;
+    }
+    if (value === null || value === false && (key === 'hidden' || key === 'disabled')) {
+      delete frontmatter[key];
+      if (key === 'model') delete frontmatter.variant;
+      continue;
+    }
+    if (key === 'color' && (typeof value !== 'string' || !HEX_COLOR.test(value))) {
+      continue;
+    }
+    if (key === 'steps') {
+      const steps = positiveInt(value);
+      if (steps === undefined) delete frontmatter.steps;
+      else frontmatter.steps = steps;
+      continue;
+    }
+    if (key === 'permissions') {
+      const permissions = normalizePermissions(value, undefined);
+      delete frontmatter.permission;
+      if (permissions.length === 0) delete frontmatter.permissions;
+      else frontmatter.permissions = permissions;
+      continue;
+    }
+    if (key === 'model') delete frontmatter.variant;
+    frontmatter[key] = value;
+  }
+  return { frontmatter, body };
+}
+
+/**
+ * Write only the keys in `patch` onto the existing markdown document.
+ * `confirmDrop` removes fields the current format cannot represent.
+ * Unmentioned fields, including permissions, stay as they are.
+ *
+ * @param {{ frontmatter?: Record<string, unknown>, body?: string }} existing
+ * @param {Record<string, unknown>} patch
+ * @param {boolean} confirmDrop
+ */
+export function writeAgentDocument(existing, patch, confirmDrop) {
+  const frontmatter = { ...(existing?.frontmatter || {}) };
+  let body = typeof existing?.body === 'string' ? existing.body : '';
+  if (confirmDrop) {
+    const inspection = inspectAgentConfig({
+      ...frontmatter,
+      ...(body.trim() ? { prompt: body } : {}),
+    });
+    for (const item of inspection.dropped) {
+      if (item.key === 'prompt') {
+        body = '';
+        delete frontmatter.prompt;
+      } else {
+        delete frontmatter[item.key];
+      }
+    }
+  }
+  return applyNativePatch({ frontmatter, body }, patch);
+}
+
+const encodeModel = (model, variant) => {
+  if (typeof model !== 'string') return undefined;
+  const trimmed = model.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.includes('#')) return trimmed;
+  if (typeof variant === 'string' && variant.trim() && !variant.includes('#')) {
+    return `${trimmed}#${variant.trim()}`;
+  }
+  return trimmed;
+};
+
+const positiveInt = (value) => {
+  const number = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN;
+  if (!Number.isInteger(number) || number < 1) return undefined;
+  return number;
+};
+
+const isRequest = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const request = /** @type {Record<string, unknown>} */ (value);
+  return request.headers != null || request.body != null;
+};
+
+const readSystem = (source) => {
+  if (typeof source.system === 'string') return source.system;
+  if (typeof source.prompt === 'string' && !PROMPT_FILE.test(source.prompt.trim())) return source.prompt;
+  return '';
+};
+
+const normalizePermissions = (permission, tools) => {
+  /** @type {Array<{ action: string, resource: string, effect: string }>} */
+  const rules = [];
+  if (tools && typeof tools === 'object' && !Array.isArray(tools)) {
+    for (const [tool, enabled] of Object.entries(tools)) {
+      if (typeof enabled !== 'boolean') continue;
+      pushRule(rules, renameAction(tool), '*', enabled ? 'allow' : 'deny');
+    }
+  }
+  if (isEffect(permission)) {
+    pushRule(rules, '*', '*', permission);
+  } else if (Array.isArray(permission)) {
+    for (const rule of permission) {
+      if (!rule || typeof rule !== 'object') continue;
+      if (typeof rule.permission === 'string' && typeof rule.pattern === 'string') {
+        pushRule(rules, renameAction(rule.permission), rule.pattern, rule.action);
+        continue;
+      }
+      pushRule(rules, renameAction(rule.action), rule.resource, rule.effect);
+    }
+  } else if (permission && typeof permission === 'object') {
+    for (const [key, rule] of Object.entries(permission)) {
+      const action = renameAction(key);
+      if (isEffect(rule)) {
+        pushRule(rules, action, '*', rule);
+        continue;
+      }
+      if (rule && typeof rule === 'object' && !Array.isArray(rule)) {
+        for (const [resource, effect] of Object.entries(rule)) {
+          pushRule(rules, action, resource, effect);
+        }
+      }
+    }
+  }
+  return rules;
+};
+
+const pushRule = (rules, action, resource, effect) => {
+  if (!action || !resource || !isEffect(effect)) return;
+  const index = rules.findIndex((rule) => rule.action === action && rule.resource === resource);
+  const next = { action, resource, effect };
+  if (index >= 0) rules[index] = next;
+  else rules.push(next);
+};