feat(transport,client-core): name a wire version skew at handshake instead of timing out

[Zerlight]

Summary

Phase 6 of CODE-627 — Conversation turn graph & immutable attachment store. Linear: https://linear.app/arcbox/issue/CODE-641/feattransport-tunnel-minimum-version-advisory-for-below-floor-clients

Stack: #525 ← this PR (ruocheng/code-641, base ruocheng/code-640) ← top of the stack. Merge bottom-up; this PR's diff is only its own commits.

The precondition for the floor-bump release. The client half of the advisory already existed: since wire v64 (2026-07-31) the pong carries version + minCompatible and LinkCodeClient names both skews from it. What never worked was the transport boundary — every server transport (socket.io, ws, tunnel peer) refused a below-floor frame silently, so an old client's ping was never answered and its handshake died in the 5 s timeout ("daemon unavailable or wire protocol mismatch"), and a newer client dropped an older host's pong the same way, which made the existing "update the host" branch unreachable. One rule fixes both directions on every carrier: parseWireMessage accepts a below-floor frame only if its payload validates as ping or pong; everything else below the floor is still refused. The Hub's existing pong path then answers an old client, and the reply travels back on the same connection — so the tunnel needs no wire-version surface of its own and no relay change (the relay forwards WireMessage frames opaquely; that assumption cannot be verified from this repo). The client turns the skew into a typed WireIncompatibleError { remedy: 'update-host' | 'update-app', peerVersion, peerMinCompatible }, the connection controller stops retrying on it (a skew cannot heal by retrying), mobile renders an update-required screen instead of "Host unavailable", and the workbench's connection state names the side that must update instead of asking to start a daemon that is running. The deprecation-window policy is recorded: the floor may move only after the update screen has shipped in at least two mobile store releases.

Commits

• feat(schema,transport): accept the handshake below the wire floor so a skew is named instead of timing out
• feat(client-core): type the wire incompatibility and stop retrying it
• feat(mobile): show an update-required state for a wire version skew
• docs: record the version-agnostic handshake and the floor-bump deprecation window
• fix(workbench): name a wire skew in the connection state instead of asking to start the daemon

Verification

Every commit passed pnpm check:ci and pnpm test at its own tip; the tip (1b280635) is at pnpm check:ci 0 errors, pnpm test 3482 passed / 1 skipped. Tests: the schema contract (a below-floor ping/pong is accepted, a bare {kind:'pong'} claim and every other kind below the floor are refused; the new acceptance test fails on the previous parser), a raw socket.io client and a raw ws client stamping v−1 sending ping through a Hub and receiving pong {version, minCompatible}, a below-floor peer ping delivered through the tunnel peer transport, an older host's below-floor pong reaching LinkCodeClient through the real WsTransport as update-host, both remedies from the handshake, and the controller stopping after one attempt on the typed error (and again after a deliberate retry) while still exhausting its budget on an ordinary failure. Adversarial review (isolated read-only worktree): ACCEPT-WITH-FINDINGS, no P1/P2 — it could not make a below-floor peer do anything beyond having its handshake answered; its findings (a wrong docs anchor, the workbench copy, comment and API tidy-ups, the mobile redial flicker, the ws-carrier test gap) are folded into these commits. Observed running: against the development daemon (tsx watch, hot-reloaded), a raw wire-v70 client's ping got pong {version: 82, minCompatible: 76} back within milliseconds; the webview, pointed at a stand-in daemon answering pings with an out-of-range pong, rendered "This LinkCode build is too old to talk to the daemon at … Update the app." and, with the range inverted, "The daemon at … is too old for this LinkCode build. Update the daemon." Not rendered on a device: the mobile update screen against a skewed daemon (the hook logic is unit-covered; the SwiftUI view is a copy branch).

Checklist

