@openchambery/web 2.0.0-beta.9 → 2.0.1

package/server/lib/opencode/DOCUMENTATION.md

@@ -5,7 +5,7 @@ This module provides OpenCode server integration utilities for the web server ru
 
 ## Entrypoints and structure
 - `packages/web/server/lib/opencode/index.js`: public entrypoint (currently baseline placeholder).
-- `packages/web/server/lib/opencode/auth.js`: provider authentication file operations.
+- `packages/web/server/lib/opencode/auth.js`: host-only authoritative provider credential API reads and deletion.
 - `packages/web/server/lib/opencode/auth-state-runtime.js`: managed OpenCode server auth password/header runtime.
 - `packages/web/server/lib/opencode/cli-options.js`: CLI/environment option parsing for server startup arguments.
 - `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.
@@ -15,7 +15,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `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/upgrade-screen.js`: startup gate for a detected OpenCode below `2.0.15`. It does not own process lifecycle. `GET /api/opencode/compatibility` classifies the version already detected by startup. `POST /api/opencode/install-required` installs `max(pin, 2.0.15)` through `installPinnedOpenCode2Cli`, points the managed binary at that cache, and restarts through the existing lifecycle hooks. Success requires the running serve to report `2.0.15` or newer. External serves are not replaced. Failure returns `upgraded: false` and the error; it does not claim the previous process was restored.
+- `packages/web/server/lib/opencode/upgrade-screen.js`: startup gate for the running OpenCode below `2.0.20`. Client/schema dependencies and the default CLI install target are pinned to `2.0.23`; the compatible execution floor is independently `2.0.20` (credential API). An unreadable running version is unavailable even when the local CLI is compatible. `POST /api/opencode/install-required` installs the pin into the owned cache and uses existing lifecycle hooks. Success requires the running service to meet both the floor and selected target. External services are not replaced; compatible newer shared services are not automatically downgraded. Failure restores binary selection and reports `upgraded: false`, without claiming process restoration.
 - `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.
@@ -23,9 +23,9 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/project-directory-runtime.js`: request-scoped and settings-backed project directory resolution/validation runtime.
 - `packages/web/server/lib/opencode/config-entity-routes.js`: route registration for agent/command/MCP config orchestration and reload semantics.
 - `packages/web/server/lib/opencode/provider-catalog.js`: fail-closed projection for the safe provider catalog response.
-- `packages/web/server/lib/opencode/snippets.js`: opencode-snippets-compatible snippet file CRUD, discovery, and hashtag expansion.
 - `packages/web/server/lib/opencode/cli-options.js`: CLI/environment option parsing for server startup arguments.
 - `packages/web/server/lib/opencode/core-routes.js`: server status/system routes, auth/access guard routes, and settings utility route registration.
+  - `PATCH /api/client-auth/clients/:id` edits the stored device label (trimmed, 1–80 characters), returning `{ client }` without credentials. Owner UI sessions and local/paired desktop clients can edit any device; other client tokens can edit only themselves. Missing devices return 404, invalid labels 400, unauthorized targets 403. Renaming shares the client store mutation queue and preserves token identity, metadata and revocation. Web, Electron and mobile use the web `ClientAuthAPI`; VS Code does not expose client management.
 - `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. The SPA fallback sends `index.html` relative to `root`, so deep links keep working when the install lives under a dot directory.
