@yuriai/web 0.1.4 → 0.1.6

package/dist/mobile.html

@@ -63,7 +63,7 @@
       })();
     </script>
 
-    <script type="module" crossorigin src="/assets/mobile-CfPAWSXr.js"></script>
+    <script type="module" crossorigin src="/assets/mobile-DiL1n1m5.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-hePW80VL.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-auth-ef9W7A43.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-switch-CAZiOV2G.js">
@@ -86,10 +86,10 @@
     <link rel="modulepreload" crossorigin href="/assets/platform-7bX6qtBV.js">
     <link rel="modulepreload" crossorigin href="/assets/terminalApi-BHXvha-U.js">
     <link rel="modulepreload" crossorigin href="/assets/runtime-file-download-DAOam_oV.js">
-    <link rel="modulepreload" crossorigin href="/assets/types-0GGhodUf.js">
-    <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-CnsewE-n.js">
-    <link rel="modulepreload" crossorigin href="/assets/native-config-Cu2rtzKa.js">
-    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-CE0t2CEh.js">
+    <link rel="modulepreload" crossorigin href="/assets/types-DZcrt4Z0.js">
+    <link rel="modulepreload" crossorigin href="/assets/capgoAdapter-ChF9Cg3G.js">
+    <link rel="modulepreload" crossorigin href="/assets/native-config-D9DfX51I.js">
+    <link rel="modulepreload" crossorigin href="/assets/runtimeConfig-MKo97i27.js">
     <link rel="stylesheet" crossorigin href="/assets/src-CmermOKP.css">
   </head>
   <body class="h-full bg-background text-foreground">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuriai/web",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "main": "./server/index.js",

package/server/lib/content-search/DOCUMENTATION.md

@@ -69,7 +69,11 @@ session/message APIs supply the history directly.
 
 Web/desktop and hosted/Capacitor mobile mount the same `OnboardingScreen`
 `content-index` step after connecting. It displays thirty-day progress, preserves
-progress on request failure, and closes when verification succeeds. Continuing
+progress on request failure, and closes when verification succeeds. The dialog
+waits for a nonzero session total: pending catalog discovery and a successfully
+empty fresh installation never flash onboarding. The status check continues
+while the total is unknown/zero, so subsequently discovered history still opens
+the step; hiding it does not certify coverage or cancel Host indexing. Continuing
 in the background dismisses only this startup/runtime's UI, never writes a
 completion marker and never cancels Host work. Polling stops after completion or
 dismissal; runtime changes recheck. Older Hosts without the new status fields

package/server/lib/opencode/DOCUMENTATION.md

@@ -32,8 +32,8 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/v1-migration-gate.js`: pure V1→v2 migration admission gate (`GET /api/experimental/migration/v1` → whether transcript may be fetched).
 - `packages/web/server/lib/opencode/managed-capabilities-runtime.js`: managed-child scheduled-task resources, config injection, rotating bridge identity, and bridge authorization.
 - `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.
-- `packages/web/server/lib/opencode/ensure-cli.js`: detect local `opencode` version and install the pinned official V2 into the Yuri data dir when missing or too old. Never uses a packaged/bundled binary.
-- `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` upgrades the selected shared global CLI in place; other supported local installations use the owned-cache installer. Global upgrades do not persist a binary override, so subsequent launches still follow shell discovery. 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 or package-manager rollback.
+- `packages/web/server/lib/opencode/ensure-cli.js`: detect local `opencode` version and install the latest stable official V2 into the Yuri data dir when no usable CLI exists, falling back to the tested pin if registry lookup fails. Never uses a packaged/bundled binary.
+- `packages/web/server/lib/opencode/upgrade-screen.js`: startup gate for the running OpenCode below `2.0.20`. Client/schema dependencies and the required-upgrade target are pinned to `2.0.23`; fresh automatic installations resolve latest stable 2.x. 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` upgrades the selected shared global CLI in place; other supported local installations use the owned-cache installer. Global upgrades do not persist a binary override, so subsequent launches still follow shell discovery. 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 or package-manager rollback.
 - `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/Yuri route wiring.
@@ -167,9 +167,10 @@ This module provides OpenCode server integration utilities for the web server ru
 - `buildUpgradeStatusSnapshot` / `evaluateOwnedUpgradeResult` / `createUpgradeOperationState` / `resolveOwnedCacheBinaryPath`.
 
 ## Public exports (ensure-cli.js)