• pnpm check:ci and pnpm test both pass (no Rust changes)
• I ran the affected surface and observed the change working — the development daemon answering a below-floor ping, and the webview against a skewed stand-in daemon in both directions
• Wire: unchanged at 82 — no frame shape changed, only the receiver's acceptance of the handshake; floor unchanged at 76; no migration
• New code and assets are my own work
• Docs and comments are updated where behavior changed (docs/ARCHITECTURE.md, root AGENTS.md Invariant 1, docs/RELEASE.md "Moving the compatibility floor")

[linear-code]

CODE-641

[pullfrog]

Important

The mechanism is sound end-to-end — but the release gate this PR exists to enable rests on a desktop "lockstep" claim that the daemon-discovery code refutes. Worth fixing now, while the reasoning is fresh, because the next person counts release windows from that line.

Reviewed changes

• Version-agnostic handshake. parseWireMessage now accepts a below-floor envelope when its payload kind is ping/pong and the payload validates, so a peer under the floor learns the range it must update into instead of dying in the 5 s timeout.
• Typed incompatibility. New WireIncompatibleError carries remedy: 'update-host' | 'update-app'; ConnectionController bail()s out of the retry loop on that type rather than burning its budget.
• Three update-required surfaces. Mobile's connection state, plus workbench's shared state for desktop and webview via the new useWorkbenchRuntimeError hook.
• Recorded floor-bump policy. A two-mobile-release advisory window in docs/RELEASE.md, docs/ARCHITECTURE.md, and root AGENTS.md.

I traced the things most likely to be quietly wrong here and they hold up, so I'll record them so nobody re-does the work:

• No below-floor frame escapes onto a send path. hub.ts:125-127 consumes the inbound ping and replies with a freshly createWireMessaged pong, returning before inbound.emit. The ws/socket.io servers and the tunnel only inbound.emit the parsed frame, and there is no cross-peer relay in TunnelTransportServer. So the as ValidatedWireMessage cast at the new branch — which does mint an object violating WireMessageSchema's .min(MIN_COMPATIBLE_WIRE_VERSION) — stays inert.
• The typed error survives every boundary. foxts' bail() wraps in AsyncRetryAbortError and the handler rethrows .cause verbatim, skipping onFailedAttempt; unwrapConnectionError only unwraps ExplicitRetryError. One bundle per app, so instanceof holds across the package edge.
• No stale-error false positive. startRecovery publishes error: undefined before flipping status to connecting, so workbench computing message unconditionally can't leak update copy into a healthy reconnect.
• The mobile prop plumbing works despite host-connection.ts not being in the diff — HostConnection is an intersection with HostClientState, and host-connection-scope.tsx:40 spreads ...state.

ℹ️ Invariant 1's "every wire change" is left unadjudicated for receiver-only changes

Holding WIRE_PROTOCOL_VERSION at 82 is defensible on the stated reasoning — no frame shape, field, or meaning changed, and no capability gate anywhere interrogates the version to decide whether a handshake will be answered. I checked; there's no probe that silently misbehaves.

The part worth a sentence somewhere is that two builds both stamping 82 now behave observably differently: a pre-PR v82 daemon leaves a below-floor client in the 5 s timeout, a post-PR v82 daemon hands it a named advisory, and nothing on the wire distinguishes them. That's not a correctness bug — the pre-PR behavior is exactly the status quo — but during a mixed-fleet floor bump it's the difference between "this daemon is broken" and "this daemon is old", and an operator can't tell which they have.

Invariant 1 says the stamp moves on every wire change. This PR is the first case where "wire change" plausibly means "receiver acceptance policy" rather than "frame shape", and the answer chosen here becomes precedent by default. Recording the call — either way — in Invariant 1 itself would keep the next person from re-deriving it. This is a judgment call for you, not something I'd assert an answer to.

ℹ️ Nitpicks

