Opencode Runtime

OpenCode runtime alignment

Keep Palot's declared OpenCode dependencies aligned without replacing the user's running service. Stable is the default; use Beta when requested. A release check is read-only. A dependency upgrade authorizes workspace changes, not a global CLI update, service restart, app installation or publication.

Use opencode for upstream API and architecture questions. Read ../../../docs/opencode-runtime.md for Palot's current runtime-selection and compatibility contract. Public desktop packages acquire OpenCode separately; they do not bundle its standalone executable.

Read-only comparison

1. Establish Palot's baseline from apps/desktop/package.json, bun.lock and SUPPORTED_OPENCODE_VERSION in apps/desktop/src/main/opencode-version.ts. Distinguish these from the installed CLI and connected service versions.

2. Check npm tags for all four published units:

   npm view @opencode/cli dist-tags --json
   npm view @opencode/client dist-tags --json
   npm view @opencode/protocol dist-tags --json
   npm view @opencode/schema dist-tags --json
   

   A candidate is aligned only when the selected tags resolve to the same exact version. Verify that latest is a supported stable major; the tag alone is not a compatibility guarantee. Use that exact version for subsequent reads, and report tag skew instead of mixing releases.

3. If the question concerns the setup/settings channel selector, also check the official opencode.ai/update/api/{latest|beta}/cli/opencode feeds. These can differ from npm tags. Report each source separately; do not substitute one channel mechanism for another.

4. Read publication dates, release notes and published package dependencies/types. For a routine stable patch, inspect the changed contracts and relevant Palot callers. Identical contracts need no integration audit. Escalate to a deeper source comparison for a new minor/major, changed public surface, unreviewed beta, ambiguous release notes or a requested feature's availability.

5. Report the checked date, baseline/candidate, important inherited fixes versus changes needing Palot work, evidence gaps and a recommendation. Do not install packages, execute downloaded binaries or call APIs that can start a service as part of a read-only check.

For a deeper comparison, map both exact published builds to upstream source. Use release tags or publish-run inputs; numbered betas map to publish workflow run_number, not the run database ID or nearest timestamp. Do not infer a source branch from a channel name. Paginate commit comparisons and state any incomplete retrieval. Source explains intent; the published package establishes availability. Use opencode-coverage only when operation/event adoption needs an audit.

Authorized dependency update

1. Select an aligned exact version. Inspect relevant exports, request/response types and event unions before changing Palot callers. Stable 2.x compatibility is the existing product policy, not a reason to skip checking upstream changes.

2. Update directly imported client/protocol packages with the pinned toolchain:

   # Run with apps/desktop as the working directory; VERSION is the exact selection.
   vp add -D -E "@opencode/client@$VERSION" "@opencode/protocol@$VERSION"
   

   Let Vite+ and Bun update the lockfile. Schema stays transitive unless Palot starts importing it. Keep exact pins. Do not add the legacy @opencode-ai/sdk.

3. Align SUPPORTED_OPENCODE_VERSION and current runtime defaults, fixtures and verification metadata. Search for the old version and review each match; preserve reviewed-beta compatibility and historical evidence. Inspect retained runtime manifests, source/notice declarations and hash checks before changing them. An external-package policy is not permission to leave a used exact-version verifier stale, nor a reason to reintroduce bundled binaries.

4. Verify actual desktop module resolution for client/protocol, and schema from the client's context, against the lockfile. Bun can leave obsolete nested packages shadowing root packages. If proven, move only those obsolete entries into a unique primary-checkout .local/ backup and recheck. Don't delete the whole dependency tree as a first response.

5. Force the desktop TypeScript build after dependency changes:

   bun run --cwd apps/desktop typecheck --force
   

   Format/lint touched files and run affected contract/service tests. Use ../../../docs/agent-development.md to select native E2E or packaging checks. API-adoption changes may need a feature-specific runtime gate. Do not raise a blanket connection minimum just because a newer package adds an API.

If a used verifier needs new executable hashes, obtain the exact architecture's official archive, verify registry integrity, then hash the original bytes. Follow the current verifier's signature contract; do not blindly ad-hoc sign an upstream signed executable. Test downloaded runtimes only in an owned isolated harness.

Local CLI and service lifecycle

• Prefer the user's existing installation. If a global update was separately authorized, identify the real executable and its package manager first. Update that installation rather than creating another or using a Vite+ global shim.
• Updating an executable and restarting a service are separate actions. Keep a healthy compatible stable 2.x service running; an unreviewed beta requires exact-version consent. Do not replace the task host for dependency validation.
• Palot's official download flow prepares an app-private fallback only after an explicit action. Preparing/resetting it must not start or restart a service.
• With restart authorization, use the existing lifecycle workflow in palot-desktop-dev and verify the resulting service version. Commands such as opencode2 api ... can start a service, so they are not read-only diagnostics.

Completion

An upgrade is complete when the manifest, lockfile, resolved modules and current verification metadata agree, relevant checks pass, and remaining compatibility limits are reported. Distinguish workspace changes from global CLI, running service and installed-app state. Do not claim those were upgraded unless they were separately authorized and verified.