-- `ensurePinnedOpenCode2Cli({ discoveredPath, pin, autoInstall, install, readVersion })`: reuse any discovered acceptable 2.x CLI (official name `opencode`). Install the pin into `~/.config/yuri/opencode-cli/<pin>/opencode` only when nothing usable is installed. `YURI_OPENCODE2_AUTO_INSTALL=0` disables download (`OPENCODE_CLI_MISSING`).
+- `ensurePinnedOpenCode2Cli({ discoveredPath, pin, autoInstall, install, readVersion })`: reuse any discovered acceptable 2.x CLI (official name `opencode`), then the newest verified owned cache. Only a fresh installation queries the stable 2.x release via `update-discovery.js`; an explicit pin or failed registry lookup uses the tested pin. Downloads stay under `~/.config/yuri/opencode-cli/<version>/opencode`. `YURI_OPENCODE2_AUTO_INSTALL=0` disables download (`OPENCODE_CLI_MISSING`).
 - `installPinnedOpenCode2Cli(options)`: download `@opencode/cli-<os>-<arch>@pin`, extract, copy as `opencode`, chmod, verify `--version`.
-- `installedOpenCode2BinaryPath(version)` / `readOpenCode2BinaryVersion(path)` / `isOpenCode2AutoInstallEnabled()`.
+- `installedOpenCode2BinaryPath(version)` / `installedOpenCode2BinaryCandidates(options)` / `readOpenCode2BinaryVersion(path)` / `isOpenCode2AutoInstallEnabled()`. Cache candidates are stable 2.x directories ordered by numeric version, so an offline restart discovers a newer installation rather than reverting to the packaged pin.
+- `terminal-path.js` exposes owned-cache CLIs to new terminals on installation/reuse. It writes an idempotent source line to zsh `.zprofile`/`.zshrc` (including `ZDOTDIR`), bash `.bashrc` and the active login profile, POSIX `.profile`, or fish `config.fish`. The sourced file in the Yuri data directory selects the verified executable directory. Windows updates only user PATH, retaining unrelated entries, broadcasts the environment change, and records `opencode-path.windows` in the data directory. Subsequent owned-cache upgrades refresh an existing terminal integration after binary verification. Existing global installations do not trigger shell edits. PATH-setup failure warns and keeps the working Yuri runtime; a later startup retries. Existing terminal processes need a new shell, and shell-file changes already completed before a failure are retained.
 - `upgradeSelectedOpenCodeCli({ binaryPath, version, launchSpec, env })`: runs the selected CLI's official `upgrade <version>` without a shell, with a five-minute deadline and bounded captured output. Returns the original CLI entry path, preserving Homebrew symlinks. Windows launch specs unwrap native/runtime shims; unresolved batch wrappers require terminal upgrade instead of spawning console grandchildren. Child output is not returned or logged. Package-manager failures never fall back to another installation; callers verify the original entry's version before restarting. Package-manager file changes cannot be rolled back by restoring Yuri's binary selection.
 
 ## Public exports (v1-migration-gate.js)
@@ -179,7 +180,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 is one internal probe — health, then V1 migration, then contract publish — under one abort timer that covers **both** fetches so a hung migration cannot outrun the per-attempt budget. `waitForOpenCodeReady` only loops that probe until its deadline; `retryOpenCodeStartup` calls the same probe with a fresh generation, ownership, and shutdown scope. 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 Yuri `/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 official V2 through the fresh-install policy above when no usable CLI exists (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 is one internal probe — health, then V1 migration, then contract publish — under one abort timer that covers **both** fetches so a hung migration cannot outrun the per-attempt budget. `waitForOpenCodeReady` only loops that probe until its deadline; `retryOpenCodeStartup` calls the same probe with a fresh generation, ownership, and shutdown scope. 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 Yuri `/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 Yuri 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:
@@ -212,7 +213,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `remote-upgrade.integration.test.js` is opt-in via `YURI_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)`: owns CLI environment and binary discovery state. Discovery order: settings/env, then interactive login-shell PATH `opencode` on macOS/Linux (host PATH if the shell snapshot is unavailable; Windows uses its hydrated host PATH), then known install locations, then a previously installed pin. Shell PATH order is authoritative for automatic discovery even if later host/runtime PATH augmentation prefers another installation. Shell aliases/functions are not executable PATH entries. Automatic discovery and bundled resources use only `opencode` (`opencode.exe` on Windows); 1.x binaries are skipped by version. Managed startup installs the pin only when no usable 2.x CLI exists; a usable bundled CLI is the last resort if installation fails. `upgradeOpenCodeCli({ binaryPath, version })` supplies the selected launch spec and shell PATH to the official CLI upgrader. Explicit settings/environment overrides retain precedence.
+- `createOpenCodeEnvRuntime(dependencies)`: owns CLI environment and binary discovery state. Discovery order: settings/env, then interactive login-shell PATH `opencode` on macOS/Linux (host PATH if the shell snapshot is unavailable; Windows uses its hydrated host PATH), then known install locations, then the newest installed stable 2.x cache. Shell PATH order is authoritative for automatic discovery even if later host/runtime PATH augmentation prefers another installation. Shell aliases/functions are not executable PATH entries. Automatic discovery and bundled resources use only `opencode` (`opencode.exe` on Windows); 1.x binaries are skipped by version. Managed startup installs through the fresh-install policy above only when no usable 2.x CLI exists; a usable bundled CLI is the last resort if installation fails. `upgradeOpenCodeCli({ binaryPath, version })` supplies the selected launch spec and shell PATH to the official CLI upgrader. Explicit settings/environment overrides retain precedence.
 - VS Code keeps a copied sidecar (`packages/vscode/src/opencode-sidecar.ts`) with the same invariants: discovery order may differ (no Electron bundled fallback), but reject list, listening lines, health path order (`/api/health` then `/global/health`), `{ healthy: true }`, and Basic username `opencode` must stay aligned. Changing one copy requires changing the other.
 - Returned API:
   - `applyLoginShellEnvSnapshot()`
