Skip to content

feat(proxy): user-zone vs self-managed port zones — zero-config port ownership (#1660) - #1670

Merged
ranxianglei merged 11 commits into
masterfrom
2026-09-30_port-zones
Sep 29, 2026
Merged

ranxianglei merged 11 commits into
masterfrom
2026-09-30_port-zones

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Sep 29, 2026 •

Copy link
Copy Markdown
Owner

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 start daemon (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:

Zone Owner Ports Behavior
User zone You (bili start) 8787 default You own it; lane hooks attach by default
Self-managed zone Lane spawns base 18787, BILI_ZONE_PORT +1 ladder on collision, sticky drift record

How a lane'd launch picks its port

  1. Explicit override (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)
  2. Else the lane's sticky record in <state>/port-zone.json (a past +1-ladder drift it still points at)
  3. Else the zone base (18787)

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)

Attach gate relaxation (#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 (crashed-session orphans) are still refused loudly. BILI_NATIVE_ATTACH_EXTERNAL now 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_PORT validation
  • tests/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 ephemeral
  • tests/claude-native.test.ts: plan {port, strict} semantics; explicit port baked + strict, zone default non-strict; repinClaudeManagedBaseUrl drift/relay/foreign coverage; install no longer persists claude.nativePort; e2e squatter test rewritten to the attach semantics
  • tests/zcode-native.test.ts: resolveZcodeNativePort env-only
  • tests/plugin-agent.test.ts: codex block without baked env; legacy heal drops it
  • typecheck clean; 379/379 non-live tests pass (8 live e2es skipped per ACP_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:

Item Kind Why the existing surface cannot express it Compat
BILI_ZONE_PORT NEW env there is no existing knob for "where the self-managed zone starts"; considered reusing port (user zone — wrong owner) and a config-file field (env matches the BILI_*_PORT convention and stays out of user config) unset → default 18787 unchanged; junk/out-of-range falls back to 18787 with a warning
BILI_CLAUDE_NATIVE_PORT / BILI_ZCODE_PORT RE-SEMANTICS: override-of-default → exact strict pin #1660 removes the per-lane defaults entirely; once no default exists, "setting the var" can only mean "this exact port", which is exactly the #964 strict semantics unset (common case) now rides the zone instead of the frozen default — the intended change; set → same port as before, strict bind preserved
claude.nativePort (config file) now READ-ONLY: install no longer writes/clears it the installer persisted it since #964 so the hook could resolve the same port; with per-session repin (#1660) persistence buys nothing ⚠ legacy installs that carry the key (default 48787) are still read as an explicit pin — migration gap under review, see thread
<state>/port-zone.json NEW state file (not config) per-lane sticky drift record; state dir by design (#535: no user-config writes) none — auto-created, garbage-tolerant, atomic RMW

…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.
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-30_port-zones (ef3c6d0)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1660-pr.1670.5ac2b72

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-pr1670.tgz
npm install -g package

Install instructions are refreshed on each push.

ework-agent and others added 4 commits September 29, 2026 16:05
…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).
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #1670 review complete (head 957e90e2, includes two follow-up commits 90cc7e8d + 3411166b that landed after my initial read, plus one doc commit I pushed directly — details below).

① 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 bili start daemon. The fix attacks the root cause (no ownership model for ports) rather than the symptom (collision handling), and matches the owner-finalized design (#1660 floor 2): user zone 8787 attach-by-default, self-managed zone 18787 + sticky drift, 48787/48789 deprecated, codex block unbaked. Direction is sound.

② Regression audit — existing behaviors on touched paths:

③ Code findings:

  1. MEDIUM — legacy claude.nativePort migration gap. Master's claudeInstall called saveClaudeNativePort(resolveClaudeNativePort()) unconditionally (plugin-install.ts:685-686 pre-change), so every claude-native install since [native] claude: three-mode alignment (proxy / launcher / native plugin) + runtime-info #964 has claude.nativePort (default 48787) persisted in config.json. This PR stops writing it but still reads it as an explicit pin → those installs stay strict-pinned at 48787 forever; the "Migration (self-healing)… no manual cleanup" claim is false for claude (true for zcode — env-only, store repaired by feat(zcode): route:"all" default with per-entry exemptions — unified fix for #1621 #1622 #1623 #1648). Two fix options: (a) stop reading the file key entirely (env-only, parity with zcode; a hand-set file pin is silently abandoned but repin migrates the URL so claude keeps working), or (b) treat value == 48787 as absent (sentinel strip), keep other values as genuine pins. I recommend (a) — consistency + zero special-casing, and "stop pinning ports" is the point of [Design] 定死端口 lane(claude 48787 / zcode 48789)端口被占时的 0 配置解法 #1660. Owner call since it's config-schema semantics.
  2. Sticky-settle asymmetry — fixed in 90cc7e8d, verified: hooks now pass port: 0 in zone mode so the launcher resolves the zone preference AND settles sticky; I confirmed opts.port is only consulted under strictPort (port-mismatch skip + squatter check), so port-0 doesn't disturb attach discovery. The new live suite pins exactly this bug class.
  3. Docs stale → fixed directly (commit 957e90e2, pushed): TECHNICAL-NOTES en/zh attach-gate section still described pre-[Design] 定死端口 lane(claude 48787 / zcode 48789)端口被占时的 0 配置解法 #1660 behavior ("manual daemon ❌ by default") although CONFIGURATION.md points readers there for the full mechanics; claude section still showed the 48787 bake; README.zh-CN was missing the "Ports, briefly" paragraph + updated claude bullet (en/zh parity).
  4. Process — missing "config surface" section in the PR body (AGENTS.md §Configuration Surface Discipline) → added directly via API edit (BILI_ZONE_PORT new env, the two re-semantics'd port vars, claude.nativePort read-only, port-zone.json state file, each with rationale + compat; references the [Design] 定死端口 lane(claude 48787 / zcode 48789)端口被占时的 0 配置解法 #1660 floor-2 sign-off and flags finding 1).
  5. DESIGN DIVERGENCE — needs owner ruling, not mine: cross-lane single-port sharing (design point ① "自管区单口共享") is not implemented: instanceCompatible still blocks lane-mismatched attaches, so N lanes ladder to N zone instances (the new live test explicitly pins "cross-lane instances are never attach targets"). Functionally correct and bounded (≤ number-of-lanes instances; 无单实例守卫:多个 bili 代理进程并存共写 sessions 目录,伴随孤儿 ref、有注册表无 transcript、计数自相矛盾的污染簇 #394 stays silent between different declared lanes), but if single-port sharing is wanted it needs the narrowed blocking set from my [Design] 定死端口 lane(claude 48787 / zcode 48789)端口被占时的 0 配置解法 #1660 floor-6 point B (keep fingerprint/host/passthrough/mitmDomains; make lane + modelWindows/modelMaxOutputs non-blocking pending runtime-info verification) — better as a follow-up issue than bundled here. Minor adjacent note: pickAttachable prefers a same-lane instance over a user-zone daemon (design said 用户主权优先) — negligible in practice (both are same-build bili), flagging for completeness.

④ 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 tests/port-zone-live.test.ts pins the WIRING against real processes (real EADDRINUSE ladder, real sticky follow, real attach) under the ACP_TEST_CLAUDE_NATIVE gate. The 90cc7e8 regression would be caught by it.

⑤ 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 claude.nativePort: recommend option (a) env-only, landable as a small follow-up commit in this PR) and confirms finding 5 (accept per-lane-in-zone as v1, or file the single-port-sharing follow-up). Everything else is verified clean.

中文摘要:审查了端口分区 PR(#1660 方向正确、#964/#1335/#1225/#1232/#446 既有行为均保持或已披露变更、测试有牙、CI 全绿);已直接在分支上修掉过时的 TECHNICAL-NOTES/README 文档并补上 PR 正文缺失的 config surface 章节;剩两个待 owner 拍板项——旧版安装残留的 claude.nativePort(建议改为 env-only 以完成迁移承诺)与跨 lane 单口共享是否留作后续 issue——拍板后即可合并。

ranxianglei and others added 6 commits September 29, 2026 17:13
…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
@ranxianglei
ranxianglei merged commit ca98193 into master Sep 29, 2026
13 checks passed
@github-actions github-actions Bot mentioned this pull request Sep 29, 2026
AEmbers pushed a commit to AEmbers/billion-context that referenced this pull request Sep 30, 2026
…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.
@ranxianglei
ranxianglei deleted the 2026-09-30_port-zones branch October 15, 2026 05:32
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.

[Design] 定死端口 lane(claude 48787 / zcode 48789)端口被占时的 0 配置解法

1 participant