Summary

What problem does this PR solve?

• Fix classification: root-cause fix for a scoped Control UI reconnect/session-lifecycle bug.
• Root cause: the session lifecycle state source was split after a Control UI sleep/network reconnect: the UI continued to display the previous sessionId, while Gateway freshness handling treated the next send like an ordinary stale send and rotated that matching transcript into a reset archive before the resumed turn landed.
• Why this is root-cause fix: the source invariant is now enforced at the owner boundaries: Control UI creates a one-shot private reconnect marker only for the displayed matching session, Gateway accepts that marker only from operator UI clients, and reply initialization receives the resume request only after public protocol validation remains closed.
• The reconnect recovery is now scoped to Control UI behavior instead of publishing a new general chat.send resume contract or Plugin SDK reply-options surface.

Why does this matter now?

• The linked bug is user-visible session loss after an ordinary Control UI reconnect.
• The earlier shape fixed that path by adding chat.send.resumeSession, but that made the fix look like a new public Gateway protocol feature and required a broader product/session-policy decision.

What is the intended outcome?

• A Control UI reconnect send can preserve the currently visible matching session for that one send.
• Ordinary stale sends still follow configured idle/daily reset freshness and create a fresh sessionId when policy requires it.
• chat.send.resumeSession is not part of the public Gateway protocol schema, generated Swift model, or docs.
• requestedSessionId / resumeRequestedSession stay on the internal Gateway/reply path and are not part of exported Plugin SDK GetReplyOptions.

What is intentionally out of scope?

• This does not introduce a third-party reconnect/resume API.
• This does not change session reset configuration, daily reset timing, idle freshness evaluation, transcript storage, or migration behavior.

What does success look like?

• Control UI reconnect recovery remains available for the original user path.
• Public WebChat / non-operator clients cannot use the private Control UI marker as a generic session freshness override.
• Protocol validation rejects resumeSession as an extra chat.send property.
• Plugin SDK reply-runtime keeps GetReplyOptions free of the private reconnect resume controls.

What should reviewers focus on?

• The product boundary: reconnect resume is now an internal Control UI affordance, not a published Gateway protocol field or Plugin SDK option.
• The session-state boundary: the one-shot resume still requires a matching sessionId; ordinary stale sends still rotate.

Linked context

Which issue does this close?

Closes #87700

Which issues, PRs, or discussions are related?

Related #89017

Was this requested by a maintainer or owner?

No direct maintainer request; ClawSweeper requested maintainer/product review for the public protocol shape, so this update narrows the shape to avoid a public API decision.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Control UI reconnect send preserves the matching visible session without exposing a public chat.send.resumeSession field.

• Real environment tested: Foreground Gateway websocket RPC from the current checkout, using real Control UI and public WebChat client identities with browser-origin and device-identity handshake requirements enabled.

• Exact steps or command run after this patch:

  • Started a foreground dev Gateway from the current checkout with isolated state.
  • Seeded stale session registry rows for the ordinary-send and reconnect-send cases.
  • Sent real chat.send websocket RPCs for Control UI reconnect, public WebChat with the private marker, and ordinary stale Control UI send.

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Validation live-control-ui-reconnect-proof (pass, exit_code=0, 103436ms):

  LIVE_GATEWAY_PROOF: PASS foreground Gateway websocket RPC exercised #87700/#89017 behavior
  scenario=control-ui-reconnect-send result=PASS requested=reconnect-preserved-session observed=reconnect-preserved-session behavior=preserved_same_visible_session_after_reconnect
  scenario=public-webchat-private-marker result=PASS rpc_ok=false error=invalid_chat_send_params behavior=private_marker_rejected_for_non_operator_client
  scenario=ordinary-stale-control-ui-send result=PASS requested=ordinary-old-session observed=e5ef8f7a-8fcc-4cc0-ade9-006bd8111b02 behavior=rotated_by_stale_freshness
  LIVE_GATEWAY_PROOF: PASS public protocol stayed closed while Control UI reconnect recovery worked
  

