Skip to content

docs(link): move the link WebSocket gate-opening work to a devlog unit, and make the fingerprints test assert the exact count after each change of state - #8679

Merged
lidge-jun merged 34 commits into
devfrom
docs/link-websocket-ocx-child-followups
Nov 13, 2026
Merged

lidge-jun merged 34 commits into
devfrom
docs/link-websocket-ocx-child-followups

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Summary

Follow-up to #8653 (the link WebSocket in ocx-child), #8658 (the TypeScript Child's restart drain) and #8675 (the fingerprints test), from their final reviews. Documentation, comments and one test; no behaviour changes.

  • A devlog unit for open work. devlog/_plan/261113_link_websocket_gate_opening/000_plan.md lists what the change that opens each Child's link WebSocket gate still has to carry.

    • Eleven items for ocx-child: the control-frame deadline, reaper wakeups, Autobahn, RSS acceptance, pinned-Codex scenarios, a pure-move split of link_ws.rs, the Child-local opt-out, macOS and Windows runs, user docs, the state-proof vectors in the Rust CI path filter, and the TypeScript Child's "no answer yet means try" rule (feat(link): try the WebSocket upgrade when the Child has no answer from its Home yet (closed gate) #8682), since ocx-child still answers 426 until a preflight has taught it the Home's advertisement.
    • Seven for the TypeScript Child: gate preconditions, the pinned Codex run, a real Child restart against Codex's retry budget, the first upgrade after a restart, the diagnostics table, three comments and the 1015 close, platforms and docs.
    • The restart items state what measurements with the pinned codex-rs (88c5856) found: a 503, a refused WebSocket connection and an upgrade closed before its 101 all spend the same stream retry budget (about 1.4 s at the default 3 retries), after which the session moves to HTTP. Treating an advertisement unknown since start as "try" keeps a turn on the WebSocket whenever the restart fits that budget; feat(link): try the WebSocket upgrade when the Child has no answer from its Home yet (closed gate) #8682 has landed that rule behind the gate, and the items now say so. Item 3 also notes that an HTTP resend that still reaches the old listener during the tunnel stop gets the relay's 503 home_unreachable with Retry-After, and that how Codex retries that 503 over HTTP was read from the Codex source at 88c5856, not measured: request-level and then turn-level retries, each waiting for Retry-After, then the turn fails; a 5 s window fits inside that budget at the defaults.
    • The restart item also records why connections are refused during a restart: the restart controller spawns the replacement only after the old listener's drain ends, while Bun releases the listening socket as soon as server.stop(false) is called. It gives the two ways to shorten that window, to choose once that window has been measured. It also gives the claim until then, with the item's conditions: a Child restart ends a running turn's WebSocket session unless the replacement accepts the upgrade within Codex's retry budget, and Codex then sends the turn over HTTP. That request reaches the replacement only if Codex's retries outlast the old listener's 503s, and it completes only if the replacement's tunnel and the Home serve it. A later session returns to the WebSocket when the replacement's cache holds on (or no answer yet) and that upgrade's own preflight answers on.
    • One line records the owner's decision of 2026-11-13: the design's 9.2 controlled validation and the U15 measurement are skipped and not measured, and any text that opens a gate must say so.
  • The structure doc states only what holds today. structure/remote-link.md no longer lists open work for ocx-child (structure docs are present tense; open work belongs in devlog/). It keeps the two present limits:

    • A frame write registers its absolute deadline before it takes the leg's write lock, so a pong (30 s) that waits behind a long data write on the same leg can reach its deadline and have the socket cut while the data write is healthy. The Home's link socket sends no pings (idleTimeout: 0), but a ping from Codex is answered on Codex's leg and meets the same limit. A close is not affected: every close write follows a close bound of at most 5 s (1 s on a stop), which the reaper enforces first. Whether the pinned codex-rs pings is to be checked before the gate opens (devlog item 1).
    • Every frame write registers and clears a reaper deadline.
      The TypeScript Child paragraph no longer says the restart drain keeps Codex's WebSocket session unconditionally: each 503, and each refused connection while no listener is bound, spends one of Codex's stream retries, so the session stays on the WebSocket only when the replacement accepts within that budget. It also says that a failed local upgrade Bun had already opened counts as a stop, and that for Bun's own oversized-message 1006 the Home receives 1011 and counts it complete, so the Child is stricter there.
  • No comments pointing outside the repository. The ocx-child link WebSocket modules (link_ws.rs, link_ws_advert.rs, link_ws_frame.rs, tests/link_websocket.rs) lose the design-addendum and lane labels ("draft 9", U1, V1, U4, X1, Y1, S2/S3, V2, R6, C7, S4, T6-4) that referred to notes outside the repository. Each comment keeps what it describes, and the module header points at the devlog unit. "design T4" references stay; the TypeScript code uses them too. Comments only.

  • The fingerprints test asserts the exact count after each change of state. Since test(server): wait for the activity holds state, not for one file event, in the link WebSocket fingerprints test #8675, every wrong mark count in "through a real Home: a cut WebSocket turn and its HTTP resend" failed as a 5 s timeout at the wait. The waits are now for a change of state, with the exact count asserted after them: wait until the holds file exists, then expect 1; after a resend answered 200, wait until the count is no longer 1, then expect 0. A holds file first written with a wrong count, or a 200 resend that moves the count to anything but 0, now fails as a mismatch. A holds file never written, or a count that stays 1 after the resend, still fails at the runner's timeout. The waits keep test(server): wait for the activity holds state, not for one file event, in the link WebSocket fingerprints test #8675's shape (one watcher armed before the Home starts; each wait checks its condition when it starts and on every event).

  • Merged with dev after feat(link): try the WebSocket upgrade when the Child has no answer from its Home yet (closed gate) #8682 and test(link): pin the Child relay wait observer across Home failures, queued aborts and cancels, and correct its comments #8683. Two normal merges of dev: 5caeeaff1 (after feat(link): try the WebSocket upgrade when the Child has no answer from its Home yet (closed gate) #8682) and 2df5d2baf (after test(link): pin the Child relay wait observer across Home failures, queued aborts and cancels, and correct its comments #8683; no conflict). The first had one conflict, in the TypeScript Child paragraph of structure/remote-link.md, resolved as dev's paragraph (from feat(link): try the WebSocket upgrade when the Child has no answer from its Home yet (closed gate) #8682) plus this PR's three edits: a failed upgrade that Bun had already opened counts as a stop; the drain keeps the WebSocket only within Codex's retry budget; and the 1006 and oversized-close counting. After the merge, that paragraph also says:

    • a cached off is replaced only by a newer preflight's verified answer, and the route-intent poll is such a preflight;
    • the 1.4 s figure is a measurement of the pinned codex-rs 88c5856, citing the devlog unit;
    • it no longer opens with a lane label.

    The machine-listener.ts comment says a cached off still tries while the relay drains.