• VERSION_AGNOSTIC_KINDS is a hand-written Set(['ping', 'pong']) rather than being derived from the keep-alive schema. Renaming either kind would silently disable the entire advisory with no type error — and the failure mode is precisely the timeout this PR removes, so it'd read as a regression in the feature rather than a rename fallout. Low likelihood (renaming those kinds is itself a breaking wire change), but the blast radius is the whole feature.
• docs/ARCHITECTURE.md:317 still reads that an unchecked object cannot reach a send path, while the sibling comment in message.ts gained the below-floor caveat. The claim is still true for the reasons traced above; it's just now true for a narrower reason than the sentence implies.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[Copilot]

🔵 Needs a closer look

The cross-layer transport, client, desktop, and mobile changes warrant final human review.

Pull request overview

This PR makes wire-version skew explicit during handshake instead of allowing incompatible peers to time out.

Changes:

• Accepts validated below-floor ping/pong frames across transports.
• Adds typed incompatibility errors and stops retries.
• Adds desktop/mobile update guidance, tests, localization, and documentation.

File summaries

File	Description
packages/presentation/i18n/src/locales/zh-cn.ts	Adds Chinese skew messages.
packages/presentation/i18n/src/locales/en.ts	Adds English skew messages.
packages/foundation/transport/tests/integration/ws-server.test.ts	Adds WebSocket handshake coverage.
packages/foundation/transport/tests/integration/socket-io.test.ts	Adds Socket.IO handshake coverage.
packages/foundation/transport/src/__tests__/tunnel.test.ts	Adds tunnel handshake coverage.
packages/foundation/schema/tests/contract/wire/envelope.test.ts	Tests handshake compatibility rules.
packages/foundation/schema/src/wire/message.ts	Allows validated below-floor handshake frames.
packages/client/workbench/src/runtime/provider.tsx	Exposes connection errors.
packages/client/workbench/src/app/connection-state.tsx	Displays skew guidance.
packages/client/core/tests/integration/wire-skew.test.ts	Adds end-to-end skew coverage.
packages/client/core/src/wire-incompatible-error.ts	Adds the typed incompatibility error.
packages/client/core/src/index.ts	Exports the new error.
packages/client/core/src/connection-controller.ts	Stops retries for wire skew.
packages/client/core/src/client.ts	Detects and preserves typed errors.
packages/client/core/src/__tests__/connection.test.ts	Tests incompatibility directions.
packages/client/core/src/__tests__/connection-controller.test.ts	Tests retry behavior.
docs/RELEASE.md	Documents the compatibility-floor policy.
docs/ARCHITECTURE.md	Documents version-agnostic handshakes.
apps/mobile/src/runtime/use-host-client.ts	Propagates skew state.
apps/mobile/src/components/host/host-connection-state.tsx	Renders update-required states.
apps/mobile/src/components/host/host-client-gate.tsx	Passes remedy state to the UI.
AGENTS.md	Updates the wire-version invariant.

Review details

• Files reviewed: 22/22 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Zerlight]

Review round (2026-09-11). Both pullfrog findings were real and are fixed; the branch is rebased onto the updated ruocheng/code-640.

• The desktop exemption was wrong. resolveDaemonUrl() prefers the Developer-tab override, then any live runtime.json advertisement, and the supervisor stands down when another install's daemon already serves the machine — so a pre-advisory desktop build does meet a newer daemon. "Lockstep" described the bundle, not the connection. docs/RELEASE.md now carries its own bullet (desktop is not exempt, only unbounded: no store-review count bounds it, so the trigger is a judgement call), and docs/ARCHITECTURE.md names the desktop release alongside the two mobile ones. Root AGENTS.md needed no edit — Invariant 1 already gates on "the clients it will refuse". The webview loses its exemption on the same ground.
• The mobile update screen contradicted itself. An update-app skew now renders no Retry button, and neither skew renders the technical failure footnote. update-host keeps Retry, matching hurryAlong, which still redials that one. The retry loop the button offered is pinned by this PR's own connection-controller.test.ts.

