Skip to content

Commit 9c8bbbf

Browse files
authored
docs(devlog): record the v2.39.0 release train (#3126)
* docs(devlog): plan the v2.39.0 release train * docs(devlog): record the five-lane v2.39.0 regression audit * docs(devlog): close the v2.39.0 release train with the shipped outcome * docs(devlog): name the server-auth flake follow-up * docs(devlog): record the executed preview promotion * docs(devlog): record the executed main promotion * docs(devlog): record the executed publish
1 parent 3e0f99a commit 9c8bbbf

7 files changed

Lines changed: 501 additions & 0 deletions

File tree

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# 260901 — v2.39.0 release train: audit, promote, publish
2+
3+
Snapshot taken 2026-09-01T01:35Z. This unit carries `dev` to `preview` and `main` and
4+
publishes 2.39.0 to npm. It is a delivery unit, not a bug-fix unit: no product code is
5+
written here unless the regression audit produces a blocker.
6+
7+
## Measured state
8+
9+
| Ref | SHA | `package.json` |
10+
|-----|-----|-----------------|
11+
| `origin/dev` | `9af3a7bebb5eb6e9bb9aab51274586897eaaba03` | `2.39.0` |
12+
| `origin/main` | `ebb4d552e` | `2.38.0` |
13+
| `origin/preview` | `93704b4f8` | `2.38.0-preview.20260831` |
14+
15+
Promotion delta `origin/main...origin/dev`: 43 commits, 252 files, +18668/-513.
16+
Neither `main` nor `preview` is an ancestor of `dev` — both carry their own release
17+
commits, which is the normal shape here. Every promotion in this repository is a merge
18+
of `dev` into a promotion branch, then a PR into the target.
19+
20+
### Gate evidence at the `dev` head
21+
22+
Cross-platform CI run `33457563882` on `9af3a7beb`: **success**. Every job passed —
23+
four test shards, `macos`, `gates`, `storage policy`, `api usage`, keyring on all three
24+
OSes, `npm-global` on all three OSes. The Windows shard matrix is `skipped`, which is its
25+
normal push-event state; `platform-windows` is `workflow_dispatch`-only.
26+
27+
No Service lifecycle run exists for `9af3a7beb` — that workflow's push trigger is
28+
path-filtered and the head commit touched none of its paths.
29+
30+
## The preview channel is two cycles stale, and that is not an accident
31+
32+
npm currently advertises `latest=2.38.0` and `preview=2.36.0-preview.20260830`.
33+
34+
The cause is recorded in CI, not in npm. `origin/preview` tip `93704b4f8` carries
35+
`2.38.0-preview.20260831`, but its push-event Cross-platform CI run `33386559501`
36+
**failed**: jobs `macos` and `test 1/4` failed while every other job passed.
37+
`release.yml` requires a *successful* `push`-event `ci.yml` run for the exact SHA on
38+
the release branch, and deliberately refuses a green pull-request run for the same SHA.
39+
So the v2.38.0 preview publish was never dispatchable. The stable publish was unaffected
40+
because `main`'s own promotion run `33385192526` passed.
41+
42+
PR #3073's description already documents an intermittent macOS failure in
43+
`tests/shutdown-launcher.test.ts` that does not reproduce on Linux. Lane E confirms
44+
whether run `33386559501` is that same flake or a real defect before we treat the
45+
preview promotion as routine.
46+
47+
## What the release workflow actually demands
48+
49+
From `.github/workflows/release.yml`, a dispatch must satisfy all of:
50+
51+
1. `expected-sha` — required, full 40 characters, and it must still be the branch tip.
52+
The guard checks out `.github/scripts/release-dispatch-guard.cjs` from the default
53+
branch, so the validation code is `main`'s, not the dispatched ref's.
54+
2. Branch/version/dist-tag coupling. From `main`: stable semver only, dist-tag `latest`.
55+
From `preview`: the version must contain `-preview.`, dist-tag `preview`. Any other
56+
ref is refused outright.
57+
3. A successful `ci.yml` run for the exact SHA, on that branch, from a `push` event.
58+
4. The service gate, when armed. It diffs the previous *merged* release tag against
59+
`HEAD` and, if any of `src/service.ts`, `src/cli.ts`, `src/cli/index.ts`,
60+
`src/lib/bun-runtime.ts`, `package.json`, `bun.lock`,
61+
`.github/workflows/service-lifecycle.yml` changed, demands a successful
62+
Service lifecycle run for the same SHA.
63+
64+
**The service gate will be armed for this release.** Measured against the delta:
65+
`package.json`, `src/cli/index.ts` and `src/service.ts` are all present. Both promotion
66+
commits therefore need a green Service lifecycle run of their own, and the push trigger
67+
will supply it because those same paths are in the merge.
68+
69+
Publication is tokenless via Trusted Publishing (OIDC); there is no `NPM_TOKEN` to check.
70+
71+
## Work phases
72+
73+
One phase, one full PABCD cycle.
74+
75+
- **wp0** — this roadmap. Docs only.
76+
- **wp1** — regression audit of the promotion delta, five parallel `gpt-5.6-sol`/high
77+
lanes, plus a gate determination. → `010`
78+
- **wp2** — promote `dev` onto `preview`, publish nothing yet. → `020`
79+
- **wp3** — promote `dev` onto `main`. → `030`
80+
- **wp4** — dispatch `release.yml` twice and prove the publish. → `040`
81+
82+
## Success criteria
83+
84+
- c-1 — every audit lane returns a verdict with file/line citations, and no blocker survives.
85+
- c-2 — the gates `release.yml` requires are green on each promotion SHA.
86+
- c-3 — `origin/preview` tip is the preview promotion SHA and its push CI is green.
87+
- c-4 — `origin/main` tip is the stable promotion SHA and its push CI is green.
88+
- c-5 — npm shows `latest=2.39.0` and `preview=2.39.0-preview.20260901`, each
89+
`gitHead` matching its promotion SHA.
90+
91+
## Out of scope
92+
93+
Merging any of the 20 open feature/fix PRs. Rewriting `dev` history. Touching product
94+
code absent a confirmed blocker. Running the full local suite — hosted exact-SHA CI is
95+
the primary evidence surface for this unit.
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# wp1 — Regression audit of the promotion delta
2+
3+
## Question this phase answers
4+
5+
Does `origin/main...origin/dev` contain anything a 2.38.0 user would experience as
6+
breakage? Green CI is necessary and not sufficient: the suite proves the tests that exist
7+
still pass, not that a behavior change is safe.
8+
9+
## Method
10+
11+
Five read-only `gpt-5.6-sol` lanes at `high` effort, dispatched in parallel with disjoint
12+
file scopes so no two lanes audit the same diff.
13+
14+
| Lane | Scope | Focus commits |
15+
|------|-------|---------------|
16+
| A | `src/responses/`, `src/server/responses/`, `src/router.ts`, `src/routing/`, `src/adapters/`, `src/vision/` | `9af3a7beb` modalities image input, `e9d198a3c` private-metadata strip, `5c0c13194` unreadable MESSAGE reply, `a0d386b49` web_search_call query, `5f0b39048` spill byte cap, `42ad9c44d` burst window, `b46164e78` dated-variant fold, `a3656a92c` cursor eof retry |
17+
| B | `src/oauth/`, `src/codex/`, `src/config/` | the eight-commit Anthropic refresh-intent stack, `a73a4c998` WHAM-401 refresh-before-quarantine, `6123be31f` session_meta by thread id |
18+
| C | `src/cli/`, `src/service.ts`, `src/update/`, `src/lib/` | `0ef04e640` start-shadowing, `330470e74` typed stop outcome, `91b2c4e19` terminal conflict resolve, `71bd7bec6` version bump |
19+
| D | `gui/`, `docs-site/` | `0db8066c0` logs filter, `b6e53d8eb` restore focus, the brand-mark series, `2a90cdaa9` conflicted-config overwrite |
20+
| E | `.github/workflows/` + npm/CI forensics | the stale preview tag and the exact dispatch shape |
21+
22+
Lane A owns the riskiest surface. The dated-variant fold now folds in both directions and
23+
at both widths — a mis-fold there collides two model ids and routes a request to the wrong
24+
model, which no test would necessarily catch. The spill byte cap introduces eviction into
25+
a directory an in-flight response reads from; eviction that outruns a reader loses response
26+
bytes. The burst-window change converts an `unknown` into an `exhausted`, and a false
27+
`exhausted` parks a healthy provider.
28+
29+
Lane B owns the highest-consequence surface. Eight commits reshape when the Anthropic
30+
refresh-intent marker is written, preserved, and cleared. The failure mode that matters is
31+
not a crash: it is a valid credential deleted or masked, so the user is silently logged out
32+
and must re-auth. `a41b7995c` (adopt newer disk credentials before cleanup) and
33+
`e476acd43` (keep post-commit cleanup from masking a durable credential) are the two
34+
commits whose interaction decides this.
35+
36+
Lane C also produces a mechanical determination the release depends on: whether the
37+
Service lifecycle gate is armed. Answer already measured — it is.
38+
39+
## Acceptance
40+
41+
Every lane returns `VERDICT: PASS` or `VERDICT: FAIL` with per-finding severity and
42+
file:line citations. Blocker findings are independently verified against the source
43+
before they change the plan; a lane's assertion is a hypothesis until the main session
44+
reads the same lines. A confirmed blocker becomes a new work phase ahead of wp2 and the
45+
promotion waits.
46+
47+
## What would make this phase fail honestly
48+
49+
A lane that reports `PASS` with no evidence of what it read is not a pass. A lane that
50+
times out is a failed dispatch, not a silent approval, and gets re-spawned once with the
51+
failure folded into the packet.
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# wp2 — Promote `dev` onto `preview`
2+
3+
## Preconditions
4+
5+
wp1 closed with no surviving blocker. `origin/dev` still at `9af3a7beb`; if it moved,
6+
re-measure before branching — the promotion is of a specific tree, not of a branch name.
7+
8+
## Version
9+
10+
`preview` must carry a `-preview.` version or `release.yml` refuses the dispatch.
11+
Prior names are date-suffixed: `v2.38.0-preview.20260831`, `v2.36.0-preview.20260830`,
12+
`v2.36.0-preview.20260829`, `v2.34.0-preview.20260827`. Today's is
13+
**`2.39.0-preview.20260901`**.
14+
15+
This means the promotion branch is not a byte-identical copy of `dev`: `package.json`
16+
carries `2.39.0` on `dev` and must read `2.39.0-preview.20260901` on `preview`. That
17+
one-line difference is the only intended divergence.
18+
19+
## Steps
20+
21+
1. `git fetch origin`, branch `codex/promote-preview-23900901` from `origin/preview`.
22+
2. Merge `origin/dev` into it. Expect exactly one conflict — `package.json` version —
23+
resolved to `2.39.0-preview.20260901`. Any other conflict is unexpected and stops
24+
this phase for inspection.
25+
3. Verify the tree matches `dev` except for that version line:
26+
`git diff origin/dev HEAD -- . ':!package.json'` must be empty.
27+
4. Push, open the PR against `preview`.
28+
5. `enforce-target` will fail and convert the PR to draft — `ALLOWED_BASES` is
29+
`["dev"]`. This is expected for every promotion PR and was handled identically for
30+
#3001, #3037, #3072, #3073. `gh pr ready`, then admin merge.
31+
6. Wait for the **push-event** Cross-platform CI run on the resulting merge commit, and
32+
for Service lifecycle, which will be triggered because `package.json`,
33+
`src/cli/index.ts` and `src/service.ts` are in the merge.
34+
35+
## The failure this phase exists to not repeat
36+
37+
v2.38.0's preview promotion merged and then its CI failed, so the publish was never
38+
dispatchable and the preview dist-tag silently stayed two cycles behind. A merged
39+
promotion branch is not a releasable one. This phase is complete only when the promotion
40+
SHA has a green push-event `ci.yml` run, not when the PR is merged.
41+
42+
If the macOS/shard failure recurs on the new promotion commit, rerun the failed jobs once
43+
(`gh run rerun <id> --failed`). A second failure at the same assertion is a real defect
44+
and escalates to a new work phase rather than being re-run until green.
45+
46+
## Evidence to capture
47+
48+
- promotion merge SHA and `git ls-remote origin refs/heads/preview`
49+
- `gh api actions/runs?head_sha=<sha>` showing `Cross-platform CI: success` (push) and
50+
`Service lifecycle: success`
51+
- the `package.json`-only diff proof from step 3
52+
53+
## Executed
54+
55+
PR #3123, merged at `75f3895c14965205be694e8ebb8e93f472630539`. The merge produced
56+
exactly the one predicted conflict (`package.json`), resolved to
57+
`2.39.0-preview.20260901`; `git diff origin/dev HEAD -- . ':!package.json'` was empty.
58+
`bun test tests/release-version-line.test.ts` passed 3/3 on the branch before push —
59+
the same file that refused v2.38.0's preview.
60+
61+
Push-event Cross-platform CI: run `33462203719`, success on rerun. Service lifecycle:
62+
success. The first attempt failed on `tests/server-auth.test.ts:2288`, analyzed in
63+
`070_outcome.md` and not a regression in this delta.
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# wp3 — Promote `dev` onto `main`
2+
3+
## Preconditions
4+
5+
wp2 closed: `origin/preview` is at the preview promotion SHA with green push CI and
6+
green Service lifecycle. wp1 produced no surviving blocker.
7+
8+
`preview` being green is not a precondition `release.yml` enforces for the stable
9+
publish — the two channels gate independently, and v2.38.0 shipped stable while its
10+
preview was red. We sequence preview first anyway: it is the cheaper place to discover
11+
that a promotion merge breaks something.
12+
13+
## Version
14+
15+
`main` requires stable semver and dist-tag `latest`. `dev` already carries `2.39.0`,
16+
so the merge should be clean with no version conflict — the same shape as v2.38.0, whose
17+
promotion PR recorded "the tree is byte-identical to `dev`".
18+
19+
## Steps
20+
21+
1. Branch `codex/promote-main-2390` from `origin/main`.
22+
2. Merge `origin/dev`. Expect no conflict. Verify `git diff origin/dev HEAD` is empty —
23+
the promoted tree should be byte-identical to `dev`.
24+
3. Push and open the PR against `main`, with a description that names what ships: the
25+
43-commit delta, the bug fixes, and any residual the audit recorded rather than hid.
26+
4. `enforce-target` fails and drafts the PR, as on every promotion. `gh pr ready`, then
27+
admin merge.
28+
5. Wait for push-event Cross-platform CI and Service lifecycle on the merge commit.
29+
30+
## Evidence to capture
31+
32+
- merge SHA, `git ls-remote origin refs/heads/main`
33+
- `gh api actions/runs?head_sha=<sha>` with both workflows `success`
34+
- the empty-diff proof from step 2
35+
36+
## Stop conditions
37+
38+
A failing job on the promotion commit that is not the documented macOS launcher flake
39+
stops the train here. `main` is the release branch; a red `main` is worse than a late
40+
release, and `release.yml` would refuse the dispatch regardless.
41+
42+
## Executed
43+
44+
PR #3125, merged at `af6113a0381d6fff2e4dce587652825c7eeb6423`. The merge was clean
45+
with no version conflict and `git diff origin/dev HEAD` was empty — the promoted tree
46+
is byte-identical to `dev`, as predicted.
47+
48+
Push-event Cross-platform CI: run `33463473330`, success on rerun. Service lifecycle:
49+
success. The first attempt failed on the Linux `test 3/4` shard, same
50+
`tests/server-auth.test.ts:2288` assertion the preview run hit on macOS — which is how
51+
we learned the flake is cross-platform rather than macOS-specific. The PR run for the
52+
identical tree had already passed `macos` and every shard, which is the contrast that
53+
made the flake diagnosis defensible rather than convenient.
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# wp4 — Dispatch `release.yml` and prove the publish
2+
3+
## Order
4+
5+
Preview first, then stable. `release.yml` declares `concurrency: group: release` with
6+
`cancel-in-progress: false`, so a second dispatch queues behind the first rather than
7+
cancelling it — but serializing them by hand keeps the evidence unambiguous about which
8+
run published what.
9+
10+
## Dispatches
11+
12+
```sh
13+
gh workflow run release.yml --ref preview \
14+
-f version=2.39.0-preview.20260901 \
15+
-f tag=preview \
16+
-f dry-run=false \
17+
-f expected-sha=<preview promotion SHA, full 40 chars>
18+
19+
gh workflow run release.yml --ref main \
20+
-f version=2.39.0 \
21+
-f tag=latest \
22+
-f dry-run=false \
23+
-f expected-sha=<main promotion SHA, full 40 chars>
24+
```
25+
26+
`dry-run` defaults to `true`; it must be passed explicitly as `false` or the workflow
27+
builds and packs without publishing. `expected-sha` is required and must be the current
28+
branch tip — if anything lands on the branch between promotion and dispatch, the guard
29+
fails the run rather than publishing a different tree than the one audited. That is the
30+
intended behavior, not an obstacle to work around.
31+
32+
## Proof of publish
33+
34+
Merged source is not a deployed package. Required evidence:
35+
36+
```sh
37+
npm view @bitkyc08/opencodex dist-tags --json # latest=2.39.0, preview=2.39.0-preview.20260901
38+
npm view @bitkyc08/[email protected] gitHead # == main promotion SHA
39+
npm view @bitkyc08/[email protected] gitHead
40+
gh release list --limit 5 # v2.39.0 tagged
41+
gh run view <release run id> --json conclusion
42+
```
43+
44+
A `gitHead` that does not match the promotion SHA means something other than the audited
45+
tree was published, and is a stop-everything condition.
46+
47+
## Known non-blocker
48+
49+
`preview=2.36.0-preview.20260830` on npm today is two cycles stale because v2.38.0's
50+
preview CI failed (unit `000`). Publishing `2.39.0-preview.20260901` moves the tag
51+
forward and closes that gap; 2.38.0-preview is skipped rather than backfilled, which
52+
matches how the previous-tag baseline in `release.yml` already computes its range.
53+
54+
## Executed
55+
56+
Preview dispatch: run `33464064409`, success, `expected-sha=75f3895c1…`.
57+
Stable dispatch: run `33464579658`, success, `expected-sha=af6113a03…`.
58+
59+
```
60+
npm view @bitkyc08/opencodex dist-tags --json
61+
{ "latest": "2.39.0", "preview": "2.39.0-preview.20260901" }
62+
```
63+
64+
`gitHead` for `2.39.0` is `af6113a0381d6fff2e4dce587652825c7eeb6423`; for
65+
`2.39.0-preview.20260901` it is `75f3895c14965205be694e8ebb8e93f472630539`. Both match
66+
their promotion SHAs exactly, which is the check that distinguishes a published package
67+
from a merged branch. GitHub releases `v2.39.0` and `v2.39.0-preview.20260901` exist.
68+
69+
The stale preview channel is closed: it moved from `2.36.0-preview.20260830` to
70+
`2.39.0-preview.20260901` in one step.

0 commit comments

Comments
 (0)