What keeps it inert: nothing here changes runtime code. The Rust edits are comments, and the test change only changes what the test waits for.

Verification

  • The test change, checked by mutation: with the first expectation changed to 2, both cases failed in under 0.5 s with "Expected: 2, Received: 1" (before, that wrong count waited for the 5 s timeout).
  • bun test tests/server/link-websocket-fingerprints.test.ts, 5 runs in a row: 29 pass, 0 fail each
  • The ocx-child CI step on stable rustc 1.100.0, at 3960dd809: cargo fmt --manifest-path native/ocx-child/Cargo.toml --check exit 0; cargo clippy --locked --manifest-path native/ocx-child/Cargo.toml --all-targets -- -D warnings exit 0; cargo test --locked --manifest-path native/ocx-child/Cargo.toml exit 0 (54 lib tests). At ade59424e, after the commit that changes one //! line in tests/link_websocket.rs: cargo fmt --check exit 0.
  • At ade59424e (after the test-comment and Rust-comment changes; the five commits that followed it edit only structure/remote-link.md and the devlog unit): bun run typecheck exit 0; bun scripts/test.ts --parallel=2 over tests/server/link-websocket-fingerprints.test.ts, structure-ssot, test-layout, file-size-ratchet and link-boundary: exit 0, 92 pass, 0 fail.
  • At 2df5d2baf (after both dev merges and the commits that answer the final review of b7e41a87d): bun run typecheck, bun run structure:check, bun run privacy:scan and cargo fmt --manifest-path native/ocx-child/Cargo.toml --check each exit 0; TMPDIR=/tmp bun scripts/test.ts --parallel=2 over tests/server/link-websocket-fingerprints.test.ts, tests/clients/link-ws-unknown-try.test.ts, link-ws-advertisement, client-machine-listener, link-relay-wait-observer, link-boundary, test-layout, test-layout-tooling, file-size-ratchet, structure-ssot and repo-hygiene: exit 0, 190 pass, 0 fail.
  • At b7e41a87d (which adds devlog item 11 in 3317975c7 and qualifies it): bun run structure:check and bun run privacy:scan each exit 0.
  • At the final head (five wording commits on 2df5d2baf, one of them a one-line comment in src/client/link-websocket.ts): bun run typecheck, bun run structure:check and bun run privacy:scan each exit 0; TMPDIR=/tmp bun scripts/test.ts --parallel=2 over structure-ssot, file-size-ratchet and link-boundary: exit 0, 61 pass, 0 fail.
  • At 3960dd809: bun scripts/test.ts --parallel=2 over every link-websocket-*.test.ts file (tests/server and tests/e2e-style), tests/responses/responses-websocket-workflow-ceiling.test.ts, the two ocx-child Cargo wrappers, and the layout, layout-tooling, structure-ssot, file-size and repo-hygiene guards: exit 0 (267 pass, 9 skip, the release-gate cases that need the pinned codex-rs binary, 0 fail).