• Observed result after fix:

  • Control UI reconnect send with the private marker kept the same visible session id.
  • Public WebChat sending the private Control UI reconnect marker was rejected by chat.send validation.
  • Ordinary stale Control UI send without the reconnect marker rotated to a new session id.
  • resumeSession remains outside the public chat.send protocol contract.

• What was not tested: None for the scoped Gateway/session behavior covered by this proof.

• Proof limitations or environment constraints: The live proof targets the runtime session boundary that caused [Bug]: Control UI webchat session silently resets after network disconnect / sleep — previous session file renamed to .jsonl.reset.* and lost from sessions tab #87700; Control UI marker construction is covered by the supplemental controller regression tests below.

• Before evidence (optional but encouraged): Before the scoped reconnect handling, a stale send with the displayed matching session was handled like an ordinary stale send and rotated instead of preserving the visible reconnect session.

Tests and validation

Which commands did you run?

• pnpm lint --threads=8 (pass, exit_code=0, 206428ms)
• node scripts/run-vitest.mjs packages/gateway-protocol/src/index.test.ts src/plugins/contracts/plugin-sdk-subpaths.test.ts src/gateway/server.chat.gateway-server-chat-b.test.ts ui/src/ui/controllers/chat.test.ts (pass, exit_code=0, 139848ms)
• pnpm exec oxfmt --check src/auto-reply/dispatch.ts src/auto-reply/reply/dispatch-from-config.types.ts src/auto-reply/reply/get-reply.types.ts src/plugins/contracts/plugin-sdk-subpaths.test.ts (pass, exit_code=0, 2584ms)
• git diff --check (pass, exit_code=0, 1276ms)
• TMPDIR=<isolated temp dir> NODE_OPTIONS=--max-old-space-size=8192 OPENCLAW_VITEST_MAX_WORKERS=2 node scripts/run-vitest.mjs run --config test/vitest/vitest.full-core-support-boundary.config.ts (pass, exit_code=0, 9189ms)
• NODE_OPTIONS=--max-old-space-size=8192 pnpm build:ci-artifacts (pass, exit_code=0, 178580ms)
• ClawSweeper commit review on the submitted range (pass; no actionable findings)

What regression coverage was added or updated?

• Protocol validator coverage proves resumeSession is not a public chat.send parameter.
• Gateway websocket coverage proves the private reconnect marker is accepted only for Control UI and rejected for public WebChat.
• Plugin SDK contract coverage proves openclaw/plugin-sdk/reply-runtime does not expose requestedSessionId / resumeRequestedSession through GetReplyOptions.
• Control UI controller coverage proves ordinary sends do not include any resume marker and reconnect sends use the private marker once.

What failed before this fix, if known?

• check-lint failed because the controller regression test read __controlUiReconnectResume with dot syntax, triggering no-underscore-dangle; the assertion now checks property absence without relaxing lint rules.
• The earlier build-artifacts boundary failure was tied to the stale pre-sync checkout; after syncing with current main, the same core-support boundary suite passes.

If no test was added, why not?

• This update only fixes CI after the existing behavior and SDK-boundary regression coverage was already present; the current test and live-proof commands above revalidated that coverage on the submitted range.

Risk checklist

Did user-visible behavior change? (Yes/No)

Yes. Control UI reconnect sends can preserve the matching visible session once; this is the intended fix for the linked session-loss path.

Did config, environment, or migration behavior change? (Yes/No)

No.

Did security, auth, secrets, network, or tool execution behavior change? (Yes/No)

Yes, in the limited sense that Gateway request validation now has an internal Control UI-only marker. Non-operator/public clients are rejected by validation coverage.

What is the highest-risk area?

Session-state and protocol boundary: avoiding a generic client-controlled override of idle/daily freshness.

How is that risk mitigated?

