feat(chat): dispatch OpenClaw turns through Gateway

[CompleteDotTech]

DO NOT MERGE - WORK IN PROGRESS

Summary

Implements the first production slice of direct OpenClaw Gateway dispatch. Cave now uses the supported v4 Gateway client as the authoritative transport when explicitly configured, captures the Gateway-accepted run ID, and never starts a duplicate CLI turn once a dispatch might have been accepted.

What changed

• Pin the official Gateway client and protocol packages to 2026.7.2-beta.4, plus the published TypeBox runtime validator.
• Add an opt-in direct Gateway dispatcher (OPENCLAW_GATEWAY_DISPATCH=1) with challenge-bound authentication, exact v4 negotiation, operator read/write scope checks, capability checks, idempotent chat.send, accepted-run binding, and run-sequence enforcement.
• Route accepted Gateway chat lifecycle events into SSE and persisted conversation turns; reject foreign runs even when session and agent match.
• Preserve the CLI bridge only when Gateway acceptance is disproven; report an indeterminate acknowledgement without duplicating the turn.
• Fence cancellation before chat.abort so queued or late results cannot turn a cancelled run into success.
• Add correlated-dispatch and route-ownership regression coverage.

Deliberate compatibility boundary

The current published protocol package validates the run-scoped chat event but does not publish a stable session.tool payload schema. This change therefore requests the capability but fails closed for tool-card projection rather than interpreting undocumented frames. The retained CLI/plain-chat stop point from #3852 remains available.

Linked work

• Implements part of Implement direct Gateway-dispatched OpenClaw tool activity #3865
• Parent compatibility work: Add full OpenClaw tool-activity compatibility #3847
• Safe fallback decision record: chore(chat): retain OpenClaw CLI fallback stop point #3852
• Milestone: feat(brand): swap app icon to the hooded-familiar mark #3 Runtime Tool-Activity Compatibility

Validation

• node --experimental-strip-types src/lib/openclaw-gateway.test.ts
• node --experimental-strip-types src/app/api/chat/send/harness-routing-tool-events.test.ts
• pnpm check:tests-wired
• pnpm exec tsc --noEmit --pretty false
• pnpm lint
• git diff --check

[CompleteDotTech]

do not merge work in progress.

[BunsDev]

Frontend build blocker: stale api-contracts.test.ts adapter-count assertions

The Frontend build fails (not stale/flaky — it tested the current head 8eab170e0). The Gateway dispatch path adds a third /chat/send adapter path, but a cluster of contract assertions in src/app/api/api-contracts.test.ts still expect exactly 2 adapter paths. Confirmed the code now has 3 registerChatRun( calls (lines 609, 768, 2145) while the test asserts 2.

Affected assertions (each encodes intended stop/cancel semantics for the send route — a design call, not a rubber-stamp bump):

• runRegistrations → both adapter paths must register with the stop registry (= registerChatRun() — currently expects 2
• cancelledFlags → both adapter paths must persist cancelled: true on the assistant turn — currently expects 2
• guardedDiagnostics → empty-response diagnostic skipped when cancelled — currently expects 2
• stopReads → both paths detect deliberate stop (runHandle.stopRequested) — legitimately stays 2 (only 2 paths read it)

Question for the author: should the new Gateway dispatch path behave identically to the other two adapters (register with the stop registry, persist cancelled: true, guard empty-response diagnostics)? If yes, bump the three counts 2→3. If the Gateway path intentionally differs on cancel-safety, the assertions need path-specific updates instead. Not guessing at cancel-safety behavior here.

[BunsDev]

Closing as superseded by #3905. The newer draft carries the Gateway scope on current main with stable Cave-run idempotency, reconnect fencing, capability checks, credential isolation, and the explicit fail-closed blockers. This older branch remains on a stale base, includes unrelated commits, and its retry/sequence handling can duplicate or accept uncorrelated side effects, so it should not be merged.