Review: a gpt-6.1-terra reviewer (xhigh, read-only) reviewed the first four commits (no findings) and then the devlog correction for the measured restart facts (no findings). A fresh gpt-6.1-terra reviewer (xhigh, read-only) then reviewed the final-review fixes over three rounds. Round 1 found the restart claim and the structure drain sentence unconditional (P2); round 2 found the claim still stated outcomes, not conditions (P2). Both are fixed; round 3 had no findings. Round 4 reviewed the added ocx-child item 11, requested by #8682's final review: no P0-P2, and its one P3 (the TypeScript rule as cited omitted the drain exception for a cached off) is fixed. Rounds 5 and 6 reviewed the answers to the final review of b7e41a87d: the merge resolution, N1 and N2, P3-A to P3-D and the devlog updates. Round 5 found that reaching the replacement over HTTP was stated as guaranteed (P2) and that the route-intent poll was named as the only first source of an answer (P3); both are fixed, and round 6 had no findings. The final review of 2df5d2baf (approve with nits) listed nine wording P3s. They are fixed in the last five commits and in this text, which the coordinator read in place of another terra round:

  • the drain comment in src/client/link-websocket.ts says "within its retry budget";
  • a cached off counts draining during a restart drain;
  • a failed local upgrade Bun had opened also counts as a stop;
  • item 4 lists more first answers;
  • item 3 keeps its budget condition and cites the source reading of the HTTP 503 retry.

Open P0-P2: 0.

NOT RUN: clippy and cargo test at the final head (the only Rust change since 3960dd809 is one doc-comment line; CI's ocx-child step runs both); macOS (where #8675's race occurred; the waits keep its shape); the full bun run test suite.

Checklist

  • No runtime behaviour change
  • structure/remote-link.md updated (present tense only)
  • Open work recorded in devlog/_plan

@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Caution

Review failed

The pull request is closed.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Nov 13, 2026
@lidge-jun lidge-jun changed the title docs(link): move the link WebSocket gate-opening work to a devlog unit, and make the fingerprints test fail on the count docs(link): move the link WebSocket gate-opening work to a devlog unit, and make the fingerprints test assert the exact count after each change of state Nov 13, 2026
@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 10:57
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 10:57
@lidge-jun
lidge-jun merged commit 726bd71 into dev Nov 13, 2026
28 checks passed
@lidge-jun
lidge-jun deleted the docs/link-websocket-ocx-child-followups branch November 13, 2026 10:57
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T10:58:36.310579Z 18034a4 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant