Repository navigation
feat(proxy): user-zone vs self-managed port zones — zero-config port ownership (#1660) - #1670
Conversation
…zone (18787) (#1660) Manual `bili start` owns its port; everything a lane spawns for you lives in a separate self-managed zone and follows its own drift — zero-config installs never fight the user for a port. - Zone base 18787 (BILI_ZONE_PORT override); lane'd launches try the lane's sticky record (<state>/port-zone.json) first, else the base; the spawn child's EADDRINUSE +1 ladder resolves collisions and the settled port is recorded sticky so later launches follow drift automatically. Unlane'd launches keep the OS ephemeral default. - Claude native hook: rides the zone (non-strict) and re-pins the managed ANTHROPIC_BASE_URL to the live origin each session (drift self-heals); explicit BILI_CLAUDE_NATIVE_PORT keeps #964 strict-port semantics (refuse a squatter loudly). claude.nativePort is no longer persisted — install no longer writes the bili config file. - Zcode native lane + MCP respawn: same explicit-??-zone resolution. - Attach gate (#1335/#1660): a manual `bili start` daemon (no lane, no launch token) is user-zone by definition — lane'd hooks attach to it by default; unarmed LANE'd listeners are still refused. attachExternal now only matters for lane'd targets. - Codex MCP block: no baked BILI_MCP_PROXY origin anymore — the shell discovers the live proxy at startup (env > instance file > 8787), so the block cannot go stale on port drift or reboot. Docs: README/CLIENTS(+zh-CN)/CONFIGURATION(+zh-CN) updated for the zone model, migration off 48787/48789 (self-healing), and the new env rows.
📦 Built Package ArtifactBranch: Option A — Install this exact build (recommended)npm install -g billion-context@0.0.1660-pr.1670.5ac2b72This exact version is immutable and reproducible. The rolling Option B — Download artifact
tar xzf billion-context-pr1670.tgz
npm install -g packageInstall instructions are refreshed on each push. |
…, install needs no live proxy
…orts skipped the sticky settle The native call sites resolved lanePreferredPort() themselves and passed a concrete port, which made the launcher's zoneLane condition (lane && port <= 0) false: the sticky record was never written and the +1-ladder drift was never recorded. Caught by a live local smoke test — first launch landed on 18787 by preference, but port-zone.json stayed empty and a drift (squatter on 18787 → 18788) would never become sticky. An explicit pin (BILI_CLAUDE_NATIVE_PORT / BILI_ZCODE_PORT) still passes its exact port + strict; kimi/dsh/opencode already passed port 0 and were unaffected. Single resolution point now lives in the launcher: zone preference, ladder drift, sticky settle.
…s, mocked and live (#1660) The sticky lifecycle shipped with single-shot unit tests (one spawn, one assert), so the bug class where a call site pre-resolves the port and the settle never fires (90cc7e8) had no surface to fail on. This pins the REPEATED loop, two layers deep: Mocked sequences (tests/port-zone.test.ts, always run) — a one-daemon sim whose zonePreferredPort/writeZonePort delegate to a REAL temp port-zone file, so the full write→read sticky loop runs on disk: - settle → attach → drift (squatter) → re-settle → attach-follows-drift - second lane: never attaches cross-lane, settles its own key - explicit strictPort pin: exact spawn port, BILI_STRICT_PORT crosses the boundary, no sticky write - unlane'd: ephemeral, zone file untouched Live matrix (tests/port-zone-live.test.ts, gated on ACP_TEST_CLAUDE_NATIVE like the claude-native live e2e — CI's dedicated matrix runner sets it, #1248 keeps it off loaded local sandboxes) — real dist proxies, real spawn handshake, real EADDRINUSE ladder, real attach probe: - lane'd port-0 binds 18787 + settles sticky; repeat attaches - squatter on the sticky port → +1 drift settles sticky; repeat attaches at the drifted port - explicit strictPort pin binds exactly, no zone record - second lane spawns its own daemon past the first, independent sticky keys - unlane'd launch is ephemeral, no zone file materialized
TECHNICAL-NOTES (en/zh): the reuse/attach-gate section still described the pre-#1660 rule (manual daemons refused by default) although CONFIGURATION.md points readers there for the full mechanics — rewrite it: user-zone instances (no lane, no launch token) attach by default, unarmed lane'd orphans are still refused loudly, BILI_NATIVE_ATTACH_EXTERNAL now only matters for lane'd targets (=0 closes even user zone), self-spawns ride the 18787 zone instead of ephemeral ports, fingerprint check still runs first. Claude native section: port resolution is explicit-pin strict vs zone base/sticky drift, per-session repin of the managed URL, install no longer persists claude.nativePort. README.zh-CN: mirror the en 'Ports, briefly' paragraph and the updated claude bullet (en/zh parity).
[bot] 🏷 PR #1670 review complete (head ① Direction (original issue #1660) — verified the problem is real: ad-hoc per-lane pins (claude 48787 strict / zcode 48789 / rest ephemeral) plus the #1335 gate refusing a deliberate manual ② Regression audit — existing behaviors on touched paths:
③ Code findings:
④ Test validity — assertions have teeth: spawn-count/attached-flag/file-content/idempotency checks (not tautologies), the mocked matrix pins the decision table (settle→attach→drift→re-settle), and the new ⑤ Diff cleanliness — focused; every line traces to #1660; docs now synced after my commit. CI — all 8 workflow runs green on head: CI (ubuntu 22/24 + windows 22/24), e2e-fake-codex, e2e-native-dsh/pi/opencode, e2e-local-registry, PR Build Artifact, version-guard. (The secret-gated real-upstream ci-e2e doesn't auto-trigger here — launcher.ts isn't in its hot-file list — the fake-upstream e2e lanes cover the changed client paths.) Verdict: mergeable once owner rules on finding 1 (legacy 中文摘要:审查了端口分区 PR(#1660 方向正确、#964/#1335/#1225/#1232/#446 既有行为均保持或已披露变更、测试有牙、CI 全绿);已直接在分支上修掉过时的 TECHNICAL-NOTES/README 文档并补上 PR 正文缺失的 config surface 章节;剩两个待 owner 拍板项——旧版安装残留的 |
…obe in tests Found while verifying #1670 on a machine whose PATH shadows opencode v2 (a stray node_modules/.bin walk by npm test): the idempotent-rerun note was the hardcoded string "plugin present", but tests build the expectation from pickPluginKey(detectOpencodeMajor()) — so any host with opencode 2.x failed three install tests. The note now names the effective key ("plugin present" / "plugins present"), and the v1-shaped dev-form e2e pins BILI_CLIENT_BIN to an unresolvable path (probe fails soft to major 1) so it never depends on the host binary. The e2e-registry v2 stub assertion follows the new wording.
Real Windows machines (node under "Program Files", localized cmd errors, existing USERPROFILE homes) exposed four CI-invisible test assumptions: - discover: withHome now mirrors HOME into USERPROFILE on win32 so os.homedir() resolves inside the sandbox instead of the real ~/.zcode - doctor: withEnv mirrors HOME->USERPROFILE on win32 for the same reason (real ~/.dsh profiles were leaking into sandboxed-home tests) - hook-command: the "& spaced head" PowerShell call-operator form is no longer demanded of cmd (production hooks resolve a bare node; cmd never sees a spaced head) - hermes: the missing-CLI assertion now matches the shared manual-enable tail, since a Windows shell probe fails with a localized error instead of ENOENT
Codex is the one client a plugin install cannot make self-sufficient: traffic routing is env-only (no config seam for the ChatGPT-login provider; managed model_providers would drop subscription login) and an MCP server cannot inject env into its parent. Document the three postures honestly across all four doc files: - README.md / README.zh-CN.md: add the missing codex row to the "Which do I need?" table and rewrite the Option-1 note (also stops lumping codex together with omp, which is self-spawning native). - CLIENTS.md / CLIENTS.zh-CN.md: new Codex section — seam matrix (claude has SessionStart hook, zcode has provider store, codex has neither), posture table (bili codex / plugin + running bili + HTTPS_PROXY / plugin alone = -32003), #1660 de-bake rationale (#403), resolution order env > live instance > 8787, headless session binding (#760).
# Conflicts: # CONFIGURATION.md # CONFIGURATION.zh-CN.md # tests/plugin-install-opencode.test.ts
…ed (breaks #1101 T9 on CI)
…defined The ranxianglei#1646 sweep replaced fs.rmSync cleanups with the rmrf() helper but missed two bare rmSync() calls whose node:fs imports no longer existed: - tests/issue1086-chain-self-exemption.test.ts:728 — uncovered, so "ranxianglei#1101 T9: BILI_CHAIN_CONTENT env parse" dies with ReferenceError: rmSync is not defined (this is the current red master). - tests/tunnel-guard.test.ts:385 — wrapped in a best-effort try/catch, so it fails silently and leaks the scratch dir instead. Both now call rmrf(), consistent with the rest of the sweep (and pick up its ENOTEMPTY retry semantics). Found via a CI failure on ranxianglei#1670; the files are byte-identical on master, which is red on its latest run (8293a54) with the same error.
Closes #1660.
The problem (#1660)
Port collisions between user-owned and lane-spawned proxies were resolved ad hoc per lane: claude pinned 48787 (strict, fails on squatter), zcode pinned 48789, everything else took an OS ephemeral port. A manual
bili startdaemon (user zone, 8787) was refused by the #1335 attach gate, so every session spawned its own proxy even when the user deliberately ran a resident one.The model
Two disjoint port zones:
bili start)BILI_ZONE_PORTHow a lane'd launch picks its port
BILI_CLAUDE_NATIVE_PORT/BILI_ZCODE_PORT) → that exact port, strict (squatter refused loudly, [native] claude: three-mode alignment (proxy / launcher / native plugin) + runtime-info #964 preserved)<state>/port-zone.json(a past +1-ladder drift it still points at)The spawned child's EADDRINUSE +1 ladder resolves collisions; the settled port is written back sticky so later launches follow drift automatically. Unlane'd launches keep the OS ephemeral default.
Drift-repair (why non-strict is now safe)
ANTHROPIC_BASE_URLto the live origin each session (repinClaudeManagedBaseUrl), so a hopped port self-heals on next launch.claude.nativePortis no longer persisted — install no longer writes the bili config.Attach gate relaxation (#1335/#1660)
A manual
bili startdaemon (no lane, no launch token) is user-zone by definition — lane'd hooks attach to it by default. Unarmed lane'd listeners (crashed-session orphans) are still refused loudly.BILI_NATIVE_ATTACH_EXTERNALnow only matters for lane'd targets.Codex MCP block: no baked origin
The block no longer bakes
BILI_MCP_PROXY— the MCP shell discovers the live proxy at startup (env > instance file > 8787 fallback), so the block cannot go stale on port drift or reboot. Legacy blocks with the env line are healed on reinstall.Migration (self-healing)
Existing installs pointing at 48787/48789: the next session's hook/lane rides the zone, and drift-repair rewrites the baked URL/store entry to the live origin — no manual cleanup.
Test plan
tests/port-zone.test.ts(new): sticky record round-trip, garbage tolerance,lanePreferredPort,BILI_ZONE_PORTvalidationtests/launcher.test.ts: zone preference + sticky settle via injected sinks; user-zone daemon attached by default; claude-native hooks must not attach to a lifecycle-less proxy — attach gate + self-managed fallback #1335 fixtures now lane'd (refusal semantics preserved); unlane'd stays ephemeraltests/claude-native.test.ts: plan{port, strict}semantics; explicit port baked + strict, zone default non-strict;repinClaudeManagedBaseUrldrift/relay/foreign coverage; install no longer persistsclaude.nativePort; e2e squatter test rewritten to the attach semanticstests/zcode-native.test.ts:resolveZcodeNativePortenv-onlytests/plugin-agent.test.ts: codex block without baked env; legacy heal drops itACP_TEST_CLAUDE_NATIVE)Note: hermes' Python-side discovery keeps its conservative #1335 gate copy (unarmed refused) — deliberate for now, recorded in #1660.
Config surface (AGENTS.md §Configuration Surface Discipline)
Owner sign-off for the overall design: #1660 floor 2 (2026-09-29, 与 owner 对齐). Changes against the existing surface:
BILI_ZONE_PORTport(user zone — wrong owner) and a config-file field (env matches theBILI_*_PORTconvention and stays out of user config)BILI_CLAUDE_NATIVE_PORT/BILI_ZCODE_PORTclaude.nativePort(config file)<state>/port-zone.json