@openchambery/web 2.0.0-beta.26 → 2.0.0-beta.29

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,7 +23,6 @@ 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.
 - `packages/web/server/lib/opencode/shutdown-runtime.js`: graceful shutdown orchestration runtime for watcher/session/terminal/process/server teardown.
@@ -55,13 +54,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.
@@ -89,9 +87,9 @@ This module provides OpenCode server integration utilities for the web server ru
   - `PUT /api/behavior/agents-md`
   - `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. `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.
+  - `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 +128,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 +153,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:
@@ -210,6 +208,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`
@@ -333,7 +332,6 @@ Failures of either required list still return HTTP 502 for the caller to retry.
   - 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
 
@@ -346,6 +344,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()`
@@ -513,16 +512,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: {