Skip to content

Commit fbc6f26

Browse files
authored
Merge pull request lidge-jun#2121 from lidge-jun/fix/native-main-gate-reason
fix(codex): name the native-main gate reason when the fence returns 503
2 parents 239cae9 + 745f6f6 commit fbc6f26

8 files changed

Lines changed: 614 additions & 1 deletion

File tree

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# 100 — Post-split rebase of the stack
2+
3+
## What changed under us
4+
5+
The mega-file split landed while this work was open:
6+
7+
| PR | Merge |
8+
|---|---|
9+
| #2019 WP1 types | `da86a830a` |
10+
| #2023 WP1b clusters | `2235f456d` |
11+
| #2036 WP2a config leaf | `eca18d0c8` |
12+
13+
`src/types/tools.ts` now exists on `dev` and `OcxTool` lives there. **#1934 also
14+
merged** (`a5289aad5`), which `070` had named as the real collision hazard for
15+
`#1587` — it touched all five of that fix's files.
16+
17+
So both of `#1587`'s blockers cleared at once. It moves from "last, most
18+
contested files" to implementable.
19+
20+
## Rebase
21+
22+
Bottom-up, three branches, **zero conflicts**:
23+
24+
```
25+
fix/service-proxy-env eb910776a -> d7caaa9bf
26+
fix/tray-registry-encoding e3b063750 -> f1f400fea
27+
fix/cursor-abort-teardown 346eaa80d -> 2c4e00ede
28+
```
29+
30+
Zero conflicts is the expected result and not the interesting part: none of the
31+
three fixes touches `types.ts`, `config.ts`, or anything the split moved. That
32+
was the collision analysis in `070`, and it held.
33+
34+
## The verification that actually mattered
35+
36+
A green result from *before* the rebase proves nothing here — the split replaced
37+
`types.ts` with a barrel and moved every type cluster, so the whole tree these
38+
branches compile against is different.
39+
40+
Re-run on the rebased top of stack:
41+
42+
```
43+
bun test service + tray + windows-text + cursor-cancel + cursor-eof
44+
163 pass / 0 fail
45+
bun x tsc --noEmit
46+
exit 0
47+
```
48+
49+
## Deferred items: what is still blocked
50+
51+
Re-checked live rather than carried from the previous turn:
52+
53+
| PR | State | Consequence |
54+
|---|---|---|
55+
| #2029 | OPEN, `CHANGES_REQUESTED` | `#2114` still must not get a competing PR |
56+
| #2101 | OPEN | `#2108` phase 1 still collides on `server/index.ts` + `auth-context.ts` |
57+
| #2054 | OPEN, `CHANGES_REQUESTED` | the kimi-k3 and 429 halves of `#1527` still cannot start |
58+
59+
Only `#1587` actually became unblocked. The other three deferrals stand for the
60+
same reasons they were recorded, which is worth stating explicitly — "the split
61+
landed" is not a general unblock.
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 110 — #2114 disposition: unblock, do not compete
2+
3+
Outcome: **no code PR.** Two comments — the containment on #2029
4+
(`5342888183`) and the ownership record on #2114 (`5342892253`).
5+
6+
## What the reviewer actually objected to
7+
8+
Read rather than summarized. @Ingwannu on #2029:
9+
10+
> A missing user bus does not prove that `~/.config/systemd/user/opencodex-proxy.service`
11+
> is absent. The definition can remain on disk while the user manager is
12+
> unavailable, and it can name another `CODEX_HOME` or `OPENCODEX_HOME`.
13+
> Returning absent before inspecting that artifact lets the ownership preflight
14+
> treat the machine as unclaimed and overwrite a foreign or interrupted
15+
> installation.
16+
17+
That is the same hazard `020` arrived at independently and wrote down as
18+
"test 3". Two people reaching it separately is the strongest signal in this
19+
whole unit that it is the real constraint.
20+
21+
## The finding that made this a comment instead of a PR
22+
23+
The reviewer asked for: inspect the unit file, absent → `absent`, exists →
24+
present claim with registration absent, unreadable → `unknown`.
25+
26+
**`inspectSystemd` already does exactly that**, at lines 289-313 — check
27+
`artifactPresence(definitionPath)`, `readFileSync`, parse
28+
`unitEnvValue(body, "CODEX_HOME")` and `OPENCODEX_HOME`, return a `present`
29+
claim. The no-bus branch simply returns before reaching it.
30+
31+
So the containment needs **no new machinery** — only a different control path
32+
through code that is already there. A separate PR would have re-implemented
33+
something sitting twenty lines below.
34+
35+
## Why not just open our own PR anyway
36+
37+
#2114 and #1939 are one classifier with two symptoms: a refused sync there, a
38+
process-lifetime native-main 503 here. A second PR on the same function means
39+
two people making the same fail-closed security-adjacent call, and whichever
40+
lands second silently overwrites the first.
41+
42+
The stderr shapes make the overlap concrete. #2029 matches two messages and
43+
pins everything else as `unknown`; #2114's shape is a third
44+
(`Failed to connect to user scope bus via local transport…`) and is currently
45+
on the pinned side.
46+
47+
## What was offered
48+
49+
- The concrete code shape, reusing the existing helpers.
50+
- The locale-fragility tradeoff **stated rather than hidden**: string matching
51+
will miss a non-English systemd. Worth noting that with the disk check, a
52+
mismatch degrades to a missed recovery rather than a wrong admission — which
53+
is a much safer thing to be locale-sensitive about. Alternative named
54+
(`LC_ALL=C`) without pretending it is free.
55+
- Six regressions, including the #2114 stderr and the existing
56+
non-bus-non-zero assertion kept as the over-widening guard.
57+
- A rebase note: the review's "125 commits behind" is stale, but `dev` has since
58+
taken the split, so a rebase is needed regardless.
59+
60+
## What was deliberately not done
61+
62+
No push to a contributor branch, no competing PR, and #2114 left **open and
63+
linked** rather than closed as a duplicate — the 503 symptom is distinct enough
64+
that someone hitting it should find that thread rather than a redirect.
Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# 120 — #2108 phase 1: log the concrete native-main gate reason
2+
3+
Work-phase `wp2108`. One PABCD cycle. Phase 2 (retryable boot-time `unknown`)
4+
is explicitly NOT in this cycle.
5+
6+
**Revision note.** The first draft of this doc proposed a response header
7+
`x-ocx-native-main-gate-reason` alongside the log line. An adversarial audit
8+
returned `fail` and it was correct; the header is removed. What follows is the
9+
design that survived, with the refutation recorded because it is the reason the
10+
scope is what it is.
11+
12+
## The decision that gated this cycle
13+
14+
`040_2108_windows_reboot_gate.md` said: check PR #2101 before starting, because
15+
it edits both files phase 1 touches.
16+
17+
**#2101 is still OPEN** (`REVIEW_REQUIRED`, head `ingw/fix-daybreak-account-entitlement`,
18+
1397 lines, last touched 2026-08-19T12:00:56Z). The collision is real, so the
19+
only question is whether it is avoidable.
20+
21+
Its hunks in `src/codex/auth-context.ts` cover, in old-file lines: 23-28,
22+
237-242, 260-267, 273-278, 302-308, 312-318, 325-330. Its hunks in
23+
`src/server/index.ts` cover 58, 894, 906, 940, 957, 971, 1038.
24+
25+
**`auth-context.ts:115-131` is clear** — nearest hunk edges are 28 and 237.
26+
This cycle changes nothing else, in any file.
27+
28+
That is what makes this an implement rather than a defer. All three throw sites
29+
sit in or beside #2101's hunks: `:313` (inside 312-318), `:319` (one line past
30+
that hunk, still inside its rebase blast radius), and `:326` (inside 325-330).
31+
A design that had to edit any of them would have been a defer.
32+
33+
## What ships
34+
35+
One file: `src/codex/auth-context.ts`, lines 115-131 only. No other production
36+
file, and no signature any other file calls.
37+
38+
### The reason is captured and logged in the constructor
39+
40+
`CodexMainProfileDrainingError` has a zero-arg constructor today. It gains:
41+
42+
- a `readonly reason?: NativeMainStartupBlockReason`, read from
43+
`nativeMainStartupGateSnapshot()` **in the constructor**;
44+
- one `console.warn` naming that reason, deduped per distinct reason.
45+
46+
Capturing in the constructor is the whole design. It is the only moment where
47+
the reason is both in scope and true — every catch site has already lost it, and
48+
re-reading the gate later can observe a different value.
49+
50+
### Why there is no header
51+
52+
The first draft wanted a header so the reason would be machine-readable. Three
53+
findings killed it, and each one independently:
54+
55+
**It cannot reach the caller without editing five files.**
56+
`codexMainProfileDrainingResponse()` is called with zero arguments at
57+
`core.ts:1121`, `compact.ts:390`, `search.ts:126`, `live.ts:542`,
58+
`images.ts:441`. Threading a reason means editing all five — and `core.ts` and
59+
`compact.ts` are both edited by #2101. The collision we set out to avoid comes
60+
straight back.
61+
62+
**Having the response re-read the gate is worse, not cheaper.** It looks like a
63+
one-file fix, but `nativeMainStartupGateSnapshot()` returns fresh state each
64+
call and `completeNativeMainRecovery()` can flip it to `ready` between the throw
65+
and the catch. The header would then be blank or wrong exactly when recovery is
66+
racing — which is the scenario #2108 is about.
67+
68+
**It would not reach the Claude surface anyway.** `claude-messages.ts:823-829`
69+
builds a new `Response` with a hand-written header object carrying only
70+
`Content-Type` and `Retry-After`; every other header is dropped. The WebSocket
71+
fence path exposes no response headers at all.
72+
73+
So the log line is not a consolation prize. It is the only surface that reaches
74+
every path this fence can fire on.
75+
76+
### Why not the message, and why not `/api/logs`
77+
78+
Both are closed off, which is worth stating because they are the obvious first
79+
guesses.
80+
81+
**The message must not change.** `claude-messages.ts:818-820` identifies this
82+
response by `message === CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE`. Break that
83+
match and `isTransientUpstreamStatus(503)` takes over, remapping the fence to
84+
Anthropic 529 — a local maintenance state would start telling Claude Code to
85+
back off and retry an upstream that was never involved.
86+
87+
**`/api/logs` cannot carry it either.** `upstreamError` is populated by reading
88+
the response body back and taking `json.error.message` and nothing else
89+
(`request-log.ts:755-759`, via `relay.ts:434-442`). Headers are already gone.
90+
`error.code` is likewise filtered: `requestLogErrorCode` pins 503 to
91+
`server_is_overloaded` and refuses to forward arbitrary codes by design
92+
(`request-log.ts:508-540`, comment at :514).
93+
94+
That leaves stdout — which is where the reporter was reading anyway. Their
95+
excerpt interleaves `[17:25:23] opencodex service wrapper start` with the 503
96+
lines, so a `console.warn` lands in the stream they already quoted.
97+
98+
### Dedup, and the site that has no reason
99+
100+
Deduped per distinct reason: the reporter's log shows three 503s in eleven
101+
seconds and a real client retries harder than that. A per-request line buries
102+
the signal it exists to produce. Dedup state is module-level, so the module
103+
exports a reset for tests — otherwise the second test in a Bun process observes
104+
nothing and the assertion passes vacuously.
105+
106+
The third throw site, `:326`, fires when `claimMainProfile()` refuses. That is
107+
the **turn-drain** fence (`lifecycle.ts:180`), not the startup gate — line 318
108+
has already established `nativeMainTrafficBlocked` is false there, so the
109+
snapshot reads `ready` and carries no reason.
110+
111+
That site must stay silent. Constructor capture gets this right by
112+
construction: a reason is recorded only when the snapshot is `blocked`. A 503
113+
with no reason therefore means "not the startup fence", which is itself a
114+
distinction #2108 needs — the reporter could not make it.
115+
116+
Only `reason` is emitted. The snapshot also carries `homeId`, which is derived
117+
from a profile directory path and has no business in a log line.
118+
119+
## Why logging and not the mechanism
120+
121+
The trigger is still unidentified. `040` names two candidates that settle to
122+
different reasons: ACL fail-closed gives `owner-unavailable`
123+
(`native-profile-startup.ts:138-139`), probe fail-closed gives
124+
`ownership-unknown` (`:311`). One log line separates them.
125+
126+
**No test anywhere asserts `owner-unavailable`.** It is produced at
127+
`native-profile-startup.ts:139` and asserted nowhere in the suite — the
128+
candidate branch we most need named in the field is the one with no coverage.
129+
130+
## Test plan
131+
132+
Drive the real gate, never a module mock — the existing tests already do this
133+
(`tests/codex-auth-context.test.ts:250-254` via
134+
`initializeNativeMainStartupGate({ probeRecoveryState: () => "manual" })`,
135+
`tests/native-profile-startup.test.ts:291-292` via
136+
`blockNativeMainStartupForUnownedServiceHome`). Capture the log with a local
137+
`spyOn(console, "warn")`, the repo idiom (`app-owned-memory.test.ts:237`).
138+
139+
1. `ownership-unknown` fence → `err.reason` is `ownership-unknown` **and the
140+
warn fires carrying it**. The log assertion is the deliverable; without it
141+
this cycle ships something unobserved.
142+
2. `foreign-ownership` fence → same, different value. Proves the value is read
143+
rather than hardcoded.
144+
3. Second construction under the same reason → no second warn. Pins the dedup.
145+
4. No fence active → no reason, no warn. Pins the `:326` turn-drain case.
146+
5. Message, status, `Retry-After` unchanged. This is the claude-messages guard.
147+
Worth knowing it is weaker than it sounds: grepping
148+
`tests/claude-messages-endpoint.test.ts` for `nativeMainFence`, `529`, or the
149+
message constant returns nothing, so the 503→529 remap has no direct
150+
regression test of its own.
151+
152+
**Red-drive is mandatory.** Lesson 1 of this session: the first #1527 attempt
153+
patched a helper that was not on the failure path and all ten tests still
154+
passed. Each assertion must be seen failing before the fix.
155+
156+
## Verification
157+
158+
```
159+
bun test tests/codex-auth-context.test.ts tests/native-profile-startup.test.ts tests/native-profile-drain-server.test.ts
160+
bun x tsc --noEmit
161+
bun run privacy:scan
162+
```
163+
164+
`privacy:scan` is not ceremony here — this cycle adds a log statement, which is
165+
the exact thing that scan exists to police.
166+
167+
CI is ignored this cycle by standing instruction while the merge train churns;
168+
local green is the judgment surface.
169+
170+
## Stack position
171+
172+
Stacks on `fix/cursor-abort-teardown` (#2118), targeting it. Retarget to `dev`
173+
after the parents land.
174+
Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# 121 — #2108 phase 1 implementation record
2+
3+
Shipped: PR [#2121](https://github.com/lidge-jun/opencodex/pull/2121), commit
4+
`18a383e8e`, branch `fix/native-main-gate-reason` stacked on
5+
`fix/cursor-abort-teardown` (#2118).
6+
7+
Issue disposition posted:
8+
[#2108 comment 5343287759](https://github.com/lidge-jun/opencodex/issues/2108#issuecomment-5343287759).
9+
`Refs`, not `Closes` — this makes the next occurrence diagnosable, it does not
10+
stop the fence sticking.
11+
12+
## What the plan audit changed
13+
14+
Draft 1 of `120` proposed a response header `x-ocx-native-main-gate-reason`
15+
alongside the log line. The A-gate audit returned **fail**, and the header was
16+
dropped entirely. The refutation is worth keeping because it is not obvious:
17+
18+
- The header cannot reach the caller without editing the five zero-arg
19+
`codexMainProfileDrainingResponse()` call sites — and `core.ts`/`compact.ts`
20+
are both edited by #2101, so the collision the whole design existed to avoid
21+
came straight back.
22+
- Having the response builder re-read the gate instead *looks* like a one-file
23+
fix, but `completeNativeMainRecovery()` can flip the snapshot to `ready`
24+
between throw and catch. The header would go blank or wrong exactly when
25+
recovery is racing, which is the scenario #2108 is about.
26+
- It would not reach the Claude surface anyway: `claude-messages.ts:823-829`
27+
rebuilds its response with a hand-written header object.
28+
29+
The audit also caught a third throw site the plan had missed (`:326`,
30+
turn-drain), that the `console.warn` assertion — phase 1's entire purpose — was
31+
absent from the test plan, and that `privacy:scan` was missing from a cycle
32+
whose only product is a log statement.
33+
34+
Round 2 returned **pass**, and the reviewer went further than asked: it copied
35+
`src`/`tests` to a scratch tree and mutated them there. Removing the
36+
`console.warn` body goes red (2 fail); removing the dedup check goes red. That
37+
is stronger evidence than my own red-drive, because it tests the assertions
38+
rather than the fix.
39+
40+
## The shipped shape
41+
42+
`src/codex/auth-context.ts:115-166` only, plus a derived type export in
43+
`native-profile-startup.ts` and the tests.
44+
45+
`CodexMainProfileDrainingError` reads `nativeMainStartupGateSnapshot()` in its
46+
constructor, records `reason` when the gate is `blocked`, and warns once per
47+
distinct reason. Every call site — 3 constructions, 5 response builders — is
48+
byte-identical.
49+
50+
The `:326` turn-drain site stays silent by construction (early return on
51+
`status !== "blocked"`), which makes a reasonless 503 mean "not the startup
52+
fence". That distinction did not exist before and the reporter could not make it.
53+
54+
## Collision outcome
55+
56+
`git diff -U0` puts this change at old-file lines 15 and 118-124. #2101's
57+
`auth-context.ts` hunks are 23-28, 237-242, 260-267, 273-278, 302-308, 312-318,
58+
325-330. Zero overlap, no adjacency. `native-profile-startup.ts` is not among
59+
#2101's 20 files. In the test file both PRs add imports around lines 59-63,
60+
which merges cleanly.
61+
62+
## Verification
63+
64+
204 pass / 0 fail / 903 expect() across the five native-main gate suites plus
65+
`chat-completions-endpoint` and `claude-messages-endpoint`. `tsc --noEmit`
66+
exit 0. `privacy:scan` exit 0.
67+
68+
Red-drive: with the fix staged as a no-op export, 2 fail on
69+
`reason === undefined` and the silence case passed — the assertions were doing
70+
the work, not a module-load error.
71+
72+
**Coverage caveat, stated in the PR too:** macOS only. `owner-unavailable` is a
73+
Windows icacls path, and nothing in the suite asserts it — it is produced at
74+
`native-profile-startup.ts:139` and asserted nowhere. The branch the reporter
75+
most likely hit is the one with no coverage, which is the argument for shipping
76+
the diagnostic before the mechanism.
77+
78+
## Stack correction worth recording
79+
80+
The commit first landed on `fix/cursor-abort-teardown` itself rather than a new
81+
branch. Corrected by `git switch -c fix/native-main-gate-reason` followed by
82+
`git branch -f fix/cursor-abort-teardown origin/fix/cursor-abort-teardown` —
83+
resetting the local branch to its already-pushed head, no force-push, no
84+
contributor branch touched. Caught by reading `git log` after the commit rather
85+
than assuming the branch was where I left it.
86+
87+
## What phase 2 needs
88+
89+
A field report that names a reason. Phase 2 makes a boot-time `unknown`
90+
retryable while `OCX_SERVICE=1` instead of a process-lifetime fence, keeping
91+
genuine `foreign` fail-closed with a retry cap. Two narrower fixes stand on
92+
their own: a timed-out `sc.exe query` with WinSW xml and exe both absent must
93+
not mark the machine `unknown`, and a second ACL `ETIMEDOUT` should back off
94+
and retry so a warm icacls reopens the gate without `ocx restart`.
95+

0 commit comments

Comments
 (0)