@@ -378,7 +379,7 @@ Unrelated upstream failures are not retried.
   - Provider catalog responses include only provider `id`, `name`, and safe models. Safe models include `id`, `name`, fixed text/audio/image/video/pdf capability modalities, bounded cost/limit fields, `release_date`, and variant names with `{}` values. v2 `ModelInfo.variants` is an array of `{ id, settings?, headers?, body? }`; projection keeps ids in array order as empty-object keys and drops request payloads. v2 `capabilities.tools` maps to `toolcall`, and `input`/`output` modality name arrays map to boolean maps. v2 `cost` tier arrays keep the untiered base price. Identifiers are bounded to 512 characters, display names to 1024, release dates to 64, numeric values to absolute 1e9, and catalog collections to 200 providers, 500 models per provider, and 100 defaults or variants. Provider credentials/configuration and unallowlisted model fields stay server-side. Malformed catalog roots and SDK error envelopes return HTTP 502. `partial: true` is structural only: provider/model/default truncation, dropped providers/models/defaults, or truncated variant dictionaries. Soft allowlist stripping of optional metadata (unknown modalities, non-boolean capability flags, out-of-range cost/limit numbers, empty/null/invalid `release_date`, invalid variant ids) keeps valid models and must not set `partial: true`, or UI refresh retains a stale complete snapshot after OpenCode provider updates. The same input shapes are accepted by the VS Code projector and `packages/ui/src/lib/configCatalogParser.ts`.
   - Agents: `/api/config/agents/:name` and `/api/config/agents/:name/config`. A `native` create or update writes only the fields in that object into the selected user or project markdown file. `scope` chooses the file. `confirmDrop` removes fields the current format cannot represent; every other field already in the file stays unchanged.
   - Commands: batched metadata via `POST /api/config/commands/metadata`; `{ catalog: true }` returns the compact autocomplete catalog without templates, plus CRUD at `/api/config/commands/:name`
-  - Global raw configs: `GET /api/config/global` discovers existing config targets; `GET/PUT /api/config/global/:target` reads and writes `opencode`, `oh-my-opencode-slim`, and `oh-my-openagent` JSON or JSONC files
+  - Global raw configs: `GET /api/config/global` always offers OpenCode and discovers existing plugin targets; `GET/PUT /api/config/global/:target` reads and writes `opencode`, `oh-my-opencode-slim`, and `oh-my-openagent` JSON or JSONC files. Missing OpenCode configuration returns an editable schema template without writing to disk; the first save creates `opencode.jsonc` (or the explicit `OPENCODE_CONFIG` path). Existing JSON/JSONC precedence and comments are preserved.
   - MCP servers: `/api/config/mcp` and `/api/config/mcp/:name`
 
 ### Catalog / Yuri-owned API change checklist

package/server/lib/opencode/config-entity-routes.js

@@ -166,7 +166,7 @@ async function findGlobalConfigPath(target, configDirectory) {
     }
   }
 