• resumeSession was removed from the public schema and generated Swift model.
• requestedSessionId / resumeRequestedSession were removed from exported GetReplyOptions and kept on internal Gateway/reply option types.
• The private marker is stripped before validation only for operator UI clients.
• Public WebChat coverage proves the marker is rejected for non-Control UI clients.
• Reply initialization still only resumes when the supplied sessionId matches the current session entry.

Related open PR / competition scan / contract scope:

• This update is scoped to the existing author PR fix(webchat): sessions persist after reconnects #89017 for [Bug]: Control UI webchat session silently resets after network disconnect / sleep — previous session file renamed to .jsonl.reset.* and lost from sessions tab #87700; it does not open a competing public-protocol PR or ask maintainers to accept a new public Gateway field.
• Same-contract check: the canonical source of truth remains the Gateway protocol schema; public clients get no resumeSession property, and the generated Swift model no longer exposes one.
• Compatibility boundary: because the public field was only proposed in this unmerged PR, removing it avoids creating a new external client contract rather than breaking a released one.

Patch quality warnings / notes:

• Patch quality warning, diff size: the PR necessarily spans Control UI request construction, Gateway request validation, session initialization, generated protocol model, docs, and regression tests so the contract is narrowed consistently; splitting would leave either the UI marker, protocol schema, or Gateway behavior inconsistent.
• Patch quality warning, default return: src/gateway/server.chat.gateway-server-chat-b.test.ts returns undefined from the mocked reply only to stop the harness after capturing reply initialization options; this is test-only control flow, not a production fallback.
• Patch quality warning, type escape: the unknown casts are confined to UI helper/test setup where the shared UI state object is intentionally sliced down to chat-controller fields; they do not widen the runtime chat.send payload or relax Gateway validation.

Current review state

What is the next action?

Maintainer-ready confidence: high after syncing with current main, fixing the remaining lint failure, revalidating build-artifacts coverage, refreshing live Gateway proof, and passing ClawSweeper commit review.

Review the narrowed implementation and let CI settle after this update.

What is still waiting on author, maintainer, CI, or external proof?

• Author-side conflict resolution is done against current main.
• Author-side CI repair is done: the check-lint failure is fixed without changing runtime behavior.
• Author-side product/API narrowing is done: no public chat.send.resumeSession protocol field remains.
• Author-side Plugin SDK boundary follow-up is done: reconnect resume controls are internal-only and not exported through GetReplyOptions.
• Remote CI and hosted ClawSweeper labels still need to recalculate after submit.
• Maintainers still need to accept the scoped one-shot Control UI freshness exception as the intended behavior for [Bug]: Control UI webchat session silently resets after network disconnect / sleep — previous session file renamed to .jsonl.reset.* and lost from sessions tab #87700.

Which bot or reviewer comments were addressed?

• RF-001: the existing status: ⏳ waiting on author label is addressed by this update; it should be recalculated by hosted ClawSweeper after submit.
• RF-002: addressed by Plugin SDK contract coverage proving public dispatch helper parameter types cannot accept private resume keys.
• RF-003: disclosed as the remaining maintainer product judgment: the one-shot Control UI exception to idle/daily freshness is intentionally scoped, requires a matching current sessionId, and is backed by live Gateway proof.
• RF-004: addressed by keeping requestedSessionId and resumeRequestedSession out of exported Plugin SDK GetReplyOptions.
• RF-005: disclosed as the intended scoped session-policy exception; it is Control UI-only, one-shot, and requires the matching current sessionId.
• RF-006: addressed by narrowing public reply-runtime dispatch signatures and running targeted Vitest coverage for Plugin SDK subpaths, Gateway reconnect forwarding/rejection, and session freshness behavior.
• RF-007: addressed by keeping resume controls out of the public Plugin SDK surface and carrying them only through internal Gateway/reply option types.
• RF-008: addressed by running the requested Vitest command successfully.
• RF-009: addressed by running the requested oxfmt --check command successfully.
• RF-010: addressed by running git diff --check successfully.