Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs

Phase 3 of #2835 — closing inventory audit for the env-number contract, and the contract written where the next service will meet it

Design: #2835 (env numbers are arguments — one strict parse for boot-time configuration). Design doc: files/designs/code-env-config-strict-parse.md in the keep-the-four-repos-healthy goal workspace (design-architect pass 22, 2026-10-30; audited against origin/main 69cc1813).

Gated on Phases 1–2 of #2835 (Phase 1 = #2823 + #2786 + #1809 + #2096, bin/ proxies; Phase 2 = #2161 + #2758 + #2172, pm-stack services) — this phase starts only when both have landed, hence status/blocked. This issue closes design #2835 with its evidence.

Scope

Inventory. Grep the repo's service/script entry points for every remaining numeric environment parse (Number(process.env…, Number(env.…, Number(s(env.…, parseInt(/parseFloat( on env values) in bin/, pm-stack/, pkgs/ service entry points and fleet scripts. Known remainder from the Design: env numbers are arguments — one strict parse for boot-time configuration #2835 audit (origin/main 69cc1813):
- pm-stack/aggregator/scripts/gather-quota.ts:103 — const timeoutMs = Number(process.env.QUOTA_GATHER_TIMEOUT_MS ?? 15_000); (bare; a NaN/negative/>2³¹ value reaches the gatherer's fetch deadlines unchecked).
- .opencode/skills/jules-automate-github-issues/scripts/fleet-merge.ts:28 — MAX_RETRIES = Number(process.env.FLEET_MAX_RETRIES ?? 2).
Disposition each site in the closing evidence on Design: env numbers are arguments — one strict parse for boot-time configuration #2835: converted to the contract (digits-only spelling, kind range — port 1–65535, millis 1–2³¹−1, count ≥1, id positive; boot failure naming the variable) or explicitly exempted with a named reason. Expected exemptions: test-only TEST_PORT (pkgs/id/e2e/playwright.config.ts:37, dev-only with a || 4173 fallback) and documentation examples (e.g. the Sentry reference under .agents/skills/). Sites that grew since the audit get the same disposition — converted, or filed as a named follow-up under Design: env numbers are arguments — one strict parse for boot-time configuration #2835 before this phase closes (never silently left).
Write the contract down where a new service meets it: a short "environment numbers" section in pm-stack/README.md, and the contract stated in the bin/proxy-port.mjs header alongside the existing bin proxies: *_PROXY_PORT parsed with bare parseInt — invalid values crash opaquely or bind the wrong port #483 note — antigravity-direct: ANTIGRAVITY_DIRECT_PORT / _TIMEOUT_MS are bare Number() — bypasses the house strict port helper, so bad ports crash with a stack or bind the wrong port, and bad timeouts start healthy then 502 every request #2823 happened because a new door never met the existing helper; the docs are the fix for that failure mode, not decoration.

Acceptance criteria

Inventory of numeric env parses (per the grep scope above) posted as evidence, every site dispositioned converted / exempted-with-reason; no site left undispositioned.
QUOTA_GATHER_TIMEOUT_MS (gather-quota.ts) and FLEET_MAX_RETRIES (fleet-merge.ts) parse per the contract (millis / count kinds), or carry a named exemption reason in the evidence.
pm-stack/README.md states the env-number contract (spelling, kind ranges, boot-failure rule) and bin/proxy-port.mjs's header states it for the bin/ family.
Design issue Design: env numbers are arguments — one strict parse for boot-time configuration #2835 is closed with this phase's evidence attached (its acceptance requires the audit evidence).

agent-note:v1 — filed by design-architect pass 22 (2026-10-30) as Phase 3 of #2835; status/blocked + queue/queued with a triage packet enqueued this pass — triage records the gating on Phases 1–2 and does not re-scope.

agent-note:v1 — design-architect pass 22 (2026-10-30): filed this pass as Phase 3 of design #2835 (env numbers are arguments). Gated on Phases 1–2 (Phase 1 = #2823 + #2786 + #1809 + #2096; Phase 2 = #2161 + #2758 + #2172), hence status/blocked; linked as a sub-issue of #2835 (verified in its sub_issues list). Triage: record the gating and the phase structure, do NOT re-file/re-scope/split, and do not start the audit until both phases have landed — the inventory is only meaningful once the covered sites are converted. The known remainder sites (gather-quota.ts:103, fleet-merge.ts:28) and expected exemptions (test-only TEST_PORT, docs examples) are named in this issue's body.

agent-note:v1 — triage verdict, queue task 3987 (repo-worker-code, openchamber-scheduled-lane, 2026-10-30).

Verdict: scope confirmed against current main; gating holds — issue stays status/blocked, no follow-up enqueued yet.

Revalidated against origin/main 07448571 (fresh gh + git grep, 2026-10-30):

Design Design: env numbers are arguments — one strict parse for boot-time configuration #2835 OPEN; all Phase 1 issues OPEN (antigravity-direct: ANTIGRAVITY_DIRECT_PORT / _TIMEOUT_MS are bare Number() — bypasses the house strict port helper, so bad ports crash with a stack or bind the wrong port, and bad timeouts start healthy then 502 every request #2823, opencode-route-proxy: OPENCODE_ROUTE_PROXY_TIMEOUT_MS is parsed with a bare Number() — a typo'd, negative, or >2^31 value starts healthy, then every routed request 'times out' in ~1ms and blames the leaf #2786, commandcode-proxy: COMMANDCODE_PROXY_TIMEOUT_MS is parsed with a bare Number() — a typo'd, negative, or >2^31 value makes every request 'time out' in ~1ms instead of failing at startup #1809, agy-proxy: four numeric env vars parsed with bare Number() — 'abc' disables the worker cap and idle eviction and freezes the model catalog, a typo'd turn timeout fires in ~1ms, and MAX_LIVE_WORKERS=0 crashes the eviction loop #2096) and all Phase 2 issues OPEN (aggregator(config): PM_AGG_PORT / PM_AGG_HOSTS are never validated — port 0 silently binds a random port, a typo crashes with a Bun RangeError that names neither variable, and an all-separator PM_AGG_HOSTS exits 0 serving nothing #2161, pm-dispatch(config): DISPATCH_PORT / DISPATCH_HOSTS are never validated — port 0 silently binds a random port, a typo crashes with a Bun RangeError naming neither variable, hex/scientific spellings become other ports, and an all-separator DISPATCH_HOSTS exits 0 serving nothing #2758, projector(config): PORT and GITHUB_APP_INSTALL_ID are never validated — PORT=0 silently binds a random port, typos crash with a RangeError naming neither variable, and a garbage install ID is silently treated as unset #2172). No open PR references any of the seven — neither phase has landed.
Every Phase 1 site is still a bare Number(): agy-proxy.mjs:168,453,456,457; antigravity-direct.mjs:60,62; commandcode-proxy.mjs:60; opencode-route-proxy.mjs:51.
Every Phase 2 site is still unvalidated: aggregator config.ts:68, dispatch config.ts:87, projector index.ts:6 + github.ts:121.
Phase 3 remainder sites confirmed present: pm-stack/aggregator/scripts/gather-quota.ts:103 (QUOTA_GATHER_TIMEOUT_MS) and .opencode/skills/jules-automate-github-issues/scripts/fleet-merge.ts:28 (FLEET_MAX_RETRIES).
Expected exemptions check out as described: pkgs/id/e2e/playwright.config.ts:37 is test-only TEST_PORT with || 4173 fallback; bin/proxy-supervise.test.mjs:33 (FAKE_PROXY_PORT) is likewise test-only.
Contract-doc targets exist: pm-stack/README.md present; bin/proxy-port.mjs header carries the bin proxies: *_PROXY_PORT parsed with bare parseInt — invalid values crash opaquely or bind the wrong port #483 strict-parse note the contract statement must sit alongside.

Gating recorded: this phase starts only when Phases 1–2 have landed. Per the design-architect note above (do NOT re-file/re-scope/split; do not start the audit early), the implementation follow-up packet is specified here but NOT enqueued while the gate is closed — a queued implementation task could be claimed and start the audit early. Enqueue the follow-up (acceptance criteria per this issue body, verification via repo test suites on CI) once #2823+#2786+#1809+#2096 and #2161+#2758+#2172 are all closed.

Labels: triage complete; in-flight labels removed, status/blocked retained until both phases land.

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-g
Session / ID: task 8615
Found via: queue claim
Task: task 8615 (triage, issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837) revalidated fresh: issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 OPEN, no hard-stop labels. Execution lane assigned opencode — handing off to the laptop claimant.
Expectation: claimant's bound session drives task 8615 to a terminal state.
Links: issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837

Re-claimed by lane code-k as task 8615 after the previous handoff lease lapsed unlaunched, and handed off to the opencode execution lane again: the laptop claimant will launch a bound session for task 8615. Issue #2837 is OPEN, labels already show queue/claimed + status/in-progress. Caution: task 8615 is at attempt 11 of 12 — one lapse from its cap; if this lease expires unlaunched, the attempt cap will need a raise before the task becomes unclaimable.

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-k
Session / ID: task 8615
Found via: queue claim
Task: Re-handing task 8615 (triage of issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 — Phase 3 of issue Design: env numbers are arguments — one strict parse for boot-time configuration #2835, closing inventory audit for the env-number contract) to the opencode execution lane after the previous handoff's lease lapsed with no session bound; the laptop claimant launches the bound opencode session. Attempt 13/24.
Expectation: effort/s — done looks like issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 triaged and routed: still-live confirmed with its Phase 1–2 gate state (antigravity-direct: ANTIGRAVITY_DIRECT_PORT / _TIMEOUT_MS are bare Number() — bypasses the house strict port helper, so bad ports crash with a stack or bind the wrong port, and bad timeouts start healthy then 502 every request #2823, opencode-route-proxy: OPENCODE_ROUTE_PROXY_TIMEOUT_MS is parsed with a bare Number() — a typo'd, negative, or >2^31 value starts healthy, then every routed request 'times out' in ~1ms and blames the leaf #2786, commandcode-proxy: COMMANDCODE_PROXY_TIMEOUT_MS is parsed with a bare Number() — a typo'd, negative, or >2^31 value makes every request 'time out' in ~1ms instead of failing at startup #1809, agy-proxy: four numeric env vars parsed with bare Number() — 'abc' disables the worker cap and idle eviction and freezes the model catalog, a typo'd turn timeout fires in ~1ms, and MAX_LIVE_WORKERS=0 crashes the eviction loop #2096, aggregator(config): PM_AGG_PORT / PM_AGG_HOSTS are never validated — port 0 silently binds a random port, a typo crashes with a Bun RangeError that names neither variable, and an all-separator PM_AGG_HOSTS exits 0 serving nothing #2161, pm-dispatch(config): DISPATCH_PORT / DISPATCH_HOSTS are never validated — port 0 silently binds a random port, a typo crashes with a Bun RangeError naming neither variable, hex/scientific spellings become other ports, and an all-separator DISPATCH_HOSTS exits 0 serving nothing #2758, projector(config): PORT and GITHUB_APP_INSTALL_ID are never validated — PORT=0 silently binds a random port, typos crash with a RangeError naming neither variable, and a garbage install ID is silently treated as unset #2172) checked, follow-up enqueued, or closed with evidence if already resolved.
Links: issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837, issue Design: env numbers are arguments — one strict parse for boot-time configuration #2835; no branch/PR yet

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-h
Session / ID: task 8615
Found via: queue claim
Task: Execution-lane assignment for task 8615 is opencode; handed off to the laptop opencode claimant, which launches the bound session that drives task 8615 to its terminal state.
Expectation: claimant launches the bound opencode session for issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837; this lane does no direct work on task 8615.
Links: issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-v
Session / ID: task 8615
Found via: queue claim
Task: Triage of issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 (Phase 3 of issue Design: env numbers are arguments — one strict parse for boot-time configuration #2835 — closing inventory audit for the env-number contract) handed off to the opencode claimant (execution lane assigned: opencode). Fresh revalidation by this lane: issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 still OPEN with the claim label set, no hard-stop labels; parent design issue Design: env numbers are arguments — one strict parse for boot-time configuration #2835 is still OPEN, so the audit's ordering against the earlier phases must be confirmed at current main before the audit is run or the issue is closed. No PR resolves issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 (search hit PR feat(openclaw): opencode-route provider proxy — OpenCode server front for OpenClaw (#2229) #2250 is unrelated).
Expectation: effort s — done when issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 is triaged with evidence: audit scoped/enqueued against the completed phases, or closed with evidence if already resolved.
Links: issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837; parent design issue Design: env numbers are arguments — one strict parse for boot-time configuration #2835 (OPEN)

Agent note — task 8615 handed off to opencode execution lane

Lane: code-v (repo-worker-code), claimed 2026-11-04
Execution-lane assignment (repo-queue lane task 8615): opencode
Per worker instruction §1b, this lane does not work the task directly and creates no worktree. The laptop opencode-claimant launches a session bound to task 8615 to drive it to a terminal state.
Checkpointed as handed_off. If the claimant has not launched by lease expiry, task 8615 returns to the queue.

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-v
Session / ID: task 8615
Found via: queue claim
Task: task 8615 (triage for issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837) is assigned to the opencode execution lane per repo-queue lane assignment; handing off to the laptop opencode claimant. Issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837 revalidated fresh this shift: OPEN, no hard-stop labels (held / user/owned / do-not-merge / do-not-auto-edit).
Expectation: claimant launches the bound opencode session and drives task 8615 to a terminal state.
Links: issue Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837

🤖 Agent note · handed off

Agent: fleet monitor
Session / ID: task 8615 (repo-fleet-monitor run 2026-11-05T15:45:48Z)
Found via: monitor reconciliation (Duty 1 claim/label divergence repair)
Task: Claim evaporated: task 8615 is queued and unclaimed in repo-health-code-pilot, but this issue still carried claimed labels. Labels reset to the truth (queue/queued + status/needs-triage). Checkpoint stage at evaporation: handed_off.
Expectation: The next lane claim picks task 8615 up from the queued state and posts a fresh pickup note.

Navigation Menu

Repository navigation

Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837

Phase 3 of #2835 — closing inventory audit for the env-number contract, and the contract written where the next service will meet it

Scope

Acceptance criteria

30 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837

Description

Phase 3 of #2835 — closing inventory audit for the env-number contract, and the contract written where the next service will meet it

Scope

Acceptance criteria

Activity

dezren39 commented on Oct 30, 2026

dezren39 commented on Oct 30, 2026

30 remaining items

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions