Skip to content

[PR] fix: pin opencode plugin entry to an exact version so boots resolve from local cache (#1108) — revival of PR #1143 - #1363

Closed
ranxianglei wants to merge 8 commits into
masterfrom
2026-09-26_opencode-pinned-entry-revival
Closed

ranxianglei wants to merge 8 commits into
masterfrom
2026-09-26_opencode-pinned-entry-revival

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Revival of PR #1143 (closed unmerged 2026-09-23 while on hold for the hermetic local-registry e2e harness, issue #1153). That harness has since landed via PR #1161 (merged 2026-09-25), which unblocks this change.

The four original commits were cherry-picked verbatim onto current master (d3c8af84) with zero conflicts:

  1. fix: pin opencode plugin entry to an exact version so boots resolve from local cache (#1108) — the installer now writes billion-context@<version> into opencode's config instead of the bare billion-context@latest; legacy bare entries migrate to a pin, stale pins to the current version, dev shims to a pin; foreign entries are preserved ([Bug] bili plugin install/remove opencode 会静默删除 plugins 数组里的对象形态条目({package, options} 一起丢) #1002).
  2. fix: update lane re-pins the opencode entry to the resolved npm latest (#1108)
  3. fix: opencode lane self-updates by re-pinning its entry on the update check (#1108) — src/update.ts: when a self-update lands, the opencode lane's entry is re-pinned to the new version so the next boot loads it.
  4. test: hermetic-registry e2e gate for the opencode pinned entry + re-pin self-update (#1108) — extends tests/e2e/e2e-registry.test.ts (the feat: hermetic local npm registry e2e infra — real self-update chain coverage (#1153) #1161 harness) to cover install→pin→boot-from-cache and self-update→re-pin end-to-end against the local verdaccio instance.

Why (root cause, from #1108)

A bare @latest spec forces opencode to resolve the dist-tag against the npm registry on every boot. Combined with opencode-side defects (fixed managed-service port inside the macOS ephemeral range + uncapped respawn supervisor), any transient registry hiccup turns into an unbounded restart loop. Pinning an exact version makes boots resolve from the already-installed local package; updates still flow because the update lane re-pins on each successful self-update check.

Behavior change (disclosed)

  • OLD: opencode plugin entry = bare billion-context@latest; every boot hits the npm registry dist-tag resolution; a stale/frozen copy could never see a newer version through opencode alone.
  • NEW: entry = exact billion-context@<v>; boots resolve locally; freshness comes from bili's own update lane re-pinning (checked every ~3 min while bili runs). A machine where bili never runs keeps its last pinned version until manually updated — same as every other host-managed lane by design (native模式下自动更新问题需要解决 #991).

Pre-flight (this head, on master d3c8af8)

  • typecheck ✅
  • full suite: 2643 pass / 0 fail / 11 skipped ✅
  • build ✅ (+ dist-import-annotations gate OK)
  • hermetic registry e2e (ACP_TEST_REGISTRY=1): 6/6 ✅

Note: touches src/update.ts — per AGENTS.md §5, shipping this release needs a no-op validation release first (existing upgrade path proven healthy) before the updater change goes out.

Fixes #1108

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-26_opencode-pinned-entry-revival (d82eed3)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1744-pr.1363.06cd7a5

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1363.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Received — reviewing PR 2026-09-26_opencode-pinned-entry-revival (69b7093) now. Plan: ① audit original issue #1108 direction, ② regression sweep over touched paths (installer write path, update lane, opencode boot resolution), ③ code review, ④ test-validity check on the new e2e gate, ⑤ diff cleanliness. Full report shortly.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — verdict: correct, well-tested, ready for the release gate. No code changes needed; I fixed one stale doc spot directly on the branch (details below). Base is fresh (branch sits on current master d3c8af84, zero drift) and all 11 CI checks are green on head 69b7093.

① Original issue direction (#1108)

Verified against the issue thread: the root cause chain held up across multiple validation rounds there (deterministic repro) — a bare spec forces @latest dist-tag re-resolution on every boot, and opencode 2.x's managed-service defects (fixed port inside the ephemeral range + uncapped respawn + ~2s probe window) turn any slow round-trip into an unbounded restart loop on large instances. This fix removes the one trigger we control (the spec form); the opencode-side defects are correctly left out of scope (different repo). Direction matches what was previously reviewed on #1143. ✓

② Regression sweep — existing behaviors on touched paths

Path Existing behavior Verdict
Install — applyOpencodePluginEntry (src/plugin-install.ts:1041) entry form, idempotency, foreign-entry preservation (#1002), shim migration Entry form bare→pinned = the disclosed change. Idempotent short-circuit ("plugin present", file untouched), foreign entries verbatim, shim→entry migration all preserved. New dedup (bare + pin coexisting → single pin) is correct and tested. Unpinnable version (""/non-semver/0.0.0) falls back to the bare name = old behavior (safe fallback, documented, tested).
Remove (src/plugin-install.ts:1258) removed bare entry + shim dir Now also removes pinned entries — a required consequence: without it, remove would orphan the pin that install writes. Same root change, not called out separately in the PR body; noted here.
Status (src/plugin-install.ts:1318) counted the bare entry as installed Now counts pinned entries too — required for consistency, else status would report "not installed" right after install writes a pin.
Update lane bili plugin update opencode (src/plugin-install.ts:1884) zero network when an entry existed ("upgrade via opencode's plugin manager") Now always does one registry resolve for this lane, re-pins when bili itself is npm-form, otherwise reports pin state. User-visible message strings changed (minor). Nit, non-blocking: for a legacy bare entry under a dev-checkout bili the stale message reads "plugin entry pinned to billion-context…" — awkward wording for a bare spec, still actionable advice.
checkForUpdate (src/update.ts:649-658) host-managed copies: early refusal, zero registry traffic opencode-owned copies now make exactly one dist-tag poll per ~3-min cycle — the managed branch returns before the normal fetch (line 665), so there is no double poll, and this mirrors the existing dsh-lane pattern (#1196). Re-pin fires only when latest > current (isVersionNewer, proper semver incl. prerelease ordering) → no feedback loop. Fully try/caught, never throws, confined to the refusal branch; download/extract/install path and the global self-update are untouched. Worst case = a silently logged failed re-pin leaving the old version = pre-change behavior.
Other lanes (pi/dsh/hermes/reference) — Untouched.

No unintended regressions found. The two user-visible behavior changes (entry form; one extra dist-tag poll per cycle for opencode-managed copies) are both disclosed or disclosed-by-consequence and consistent with the Install-Lane & Update-Ownership contract (#1196/#991).

③ Code review

④ Test validity — real teeth, not tautologies

  • Units (tests/plugin-install-opencode.test.ts, tests/update-opencode-repin.test.ts): assert exact config array/map state and exact note strings; cover semver + prerelease pinning, bare fallback, legacy-bare migration, shim migration, duplicate-pin collapse, map form, foreign preservation, dev-checkout refusal, and fetch-failure → warn + no throw + config untouched.
  • E2E (tests/e2e/e2e-registry.test.ts): real chain against the local verdaccio — self-update OLD→NEW over the real integrity chain, bare→pin migration + idempotent second install, managed-copy re-pin through the update check's refusal branch (copy provably NOT written, entry re-pinned — this exercises the new src/update.ts path end-to-end), and an offline npm pack --offline byte-identical proof of boot locality.
  • One nuance: the boot-locality subtest uses npm CLI cache semantics as a proxy for opencode's Npm.add machinery (opencode source isn't available in this repo) — a reasonable proxy, and the test comment says so.

⑤ Diff cleanliness

5 files, all on-topic; no lockfile churn, no whitespace noise; comments carry the #1108 rationale where non-obvious. Clean.

Independent local verification (exact head 69b7093)

typecheck ✅ · build ✅ (+ dist-import-annotations gate OK) · targeted units 23/23 ✅ · hermetic registry e2e 6/6 ✅ (ACP_TEST_REGISTRY=1). Matches the PR's pre-flight claims.

Fixed in passing (labeled commit on the branch)

tests/e2e/README.md's "Deferred scenarios" paragraph was stale — it listed zero-registry-round-trip resolution (#1108) and the pinned-entry assertions as "next up", but this PR implements both (and removed the TODO(#1143) marker the paragraph referenced). Updated to "Pinned-entry scenarios (#1108)" + remaining deferral (#1149 tag-cleanup). Docs-only, commit 21ebe4aa, pushed — CI will re-run on it (trivially green).

Framing nit (non-blocking)

OP says the commits were "cherry-picked verbatim"; the branch actually carries four commits vs master (0e78dd56, 1bd73ad0, d5580cca, 69b7093) whose content matches OP's own enumeration — which already includes work beyond the original #1143 scope (the update-lane re-pin and the e2e extension). The enumeration is accurate; "verbatim" is just loose wording.

Release gate (per AGENTS.md)

  • §5: src/update.ts is touched → ship a no-op validation release first (prove the existing upgrade path healthy end-to-end), then merge this.
  • §7.4 auto-merge gate feat: release CI (npm auto-publish on release branch) #8 (load-bearing infra: src/update.ts) + user-visible behavior changes → human merge either way.

Suggested sequence: no-op release → observe a real auto-updated OLD → NEW succeed → merge this PR → let it ride in the next release.


中文摘要: 审核通过——opencode 插件入口由裸 @latest 改为精确版本锁定(安装写入、更新检查时重钉、托管副本拒绝分支自更新),方向与 #1108 根因一致;回归清点(安装/移除/状态/更新通道/自更新路径)无意外破坏,两处可见行为变更均已披露;CI 全绿且本地独立复验通过(typecheck/build/单测 23/23/hermetic e2e 6/6);顺手修了 README 过期段落(docs-only 提交 21ebe4aa 已推);因触碰 src/update.ts,需先走 no-op 验证发布、再由人工合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

双写者竞争评估:opencode 写回 entry 会不会把 pin 覆盖回来(owner 提出的问题)

结论:不会乒乓。三个机制锁死,分歧只可能是单次瞬态,收敛点永远是 registry latest。

写者画像

  • opencode 侧:只在用户显式 install/update 插件时写自己的配置;boot 只读 entry 并解析(pin 后从本地缓存,不碰网络),不重写 entry。不是周期性写者。
  • bili 侧两个写点,且写值永远收敛到 registry latest:
    1. repinOpencodeLaneIfNewer(src/update.ts)——只在 registry latest > bili 自身版本 时动笔(isVersionNewer 门),且只在 self-update 拒绝分支(owner === "opencode")触发;
    2. bili plugin install opencode / launcher 迁移——把 bare / stale pin 抬到 current。

防覆盖三重锁(读码核过)

  1. repinOpencodeEntryImpl 的 swap = (x) => isOpencodeNpmEntry(x) && x !== desired——只认 npm 形态的自家 entry(billion-context / billion-context@*);foreign entry 原样保留([Bug] bili plugin install/remove opencode 会静默删除 plugins 数组里的对象形态条目({package, options} 一起丢) #1002)。
  2. 包缓存里的副本本体永远不写(native模式下自动更新问题需要解决 #991)——争的只是 entry 字符串,不是代码拷贝。
  3. isVersionNewer 门——不比自己新的版本永远不触发写。

三场景推演

场景 结果
opencode 侧装了更新 v155,bili 跑 153 bili 看 latest(155)>self(153)→ re-pin 到 155 = 与 opencode 写的相同值,收敛,零冲突
opencode 侧显式装了更旧 v152 isVersionNewer(153,153)=false → bili 不写,entry 停 152(分叉但稳定,无乒乓);下次 bili plugin install opencode 的 stale-pin 迁移抬回 current——尊重用户显式降级意图,host-managed 契约行为
bili 全局自更新 153→155 成功后 re-pin entry→155,boot 本地加载新版——唯一常规写路径

乒乓要求两个写者周期性写不同值:bili 目标值恒=registry latest,opencode 只在用户动作时写、写的也是 registry 上存在的版本 → 单收敛点,不可能循环。

遗留观察(非阻塞)

  • 场景 B(用户在 opencode 里主动装旧版)会停留在旧 pin 直到下一次 bili plugin install opencode 或 launcher 迁移——若认为应更快收敛,可在 update check 里加一条"entry 版本 < bili current 时也 re-pin"的策略,但这改变了"尊重显式降级"的语义,需要 owner 单独拍板。
  • 本 PR 触碰 src/update.ts:按 AGENTS.md §5,合并后的下一个发版需先 no-op 验证版证明现有升级路径健康,再正式携带本变更(PR 描述已自带该声明)。

中文摘要:opencode 不是周期写者;bili 只在 registry 有更新版本时写、只写自家 entry 字符串、永不写副本本体;两写者目标值同为 registry latest,故最多单次瞬态分歧、自动收敛,不存在互相覆盖成环。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 结论一致:无乒乓。三重锁逐行核过,另有一处场景 B 的精度修正、一条对你遗留观察的建议、一个需要点名的外部前提。

三重锁复核(行级)

  1. swap = (x) => isOpencodeNpmEntry(x) && x !== desired(src/plugin-install.ts:1201)——只认自家 npm 形态 entry(bare 或 @* pin),foreign 原样保留([Bug] bili plugin install/remove opencode 会静默删除 plugins 数组里的对象形态条目({package, options} 一起丢) #1002)。✓
  2. 拒绝分支永不写副本本体(src/update.ts:649-658,early return 在 download/extract/install 之前;e2e 明确断言 the opencode-owned copy must NOT be written)。✓
  3. isVersionNewer 门(src/update.ts:542:if (!latest || !isVersionNewer(latest, opts.currentVersion)) return;)。✓

门的一个细节值得点明:opts.currentVersion 来自运行中副本自己的 package.json(src/version.ts 运行时读 dist/../package.json)。对托管副本而言就是托管副本的版本,不是全局 bili 的版本——这影响下面场景 B 的推演。

场景 B 精度修正:"停在 152"只在降级副本不含 re-pin 逻辑时成立

用户经 opencode 显式装的旧版,分两种:

  • 旧版早于本 PR 发布(代码里没有 re-pin 逻辑):确实稳定停在旧 pin,直到显式 bili plugin install/update opencode 抬回——你的描述成立。
  • 旧版已含本逻辑(≥ 发布版):该副本自己的 update check 会看到 latest > self → ~3 min 内 re-pin 回 latest,下次 boot 拉回新版。这不是缺陷,是 dsh plugin-market installs never auto-update: the refresh chain's only trigger is a global bili self-update #1196 lane 契约的既有语义("lanes converge to the registry version within one check cycle")——host-managed lane 里显式降级 = 瞬态漂移,不是持久 pin,与 dsh profile bundle 被拉回 latest 的行为同类。若希望"显式降级应粘住",那是一个独立的产品决定(需要 pin 标记/manual-lock 之类新机制),不属于本 PR 范围。

对遗留观察的建议:不加 "entry < current 也 re-pin"

最坏分歧态(copy == latest、entry 被手工/外部改低)在现有门下也会自愈,推演:

  • cycle N:门 latest > self = false → 不写;
  • 下次 opencode boot:解析旧 entry、拉旧版,self 变旧;
  • cycle N+1:latest > self = true → re-pin 回 latest;
  • 下次 boot 回到 latest,门 false,稳态。

收敛最多花 一次 boot + 一个 check cycle。你提的策略不改变不动点(latest),只会让手工分歧的配置每个周期多一次 config 写入(churn 增加、收益为零)。建议维持现有门不变。

一个本仓库无法验证的外部前提(点名)

"opencode 不是周期性写者"依赖 opencode 侧行为:#1108 的证据覆盖了 boot 路径(只读 entry + 解析,pin 后走本地缓存),这是承重部分,可信。但显式 install/update 时 opencode 写回的 entry 形态在本仓库不可见——若它把 entry 规范成 bare,则每次用户驱动的 opencode 更新会触发一次 bili 修复写(bare→pin)。仍非循环(用户动作驱动、每轮 bili 最后落子、收敛到 latest),只是每次显式更新多一次修复写。不影响"无乒乓"结论,但作为假设记录在此。

发布门

同意你的收尾声明:触碰 src/update.ts → §5 先 no-op 验证发布,观察到真实 auto-updated OLD → NEW 成功后再合并本 PR(§7.4 gate #8,人工合并)。本轮讨论不需要任何代码改动。


中文摘要: 同意"无乒乓"结论,三重锁已逐行核实(swap 只认自家 entry / 永不写副本本体 / isVersionNewer 门,且门比较的是运行副本自身版本);修正一处:用户显式降级到的版本若已含 re-pin 逻辑,会在一个 check cycle 内自动收敛回 latest(#1196 契约语义,降级=漂移而非持久 pin);"entry<current 也 re-pin"策略不必加——最坏分歧一次 boot+一个周期即自愈,加了只多 churn;唯一外部前提(opencode 显式更新时不把 entry 写回 bare)本仓库不可验证,但即使违反也只是每次用户动作多一次修复写,仍无循环;无需改码,按 no-op 验证发布 → 人工合并流程推进即可。

ework-agent and others added 6 commits September 26, 2026 19:39
…rom local cache (#1108)

A bare npm spec makes opencode's managed plugin service re-resolve @latest
against the npm registry at every boot; on slow networks that pushes cold
start past the health-check window and the supervisor respawn-loops. Write
"billion-context@<self-version>" instead (bare-name fallback when the
version is unknown), recognize both forms everywhere the entry is matched,
and have the update lane report stale pins instead of the generic
opencode-managed hint.
#1108)

Install pins the installing bili's version (sync, offline — equals npm
latest in the normal just-installed flow); `bili plugin update opencode`
now resolves the newest registry version and re-pins the entry in place
(only the entry string — the opencode-managed package copy stays
opencode's, #991). Foreign entries preserved verbatim (#1002).
… check (#1108)

The spawned proxy runs startAutoUpdate like any install; its checkForUpdate
currently early-returns for host-managed copies without even looking at the
registry, so a pinned entry would freeze the opencode lane forever. In the
refusal branch (owner opencode) resolve the newest registry version and
re-pin the config entry instead — opencode's own manager fetches that
version at next boot, from local cache afterwards. The copy itself stays
opencode's (#991); the hook lives entirely inside the refusal branch and
never touches the check/download/extract/install path, and every failure is
caught and logged.
…in self-update (#1108)

The gate the maintainer asked for on PR #1143: publish old/new versions to
the local verdaccio, then verify on the real chain that (a) plugin install
writes the exact-version entry (and is idempotent), (b) an opencode-managed
old copy's update check re-pins the entry instead of writing itself, and
(c) the exact spec resolves from local cache with --offline, byte-identical
to the registry tarball. Replaces the TODO(#1143) master-semantics
assertions.
@ranxianglei
ranxianglei force-pushed the 2026-09-26_opencode-pinned-entry-revival branch from 21ebe4a to 2a84854 Compare September 26, 2026 11:46
@ranxianglei

Copy link
Copy Markdown
Owner Author

(ai: zhipuai-lb/glm-5.3)

陈旧票清理(第三批动作①):目标 issue #1108 已关。为避免重复劳动关闭本 PR;如判断有误请直接 reopen 并留言。

@ranxianglei ranxianglei changed the title fix: pin opencode plugin entry to an exact version so boots resolve from local cache (#1108) — revival of PR #1143 [PR] fix: pin opencode plugin entry to an exact version so boots resolve from local cache (#1108) — revival of PR #1143 Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[opencode 2.x] bare npm spec ("billion-context") triggers managed-service restart loop; pinning an exact version avoids it

1 participant