@@ -55,13 +55,12 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/ui-auth/ui-passkeys.js`: UI passkey storage and WebAuthn registration/authentication helpers (outside OpenCode module).
 
 ## Public exports (auth.js)
-- `readAuthFile()`: Reads and parses `~/.local/share/opencode/auth.json`.
-- `writeAuthFile(auth)`: Writes auth file with automatic backup.
-- `removeProviderAuth(providerId)`: Removes a provider's auth entry.
-- `getProviderAuth(providerId)`: Returns auth for a specific provider or null.
-- `listProviderAuths()`: Returns list of provider IDs with configured auth.
-- `AUTH_FILE`: Auth file path constant.
-- `OPENCODE_DATA_DIR`: OpenCode data directory path constant.
+- `configureOpenCodeCredentials(resolveClient)`: host composition injects a call-time SDK client resolver; `null` detaches it. Web/Electron share server wiring; VS Code wires its manager in extension activation. Mobile clients use their host.
+- `openCodeCredentialSource({ buildOpenCodeUrl, getOpenCodeAuthHeaders })`: resolves the current endpoint/auth at each read rather than capturing a previous runtime.
+- `readOpenCodeCredentials()`: async SDK `credential.list()` read of the running service; validates entries and projects only active accounts into the quota/TTS credential shape. OAuth `metadata.accountID` becomes `accountId`. No local `auth.json`, local environment, or local provider-config fallback; external service environment-only keys are not exposed by the credential API.
+- `getProviderAuth(providerId)`: async selected stored credential or authoritative `null`; network/auth/schema failures reject with a sanitized error, never empty success.
+- `removeProviderAuth(providerId)`: deletes every stored account for that integration through SDK `credential.remove`, preserving unrelated integrations. Partial failure rejects explicitly; retry lists remaining accounts. Auth-only disconnect requires no process restart.
+- Credential values remain host-only. `credential-boundary.js` blocks raw credential list/creation responses (GET/HEAD/POST `/api/credential`, including encoded/trailing-slash forms) in Web proxy and VS Code bridge because v2 replies contain keys. Provider-source responses expose only existence; errors never include upstream credential bodies/headers. Explicit legacy config-sync file transfer is not a current-service credential source or login operation.
 
 ## Public exports (shared.js)
 - `OPENCODE_CONFIG_DIR`, `AGENT_DIR`, `COMMAND_DIR`, `SKILL_DIR`, `CONFIG_FILE`, `CUSTOM_CONFIG_FILE`: Path constants.
@@ -87,11 +86,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` (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/compatibility`: startup upgrade-screen status. `state` is `compatible` at OpenCode `2.0.15` or newer, `incompatible` when a detected version is older or not 2.x, and `unavailable` when no version could be read. `canInstall` is true only for a local (managed or bundled) runtime this platform can install into the owned cache. External serves are reported and not replaced.
-  - `POST /api/opencode/install-required`: installs the upgrade-screen target (`2.0.15`, or the pin when the pin is newer) into the owned cache and restarts through the existing lifecycle. `upgraded: true` only after the running serve verifies at or above that target. Failure is `upgraded: false` plus `error`. Concurrent installs are single-flight.
-  - `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.
+  - `POST /api/opencode/upgrade` (ticket 12): installs the remote latest or explicitly targeted `@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` (official npm `@opencode/cli` latest stable 2.x release), `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. `update-discovery.js` shares one in-flight registry request per host, caches successful checks for five minutes and failed checks for thirty seconds, with a five-second request deadline. Failed registry checks return HTTP 500 with `available: null`, never a false up-to-date result. An upgrade without an explicit target resolves this same remote release. Shared Web/Electron/hosted-mobile/Capacitor clients check after startup, every five minutes while visible, on focus/reconnect, and on runtime changes; query results and dismissed notifications are scoped to the host. Successful upgrade already includes process restart and live version verification, so no second reload is needed.
+  - `GET /api/opencode/compatibility`: startup upgrade-screen status. `compatible` requires the running OpenCode 2.x at `2.0.20` or newer; older/invalid versions are `incompatible`; unreadable running versions are `unavailable`. External serves are not replaced.
+  - `POST /api/opencode/install-required`: installs the pin (`2.0.23`, never below the `2.0.20` floor) into the owned cache and restarts through the existing lifecycle. `upgraded: true` requires live version verification. Concurrent installs are single-flight; failures remain errors.
+  - `GET /api/opencode/contract`: runtime contract admission for the **running serve**. Reachability, auth, execution, migration, and CLI↔serve mismatch are separate. The `2.0.20` floor is independent of the `2.0.23` install pin; compatible newer 2.x services remain admitted.
   - `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`
@@ -130,7 +129,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `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`.
+- Pure admission matrix. `RUNTIME_CONTRACT_MIN_VERIFIED` (`2.0.20`) is the documented 2.x floor, shared with the startup gate through `MINIMUM_OPENCODE2_VERSION`; the VS Code sidecar mirrors this 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.
@@ -155,7 +154,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `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. 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).
+- `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. Startup does not prewarm persisted project directories: v2 session lists are storage-scoped and do not initialize locations, while location-scoped reads must follow actual consumer demand. 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:
@@ -180,6 +179,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `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.
+- `remote-upgrade.integration.test.js` is opt-in via `OPENCHAMBER_TEST_REMOTE_UPGRADE=1`; it downloads official binaries, starts an isolated 2.0.16 shared service, discovers the remote latest release through the status route, upgrades through the HTTP route, and verifies the running version and cleared update availability. It never restarts the user's shared service.
 
 ## Public exports (env-runtime.js)
 - `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`.
@@ -209,6 +209,7 @@ This module provides OpenCode server integration utilities for the web server ru
 
 ## Public exports (env-config.js)
 - `resolveOpenCodeEnvConfig(options?)`: resolves and validates OpenCode host/port/hostname environment configuration.
+- `OPENCODE_HOST` still requires an explicit port; HTTP `:80` and HTTPS `:443` retain their effective port even when URL normalization removes it. Host precedence, IPv6 and path/query/hash validation are unchanged.
 - Returned object fields:
   - `configuredOpenCodePort`
   - `configuredOpenCodeHost`