Left for the owner, flagged rather than invented: what measurably bounds the desktop window (auto-update adoption has no dwell or adoption trigger the way "two store releases" does), and the N=2 mobile count itself, which is still a proposal.

[Copilot]

🟡 Changes recommended

The English and Chinese update messages direct Android users to the App Store instead of providing platform-appropriate guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 22/22 changed files
• Comments generated: 2
• Review effort level: Lite

[pullfrog]

ℹ️ No critical issues — minor suggestions inline.

Both findings from the previous review are genuinely fixed, not relocated. One consequence of the mobile fix is worth a look before merge.

Reviewed changes

• Corrected the desktop exemption in docs/RELEASE.md and docs/ARCHITECTURE.md. The new "Desktop is not exempt, only unbounded" bullet names the actual non-bundled paths — resolveDaemonUrl(), the runtime.json advertisement, the Developer-tab override, the supervisor stand-down — and folds the webview into the same rule. Root AGENTS.md Invariant 1 was correctly left alone: it already defers to docs/RELEASE.md, so the three-site partial-fix trap I warned about is avoided rather than half-hit.
• Dropped the Retry button on the mobile update-app screen and suppressed the raw failure footnote under either named skew, so the friendly copy isn't shadowed by triage voice.

ℹ️ Nitpicks

• packages/client/workbench/src/app/connection-state.tsx:46 still renders Retry unconditionally, including on update-app. I scoped this out last round on the grounds that the workbench surfaces don't share mobile's flip-flop tension, and that reasoning still holds — flagging only because the two platforms now diverge visibly on the same state. No change needed if the divergence is intentional.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[xiaoland]

LGTM

[xiaoland]

Manual Verification

新建会话

结论：不能通过；在截图完毕，重新聚焦应用后，就出现了如上图的情况。

可以稳定复现：

历史会话

历史会话无法加载（如图报错）

或者为空

但也有加载出来的情况

[pullfrog]

Your organization has disabled Claude subscription access for Claude Code. Ask your Claude organization's admin to re-enable it in the Claude Console, or set an ANTHROPIC_API_KEY for this repo instead, then re-trigger the run.

Add repo secret → · Model settings → · Setup docs → · Ask in Discord →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}

[Zerlight]

@xiaoland following up on your review.

The completed-reply → “Output for this turn is unavailable” after refocus is real, but it is not caused by this PR’s wire-advisory commits. Conversation reads revalidate on focus. Settled output is reconstructed from attributed native Claude history; when that attribution fails or returns no usable partition, the projection installs history-unavailable placeholders and still advances the journal watermark, so the live reply is discarded and the client will not replay it.

The first failing projection is on stacked ancestor PR #510 (ruocheng/code-631), already in this PR’s base. The fixes landed there and were restacked through ruocheng/code-641.

Cause

1. Native history attribution can fail or return no usable partition. The completed-turn cut then discarded the live journal even when a complete matching interval survived.
2. Claude execution uses the project/account environment, but native SDK history and raw transcript supplements previously used the daemon/default directories. A custom CLAUDE_CONFIG_DIR can split writer and reader.
3. Missing direct native history returned an empty conversation instead of failing, so a retained sidebar entry could open blank. Duplicate No conversation found banners were the same provider-result error plus a later stream-error.
4. Host prompt echoes can precede the running state, so their journal start had no turn ID and real-session journal recovery could not bind.

Fixes (on ruocheng/code-631, restacked through this branch)

• 46d640b1 retain complete live turns when native history is unavailable — recovery uses the existing bounded journal only when a complete matching turn/run/epoch interval from user-message start through terminal stop survives. Gaps, evictions, wrong run/epoch, and incomplete intervals still reject recovery. No second durable transcript store, no inferred provider checkpoints, no weakened fingerprint validation.
• 8d7a4664 scope Claude history to its execution configuration — internal history-read account context, cache invalidation on config changes, consistent resolved Claude roots, isolated Node workers for SDK operations on alternate roots. Daemon process.env is not mutated.
• 10bfec45 attribute prompt echoes before turn dispatch completes — SessionEventProcessor.broadcast accepts explicit turn attribution; prompt/command dispatch supplies the persisted intent’s turn ID.