-  return null;
+  return target === 'opencode' ? configPath : null;
 }
 
 function validateGlobalConfigContent(content) {
@@ -282,6 +282,10 @@ export const registerConfigEntityRoutes = (app, dependencies) => {
       return res.json({ target: req.params.target, fileName: target.fileName, content });
     } catch (error) {
       if (error?.code === 'ENOENT') {
+        if (req.params.target === 'opencode') {
+          return res.json({ target: 'opencode', fileName: target.fileName,
+            content: '{\n  "$schema": "https://opencode.ai/config.json"\n}\n' });
+        }
         return res.status(404).json({ error: `${target.fileName} does not exist` });
       }
       console.error('Failed to read global configuration:', error);

package/server/lib/opencode/config-entity-routes.test.js

@@ -495,6 +495,29 @@ describe('config entity agent metadata route', () => {
 describe('global raw configuration routes', () => {
   beforeEach(() => vi.stubEnv('OPENCODE_CONFIG', ''));
   afterEach(() => vi.unstubAllEnvs());
+  it('offers an editable JSONC template on a fresh machine and creates it only on save', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'yuri-global-config-'));
+    const configDirectory = path.join(root, 'opencode');
+    const app = express();
+    app.use(express.json());
+    registerConfigEntityRoutes(app, createDependencies(vi.fn(), configDirectory));
+    try {
+      const available = await request(app).get('/api/config/global').expect(200);
+      expect(available.body.targets).toEqual([{ target: 'opencode', fileName: 'opencode.jsonc' }]);
+      const template = await request(app).get('/api/config/global/opencode').expect(200);
+      expect(JSON.parse(template.body.content)).toEqual({ $schema: 'https://opencode.ai/config.json' });
+      await expect(fs.stat(configDirectory)).rejects.toMatchObject({ code: 'ENOENT' });
+      const content = '{\n  // first configuration\n  "model": "provider/model"\n}\n';
+      await request(app).put('/api/config/global/opencode').send({ content }).expect(200);
+      expect(await fs.readFile(path.join(configDirectory, 'opencode.jsonc'), 'utf8')).toBe(content);
+      const loaded = await request(app).get('/api/config/global/opencode').expect(200);
+      expect(loaded.body.content).toBe(content);
+      await request(app).get('/api/config/global/oh-my-openagent').expect(404);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
   it('reads and validates the configured OpenCode and oh-my-opencode files', async () => {
     const app = express();
     app.use(express.json());

package/server/lib/opencode/ensure-cli.js

@@ -2,8 +2,11 @@ import { execFile, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { createOpenCodeUpdateDiscovery } from './update-discovery.js';
+import { configureOpenCodeTerminalPath } from './terminal-path.js';
 import {
   PINNED_OPENCODE2_VERSION,
+  compareOpenCode2Versions,
   isAcceptableOpenCode2HealthVersion,
   isOpenCode2VersionAtLeast,
   npmPackageForOpenCode2,
@@ -12,6 +15,7 @@ import {
 } from './opencode2-pin.js';
 
 const INSTALL_FETCH_TIMEOUT_MS = 30_000;
+const discoverLatestVersion = createOpenCodeUpdateDiscovery();
 
 export async function upgradeSelectedOpenCodeCli({ binaryPath, version, launchSpec, env = process.env, execFileImpl = execFile }) {
   if (launchSpec?.wrapperType === 'cmd-wrapper') {
@@ -55,6 +59,15 @@ export function installedOpenCode2BinaryPath(version = PINNED_OPENCODE2_VERSION,
   return path.join(dataDir, 'opencode-cli', version, openCodeBinaryName(options.platform));
 }
 
+export function installedOpenCode2BinaryCandidates(options = {}) {
+  const root = path.dirname(path.dirname(installedOpenCode2BinaryPath(undefined, options)));
+  let versions;
+  try { versions = fs.readdirSync(root).filter((name) => /^2\.\d+\.\d+$/.test(name)); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return versions.sort((a, b) => compareOpenCode2Versions(b, a))
+    .map((version) => installedOpenCode2BinaryPath(version, options));
+}
+
 export function readOpenCode2BinaryVersion(binaryPath, options = {}) {
   if (typeof binaryPath !== 'string' || !binaryPath.trim()) return '';
   const run = typeof options.spawnSync === 'function' ? options.spawnSync : spawnSync;
@@ -217,12 +230,16 @@ export async function installPinnedOpenCode2Cli(options = {}) {
   if (preparedVersion !== version) {
     throw new Error(`Installed opencode2 version mismatch: expected ${version}, got ${preparedVersion || 'unknown'}`);
   }
+  if (['opencode-path.sh', 'opencode-path.fish', 'opencode-path.windows'].some((name) => fs.existsSync(path.join(dataDir, name)))) {
+    try { configureOpenCodeTerminalPath(outputBinary, { ...options, dataDir }); }
+    catch (error) { console.warn('[OpenCode] Terminal PATH refresh failed:', error.message); }
+  }
   return outputBinary;
 }
 
 /**
- * Reuse any discovered acceptable 2.x CLI. Install the pin only when nothing
- * usable is already installed (global PATH, explicit override, or cache).
+ * Reuse any discovered acceptable 2.x CLI. Fresh installs resolve stable 2.x;
+ * an explicit pin or an unavailable registry uses the tested version instead.
  */
 export async function ensurePinnedOpenCode2Cli(input = {}) {
   const pin = input.pin || PINNED_OPENCODE2_VERSION;
@@ -232,18 +249,29 @@ export async function ensurePinnedOpenCode2Cli(input = {}) {
     ? input.readVersion
     : (binaryPath) => readOpenCode2BinaryVersion(binaryPath, input);
   const install = typeof input.install === 'function' ? input.install : installPinnedOpenCode2Cli;
+  const finish = (result) => {
+    const root = path.dirname(path.dirname(installedOpenCode2BinaryPath(pin, input)));
+    const relative = path.relative(root, result.path);
+    if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+      try { configureOpenCodeTerminalPath(result.path, input); }
+      catch (error) { console.warn('[OpenCode] CLI is available in Yuri, but terminal PATH setup failed:', error.message); }
+    }
+    return result;
+  };
 
   if (discoveredPath) {
     const version = readVersion(discoveredPath);
     if (isAcceptableOpenCode2HealthVersion(version)) {
-      return { path: discoveredPath, version, source: 'discovered', installed: false };
+      return finish({ path: discoveredPath, version, source: 'discovered', installed: false });
     }
   }
 
-  const cached = installedOpenCode2BinaryPath(pin, input);
-  const cachedVersion = readVersion(cached);
-  if (cachedVersion === pin || isOpenCode2VersionAtLeast(cachedVersion, pin)) {
-    return { path: cached, version: cachedVersion, source: 'installed', installed: false };
+  const candidates = [...new Set([...installedOpenCode2BinaryCandidates(input), installedOpenCode2BinaryPath(pin, input)])];
+  for (const cached of candidates) {
+    const cachedVersion = readVersion(cached);
+    if (isOpenCode2VersionAtLeast(cachedVersion, pin)) {
+      return finish({ path: cached, version: cachedVersion, source: 'installed', installed: false });
+    }
   }
 
   if (!autoInstall) {
@@ -254,10 +282,19 @@ export async function ensurePinnedOpenCode2Cli(input = {}) {
     throw error;
   }
 
-  const installedPath = await install({ ...input, version: pin });
+  let target = pin;
+  if (!input.pin) {
+    try {
+      const latest = await (input.resolveLatestVersion || discoverLatestVersion)();
+      if (/^2\.\d+\.\d+$/.test(latest) && isOpenCode2VersionAtLeast(latest, pin)) target = latest;
+    } catch {
+      console.warn('[OpenCode] Latest version lookup failed; using the tested fallback version.');
+    }
+  }
+  const installedPath = await install({ ...input, version: target });
   const version = readVersion(installedPath);
-  if (version !== pin) {
-    throw new Error(`Installed OpenCode version mismatch: expected ${pin}, got ${version || 'unknown'}`);
+  if (version !== target) {
+    throw new Error(`Installed OpenCode version mismatch: expected ${target}, got ${version || 'unknown'}`);
   }
-  return { path: installedPath, version, source: 'installed', installed: true };
+  return finish({ path: installedPath, version, source: 'installed', installed: true });
 }

package/server/lib/opencode/ensure-cli.test.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { PINNED_OPENCODE2_VERSION } from './opencode2-pin.js';
+import { configureOpenCodeTerminalPath } from './terminal-path.js';
 import {
   ensurePinnedOpenCode2Cli,
   installedOpenCode2BinaryPath,
@@ -11,6 +12,8 @@ import {
   upgradeSelectedOpenCodeCli,
 } from './ensure-cli.js';
 
+vi.mock('./terminal-path.js', () => ({ configureOpenCodeTerminalPath: vi.fn() }));
+
 const tempDirs = [];
 
 const createTempDir = (prefix) => {
@@ -20,12 +23,60 @@ const createTempDir = (prefix) => {
 };
 
 afterEach(() => {
+  vi.clearAllMocks();
   for (const dir of tempDirs.splice(0)) {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
 
 describe('ensurePinnedOpenCode2Cli', () => {
+  it('resolves the latest stable 2.x for a fresh installation', async () => {
+    const dataDir = createTempDir('yuri-latest-cli-');
+    const installed = path.join(dataDir, 'opencode-cli', '2.9.1', 'opencode');
+    const install = vi.fn(async () => installed);
+    const result = await ensurePinnedOpenCode2Cli({ dataDir,
+      resolveLatestVersion: async () => '2.9.1', install,
+      readVersion: (file) => file === installed ? '2.9.1' : '',
+    });
+    expect(install).toHaveBeenCalledWith(expect.objectContaining({ version: '2.9.1' }));
+    expect(result.version).toBe('2.9.1');
+    expect(configureOpenCodeTerminalPath).toHaveBeenCalledWith(installed, expect.objectContaining({ dataDir }));
+  });
+
+  it.each(['1.18.4', '3.0.0', '2.9.1-beta.1', '2.0.1'])('never chooses an unsuitable fresh-install target %s', async (latest) => {
+    const install = vi.fn(async () => '/installed/opencode');
+    await ensurePinnedOpenCode2Cli({ dataDir: createTempDir('yuri-invalid-cli-'), install,
+      resolveLatestVersion: async () => latest,
+      readVersion: (file) => file === '/installed/opencode' ? PINNED_OPENCODE2_VERSION : '',
+    });
+    expect(install).toHaveBeenCalledWith(expect.objectContaining({ version: PINNED_OPENCODE2_VERSION }));
+  });
+
+  it('reuses the newest verified cache offline instead of reinstalling the pin', async () => {
+    const dataDir = createTempDir('yuri-new-cache-');
+    for (const version of [PINNED_OPENCODE2_VERSION, '2.9.1', '2.10.0']) {
+      fs.mkdirSync(path.join(dataDir, 'opencode-cli', version), { recursive: true });
+    }
+    const latest = installedOpenCode2BinaryPath('2.10.0', { dataDir });
+    const resolveLatestVersion = vi.fn();
+    const result = await ensurePinnedOpenCode2Cli({ dataDir, resolveLatestVersion,
+      readVersion: (file) => path.basename(path.dirname(file)),
+      install: async () => { throw new Error('must not install'); },
+    });
+    expect(result).toMatchObject({ path: latest, version: '2.10.0', installed: false });
+    expect(resolveLatestVersion).not.toHaveBeenCalled();
+  });
+
+  it('uses the tested pin when the registry is unavailable', async () => {
+    const dataDir = createTempDir('yuri-offline-cli-');
+    const install = vi.fn(async () => '/installed/opencode');
+    await ensurePinnedOpenCode2Cli({ dataDir, install,
+      resolveLatestVersion: async () => { throw new Error('offline'); },
+      readVersion: (file) => file === '/installed/opencode' ? PINNED_OPENCODE2_VERSION : '',
+    });
+    expect(install).toHaveBeenCalledWith(expect.objectContaining({ version: PINNED_OPENCODE2_VERSION }));
+  });
+
   it('runs upgrade through the selected launch target and preserves its CLI entry path', async () => {
     const dir = createTempDir('yuri-upgrade-cli-');
     const script = path.join(dir, 'cli.cjs');
@@ -86,6 +137,7 @@ describe('ensurePinnedOpenCode2Cli', () => {
     });
     expect(result.source).toBe('discovered');
     expect(result.path).toBe('/opt/old-opencode');
+    expect(configureOpenCodeTerminalPath).not.toHaveBeenCalled();
   });
 
   it('installs the pin only when no usable 2.x binary is present', async () => {

package/server/lib/opencode/env-runtime.js

@@ -3,8 +3,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { mergePathValues } from './path-utils.js';
-import { PINNED_OPENCODE2_VERSION, isAcceptableOpenCode2HealthVersion, isOpenCode1xVersion } from './opencode2-pin.js';
-import { ensurePinnedOpenCode2Cli, installedOpenCode2BinaryPath, readOpenCode2BinaryVersion, upgradeSelectedOpenCodeCli } from './ensure-cli.js';
+import { isAcceptableOpenCode2HealthVersion, isOpenCode1xVersion } from './opencode2-pin.js';
+import { ensurePinnedOpenCode2Cli, installedOpenCode2BinaryCandidates, readOpenCode2BinaryVersion, upgradeSelectedOpenCodeCli } from './ensure-cli.js';
 
 export const createOpenCodeEnvRuntime = (deps) => {
   const {
@@ -280,12 +280,12 @@ export const createOpenCodeEnvRuntime = (deps) => {
   };
 
   const resolveInstalledOpenCodeCliPath = () => {
-    const installed = installedOpenCode2BinaryPath(PINNED_OPENCODE2_VERSION, {
+    const installed = installedOpenCode2BinaryCandidates({
       env: process.env,
       homedir: resolveHomeDir,
       platform: process.platform,
-    });
-    if (isExecutable(installed) && !isWindowsOpenCodeDesktopAppPath(installed)) {
+    }).find((binary) => isExecutable(binary) && !isWindowsOpenCodeDesktopAppPath(binary));
+    if (installed) {
       clearWslOpencodeResolution();
       state.resolvedOpencodeBinarySource = 'installed';
       return installed;

package/server/lib/opencode/terminal-path.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export function configureOpenCodeTerminalPath(binaryPath, options = {}) {
+  const env = options.env || process.env;
+  const home = typeof options.homedir === 'function' ? options.homedir() : options.homedir || os.homedir();
+  const platform = options.platform || process.platform;
+  const dataDir = options.dataDir || env.YURI_DATA_DIR || path.join(home, '.config', 'yuri');
+  const directory = path.dirname(binaryPath);
+  if (platform === 'win32') {
+    const run = options.spawnSync || spawnSync;
+    const result = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `
+$ErrorActionPreference = 'Stop'
+$root = $env:YURI_CLI_CACHE_ROOT.TrimEnd('\\') + '\\'
+$entries = @([Environment]::GetEnvironmentVariable('Path', 'User') -split ';' | Where-Object { $_ -and -not $_.StartsWith($root, [StringComparison]::OrdinalIgnoreCase) })
+$value = (@($env:YURI_CLI_BIN_DIR) + $entries) -join ';'
+[Environment]::SetEnvironmentVariable('Path', $value, 'User')
+Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class YuriEnvironment { [DllImport("user32.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern IntPtr SendMessageTimeout(IntPtr hWnd, uint msg, UIntPtr wParam, string lParam, uint flags, uint timeout, out UIntPtr result); }'
+$result = [UIntPtr]::Zero
+[void][YuriEnvironment]::SendMessageTimeout([IntPtr]0xffff, 0x1a, [UIntPtr]::Zero, 'Environment', 2, 5000, [ref]$result)
+`], { env: { ...env, YURI_CLI_CACHE_ROOT: path.join(dataDir, 'opencode-cli'), YURI_CLI_BIN_DIR: directory },
+      encoding: 'utf8', timeout: 15_000, windowsHide: true });
+    if (result.status !== 0) throw new Error('Cannot add OpenCode to the Windows user PATH');
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(path.join(dataDir, 'opencode-path.windows'), directory);
+    return;
+  }
+
+  const shell = env.SHELL || (platform === 'darwin' ? '/bin/zsh' : '/bin/sh');
+  const kind = path.basename(shell);
+  const files = [];
+  if (kind === 'zsh') {
+    const run = options.spawnSync || spawnSync;
+    const probe = run(shell, ['-c', 'printf "%s" "${ZDOTDIR:-$HOME}"'], { env: { ...env, HOME: home }, encoding: 'utf8', timeout: 5000 });
+    if (probe.status !== 0 || !path.isAbsolute(probe.stdout || '')) throw new Error('Cannot resolve zsh startup directory');
+    files.push(path.join(probe.stdout, '.zprofile'), path.join(probe.stdout, '.zshrc'));
+  } else if (kind === 'bash') {
+    files.push(path.join(home, '.bashrc'));
+    files.push(['.bash_profile', '.bash_login', '.profile'].map((name) => path.join(home, name)).find((file) => fs.existsSync(file)) || path.join(home, '.profile'));
+  } else if (['sh', 'dash', 'ksh'].includes(kind)) {
+    files.push(path.join(home, '.profile'));
+  } else if (kind === 'fish') {
+    files.push(path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'fish', 'config.fish'));
+  } else {
+    throw new Error(`Cannot configure OpenCode PATH for shell ${kind}`);
+  }
+
+  const quote = kind === 'fish'
+    ? (value) => `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+    : (value) => `'${value.replace(/'/g, "'\\''")}'`;
+  const envFile = path.join(dataDir, kind === 'fish' ? 'opencode-path.fish' : 'opencode-path.sh');
+  const content = kind === 'fish'
+    ? `contains -- ${quote(directory)} $PATH; or set -gx PATH ${quote(directory)} $PATH\n`
+    : `case ":$PATH:" in *${quote(`:${directory}:`)}*) ;; *) export PATH=${quote(directory)}:"$PATH" ;; esac\n`;
+  fs.mkdirSync(path.dirname(envFile), { recursive: true });
+  fs.writeFileSync(`${envFile}.tmp`, content, { mode: 0o600 });
+  fs.renameSync(`${envFile}.tmp`, envFile);
+  const line = `${kind === 'fish' ? 'source' : '.'} ${quote(envFile)} # Yuri OpenCode CLI PATH`;
+  for (const file of files) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let existing = '';
+    try { existing = fs.readFileSync(file, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (!existing.split('\n').includes(line)) fs.appendFileSync(file, `\n${line}\n`);
+  }
+}

package/server/lib/opencode/terminal-path.test.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { afterEach, expect, test, vi } from 'vitest';
+import { ensurePinnedOpenCode2Cli, installPinnedOpenCode2Cli } from './ensure-cli.js';
+import { configureOpenCodeTerminalPath } from './terminal-path.js';
+
+const roots = [];
+afterEach(() => { for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true }); });
+
+test.each(['/bin/bash', '/bin/zsh'].filter((shell) => fs.existsSync(shell)))('fresh installation is available in %s, preserves rc content and is idempotent', async (shell) => {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "yuri cli's "));
+  roots.push(home);
+  const dataDir = path.join(home, '.config', 'yuri');
+  const binary = path.join(dataDir, 'opencode-cli', '2.9.1', 'opencode');
+  const zdotdir = path.join(home, 'zsh');
+  fs.mkdirSync(zdotdir);
+  const rc = shell.endsWith('zsh') ? path.join(zdotdir, '.zshrc') : path.join(home, '.bashrc');
+  fs.writeFileSync(rc, '# user configuration\n');
+  const options = { pin: '2.9.1', dataDir, homedir: () => home,
+    env: { HOME: home, ZDOTDIR: zdotdir, SHELL: shell, PATH: '/usr/bin:/bin' },
+    install: vi.fn(async () => {
+      fs.mkdirSync(path.dirname(binary), { recursive: true });
+      fs.writeFileSync(binary, '#!/bin/sh\nprintf "2.9.1\\n"\n', { mode: 0o755 });
+      return binary;
+    }),
+  };
+  await ensurePinnedOpenCode2Cli(options);
+  const first = fs.readFileSync(rc, 'utf8');
+  expect(first).toContain('# user configuration\n');
+  const result = spawnSync(shell, ['-ic', 'opencode --version'], {
+    env: options.env, encoding: 'utf8', timeout: 5000,
+  });
+  expect(result.status, result.stderr).toBe(0);
+  expect(result.stdout.trim()).toBe('2.9.1');
+  await ensurePinnedOpenCode2Cli(options);
+  expect(fs.readFileSync(rc, 'utf8')).toBe(first);
+  expect(options.install).toHaveBeenCalledTimes(1);
+
+  await installPinnedOpenCode2Cli({ ...options, version: '2.10.0',
+    fetch: async (url) => String(url).endsWith('/2.10.0')
+      ? Response.json({ dist: { tarball: 'https://example.com/cli.tgz' } }) : new Response('fixture'),
+    extract: async (_archive, target) => {
+      fs.mkdirSync(target, { recursive: true });
+      fs.writeFileSync(path.join(target, 'opencode'), '#!/bin/sh\nprintf "2.10.0\\n"\n');
+    },
+  });
+  const upgraded = spawnSync(shell, ['-ic', 'opencode --version'], { env: options.env, encoding: 'utf8', timeout: 5000 });
+  expect(upgraded.status, upgraded.stderr).toBe(0);
+  expect(upgraded.stdout.trim()).toBe('2.10.0');
+  expect(fs.readFileSync(rc, 'utf8')).toBe(first);
+});
+
+test('Windows updates only user PATH using a hidden first-level process and reports failure', () => {
+  const spawn = vi.fn(() => ({ status: 0 }));
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'yuri-win-path-'));
+  roots.push(dataDir);
+  const binary = path.join(dataDir, 'opencode-cli', '2.9.1', 'opencode.exe');
+  const options = { platform: 'win32', dataDir, homedir: dataDir, spawnSync: spawn, env: {} };
+  configureOpenCodeTerminalPath(binary, options);
+  expect(spawn).toHaveBeenCalledWith('powershell.exe', expect.arrayContaining(['-NoProfile', '-NonInteractive']), expect.objectContaining({
+    windowsHide: true, env: expect.objectContaining({ YURI_CLI_BIN_DIR: path.dirname(binary) }),
+  }));
+  expect(spawn.mock.calls[0][1].at(-1)).toContain("GetEnvironmentVariable('Path', 'User')");
+  spawn.mockReturnValue({ status: 1 });
+  expect(() => configureOpenCodeTerminalPath(binary, options)).toThrow('Windows user PATH');
+});