@@ -265,6 +266,7 @@ This module provides OpenCode server integration utilities for the web server ru
 
 ## Public exports (settings-normalization-runtime.js)
 - `createSettingsNormalizationRuntime(dependencies)`: creates normalization/sanitization runtime for shared settings helper logic.
+- Filesystem path normalization prefers `realpathSync.native` (falling back to the injected function when native is unavailable), so case-insensitive volumes use the same spelling as Git/OpenCode. It never lowercases directory names; inaccessible paths keep their original value. Existing settings read/write normalization repairs project paths and the existing deterministic-ID migration carries project storage/icons and active selection to the resulting ID. Web, in-process Electron, and hosted/native mobile use this Host boundary; extension-only VS Code retains its workspace-folder ownership.
 - Returned API:
   - `normalizeDirectoryPath(value)`
   - `normalizePathForPersistence(value)`
@@ -321,6 +323,10 @@ 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)
+The provider catalog's optional `model.default` lookup may fail independently:
+available provider/model lists still return successfully without defaults.
+Failures of either required list still return HTTP 502 for the caller to retry.
+
 - `registerConfigEntityRoutes(app, dependencies)`: registers configuration entity routes:
   - `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`.
@@ -328,7 +334,6 @@ It makes no model requests and never reads real user credentials.
   - 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`
-  - Snippets: `/api/config/snippets`, `/api/config/snippets/:name`, and `/api/config/snippets/expand`
 
 ### Catalog / OpenChamber-owned API change checklist
 
@@ -341,6 +346,7 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
   5. Coordinate `partial` semantics between Host projection, VS Code projection (`packages/vscode/src/provider-catalog-runtime.ts`), and `packages/ui/src/lib/configCatalogParser.ts`. Reserve `partial: true` for structural incompleteness (dropped/truncated providers, models, defaults, variants). Soft metadata stripping must stay non-partial; a false `partial: true` blocks UI refresh of an existing complete snapshot and can leave model pickers on stale catalogs after OpenCode provider updates.
 
 ## Public exports (auth-state-runtime.js)
+- Initial user auth prefers `OPENCODE_PASSWORD` over `OPENCODE_SERVER_PASSWORD`; HMR preserves the captured choice and active password. Private child environments set both names to the active header password after merging shell/host env. Registered shared-service auth is authoritative (including no password), uses username `opencode`, and never falls back to private env credentials.
 - `createOpenCodeAuthStateRuntime(dependencies)`: creates runtime for managed OpenCode auth password state and request headers.
 - Returned API:
   - `getOpenCodeAuthHeaders()`
@@ -508,16 +514,21 @@ The V2 skill catalog uses `id` as the existing OpenChamber `name` invocation key
   reuse the existing UI-password / CORS path, register before the generic proxy,
   and return 501 when the service is disabled. Logs never include message
   bodies, parts, or tokens.
-- Provider auth: `~/.local/share/opencode/auth.json`.
-- User config: `~/.config/opencode/opencode.json` or `~/.config/opencode/opencode.jsonc`.
-- Project config: `<workingDirectory>/.opencode/opencode.json` or `opencode.json`.
+- Provider auth: running OpenCode v2 credential API (no direct access to legacy auth files or OpenCode database).
+- `config-files.js` owns physical JSON/JSONC discovery, layer provenance and structural writes for Web/Electron and the VS Code extension. Global directory: `OPENCODE_CONFIG_DIR`, otherwise `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode`.
+- Global documents load `opencode.json` then `opencode.jsonc`; V2 does not load legacy `config.json`. Both are retained as separate writable documents. `userConfig` / `projectConfig` are merged read views; mutations must use `getConfigForPath`, `getJsonEntrySource`, or `getJsonWriteTarget`, never persist a merged view into one file.
+- Project documents load from filesystem root to the working directory, all direct JSON/JSONC files first, then all `.opencode` files. `documents` records low-to-high precedence; `userLayers` / `projectLayers` retain physical sources. Custom files sit above global files and below project documents, matching V2 `ConfigDiscovery.names` and `Config.load`.
 - Custom config: `OPENCODE_CONFIG` env var path.
+- Raw global editors in Web and VS Code edit the explicit custom file when set, otherwise the highest-precedence existing global document (JSONC wins). New global documents default to `opencode.jsonc`. Raw content is one physical document, never a synthetic merged serialization.
+- Missing, whitespace-only and comment-only files are empty layers. Malformed/non-object JSONC and IO failures throw; partial parser results never become empty success. Both raw and structured writers validate the existing document before replacement.
+- Structured writes diff object fields, preserve untouched comments/formatting (including BOM/CRLF), and remove properties with adjacent separator commas without consuming surrounding comments. Arrays are replaced as owned values. A failed round-trip aborts instead of falling back to whole-file serialization.
+- Writes stage a same-directory temporary file, preserve file mode, create `.openchamber.backup`, then atomically rename; failed staging/backup/rename leaves the original intact and cleans the temporary file. Existing symlinks are resolved first: staging/rename target the real file, the link remains unchanged, and the backup stays beside the supplied config path. Dangling symlinks fail before staging; existing target permissions are restored on the staged file regardless of umask. Deleting an entity removes it from its selected source document; lower-precedence definitions may become visible afterward.
 - Rate limit config: `OPENCHAMBER_RATE_LIMIT_MAX_ATTEMPTS`, `OPENCHAMBER_RATE_LIMIT_NO_IP_MAX_ATTEMPTS` env vars.
 
 ## Notes for contributors
 - This module serves as foundation for OpenCode-related server utilities.
 - Route ownership moved to module-level `routes.js`; `index.js` wires dependencies only.
 - All file writes include automatic backup before modification.
-- Config merging follows priority: custom > project > user.
+- Config merging follows priority: project `.opencode` > project direct > custom > global JSONC > global JSON.
 - UI auth uses scrypt for password hashing with constant-time comparison.
 - Tunnel auth treats `host.docker.internal` as local-only when the socket remote IP is private/loopback.

package/server/lib/opencode/agents.js

@@ -197,23 +197,12 @@ function getAgentPermissionSource(agentName, workingDirectory, lookupCache = nul
     }
   }
 
-  // Check JSON layers in effective override order. readConfigLayers merges
-  // user -> project -> custom, so custom wins over project, project over user.
+  // Check physical documents in effective override order, including both global files.
   const layers = readConfigLayers(workingDirectory);
-
-  const customJsonPermission = layers.customConfig?.agent?.[agentName]?.permission;
-  if (customJsonPermission !== undefined && layers.paths.customPath) {
-    return { source: 'json', scope: 'custom', path: layers.paths.customPath };
-  }
-
-  const projectJsonPermission = layers.projectConfig?.agent?.[agentName]?.permission;
-  if (projectJsonPermission !== undefined && layers.paths.projectPath) {
-    return { source: 'json', scope: AGENT_SCOPE.PROJECT, path: layers.paths.projectPath };
-  }
-
-  const userJsonPermission = layers.userConfig?.agent?.[agentName]?.permission;
-  if (userJsonPermission !== undefined) {
-    return { source: 'json', scope: AGENT_SCOPE.USER, path: layers.paths.userPath };
+  for (const layer of layers.documents.toReversed()) {
+    if (layer.config?.agent?.[agentName]?.permission !== undefined) {
+      return { source: 'json', scope: layer.scope, path: layer.path };
+    }
   }
 
   return { source: null, scope: null, path: null };
@@ -300,7 +289,7 @@ function getAgentSources(agentName, workingDirectory, lookupCache = createAgentL
   const jsonSource = getJsonEntrySource(layers, 'agent', agentName);
   const jsonSection = jsonSource.section;
   const jsonPath = jsonSource.path || layers.paths.customPath || layers.paths.projectPath || layers.paths.userPath;
-  const jsonScope = jsonSource.path === layers.paths.projectPath ? AGENT_SCOPE.PROJECT : AGENT_SCOPE.USER;
+  const jsonScope = layers.projectLayers.some((layer) => layer.path === jsonSource.path) ? AGENT_SCOPE.PROJECT : AGENT_SCOPE.USER;
 
   const sources = {
     md: {
@@ -444,7 +433,7 @@ function getAgentConfig(agentName, workingDirectory, lookupCache = createAgentLo
   const jsonSource = getJsonEntrySource(layers, 'agent', agentName);
 
   if (jsonSource.exists && jsonSource.section) {
-    const scope = jsonSource.path === layers.paths.projectPath ? AGENT_SCOPE.PROJECT : AGENT_SCOPE.USER;
+    const scope = layers.projectLayers.some((layer) => layer.path === jsonSource.path) ? AGENT_SCOPE.PROJECT : AGENT_SCOPE.USER;
     return {
       source: 'json',
       scope,
@@ -756,8 +745,9 @@ function deleteAgent(agentName, workingDirectory, scope) {
   const layers = readConfigLayers(workingDirectory);
 
   if (requestedScope === AGENT_SCOPE.PROJECT) {
-    if (layers.paths.projectPath && deleteJsonAgentEntry(layers.projectConfig, agentName)) {
-      writeConfig(layers.projectConfig, layers.paths.projectPath);
+    const target = layers.projectLayers.toReversed().find((layer) => layer.config?.agent?.[agentName] !== undefined);
+    if (target && deleteJsonAgentEntry(target.config, agentName)) {
+      writeConfig(target.config, target.path);
       console.log(`Removed project-level agent from opencode.json: ${agentName}`);
       return;
     }
@@ -765,8 +755,9 @@ function deleteAgent(agentName, workingDirectory, scope) {
   }
 
   if (requestedScope === AGENT_SCOPE.USER) {
-    const userJsonPath = layers.paths.customPath || layers.paths.userPath;
-    const userJsonConfig = layers.paths.customPath ? layers.customConfig : layers.userConfig;
+    const target = layers.documents.toReversed().find((layer) => layer.scope !== 'project' && layer.config?.agent?.[agentName] !== undefined);
+    const userJsonPath = target?.path;
+    const userJsonConfig = target?.config;
     if (userJsonPath && deleteJsonAgentEntry(userJsonConfig, agentName)) {
       writeConfig(userJsonConfig, userJsonPath);
       console.log(`Removed user-level agent from opencode.json: ${agentName}`);

package/server/lib/opencode/auth-state-runtime.js

@@ -31,7 +31,7 @@ export const createOpenCodeAuthStateRuntime = (dependencies) => {
     const normalized = normalizeOpenCodePassword(password);
     if (!isValidOpenCodePassword(normalized)) {
       setAuthPassword(null);
-      setAuthSource(null);
+      setAuthSource(source || null);
       delete process.env.OPENCODE_SERVER_PASSWORD;
       syncToHmrState();
       return null;
@@ -45,13 +45,13 @@ export const createOpenCodeAuthStateRuntime = (dependencies) => {
   };
 
   const getOpenCodeAuthHeaders = () => {
-    const password = normalizeOpenCodePassword(getAuthPassword() || process.env.OPENCODE_SERVER_PASSWORD || '');
+    const password = normalizeOpenCodePassword(getAuthPassword() || '');
 
     if (!password) {
       return {};
     }
 
-    const username = process.env.OPENCODE_SERVER_USERNAME?.trim() || 'opencode';
+    const username = getAuthSource() === 'shared-service' ? 'opencode' : process.env.OPENCODE_SERVER_USERNAME?.trim() || 'opencode';
     const credentials = Buffer.from(`${username}:${password}`).toString('base64');
     return { Authorization: `Basic ${credentials}` };
   };

package/server/lib/opencode/auth-state-runtime.test.js

@@ -0,0 +1,59 @@
+import crypto from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+import { createOpenCodeAuthStateRuntime } from './auth-state-runtime.js';
+import { createHmrStateRuntime } from './hmr-state-runtime.js';
+
+const setup = (env = {}) => {
+  const processLike = { env: { ...env } };
+  const hmr = createHmrStateRuntime({ globalThisLike: {}, os: { homedir: () => '/example' }, processLike, stateKey: 'test' });
+  const state = hmr.getOrCreateHmrState();
+  hmr.ensureUserProvidedOpenCodePassword(state);
+  const restore = () => hmr.restoreRuntimeFromState({ hmrState: state, userProvidedOpenCodePassword: hmr.getUserProvidedOpenCodePassword(state) });
+  const runtimeState = restore();
+  const auth = createOpenCodeAuthStateRuntime({ crypto, process: processLike,
+    getAuthPassword: () => runtimeState.openCodeAuthPassword,
+    setAuthPassword: (value) => { runtimeState.openCodeAuthPassword = value; },
+    getAuthSource: () => runtimeState.openCodeAuthSource,
+    setAuthSource: (value) => { runtimeState.openCodeAuthSource = value; },
+    getUserProvidedPassword: () => hmr.getUserProvidedOpenCodePassword(state),
+    syncToHmrState: () => hmr.syncStateFromRuntime(state, runtimeState),
+  });
+  return { auth, restore, runtimeState, processLike, hmr, state };
+};
+
+describe('OpenCode auth ownership', () => {
+  it('uses v2 before legacy credentials and preserves the captured choice through HMR/restart', async () => {
+    const test = setup({ OPENCODE_PASSWORD: 'v2-fixture', OPENCODE_SERVER_PASSWORD: 'legacy-fixture' });
+    const password = await test.auth.ensureLocalOpenCodeServerPassword({ rotateManaged: true });
+    expect(password === 'v2-fixture').toBe(true);
+    expect(test.auth.getOpenCodeAuthHeaders().Authorization === `Basic ${Buffer.from(`opencode:${password}`).toString('base64')}`).toBe(true);
+    test.processLike.env.OPENCODE_PASSWORD = 'later-shell-fixture';
+    test.hmr.ensureUserProvidedOpenCodePassword(test.state);
+    expect((await test.auth.ensureLocalOpenCodeServerPassword({ rotateManaged: true })) === password).toBe(true);
+    expect(test.restore().openCodeAuthPassword === password).toBe(true);
+  });
+
+  it('rotates generated credentials while old credentials fail a controlled auth check', async () => {
+    const { auth, restore } = setup();
+    const old = await auth.ensureLocalOpenCodeServerPassword();
+    const previousHeader = auth.getOpenCodeAuthHeaders().Authorization;
+    const password = await auth.ensureLocalOpenCodeServerPassword({ rotateManaged: true });
+    const accepts = (header) => header === `Basic ${Buffer.from(`opencode:${password}`).toString('base64')}`;
+    expect(password !== old).toBe(true);
+    expect(accepts(previousHeader)).toBe(false);
+    expect(accepts(auth.getOpenCodeAuthHeaders().Authorization)).toBe(true);
+    expect(restore().openCodeAuthPassword === password).toBe(true);
+  });
+
+  it('adopts only shared registration credentials and never falls back to private env after clearing', () => {
+    const { auth, processLike, restore } = setup({ OPENCODE_PASSWORD: 'private-fixture', OPENCODE_SERVER_USERNAME: 'private-user' });
+    auth.adoptOpenCodeServerPassword('registration-fixture', 'shared-service');
+    expect(auth.getOpenCodeAuthHeaders().Authorization === `Basic ${Buffer.from('opencode:registration-fixture').toString('base64')}`).toBe(true);
+    auth.adoptOpenCodeServerPassword(null, 'shared-service');
+    expect(restore().openCodeAuthPassword).toBeNull();
+    expect(restore().openCodeAuthSource).toBe('shared-service');
+    auth.adoptOpenCodeServerPassword(null, null);
+    processLike.env.OPENCODE_SERVER_PASSWORD = 'stale-fixture';
+    expect(auth.getOpenCodeAuthHeaders()).toEqual({});
+  });
+});

package/server/lib/opencode/auth.d.ts

@@ -0,0 +1,13 @@
+import type { OpenCodeClient } from '@opencode/client';
+
+export type ProviderCredential =
+  | { type: 'api'; key: string }
+  | { type: 'oauth'; access: string; refresh: string; expires: number; accountId?: string; enterpriseUrl?: string };
+export function configureOpenCodeCredentials(resolveClient: (() => OpenCodeClient) | null): void;
+export function openCodeCredentialSource(deps: {
+  buildOpenCodeUrl: (path: string, prefix?: string) => string;
+  getOpenCodeAuthHeaders: () => Record<string, string>;
+}): () => OpenCodeClient;
+export function readOpenCodeCredentials(): Promise<Record<string, ProviderCredential>>;
+export function getProviderAuth(providerId: string): Promise<ProviderCredential | null>;
+export function removeProviderAuth(providerId: string): Promise<boolean>;

package/server/lib/opencode/auth.js

@@ -1,81 +1,91 @@
-import fs from 'fs';
-import path from 'path';
-import os from 'os';
+import { makeOpenCodeV2Client } from './v2-client.js';
 
-const OPENCODE_DATA_DIR = path.join(os.homedir(), '.local', 'share', 'opencode');
-const AUTH_FILE = path.join(OPENCODE_DATA_DIR, 'auth.json');
+/** @typedef {{ type: 'api', key: string } | { type: 'oauth', access: string, refresh: string, expires: number, accountId?: string, enterpriseUrl?: string }} ProviderCredential */
+/** @type {null | (() => import('@opencode/client').OpenCodeClient)} */
+let getClient = null;
 
-function readAuthFile() {
-  if (!fs.existsSync(AUTH_FILE)) {
-    return {};
-  }
-  try {
-    const content = fs.readFileSync(AUTH_FILE, 'utf8');
-    const trimmed = content.trim();
-    if (!trimmed) {
-      return {};
-    }
-    return JSON.parse(trimmed);
-  } catch (error) {
-    console.error('Failed to read auth file:', error);
-    throw new Error('Failed to read OpenCode auth configuration');
-  }
+/** Configure only in the trusted host. Resolve endpoint and authentication on every call. */
+export function configureOpenCodeCredentials(resolveClient) {
+  getClient = resolveClient;
 }
 
-function writeAuthFile(auth) {
-  try {
-    if (!fs.existsSync(OPENCODE_DATA_DIR)) {
-      fs.mkdirSync(OPENCODE_DATA_DIR, { recursive: true });
-    }
+export function openCodeCredentialSource({ buildOpenCodeUrl, getOpenCodeAuthHeaders }) {
+  return () => makeOpenCodeV2Client({
+    baseUrl: buildOpenCodeUrl('', '').replace(/\/+$/, ''),
+    authHeaders: getOpenCodeAuthHeaders(),
+  });
+}
 
-    if (fs.existsSync(AUTH_FILE)) {
-      const backupFile = `${AUTH_FILE}.openchamber.backup`;
-      fs.copyFileSync(AUTH_FILE, backupFile);
-      console.log(`Created auth backup: ${backupFile}`);
-    }
+const credentialError = () => new Error('Unable to read OpenCode credentials');
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 
-    fs.writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2), 'utf8');
-    console.log('Successfully wrote auth file');
-  } catch (error) {
-    console.error('Failed to write auth file:', error);
-    throw new Error('Failed to write OpenCode auth configuration');
+/** Validate before projection: malformed/unsupported responses are never empty success. */
+function validateCredentialEntries(entries) {
+  if (!Array.isArray(entries)) throw credentialError();
+  const active = new Set();
+  for (const entry of entries) {
+    if (!record(entry) || typeof entry.id !== 'string' || !entry.id || typeof entry.integrationID !== 'string'
+      || !entry.integrationID || typeof entry.active !== 'boolean' || !record(entry.value)) throw credentialError();
+    const value = entry.value;
+    if (value.type === 'key') {
+      if (typeof value.key !== 'string') throw credentialError();
+    } else if (value.type === 'oauth') {
+      if (typeof value.access !== 'string' || typeof value.refresh !== 'string' || !Number.isFinite(value.expires)) throw credentialError();
+    } else throw credentialError();
+    if (entry.active) {
+      if (active.has(entry.integrationID)) throw credentialError();
+      active.add(entry.integrationID);
+    }
   }
+  return entries;
 }
 
-function removeProviderAuth(providerId) {
-  if (!providerId || typeof providerId !== 'string') {
-    throw new Error('Provider ID is required');
-  }
-
-  const auth = readAuthFile();
-  
-  if (!auth[providerId]) {
-    console.log(`Provider ${providerId} not found in auth file, nothing to remove`);
-    return false;
+async function listCredentials(client) {
+  try {
+    return validateCredentialEntries(await client.credential.list({ signal: AbortSignal.timeout(8000) }));
+  } catch {
+    // Upstream errors can contain response bodies or request headers with secrets.
+    throw credentialError();
   }
+}
 
-  delete auth[providerId];
-  writeAuthFile(auth);
-  console.log(`Removed provider auth: ${providerId}`);
-  return true;
+function currentClient() {
+  if (!getClient) throw credentialError();
+  try { return getClient(); } catch { throw credentialError(); }
 }
 
-function getProviderAuth(providerId) {
-  const auth = readAuthFile();
-  return auth[providerId] || null;
+/** Host-only selected provider credentials. Never serialize this result to a client. */
+export async function readOpenCodeCredentials() {
+  const entries = await listCredentials(currentClient());
+  /** @type {Record<string, ProviderCredential>} */
+  const result = Object.create(null);
+  for (const entry of entries) {
+    if (!entry.active) continue;
+    const value = entry.value;
+    result[entry.integrationID] = value.type === 'key' ? { type: 'api', key: value.key } : {
+      type: 'oauth', access: value.access, refresh: value.refresh, expires: value.expires,
+      ...(typeof value.metadata?.accountID === 'string' ? { accountId: value.metadata.accountID } : {}),
+      ...(typeof value.metadata?.enterpriseUrl === 'string' ? { enterpriseUrl: value.metadata.enterpriseUrl } : {}),
+    };
+  }
+  return result;
 }
 
-function listProviderAuths() {
-  const auth = readAuthFile();
-  return Object.keys(auth);
+export async function getProviderAuth(providerId) {
+  return (await readOpenCodeCredentials())[providerId] || null;
 }
 
-export {
-  readAuthFile,
-  writeAuthFile,
-  removeProviderAuth,
-  getProviderAuth,
-  listProviderAuths,
-  AUTH_FILE,
-  OPENCODE_DATA_DIR
-};
+/** Disconnect every saved account for the provider, so deleting active cannot select another. */
+export async function removeProviderAuth(providerId) {
+  if (typeof providerId !== 'string' || !providerId.trim()) throw new Error('Provider ID is required');
+  const client = currentClient();
+  const entries = (await listCredentials(client)).filter((entry) => entry.integrationID === providerId);
+  for (const entry of entries) {
+    try {
+      await client.credential.remove({ credentialID: entry.id }, { signal: AbortSignal.timeout(8000) });
+    } catch {
+      throw new Error('Unable to remove OpenCode credentials; some accounts may already have been removed. Retry to finish disconnecting.');
+    }
+  }
+  return entries.length > 0;
+}

package/server/lib/opencode/auth.test.js

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { configureOpenCodeCredentials, getProviderAuth, readOpenCodeCredentials, removeProviderAuth, openCodeCredentialSource } from './auth.js';
+
+const key = (id, active, value = id) => ({ id, integrationID: 'openai', label: id, active, value: { type: 'key', key: value } });
+afterEach(() => { configureOpenCodeCredentials(null); vi.unstubAllGlobals(); });
+
+describe('authoritative host credential API', () => {
+  it('observes active account switching and logout without cached or legacy fallback', async () => {
+    let entries = [key('old', true), key('new', false)];
+    configureOpenCodeCredentials(() => ({ credential: { list: async () => entries } }));
+    await expect(getProviderAuth('openai')).resolves.toEqual({ type: 'api', key: 'old' });
+    entries = [key('old', false), key('new', true)];
+    await expect(getProviderAuth('openai')).resolves.toEqual({ type: 'api', key: 'new' });
+    entries = [];
+    await expect(getProviderAuth('openai')).resolves.toBeNull();
+  });
+  it('maps OAuth metadata without copying arbitrary secret-bearing fields', async () => {
+    configureOpenCodeCredentials(() => ({ credential: { list: async () => [{ ...key('a', true), value: { type: 'oauth', access: 'access', refresh: 'refresh', expires: 123, metadata: { accountID: 'account', enterpriseUrl: 'https://example.com', unrelated: 'private' } } }] } }));
+    await expect(readOpenCodeCredentials()).resolves.toEqual({ openai: { type: 'oauth', access: 'access', refresh: 'refresh', expires: 123, accountId: 'account', enterpriseUrl: 'https://example.com' } });
+  });
+  it.each([null, {}, { data: [] }, [{ ...key('a', true), value: { type: 'unknown' } }], [key('a', true), key('b', true)]])('rejects unsupported payloads without inventing empty success', async (entries) => {
+    configureOpenCodeCredentials(() => ({ credential: { list: async () => entries } }));
+    await expect(readOpenCodeCredentials()).rejects.toThrow('Unable to read OpenCode credentials');
+  });
+  it('redacts transport/auth failures and leaves them retryable', async () => {
+    const list = vi.fn().mockRejectedValueOnce(new Error('Authorization: private-token')).mockResolvedValueOnce([]);
+    configureOpenCodeCredentials(() => ({ credential: { list } }));
+    await expect(readOpenCodeCredentials()).rejects.toThrow(/^Unable to read OpenCode credentials$/);
+    await expect(readOpenCodeCredentials()).resolves.toEqual({});
+  });
+  it('removes all provider accounts, preserves other integrations and supports retry after partial failure', async () => {
+    let entries = [key('old', false), key('new', true), { ...key('other', true), integrationID: 'anthropic' }];
+    const remove = vi.fn(async ({ credentialID }) => { entries = entries.filter((e) => e.id !== credentialID); });
+    configureOpenCodeCredentials(() => ({ credential: { list: async () => entries, remove } }));
+    remove.mockImplementationOnce(async ({ credentialID }) => { entries = entries.filter((e) => e.id !== credentialID); });
+    remove.mockRejectedValueOnce(new Error('private-token'));
+    await expect(removeProviderAuth('openai')).rejects.toThrow('some accounts may already have been removed');
+    await expect(removeProviderAuth('openai')).resolves.toBe(true);
+    expect(entries.map((e) => e.id)).toEqual(['other']);
+    await expect(removeProviderAuth('openai')).resolves.toBe(false);
+  });
+  it('uses the current endpoint/auth through the real SDK for every read', async () => {
+    let origin = 'http://first.invalid';
+    let authorization = 'Basic first';
+    const requests = [];
+    vi.stubGlobal('fetch', vi.fn(async (input, init) => {
+      const req = new Request(input, init);
+      requests.push([req.url, req.headers.get('authorization')]);
+      return Response.json({ data: [key('current', true)] });
+    }));
+    configureOpenCodeCredentials(openCodeCredentialSource({ buildOpenCodeUrl: () => origin, getOpenCodeAuthHeaders: () => ({ Authorization: authorization }) }));
+    await readOpenCodeCredentials();
+    origin = 'http://second.invalid'; authorization = 'Basic second';
+    await readOpenCodeCredentials();
+    expect(requests).toEqual([['http://first.invalid/api/credential', 'Basic first'], ['http://second.invalid/api/credential', 'Basic second']]);
+  });
+});

package/server/lib/opencode/commands.js

@@ -114,7 +114,7 @@ function getCommandSources(commandName, workingDirectory) {
   const jsonSource = getJsonEntrySource(layers, 'command', commandName);
   const jsonSection = jsonSource.section;
   const jsonPath = jsonSource.path || layers.paths.customPath || layers.paths.projectPath || layers.paths.userPath;
-  const jsonScope = jsonSource.path === layers.paths.projectPath ? COMMAND_SCOPE.PROJECT : COMMAND_SCOPE.USER;
+  const jsonScope = layers.projectLayers.some((layer) => layer.path === jsonSource.path) ? COMMAND_SCOPE.PROJECT : COMMAND_SCOPE.USER;
 
   const sources = {
     md: {