Missing direct native history now throws instead of returning an empty conversation. Duplicate stream-error banners after an already-reported provider-result error are suppressed; independent and subsequent-turn stream errors remain visible.

Fork integrations that needed the same config root were restacked on their own branches:

• 5a09ce18 on ruocheng/code-632 / PR #511: validate Claude forks in the source config root
• 7c009dbd on ruocheng/code-639 / PR #524: copy Claude fork subagents from the source config root

ruocheng/code-630 is unchanged. The rest of the stack (code-631 … code-641) is pushed. This PR’s head is now b992236d.

Evidence

• Tip b992236d: 3,495 tests passed, 1 pre-existing skip; 400 test files passed, 1 skipped. check:ci passed (format, ESLint 0 errors, typecheck). Daemon and desktop production builds passed.
• Engine dispatch-to-projection regression failed before 10bfec45 and passed after.
• On the original PR head, relocating only this test’s native transcript reproduced the screenshots: native rows became zero, completed replies became unavailable on desktop reload, restoring the transcript recovered the replies.
• On the fixed build, isolated desktop profile pr529-investigation, Sonnet 5 only: session sess-mu0w7diy-1, history 5d656c8f-5339-4f1a-a205-c8435ca243b4, latest turn turn-866e4701-422d-4a04-823a-145f1ded37e5. Native desktop showed Bash · printf PR529FINALTOOL and PR529FINALANSWER with model claude-sonnet-5. Fresh daemon projection for that completed turn contains the host user-message, status/policy events, tool-call and content, agent-message chunks, token usage, and stop — no unavailable placeholder for that turn. Native SDK returned 19 rows.

Limits — please do not treat these as covered

• Recovery needs a complete bounded live journal. Genuinely missing native history cannot be reconstructed after journal loss (for example a daemon restart that already dropped the earlier events).
• Earlier turns in that same live session still display unavailable because their old journals were lost on daemon restart and interrupted test metadata disrupts native attribution. Those historical cases are not claimed repaired.
• The colleague’s exact provider/account/custom CLAUDE_CONFIG_DIR trigger is still unconfirmed.
• Pi sessions and the simulator-sidecar error are not proven fixed.

Please retry the updated ruocheng/code-641 (b992236d). If a session still blanks or placeholders after a completed reply, the useful facts are: resolved history ID, transcript location, effective config root for both CLI and daemon reader, history event/partition counts, and the first attribution mismatch. No credentials needed.

[Copilot]

🔵 Needs a closer look

Two moderate, one-vote localization findings require platform-neutral or platform-specific store wording for Android users.

Review details

Suppressed comments (2)

packages/presentation/i18n/src/locales/en.ts:1434

• This copy is shared by the Expo mobile client, which also ships on Android, so “App Store” is not the correct place for every user. Use platform-neutral wording (or select the store per platform) so Android users are not sent to a nonexistent store.

        'This version of the app is too old to talk to that host. Update it from the App Store and try again.',

packages/presentation/i18n/src/locales/zh-cn.ts:1389

• This copy is shared by the Expo mobile client, which also ships on Android, so “App Store” is not the correct place for every user. Use platform-neutral wording (or select the store per platform) so Android users are not sent to a nonexistent store.

      updateAppBody: '此版本的应用过旧，无法连接到该 host。请从 App Store 更新后重试。',

• Files reviewed: 22/22 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[pullfrog]

Your organization has disabled Claude subscription access for Claude Code. Ask your Claude organization's admin to re-enable it in the Claude Console, or set an ANTHROPIC_API_KEY for this repo instead, then re-trigger the run.

Add repo secret → · Model settings → · Setup docs → · Ask in Discord →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}