[kitlangton]

Why

Unpinned npm and Git plugins can advance while OpenCode continues loading an indefinitely cached installation. Refreshing on every config or location reload would introduce repeated network work and could change a plugin during a running server process.

What Changes

Plugin source	First package load in a server runtime	Later loads in the same runtime
Bare npm names, tags, and ranges	Refresh from the registry	Reuse the first result
Git branches, tags, and semver selectors	Refresh the remote revision	Reuse the first result
Exact npm versions	Reuse the pinned installation	Reuse the pinned installation
Full 40- or 64-character Git commits	Reuse the pinned installation	Reuse the pinned installation

If a refresh fails and a cached installation exists, OpenCode logs a warning and loads that cached plugin instead of failing startup.

Runtime Boundary

The process-global npm service records each mutable package specification after its first refresh attempt. Plugin supervisor loads opt into this behavior, so the first load of each project-local plugin acts as startup for that plugin without requiring a server-wide config scan.

Scope

This is the startup-refresh MVP only. It adds no manual update API, protocol/schema/server/client/OpenAPI surface, or plugin-management UI.

Verification

# packages/util
bun run test
bun typecheck

# packages/core
bun run test test/npm.test.ts test/config/plugin.test.ts test/plugin.test.ts
bun typecheck

# packages/www
bun typecheck
bun run check:generated
bun run build

# repository pre-push hook
bun turbo typecheck --concurrency=3

The real local Git fixture verifies mutable branch refresh across service instances, no mid-runtime refresh, exact-commit pinning, and cached fallback when the remote becomes unavailable. All listed tests, package checks, the documentation build, and the 38-package pre-push typecheck pass.