Repository navigation
feat(link): the Home accepts the Responses WebSocket over a Remote Link, behind a closed release gate - #8593
Conversation
…its SSH path ocx link status --json now asks for ?traffic=1 and shows, per link, the request and response body bytes since this process started counting, how many requests ended early, and whether the link's SSH alias goes through a ProxyCommand, a ProxyJump host or directly. Without the query the status document is unchanged, so older CLIs keep validating it. A Child counts in its relay, exactly. A Home counts response bytes exactly in its hub-link listener and request bytes by declared Content-Length, because it must keep Bun's native request. Refs goat-si/goat#3023.
Request-log and usage.jsonl rows gain requestBody {wireBytes, encoding,
decodedBytes}, filled by the shared JSON body reader for every admitted
data route, so ocx logs --json shows what a client actually sent. Older
readers rebuild rows from known fields and drop it. Refs goat-si/goat#3023.
…solution Review round 1 for the traffic counters: - count in fetchBoundLinkRelay from the data-request boundary, so a refused challenge or connection counts nothing, response bytes are counted before decoding, and the Child's own hub-state, usage and management reads count; - a connected Child's machine listener answers ?traffic=1 with its own link row, counters and SSH path; - a Home request aborted before its headers stays incomplete; - at most four ssh -G run at once and at most 32 aliases wait.
… mark a bad sidecar row failed Review round 2: response bytes are counted by a pass-through on the socket's stream, so bytes read before a cancel count, and the Child's traffic row reads failed with an unknown alias when its sidecar is unreadable or names another link, instead of passing as an idle Home-initiated link.
…s on each relay-auth answer
…failed row Review round 3: when the sidecar is missing but the durable marker names this link (or cannot be read), the Child's traffic row is failed with reason sidecar_missing and an unknown alias, instead of a Home-initiated idle link.
…ome's named features
…me that accepts it
…coded and prepared bodies Review round 1 for per-body zstd: - the Child sends a body as it is when its zstd form would exceed the Home decoder's ratio bound, so compression never turns an accepted request into a 413; - an encoded body on a JSON data route now joins the shared inbound budget at every limit, reserving its decode bound before it is read and shrinking to the measured size, so decoded bodies held at once stay bounded; - bodies a Child prepares share a 128 MiB allowance, and one that does not fit streams unchanged.
…lushed Review round 2: a Home may answer before it reads an upload, so response headers do not prove the prepared body left the Child. The transport now reports when that body's write flushed or its request was torn down, and the relay frees the allowance then.
…, switched off A Child can only relay HTTP to its Home today, so Codex re-sends the whole conversation on every model request. This adds the Home side of carrying the Responses WebSocket over a Remote Link, behind a new linkResponsesWebsocket setting that is off by default and also needs websockets. While off nothing changes: a link upgrade gets the route table's existing 404 and the relay-auth 204 is byte-identical. While on, an upgrade is admitted only on a relay session just verified on the same connection, with the exact Codex shape and the proof's own key. Every frame re-checks links.json and the key's fingerprint before the shared handler sees it; revoke, last-link close and a 30 s sweep close link sockets with 4401. Link sockets have per-link and overall caps and a transport memory budget, never evict a local socket, and carry no native steering or injection.
…switch until the bounded pump lands Review round 1 of the link WebSocket admission: - A revoke or last-link close() that runs after server.upgrade() succeeds but before Bun calls open() now still closes that socket when it opens. Before, close() could wait forever on its session lease. - linkResponsesWebsocket cannot admit or advertise anything yet. Its memory reservation assumes the link-only bounded pump, which a later slice adds and which lifts this gate. - Tests: a proof made on one connection never upgrades another, the off-state relay-auth answer equals a relay book without any WebSocket option, and the revoke case waits for the Home to end the connection before reading counters.
Final review: a status read ran ssh -G, which evaluates Match exec, could leave processes behind and could slow ocx link status. The path kind is now read from the user's and the system ssh_config with OpenSSH's first-value-wins rule, Host patterns and Includes; anything only ssh could settle reads unknown. A status read starts no process.
…link its own since Final review: evicting the oldest entry could drop a link whose request was still counting while its since claimed continuity. Eviction now skips links with requests in flight, a link counted after an eviction reports since its entry began, and an absent link reads zero since the last eviction.
Final review: a string or byte body was counted before its write completed, unlike streamed chunks.
…hild row; test and doc updates
# Conflicts: # src/client/link-relay-transport.ts # tests/fixtures/test-layout-expected.json
Conflicts resolved by keeping both features: - the hub-link listener passes homeFeatures (the zstd offer) to the relay sessions beside the WebSocket upgrade, advertisement and holds hooks, and its start context carries both homeFeatures and responsesWebsocket; - the relay-auth 204 carries the Home's features header and, only while the WebSocket feature is on, the WebSocket state proof pair; - the optional listeners pass linkHomeFeatures(activeConfig) beside the WebSocket context; - the structure page keeps the traffic section, then per-body request compression, then the Responses WebSocket section.
…td-coded With #8594 a Child may send a relayed POST /v1/responses body zstd-coded. The hold observation parsed its copy of the body as plain JSON, so a coded body never parsed and a pending result returned over HTTP left its hold in place until the operator cleared it. The copy is now decoded through decodeRequestBody, the handlers' bounded reader with its ratio limit, before it is parsed. A body that does not decode still releases nothing, and the release still applies only after the handler answered below 400.
…ey is unavailable Closes #8607. When the reference key could not be loaded or replaced, startup kept the stored no-thread holds without copying their marks into an array, as the normal path does. A holds file whose entry had no marks field then made summary(), hasMarks() and the hold-completion check read .length of undefined, so the ?children=1 and ?transport=1 status reads threw. That path now copies pendingKeys and marks the same way.
…-auth answer Since #8594 every relay-auth 204 names the Home features. The switched-off characterization still requires that the answer carries no WebSocket state pair.
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b3367cc6b6
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if (ignoreActivity && restart === undefined) throw new CliUsageError("--ignore-activity applies only to a restart of one --link-id", usage); | ||
| return { body: { op: verb, linkIds: all ? "all" : linkIds, ...(restart ? { restart } : {}), ...(ignoreActivity ? { ignoreActivity: true as const } : {}) }, wait: !noWait }; |
There was a problem hiding this comment.
Document the live activity override in the public Link guide
The new --ignore-activity override is available even while the WebSocket release gate is closed, but the public guide at docs-site/src/content/docs/guides/remote-link.md:241 still states that a busy Child prevents a restart without describing this exception. Searching docs-site/ finds neither --ignore-activity nor the new link activity clear command. Update the public guide and relevant translations to explain the override's running-work interruption risk and the hold-clear workflow; updating only the skill references and structure notes does not satisfy the scoped documentation requirement.
AGENTS.md reference: src/AGENTS.md:L29-L29
Useful? React with 👍 / 👎.
Summary
A Child's Responses WebSocket upgrade over a Remote Link gets 426 today, so every model request re-sends the whole conversation over HTTP. This branch builds the Home side of carrying that WebSocket over the link (goat-si/goat#3023). It merges switched off: with
linkResponsesWebsocketunset a link upgrade is refused exactly as today, the default status document is unchanged, and local WebSocket behaviour is unchanged. The Child side is a separate PR.The work is one branch of ordered slices; each was reviewed on its own before it was added. All slices of the Home plan are now here.
--ignore-activity?transport=1Not ready to switch on
Three things stand between this branch and enabling
linkResponsesWebsocket. The build's release gate (linkWebsocketTransportReady) stays closed whatever the tests report.tests/fixtures/link-gate-codex.jsonrecords no digest, so every run is labelled smoke only.The coordinator has not re-run the checks on the hub for head b3367cc; CI on that head covers them.
Slice T5a
Summary
A Child can relay only HTTP to its Home today: a Codex WebSocket upgrade on the Child gets 426, so Codex re-sends the whole conversation on every model request over the link. This PR adds the Home half of carrying the Responses WebSocket over a Remote Link. It ships switched off twice over: a new
linkResponsesWebsocketsetting (unset means false, and it also needswebsockets: true), and a build release gate (linkWebsocketTransportReady()is false) that a later change lifts once the link-only bounded pump and its memory measurement land. With either one closed, nothing changes: a link upgrade gets the route table's existing 404 and the relay-auth 204 is identical to today's.What the code does once both are open (exercised by tests that turn the gate on for themselves):
src/server/index/link-websocket.ts): only on a relay session thatlink-relay-sessions.tshas just consumed and verified on the same TCP connection, only with the exact Codex shape (GET /v1/responses, no query, version 13, no Origin, subprotocol or extension), and only when the upgrade's credential is the key the relay proof was made with (otherwise 401). One synchronous function checks abort, switches, shutdown drain and authorization, then takes a 32 MiB reservation from a 768 MiB budget, a slot under 8 per link and 24 overall, and a slot in the shared 128-socket gate without reclaiming a local socket. Refusals of capacity answer 426.links.jsonuncached and re-checks the key's fingerprint before the shared handler sees it; a failure fences the socket, cancels its turn and closes it with 4401.DELETE /api/link/:id(ocx link revoke) closes the link's sockets in the same task as its commit, including a socket upgraded but not yet opened; last-linkclose()refuses further upgrades and closes every link socket before draining; a 30 s sweep, running only while link sockets exist, catches rotation expiry and changes made by other processes.response.injectandresponse.steergetnative_control_unavailable_on_link, and a create never reaches native mode selection.x-opencodex-link-ws-state: onwith an HMAC proof bound to the nonce and both identities; while off the pair is absent.Every cap, budget and interval is a named value in
src/server/index/link-websocket-limits.ts. Shared code touched on purpose, each inert for local sockets: the link listener gains a websocket handler;tryReserveCodexWebSockettakes an optionalreclaimsetting, which a link upgrade passes as"link"so that it may reclaim an idle link socket and never a local one; the shared handler reads anativeControlDisabledflag only link sockets set.structure/remote-link.mdgains a section for the contract;streaming-health.mdandconfig.mdreference it. User docs indocs-site/wait for the change that opens the release gate, since the setting does nothing usable before then.Verification
Failing first: on the base commit, the end-to-end cases (a turn over a link socket, key mismatch 401, revoke 4401, a same-size same-mtime
links.jsonedit, native control refusals, close and stop with sockets open) and the listener cases (caps, budget, no eviction, sweep on an injected timer, an upgrade racing last-linkclose()) fail with today's 404 or a missing header. Characterization cases stay green before and after: the switch off in four forms, malformed, sessionless and legacy-key upgrades get today's 404, the off-state 204 equals a relay book without any WebSocket option. Thirteen mutations, each disabling one protection on the committed tree, each fail the test that guards it.Commands on this branch (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 25 files (the two new files; link listener, relay, management and enrollment-adjacent server tests; link client relay and transport tests; WebSocket registry, capacity and native steering/injection tests; lab boundary tests; layout, structure and file-size ratchet tests): 0, 481 tests, 0 failures.Tests use scratch homes, port 0 and an injected sweep timer; no sleeps or polling.
NOT RUN: the full suite (resource limit of the machine used; CI covers it), the transport memory (RSS) acceptance and the pinned Codex binary release gate, both of which belong to the changes that open the release gate.
Checklist
Slice T5b
Stacked on the link WebSocket admission PR (head f68a0ea); this PR's own commits are 70541d8, 1222065, a08ccd7.
Summary
The link WebSocket admitted by the previous PR stays behind its closed release gate; this change adds what has to be true before that gate may ever open. Without it, switching the Home's
linkResponsesWebsocketsetting off would leave open link sockets running, a link socket could live forever, and an automatic Child restart could cut a running Codex turn because WebSocket work did not count as link activity.response.createthat arrives during a turn is dropped and the socket closes with 1000 after that turn, even if the turn leaves a tool pending. With no turn running, a create is admitted only when it returns a result the socket is waiting for and nothing is untracked, so the tool loop that was running continues; any other create, and any create 60 minutes after the drain began, closes the socket without an upstream request. A draining socket that becomes idle closes.tryReserveCodexWebSocket({ reclaim: "link" })).Shared code:
CodexWebSocketActivitygainsrunning,untracked, a read-onlyreturnsPending(input)andonChange(listener);closingbecomes an accessor. Local sockets register no listener, so their behaviour is unchanged. All new durations are named values insrc/server/index/link-websocket-limits.ts.structure/remote-link.mddescribes the contract.Known gap, closed by a later change: a link socket that closes while busy only ends its activity count; durable holds and the crash fence come next.
Verification
Failing first: on the previous PR's head, 11 of the 13 original cases in the new
tests/server/link-websocket-drain.test.tsfail (the two that pass describe outcomes the earlier fail-closed switch-off already produced). Each protection was then disabled in turn on the committed tree; every one fails its guarding test, and the one that first stayed green (close after a dropped create) got a case that only it handles. A review finding (the listener did not pass its own activity book) got a test through the real listener that failed before the fix.Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 29 files (the three link WebSocket files, link listener/relay/management server and client tests, WebSocket registry, capacity, native steering and injection tests, active-turn disconnect, Child-ops scheduler and routes, lab boundaries, layout, structure and file-size ratchet): 0, 566 tests, 0 failures.Clocks and timers are injected; no sleeps or polling.
NOT RUN: the full suite (resource limit of the machine used; CI covers it), the transport memory acceptance and the pinned Codex binary release gate, which belong to the changes that open the release gate.
Checklist
Slice T5c
Stacked on the link WebSocket drain PR (head a08ccd7); this PR's own commits are 3a2bb51 through a1367f8.
Summary
Today the Responses WebSocket pump sends every complete event of an upstream chunk in one synchronous loop. For a slow reader that lets tens of MiB queue in Bun's send buffer. On a Remote Link socket, where the reader is a Child behind an SSH tunnel, that is not acceptable, so this change paces the pump for link sockets only. The link WebSocket stays behind its closed release gate.
draincallback is only a hint: the pump re-checks the buffered amount on every callback and keeps waiting while it is above the threshold. A cancel or close ends the wait. A socket that does not drain for 300 s in total is closed with 1011. The send buffer therefore stays under 1 MiB plus one event of at most 4 MiB, below the 8 MiB backpressure limit.tests/e2e-style/link-websocket-rss.test.ts(OCX_LINK_WS_RSS_ACCEPTANCE=1, optionalOCX_LINK_WS_RSS_SOCKETS) runs a Home in its own process. Every link socket sends a near-maximum message and then stops reading, and the run waits until the Home reports every link pump waiting. The peak comes from the kernel's high-water mark (VmHWM, reset after the idle reading), and the run must stay within the link socket reservations. Only that kernel measurement can satisfy the check; diagnostic knobs shrink the input or chunks, or route the same load through the HTTP link relay.The acceptance does not pass yet. With 4 sockets the Home peaks well above the 32 MiB per-socket reservation: about 100 MiB per socket for a small request and 135 MiB at full size. Much of that is the upstream body that Bun's
fetchreads ahead of a stalled reader, which the HTTP link relay also holds today. The release gate therefore stays closed, and the reservation or caps need a decision before it can open.All new numbers are named values in
src/server/index/link-websocket-limits.ts. Two test-only hooks live there (setLinkPumpTimerForTests,setLinkPumpWaitObserverForTests), following the repository's...ForTestspattern.structure/remote-link.mddescribes the pump and the gate.Verification
Failing first: on the previous PR's head, the three original pump cases in
tests/server/link-websocket-pump.test.tsfail. Seven sends went out at once to a stalled reader, the framer got whole chunks, and a cancelled pump kept sending. Cases added in review failed before their fixes: a drain callback with 2 MiB still buffered released the next event, and a drain wiring case. Disabling each of the five pacing protections in turn fails its guarding test. Forcing the memory fixture onto sampled measurement fails the acceptance on its method assertion.Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 36 files (the four link WebSocket test files and the opt-in memory test, the link listener, relay and management tests, the WebSocket endpoint, registry, capacity, bridge delivery and SSE framing tests, native steering and injection, the lab boundaries, and the layout, structure and file-size ratchet tests): 0. 668 tests, 0 failures, 1 skip (the opt-in memory test).The pump tests use a fake socket and an injected stall timer; no sleeps or polling.
NOT RUN: the full suite (resource limit of the machine used; CI covers it); the memory acceptance at 24 sockets (projected at about 2 GB; the machine used is shared and has no swap); the largest upstream chunk on the real upstream; the pinned Codex binary release gate.
Checklist
Slice T5d1
Stacked on the link WebSocket pump PR (head a1367f8); this PR's own commits are 310c8ba through eb877ec.
Summary
The Home's own automation (scheduled syncs,
ocx sync --restart-children) may restart a Child only when the link has been idle. Relayed HTTP turns count as activity already. Once Codex on a Child uses a link WebSocket, though, a socket that is cut while a turn runs or a client tool is pending used to leave nothing behind, so a restart could cut work Codex was still doing. This change records that work durably. The link WebSocket stays behind its closed release gate, and nothing is read or written on a Home that never ran the feature.<configDir>/link/activity-holds.json. A hold records the HMAC of the socket's own thread id (key inactivity-ref-key), the hashed result keys it was waiting for, a mark per running turn, and whether its results were untracked. Only hashes and counts are stored. Holds count in the link's activityinFlight(an unknown link counts one), so the existing activity gates withhold restarts without any change to them.POST /v1/responsesit means the handler answered below 400. A copy of the HTTP body is read only while the link has a releasable hold. Running marks (until fingerprint capture lands), holds without a thread id and untracked holds are left for the operator. Nothing releases a hold on a timer, and link removal deletes the link's holds.ws-run-state.jsonis written asrunningwith a strict durable write (private temp file, content fsync, rename, directory fsync whose failure fails the write). If that fails, link upgrades are refused. A graceful stop writes the holds and thenclean. A start that findsrunningor a damaged fence marks every link unknown, writes that, and only then cleans the fence. Iflinks.jsoncannot be read, every link counts as unknown and the fence staysrunning. A corrupt holds file, overflow (64 per link, 1,024 total), a failed hold write, or a lost or replaced reference key also leave the link unknown. None of these stops the Home.Not in this PR: fingerprint capture so running marks can be released by the retried request (next PR), and the operator's clear command with holds shown in
ocx link status(the PR after; owner decision D8).Verification
Failing first: the wiring cases in
tests/server/link-websocket-holds.test.tsfail on the previous PR's head (the store module did not exist). Every review fix has a regression that failed before it. The lifecycle cases run through a real Home and the real shared WebSocket handler: a workflow refusal, an upstream 400, and a refused result on its own socket. The overlapping-turn cases are controlled sequences on the activity tracker. A fixture process kills itself with SIGKILL at each durability point. About thirty mutations were run, each disabling one protection; each fails its guarding test except where a second guard covers the same case, and those are recorded.Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 38 files (all link WebSocket files incl. the new holds store and wiring tests, link listener, relay, management, peer and child-activity tests, WebSocket registry, capacity and native control tests, bridge delivery and SSE framing, lab boundaries, layout, structure and file-size ratchet): 0. 712 tests, 0 failures, 1 skip (the opt-in memory acceptance).No sleeps or polling: the real-Home cases wait on
fs.watchfor the holds file.NOT RUN: the full suite (resource limit of the machine used; CI covers it); the memory acceptance at 24 sockets; the pinned Codex binary release gate.
Checklist
Slice T5d2
Summary
When a link WebSocket closed while a turn was still running, the hold left behind only an anonymous "running" mark that the operator alone could clear. Codex retries that request on its own, over the WebSocket again or over HTTP. The Home now recognises the retry and releases the mark. Everything stays behind the closed release gate and
linkResponsesWebsocket(unset), so nothing here runs on a Home today.src/server/link-turn.ts, called fromrequest-prepare.tsand from the final request log. The link socket keeps one entry per turn, keyed by the handler's turn id: pending, then{ n, inputHmac, turnRef }(the item count, an HMAC over the canonical JSON of the expanded items, and an HMAC of Codex'sclient_metadata.turn_id), or unknown. The entry becomes done at the turn's own terminal and is removed by the turn's own cleanup. A close turns each fingerprint into a mark with its own random id. A pending or unknown entry, and a running turn without an entry, each become an unknown mark, which only the operator can clear.generateis not false) with the same own-thread hash and turn reference; the HMAC of its firstnexpanded items matches; and its terminal iscompletedwith upstream provenance. A failed, synthesized or unattributed terminal never releases a mark. Neither does another turn or thread, an input that does not extend the cut one, or a mark created after the request was fingerprinted.POST /v1/responsesreaches the seam only while its link holds a fingerprinted mark. It carries a random 128-bit per-request token header: the relay strips any peer copy before setting it, and preparation strips it before anything is forwarded (a test checks the upstream never sees it). The relay's decision, made when the handler answers or when the request aborts first, drops a token that preparation never claimed.src/link/ws-activity-holds.tsno longer imports fromsrc/server; the listener passes it the hold limits (tests/clients/link-boundary.test.ts).Requests without an observer run no new code in the pipeline; local WebSocket and HTTP behaviour is unchanged.
Verification
Tests that failed first:
tests/server/link-websocket-fingerprints.test.tsis new with this slice; the seam does not exist on the previous head.Mutations: eight protections were disabled one at a time; seven fail their test. The thread filter in the candidate lookup survives because
releaseMarkschecks the thread hash again.The real-Home cases cut a WebSocket turn, then send an HTTP retry answered 200 (the mark is released) or 400 (it stays). They wait on
fs.watchfor the holds file, with no sleeps or polling.Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 48 files: 0. 868 pass, 1 skip (the opt-in memory acceptance), 0 fail. The files cover every link WebSocket test (including the new fingerprint file), the link listener, relay, management and child-activity tests, WebSocket registry, capacity and native control, request-log and native final log, continuation boundaries and replay principals, the lab, link, quota and advisor boundaries,tests/clients/link-boundary.test.ts, layout, structure and the file-size ratchet.NOT RUN: the full suite (resource limit of the machine used; CI covers it); the memory acceptance at 24 sockets; the pinned Codex binary release gate.
Checklist
Slice T5e1
Summary
Turning the link WebSocket on is meant to stop Children re-sending whole conversations over the link. Today the Home's request log cannot show whether that happens: it does not record which transport a link request used, whether the request continued a chain or sent everything again, or which conversation it belonged to. This adds the request-log fields of design 9.1. With
linkResponsesWebsocketunset (the default) no row changes.linkobject:transport:websocketfor a link socket turn,httpfor a relayedPOST /v1/responses.continuation, with a reason where the design defines one:chained:previous_response_idexpanded locally, or left for an upstream that owns the history.miss: the replay failure's reason (scope_mismatch,spill_*), ormissingwhen preparation refuses an unexpanded continuation.full: reasonfirstfor a socket's first turn,clientfor the rest and for HTTP.threadRefandturnRef: HMAC-SHA256 refs under the Home's private activity reference key, with a domain of their own per kind. They cannot be joined to activity-hold hashes, and raw ids are never stored.POST /v1/responses. A peer cannot supply that header, and it never reaches the upstream.src/usage/link-log-fields.ts) is shared by the in-memory row, the persisted rebuild, hydration from disk and the usage-log normalization. An invalid or unknown shape is dropped.request-log.tsstays under its line cap: the new code is one spread on existing lines.Verification
Tests that failed first:
tests/server/link-request-log-fields.test.ts: validator, normalization round trip, the seam's outcomes, and a real Home over the link listener for a WebSocket turn (first, then client), a relayed HTTP turn, and a refused unexpanded continuation (miss, missing).nullbody on a non-link request with the feature off got a TypeError, and now gets the same 400 as before T5e1.Mutations: dropping the missing mark, the first-turn ordinal, the switch-on HTTP token, the final-row spread or the persisted spread each fails a test.
Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 91 files: 1763 pass, 1 skip (the opt-in memory acceptance), 1 fail; exit 1. The files are the earlier focused set plus everytests/usage/request-log*andusage-log*file and upstream-failure diagnostics.management-route-registrycase "HTTP apply retry returns the durable job without scheduling a second engine run". The Codex CLI update store answersunsafe_storeon this machine's temp directory, the case fails identically with this branch's changes stashed, and it passed in CI on eb877ec.NOT RUN: the full suite (resource limit of the machine used; CI covers it); the memory acceptance at 24 sockets; the pinned Codex binary release gate.
Checklist
Slice T5e2
Summary
An operator turning the link WebSocket on needs to see what it does per Child: how many sockets are open, how many upgrades were admitted or refused and why, and why sockets closed. This adds the live counters of design 9.3, and fixes the wiring that the hold status and clear (the T5d3a section) need on a real Home.
Counters. The link WebSocket gate keeps, per link and in memory:
aborted,draining,unauthorized,unavailable,memory,cap,failed);revoked,disabled,idle,age), otherwise the peer's close code (client,dropped,other).Every reason comes from a fixed set, so no peer text is stored. The counters are display only, reset at restart, and are dropped with the link.
Status.
GET /api/link/status?transport=1, whichocx link statusnow requests (an older Home ignores it), addsws: { open, upgrades, refused, closes, holds }to every current link row.holdsis the link's hold count. Without the query the default document and the?children=1document are byte-identical with or without the counters. The CLI validates the block tolerantly.Wiring fix. The production management routes reach the link listener through the optional-listener facade, which did not forward
linkHoldsorclearLinkHolds(added in the T5d3a section) or the newlinkTransport. On a real Home, status showed no holds and zero counters, andocx link activity clearanswered "nothing held" without clearing. The facade now forwards all three. The clear route answers 503activity_holds_unavailablewhen the hook is missing, never an empty success.Verification
Tests that failed first:
tests/server/link-websocket-transport-status.test.ts:ws; the clear removes the hold.child.holds).Mutations: each of the following fails a test:
Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 93 files: 1791 pass, 1 skip (the opt-in memory acceptance), 1 fail; exit 1. The 93 files are the earlier focused set plus the transport-status test and the CLI status-URL tests. The one failure is the unrelatedmanagement-route-registrycase "HTTP apply retry returns the durable job without scheduling a second engine run": the Codex CLI update store answersunsafe_storeon this machine's temp directory, the case fails identically with this branch's changes stashed, and it passed in CI on eb877ec.NOT RUN: the full suite (resource limit of the machine used; CI covers it); the memory acceptance at 24 sockets; the pinned Codex binary release gate.
Checklist
Slice T5f
Summary
Before the link WebSocket can be turned on, the design requires a release gate with the real Codex client (design 11.1 item 13). This adds that gate as tests only; no production code changes. Release acceptance still needs a pinned binary whose digest has been attested.
tests/e2e-style/link-websocket-release-gate.test.tsrunscodex execagainst a scratch Home, with a scratch HOME and CODEX_HOME, a minimal environment and loopback ports only. Codex reaches the Home's link listener throughtests/fixtures/link-child-relay-standin.ts, a test-only stand-in for the Child's relay (the real relay is the Child lane's work, and the stand-in claims nothing about it). Per request, the stand-in runs the relay challenge. It then either relays HTTP with the session header, or upgrades with the key and answers Codex with its own 101 carryingx-codex-websocket-max-message-bytes: 8388608. A Home refusal becomes 426. It records each create forwarded on a socket, with its size, apart from HTTP requests.OCX_LINK_GATE_CODEXnames an executable. A run is release evidence only when its sha256 equals the digest recorded for openai/codex 88c5856 intests/fixtures/link-gate-codex.json, a reviewed file that records none until a build is attested. Every other run is labelled "smoke only, not release evidence" in each test title.Verification
Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over 94 files: 1 fail, 6 skip (five gate cases and the opt-in memory acceptance); exit 1. The one failure is the unrelatedmanagement-route-registrycase "HTTP apply retry returns the durable job without scheduling a second engine run": the Codex CLI update store answersunsafe_storeon this machine's temp directory, it fails identically with this branch's changes stashed, and it passed in CI on eb877ec.NOT RUN:
Checklist
Slice T5g
Commits on top of 1770843, ending at d13c3fc.
Summary
The final review of the link WebSocket branch found cases where an activity hold could be released too early, a frame could be dropped, and two release tests could pass without exercising their case. This slice fixes them with no new feature. The switch stays unset and the build's release gate stays closed.
OCX_LINK_WS_RSS_*setting runs a diagnostic that asserts no budget. Following design 6.3, the reservation bounds what the WebSocket transport itself adds. The acceptance is therefore the WebSocket run's peak-over-idle RSS minus the HTTP relay's, under the same held upstream and synchronization, compared with n reservations. The HTTP link relay has no stall signal of its own, so its run is synchronized only on the upstream's hold. The acceptance therefore requires both runs to report a stall observed by the Home before the difference counts, and today it cannot pass. Per-test timeouts moved to file defaults. The ordinary suite skips it and gives the reason in the title (2e7d599, 97c68ff, e6aee6e, cb4d6d4).Verification
Each fix has a regression test that failed on 1770843 for the stated reason before the fix.
Commands (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0bun scripts/test.ts --parallel=2over the branch's 17 test files plus link-boundary, link-child-ops-routes, link-relay-bound-transport, management-route-registry, test-layout, test-layout-tooling, structure-ssot and file-size-ratchet (25 files): 392 pass, 8 skip, 1 fail; exit 1.management-route-registrycase "HTTP apply retry returns the durable job without scheduling a second engine run". The Codex CLI update store answersunsafe_storeon this machine's temp directory, it fails the same way with this branch's changes stashed, and the branch touches none of its files.OCX_LINK_WS_RSS_ACCEPTANCE=1, 24 sockets), twice: fails as described above. This is the truthful result.NOT RUN: the release gate with the pinned Codex binary (not built on this machine; it is skipped with that reason only where the binary is absent); the Child tunnel 503 case (Child lane); the full suite (left to CI).
Checklist
Slice T5g-2: merge of dev with #8584
Summary
#8584 (Remote Link traffic counters) landed on dev and conflicted with this branch in ten files. 71e5645 is a normal merge of origin/dev 05d34b9 that keeps both features:
ws, under?transport=1) and the traffic counters (traffic, under?traffic=1).ocx link statusasks for both and validates both blocks.linkTrafficbeside the WebSocket hooks.What the traffic book counts. It does not count what the link WebSocket gate handles. An admitted socket and every gate refusal return before a traffic flow begins, so a socket's bytes are not in
requestsor the byte counts. An upgrade the gate does not handle (the switch or the release gate off, or a request outside the Codex shape) is ordinary relayed HTTP and is counted exactly as #8584 defines. #8584's HTTP measurement is unchanged. structure/remote-link.md says so (966f0ee). A new real-Home test checks that a link WebSocket turn leaves the link's traffic at zero requests and zero bytes, while a relayed HTTP request on the same link is counted.Four tests that assert the status query string now expect
transport=1&traffic=1.Verification
Commands at 71e5645 (exit codes):
bun run typecheck: 0bun run privacy:scan: 0bun run structure:check: 0TMPDIR=/tmp bun scripts/test.ts --parallel=2over 30 focused files: 451 pass, 8 skip, 0 fail; exit 0.NOT RUN: the release gate with the pinned Codex binary, the Child tunnel 503 case (Child lane), and the full suite (left to CI).
Checklist
Slice T5g-3: merge of dev with #8287, #8606 and #8594, and two fixes
Summary
This round brings in dev and the zstd request bodies of #8594, and fixes one interaction between the two features and one stored-holds crash (#8607).
linkHomeFeatures(activeConfig)beside the WebSocket context.linkRequestCompressionswitch come from feat(link): compress Child request bodies with zstd for a Home that accepts it #8594 unchanged.POST /v1/responseszstd-coded. The hold observation parsed its body copy as plain JSON, so a pending result returned over HTTP in a coded body never released its hold. The copy is now decoded throughdecodeRequestBody, the handlers' bounded reader with its ratio limit. A body that does not decode releases nothing, and release still happens only after the handler answered below 400. The new test failed on the merged tree (the hold stayed in flight) before the fix.marks. A holds file entry withoutmarksthen madesummary(),hasMarks()and the hold-completion check throw, which broke the?children=1and?transport=1status reads. That path now copiespendingKeysandmarkslike the normal path. The new test failed with a TypeError before the fix.Verification
Commands (exit codes):
bun run typecheck0,bun run privacy:scan0,bun run structure:check0.TMPDIR=/tmp bun scripts/test.ts --parallel=2over 38 focused files at 97ef6ed: 676 pass, 8 skip, 4 fail.NOT RUN: the release gate with the pinned Codex binary, the Child tunnel 503 case (Child lane), and the full suite (left to CI).
Checklist
The head b3367cc adds one commit by the coordinator on top of 3bbda91: a merge commit that records the #8594 squash (f0166c8) as an ancestor. Its tree is the tree of 3bbda91.