Use OpenCode 2.3.2 as the minimum and recommendation. Mission calendars use native Automations and retain migrated calendar and wake identities. Isolated Windows tests verified automatic cold restart through archival for a migrated one-shot and a recurrent Mission, each with one successful passage and no duplicate start. New calendars also passed one-shot settlement and carrier cleanup. Minimum/latest CI remains required.
32 KiB
OpenCode runtime setup and admission
Minimum and recommendation: packages/server/src/opencode/runtime-support.ts;
pins: the server, UI and pruning package.json; rationale and qualification:
OPENCODE_COMPATIBILITY.md. Source changes
never upgrade or restart a user's service.
Admission
0.0.0-beta-*labels and versions below the minimum are refused with HTTP 426 and a concrete reason (runtime-support.ts). Unlisted, future-major, custom and prerelease labels are unverified and admitted after authenticated bounded API recognition.- Admission uses authenticated daemon metadata, never the selected discovery CLI's version, and precedes functional requests and plugin provisioning; replacement daemons are rechecked even at the same URL. Client/plugin pins are separate from admission.
- Recognition checks canonical session/permission/Form/inbox shapes and the
required
PUT /api/session/{sessionID}/environment; missing APIs are reported separately from an untested version. Optional configuration reload follows its own route presence. Never probe support with a write.
Scheduled Missions additionally require the consumed Automation contract and an enabled
effective native experimental.automations flag in the acquired Location. Play/Resume
prepare project-only activation automatically, preserving every discovered explicit
OFF and native environment OFF. An already enabled Location receives a ready proof
without configuration writes. Native flag resolution, targeted activation and exact
read-back are described in Missions and
native contracts.
Missing APIs, explicit OFF, a masking block, failed activation or missing exact
calendar registration keep the schedule paused or in an explained error state.
Play of a Mission without launch criteria follows its own admission path.
Setup and recovery
Global log snapshots
GET /api/opencode/logs resolves the configured OpenCode executable server-side,
runs its read-only debug paths log command, and reads the fixed opencode.log
file on that execution host. WSL paths use the existing native-to-host translator.
The route accepts no path or executable selectors, returns Cache-Control: no-store,
and fences an executable change while reading. A snapshot contains at most the
last 128 KiB, aligned after the first partial line, with an explicit truncation
flag. Missing files and discovery/read failures return fixed error codes.
Settings → OpenCode opens the snapshot on demand in the common floating output
window; Refresh requests a new snapshot. Logs may contain private data. Native
experimental.session.stats provides aggregates and experimental.session.log
provides durable session events; diagnostic log-file access uses the selected
CLI's documented global log directory.
Setup surfaces
Startup recovery and Preferences share OpenCodeSetupPanel and its store, but
missing installations, known incompatibility and optional updates expose
different actions; installed/running/minimum/recommended versions and
incompatibility reasons appear with retry and executable selection. Dismissal
leaves a recovery entry; optional updates never force the dialog. Connection
changes, foreground entry and unsupported proxy responses refresh state; stale
responses cannot overwrite a changed executable or completed action. Only a
pending folder open may resume; prompts are never replayed.
Automatic selection follows PATH order (opencode2, then opencode within
each directory), then the conventional user npm installation. An explicit
supported executable keeps priority. Setup and binary validation share one
discovery. The selector labels this source “automatic”; Choose another binary…
reveals path entry and browsing.
Recovery puts diagnosis and installation before executable selection.
Discovery reads each npm package's published bin map and real launcher target,
choosing opencode when opencode2 is only a bin/*.cjs alias.
Discovery preserves terminal PATH/PATHEXT ordering even when a standalone
executable shares the npm command directory; such an executable remains
user-managed. On POSIX, only the prefix's actual bin directory counts as an
npm command directory. A standalone executable replacing a POSIX npm symlink is
selected in PATH order and remains user-managed; only an actual symlink to
the package's .cjs alias is skipped in favor of the working opencode
command. On Windows, that alias is skipped only when the npm .cmd script
positively invokes the package's .cjs target; a customized .cmd wrapper
keeps PATH priority and the automatic npm updater never overwrites it.
Default host installation uses the backend's npm (Electron resources, beside Tauri's
bundled Node, or beside a standalone server's Node) for a global @opencode/cli installation. Both desktop
hosts bundle the npm release pinned in .npm-version (dev-docs/RUNTIME_MAINTENANCE.md);
a standalone server uses the npm installed with its Node. npm blocks dependency install
scripts unless its allow-scripts policy lists them (the default from npm 12), and the
package's postinstall links the platform executable. CodeNomad's global installation
therefore allows exactly the @opencode/cli@<version> it installs:
--allow-scripts on direct npm, npm_config_allow_scripts (with inherited values
removed) for the npm a native upgrade runs. The platform packages have no install
scripts. Never enable all scripts or write an npmrc for this. Existing writable npm installations on PATH are
reused after verifying their manifest and launcher identity; standalone/curl,
Homebrew and custom installations remain user-managed. With no PATH installation,
the user prefix is %APPDATA%/npm on Windows and ~/.local on POSIX, or an explicit
absolute NPM_CONFIG_PREFIX. Existing npm prefixes on PATH are retained. npm
publishes the normal terminal commands; CodeNomad verifies the executable version
and launcher before registering the command directory. Windows registration preserves
the HKCU Path value's type and unexpanded variables and broadcasts the environment
change. Bash, zsh, sh and fish profiles receive idempotent entries. A new terminal
is needed; the backend's own PATH is updated immediately. Remote installation and
PATH changes apply on the server host. No system Node or administrator rights are
needed for the conventional user prefix. Direct npm execution is bounded to five
minutes and 1 MiB output; the native supervisor gets six minutes so native npm's
own five-minute deadline can finish cleanup before outer cancellation.
PATH registration failure leaves the installed package discoverable; retry repairs
PATH without reinstalling or downgrading a newer shared version. Native data under
~/.local/share/opencode belongs to OpenCode.
Older OpenCode installations
OpenCode 1.x (opencode-ai) and 2.x (@opencode/cli) both declare an opencode
bin, and npm refuses (EEXIST) to link one over the other without --force, so
2.x cannot install beside a 1.x shim in the same prefix. The panel offers
"Replace OpenCode 1.x with OpenCode 2", also when 1.x cannot run (e.g. a
placeholder left by a skipped postinstall); confirmation sends the shown command
path and package version, the server refuses a mismatch under the prefix lock,
the backend's npm uninstalls opencode-ai, then the ordinary path installs and
verifies @opencode/cli.
The Windows running-image preflight covers every native file of the package:
bin/ and the nested node_modules/opencode-<os>-<arch>[-variant]/bin/. 1.0.0-1.15.0
declare a Node launcher bin (bin/opencode) that runs the nested platform
package's executable (or a bin/.opencode copy); 1.15.1+ declare bin/opencode.exe,
which postinstall links or copies from the nested package. If npm's uninstall
fails anyway, its symbolic error code (only) classifies the outcome: with the
package still intact, EPERM/EBUSY/EACCES report installation_in_use, other
codes a generic failure stating 1.x is still installed; a package npm already
changed reports legacy_partially_removed with manual npm uninstall -g opencode-ai guidance. A failure after complete removal is reported as
legacy_removed_install_failed; the next attempt is an ordinary installation,
never an automatic replay. CodeNomad leaves the data directory untouched: the
OpenCode 2 server imports 1.x sessions from the same opencode.db at startup
(upstream V1Migration).
For a foreign installation below the minimum or unusable, resolution prefers
the verified side-by-side npm installation (installationSource: "managed");
the UI says the terminal opencode may still start the older version. The user
npm prefix cannot take that installation when a non-npm command already holds
OpenCode's name in its bin directory (on macOS/Linux the prefix is ~/.local,
so a ~/.local/bin/opencode link to a curl installation qualifies, and npm
would refuse to link over it) or when the prefix is not writable. The plan then
reports foreignInstallation.blocked (occupied with that command, or
unwritable with the prefix), installation is not offered, and the panel says
how to clear the obstacle before an explicit Check. winget
portable packages are identified from default locations only:
%LOCALAPPDATA%\Microsoft\WinGet\Links or %ProgramFiles%\WinGet\Links
(symlink, or hardlink/copy fallback), or a target under a default WinGet\Packages
root. The package ID (for example SST.opencode) is shown with an optional manual
winget uninstall hint only when the resolved
<PackageIdentifier>_Microsoft.Winget.Source_8wekyb3d8bbwe directory proves it.
opencode-update/foreign-probe.ts results (5 s deadline) are cached by the
command's file identity (path, mtime and size, plus the executable an npm-style shim launches); any change
reads as unknown until reprobed. A timeout is cached as unknown for 60 s, so a
hanging wrapper reruns at most once a minute while a slow first run (for example
an antivirus scan) is retried later. At most one probe of a command runs at a
time; concurrent readers, including an explicit recheck, join it. The setup
panel's Check action sends recheck=1, which forces a fresh probe even within
that delay; automatic reads never do. Synchronous resolution (workspace launch,
binary validation) only reads the cache and starts a background probe on a miss or an expired unknown; status reads and
installation await the bounded probe first, and the backend warms it at startup.
node --import tsx scripts/test-opencode-legacy-replacement-native.mjs installs the
published opencode-ai (default 1.18.10, CODENOMAD_FIXTURE_LEGACY_VERSION) into
an isolated prefix/cache/home, checks that plain npm installation of
@opencode/cli fails with EEXIST and leaves 1.x in place, checks that a stale
consent is refused and that the native images are found, then performs the
confirmed replacement and verifies the installed 2.x command. It never runs a service.
An exclusive .codenomad-opencode-install.lock in the npm prefix serializes
CodeNomad backends; the version is re-probed under that lock. A competing backend
gets a retryable conflict. A lock left after a crash is never stolen through
time/PID heuristics: npm may outlive its backend. The server log gives the lock
path; remove it only after confirming the installer has exited. The lock covers
CodeNomad backends only. Verified npm installations at 2.0.15 or
later use the installed CLI's upgrade <exact-version> --method npm for version
changes. OpenCode retains Windows running images itself, so this path skips the
write preflight, which would reject a supported live upgrade. A private,
temporary npm command adapter supplies the backend's npm (bundled in Electron's
resources, beside Tauri's bundled Node, or beside a standalone server's own Node)
and pins the verified prefix
and registry, including when the desktop runtime has no npm launcher on PATH. It is
also the command's working directory, preventing cwd from shadowing npm on Windows.
Installer commands live in directories beside the lock inside the npm prefix:
.codenomad-upgrade-* for native upgrade and .codenomad-npm-* for direct npm.
Both supply npm/npx bound to the selected package and runtime, plus Electron's
lifecycle node command. The prefix must allow execution for its
installed commands, unlike a temporary directory that may be mounted noexec, and
npm and the OpenCode command lookup ignore these dot directories.
If the outer supervisor is terminated by timeout, signal or output limit, descendant
exit cannot be established: retain the prefix lock and these installer directories
rather than allowing a competing installation. The server error includes the lock
path; manual recovery must first verify installer processes have exited. The next
backend that acquires a fresh lock removes retained installer directories. Cleanup
never masks the execution error. Native upgrade and direct npm both verify version
and launcher after installation.
node --import tsx scripts/test-opencode-upgrade-native.mjs runs the real
installer against an isolated prefix/home/service: the installed CLI upgrades
while the running daemon keeps its PID and version. CODENOMAD_FIXTURE_NODE
selects a Node executable with npm beside it, such as Tauri's packaged Node; cleanup
uses the isolated CLI only.
The install, upgrade and legacy replacement fixtures also accept
CODENOMAD_FIXTURE_ELECTRON=1, CODENOMAD_FIXTURE_NODE=<packaged Electron executable>
and CODENOMAD_FIXTURE_RESOURCES=<packaged resources directory> to qualify
Electron's npm-only package with system Node excluded from PATH; that mode first
requires the executable to report an Electron version. Both modes set
ELECTRON_RUN_AS_NODE=1, as both desktop hosts do; Electron mode also sets
ELECTRON_NO_ASAR=1, like the Electron backend.
Explicit custom binaries stay selected. WSL and custom installations receive execution-host instructions.
Installation and service activation are separate. A technically incompatible running daemon requires
the explicit Restart shared service action, whose copy explains interruption
of other clients' active work. Activation uses official service stop and the
existing native-parent service start bridge, authenticates the daemon, validates
its contract and replaces local authority. Ordinary backend shutdown never stops
OpenCode. Unknown version labels/newer daemons cannot be downgraded by this action.
For an admitted but older daemon, restart_available keeps activation optional:
non-disruptive reconnect updates backend executable ownership so opening additional
workspaces remains possible while restart is deferred. Executable selection and
workspace execution-host eligibility are rechecked before service mutation.
Troubleshooting's Restart OpenCode service may replace an authenticated same-version daemon; unknown versions stay fail-closed. It is disabled without restart authority or after a failed fresh status check, shares the host/WSL path and serialization with update activation, confirms the all-client interruption, fences a changed executable or unmounted view and never resumes a pending workspace-open callback. Opening settings, checking status, reconnecting and reloading never restart implicitly; both actions keep session history.
Both restart controls remain actionable during passive status refreshes, including window focus. They exclude concurrent mutations and pending confirmations, retain failed-check and executable-selection fences, and use the setup action's fresh pre-mutation status read before dispatching the explicit restart.
Mounted Windows discovery directories and Linux aliases are canonicalized through the selected distro, then translated for host filesystem access. Native import URLs and lease paths stay Linux-native; canonical outside-root storage is kept. Native watchers can miss changes through mounts and symlinks, so the setup card offers explicit Reload OpenCode configuration recovery. The shared setup panel confirms it before dispatch from Settings or startup recovery. Its dialog names every effect (all loaded locations rebuilt, pending permissions/Forms cancelled, terminals/background commands closed for all clients), warns that active work can be interrupted and never presents it as a process restart or memory reclamation. Conflicting service actions are refused while an explicit action runs.
Start OpenCode at login
host-lifetime/opencode-login-start.ts backs Settings → OpenCode Launch at startup (started at login):
a voluntary preference, off by default, whose only state is one OS artifact per account.
Missions never read or change it. GET|POST /api/opencode/login-start
(server/routes/opencode-login-start.ts) returns { state: "on" | "off" | "unavailable" }
and accepts { enabled }; POST requires the live human session of recurrenceHumanSession.
A GET also reconciles stored ON supervision records as described below, which can install the artifact.
Failures cross the boundary only as login-start-unavailable (503),
login-start-unsupported-binary (422) and login-start-failed (500). OpenCodeLoginStart
runs reads, changes and supervision-record reconciliation one at a time; they only
write or remove the artifact. OpenCode then runs on its own: on Windows a crashed OpenCode
stays stopped until the next login.
The artifact starts exactly opencode serve --service for the selected executable
(resolveLoginStartLaunch). Windows takes the native image buildSpawnSpec launches, or
%SystemRoot%\System32\wsl.exe --distribution … --exec <binary> serve --service for a WSL
UNC selection (a distribution root alone is refused); command wrappers (.cmd, .ps1) are
unsupported-binary. POSIX takes the absolute executable. Both validate the link target but
keep the selected path, so a package manager's stable link survives its versioned upgrades.
The Windows task inherits the session environment. launchd and the systemd user manager supply
a minimal one, so the plist (EnvironmentVariables) and the unit (Environment=) carry the
server's PATH as it is at the last ON or refresh, and nothing else
(loginStartEnvironment). Profile overrides are never persisted in the artifact. Explicit
executable changes (both Settings patch routes) and verified installations
(opencode-update/service.ts) call refresh(), which rewrites an installed artifact; its
failure never refuses the save or the update and leaves the artifact starting the previous
executable.
- Windows (
opencode-login-start-windows.ts): one root-folder taskCodeNomad-OpenCode-Loginwith the description markerCodeNomad: start OpenCode at login, registered from XML through Windows PowerShell's ScheduledTasks module (hidden process, process-scoped-ExecutionPolicy Bypass, system module path). A singleLogonTriggerand anInteractiveToken/LeastPrivilegeprincipal for the current SID: no password, no elevation;IgnoreNew, no time limit, normal priority. The action runs a stable copy of the GUI-subsystemopencode-login-launcher.exeunder%LOCALAPPDATA%\CodeNomadOpenCodeLogin, which starts the program withCreateNoWindowand exits: no console appears and the task instance ends while OpenCode keeps running. A same-named task with another description is foreign and never replaced or removed. OFF unregisters the owned task and deletes the launcher copy. - macOS (
opencode-login-start-posix.ts):~/Library/LaunchAgents/org.codenomad.opencode-login.plistwithRunAtLoadandKeepAlive { Crashed = true }: launchd relaunches it after a crash while an explicitopencode service stopkeeps it stopped. ON writes and OFF deletes the plist withoutlaunchctl, so it applies at the next login and a running OpenCode is untouched. - Linux:
~/.config/systemd/user/codenomad-opencode-login.servicewithWantedBy=default.target,Restart=on-abnormalandRestartPreventExitStatus=SIGKILL: systemd relaunches it after a crash signal (SIGSEGV, SIGABRT…) but never after an exit code or SIGKILL: an explicitopencode service stop(exit 130), a start failing with a code and a forced kill stay stopped. It is enabled withsystemctl --user enable(never--now) and removed withdisable, its link and file. Lingering stays as the user set it. A server running inside WSL, or a host without/usr/bin/systemctl, reportsunavailable.
npm run build:host-helpers --workspace @neuralnomads/codenomad compiles the launcher with
the Windows .NET Framework compiler and, on macOS, the universal process-identity-macos
helper of process-identity.ts. It lands as dist/host-lifetime/process-identity-macos, beside
the module of the same name, so the server's import loader (src/loader.ts) resolves
extensionless relative imports to their compiled .js file before the bare path.
Supervision-record reconciliation
At server startup and before every read or change, opencode-login-start-legacy.ts reads
the supervision root (%LOCALAPPDATA%\CodeNomadServiceSupervision on Windows,
~/.codenomad-service-supervision on macOS and Linux). For an ON service key, the
login artifact is installed first; if that fails, the stored installation stays untouched for
the next pass and reads report on, since it still starts OpenCode. An explicit OFF retires it
without installing anything and fails while a stored ON cannot be released. Each guard is then released by rewriting its manifest to OFF, and only its exact
resources are removed:
- Windows disables
CodeNomad-OpenCode-<key>-Mainand-Recovery(their description marker matched exactly, directory included), waits for Main to stop running and unregisters both; Main is never ended, because its job still holds the released OpenCode. A same-key task naming another directory keeps the step pending. - macOS boots out
org.codenomad.opencode.<key>(itsAbandonProcessGroupkeeps OpenCode) and deletes the plist once launchd no longer lists the job. - Linux stops
codenomad-opencode-<key>.serviceonly whensystemctl showreports that exact file loaded withKillMode=processand no drop-in (otherwise the step waits), then disables, unlinks and reloads.
Linger recorded in linux-linger.json as owned, with an unchanged
/var/lib/systemd/linger/<user> fingerprint, is disabled only while an active or online session
exists, so the user manager and OpenCode survive. Personal, external, uncertain or altered linger
is left as it is. Incomplete steps remain for the next pass; the root disappears once empty.
Native qualification also covers a Windows-to-WSL selection
(scripts/test-opencode-login-start-wsl-native.mjs DISTRO LINUX_CLI LINUX_ROOT: isolated
roots passed through WSLENV, port and unique task; the service runs in the distribution,
reachable from Windows, with no visible window) and Linux
(scripts/test-opencode-login-start-linux-native.mjs, run on a disposable host with an esbuild
ESM bundle of opencode-login-start-posix.ts: a real logout and login starts the unit,
opencode service stop and SIGKILL stay stopped, SIGSEGV is relaunched, OFF keeps the process
running, no linger).
Checks: node --import tsx --test packages/server/src/host-lifetime/opencode-login-start.test.ts packages/server/src/host-lifetime/opencode-login-start-legacy.test.ts. Windows native
qualification: node --import tsx scripts/test-opencode-login-start-windows-native.mjs ABSOLUTE_CLI [EVIDENCE_DIRECTORY] registers a uniquely named task for an isolated service (own
HOME/XDG roots and port), runs it on demand, checks the hidden serve --service process and
that removal keeps it running, then stops the service, removes the task and compares the shared
service registration. macOS is covered by artifact and adapter tests; a real login there is a
separate qualification gate.
Stored-history migration
scripts/test-opencode-history-migration.mjs OLD_CLI TARGET_CLI seeds synthetic
older storage (location identities, forks, long histories with
reasoning/tool/compaction checkpoints, a moved worktree session, pending inbox,
provider configuration and a synthetic credential, pending Forms), copies its
DB/WAL and lets the target migrate it, retaining seeds, CLI hashes and logs in a
fresh fixture; it never touches the shared service or rewrites native tables. CI
seeds from 2.0.3, beta-19271 and 2.0.32. The target maps stored workspaceID
values to the local directory scope, keeping session IDs and content, and
CodeNomad uses that scope as is. Pending Forms end with a native restart, and
migration drops them the same way. Assertions compare old connection fields
fully and never discard unknown fields or relax history checks.
Compatibility seams
- Authentication, cancellation, origin and connection generations are regression-tested at the shared connection seam.
- Older discovery routes serve only to diagnose an outdated running daemon; they
are probed only after
/api/info(served by every admitted daemon) returns 404. - Internal identity and directory authorization keep the location/context,
import/cursor and pruning checks for older stored identities. Public workspace
selectors (
workspaceID,x-opencode-workspace) are rejected unconditionally; original cursor bytes and independent import-history ownership are preserved. - Unrecognised contracts receive the
canonical_apirefusal;legacyContractFixture(compatibility/contract-fixture.ts) is a rejection input. - Catalogs update through resource-specific events.
session.message.content.updatedis replay-only (never published live), so live invalidation ignores it. - Pruning preview stays query-only, and the CodeNomad transcript invalidates and
rereads after a prune: the plugin API has no
session.message, and publication can race. - Keep these older-identity authority checks; the synthetic migration seed alone never justifies removing them.
Validation and release gates
Checks include server/UI typechecks, server regressions, real Solid browser setup tests and rendered captures, isolated bundled-Node installation, native migration, native locations/worktrees, automation heartbeat/provisioning and pruning acceptance. On Windows, Linux and macOS ARM64, CI runs first installation at the fixed minimum, old-seed migration at the fixed minimum and resolved latest stable, plus the cross-platform native pruning gate.
Reproduce desktop and WSL acceptance
Windows desktop fixtures launch only the specified worktree's built artifacts,
use isolated native profiles/service ports and dynamically discover instrumentation.
Electron runs a private copy with an explicit server --require for the fixture's
PATH-registration guard; Tauri loads that guard through NODE_OPTIONS.
Both require its startup receipt before allowing installation.
node scripts/test-opencode-setup-desktop.mjs both ABSOLUTE_CURRENT_CLI
node scripts/test-opencode-setup-desktop.mjs both ABSOLUTE_CURRENT_CLI --resume-folder
node scripts/test-opencode-setup-desktop.mjs both ABSOLUTE_OLD_CLI --old-daemon --resume-folder
node scripts/test-opencode-setup-desktop.mjs both ABSOLUTE_OLDER_ADMITTED_CLI --compatible-daemon --resume-folder
node scripts/test-opencode-setup-wsl.mjs DISTRO ABSOLUTE_LINUX_CLI native
node scripts/test-opencode-setup-wsl.mjs DISTRO ABSOLUTE_LINUX_CLI mounted
node scripts/test-opencode-setup-wsl.mjs DISTRO ABSOLUTE_LINUX_CLI aliased reload-safety
Each desktop fixture emits results.json, artifact/resource hashes, per-host
logs/API responses and screenshots in its isolated output directory. Retain those
artifacts with the qualification PR/CI; never document machine-local paths.
Agent conventions
- OpenCode settings start with the OpenCode version card (runtime status, install/update and service actions directly inline), followed by the executable selection card, which has only the selector's own "OpenCode binary" heading and folds path entry/browsing under Choose another binary…. The runtime card shows the running version separately when different or unknown; version details shows the recommendation separately when different from the minimum. Version details and troubleshooting are collapsed disclosures at the bottom of the runtime panel; log levels remain the final settings card, with one label beside the selector and the logs action below. Troubleshooting always exposes an explicit, confirmed shared-service restart independently of updates; retain the inline activation shortcut after an update, and never downgrade a newer daemon through an older selected CLI. Configuration reload remains a separate process-preserving action. Share controls with the startup recovery dialog; never route settings through a separate management modal. The disclosures use the shared
.settings-disclosure(styles/components/settings-disclosure.css). - Startup restoration remembers only definite
426 opencode_update_requiredworkspace refusals for the recovery dialog's successful action or explicit Continue. Keep this window-owned continuation separate from the latest manually requested folder: run the manual open first, then resume only still-unbound saved tabs under their original selection/order/removal guards. Read-only status refresh and settings maintenance do not replay restoration; disposal cancels it. Never replay uncertain creations, generic errors or session mutations. - Verified shared npm OpenCode installations at 2.0.15+ delegate version changes to native
upgradethroughopencode-update/native-upgrade.ts, with the backend's npm scoped to the verified prefix. Native Windows image retention replaces the write preflight only on that path; first install, older migration and same-version repair retain direct npm/preflight. Never retry a failed native mutation via npm or restart the daemon implicitly. Validate with the isolatedscripts/test-opencode-upgrade-native.mjsfixture. - OpenCode minimum requirements must follow demonstrated technical dependencies, never the latest published or solely tested version. Keep required, recommended/tested and unverified versions distinct in
opencode/runtime-support.tsand setup diagnostics. Validate authenticated daemon metadata/contract before client use/plugin provisioning. Setup runs the backend's npm (bundled in Electron's resources for its integrated Node, beside Tauri's bundled Node, or beside a standalone server's own Node) for a shared user npm installation and prefers PATH; only an executable not namednode(Electron's) receives the scoped lifecyclenodecommand. Only a verified@opencode/clinpm installation is updated via npm; an OpenCode 1.xopencode-ainpm shim (identified by its manifest and shim target, never a version string) is replaced in its prefix only after explicit UI confirmation naming that exact installation (rechecked under the installation lock), with every native image of the package preflighted, npm failure states reported truthfully and failure after removal retryable rather than replayed. Foreign--versionprobes are asynchronous, bounded and tree-killed (opencode-update/foreign-probe.ts; on Windows throughstopWindowsProcessTree, which admits only descendants started no earlier than their parent); unknown keeps PATH precedence and synchronous resolution never spawns. Foreign installations (winget, Homebrew, curl, manual) are never modified: when below the minimum or unusable, OpenCode 2 is installed in the user npm prefix beside them and the verified managed installation wins over that PATH command; valid foreign V2 and explicit custom executables keep their precedence. Detection lives inopencode-update/legacy-installation.ts. The CodeNomad-private~/.local/share/codenomad/opencodetree (opencode-update/retired-installation.ts) must never be discovered or launched; ignore its receipts and saved selections without migrating or deleting it. Keep installer locking and Windows live-executable preflight inopencode-update/installation-lock.ts; register terminal PATH only on explicit installation. A running daemon restart is a separate explicit action. Configuration reload is also explicit: nativelocation.reloadrebuilds every loaded location and cancels pending Forms/permissions, so never use it as an automatic watcher fallback. - A selected CLI's
service statuscan reportstoppedfor a live older daemon. Preserve the bounded, read-only registration fallback inworkspaces/native-service-registration.tsand authenticate that daemon's metadata before allowing start;ensure()repeats discovery. Native service lookup is separate from plugin-root discovery, which must still use the connected daemon'sconfig.get. Never write service registration/configuration files from the backend.