fix(runtime): harden Crabfleet lifecycle boundaries

.github/workflows/deploy-crabbox-coordinator.yml

@@ -20,7 +20,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           repository: openclaw/crabbox
-          ref: main
+          ref: ec073fdcf868b2d5c450d600d900cdf41f958de9 # crabbox main, 2026-07-11
 
       - name: Set up Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0

.gitignore

@@ -1,5 +1,6 @@
 node_modules
 src/spec.generated.ts
+# Rebuilt from canonical sources by pnpm check/build/deploy; do not commit.
 src/generated.ts
 dist/
 .wrangler/

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+- Resolve final audit blockers by preserving unknown GitHub Actions input outcomes across runner replacement, disconnect, upstream close or error, bounded PTY-write failure, and post-write confirmation loss, making terminal confirmation races prefer completed delivery, retiring terminal connections after late detached-writer failures, replaying control grants across attachment gaps, retaining rollback recovery and authorized namespace retirement after a staged credential write begins, reserving expired write-started credential rows for recovery, requiring active credential generations to match the exact current lookup set, proving interrupted pre-fence migration recovery, blocking session deletion while staged credential rows remain, validating ARD safe-prime groups and nonzero key material with bounded accepted-prime caching, deferring partial-fence ZRLE resets to a trailing synchronization boundary, rejecting legacy mutations and deletions of token-owned desktop registrations, discarding definitively unowned publication recovery without tokenless cleanup, documenting the opaque publication-ID contract, completing ambiguous legacy publication cleanup despite persistence failures, and holding generated-asset tests under a crash-released lock through module consumption.
+- Close the final review blockers by requiring an exact live credential-policy lease at promotion, negotiating strict runtime-adapter deletion tombstones without breaking legacy `404` release semantics, disconnecting VNC sessions when pixel-format capability probes cannot establish a safe ZRLE boundary, classifying aborted JSON body streams as bad requests, and preserving live terminal subscriptions when browser history restores the sessions grid.
+- Complete the final audit follow-up by fencing rollback against newer legacy credential generations, keeping viewer acknowledgement timeouts from detaching live GitHub Actions sessions, fencing queued documented-runner input after relay replacement, generating ignored embedded assets before parity tests import them, resetting ZRLE exactly at pixel-format boundaries, preventing delayed tokenless desktop cleanup from deleting replacement publishers, skipping idle recovery I/O when no local state exists, and stopping canceled auto-share preflight.
+- Preserve upgrade and teardown authority by leaving pre-lookup-migration credential registrations recoverable from current and historical runtime identities, retaining GitHub Actions runner generations after queues drain, scoping Share This Mac recovery state to the normalized API origin and stable owner, allowing idle termination after unavailable recovery lookup while retaining active cleanup vetoes, terminating timed-out or canceled Tailscale descendant process groups, clearing only definitive failed publication intent, quiescing remote-input producers before final release, rejecting UltraVNC Diffie-Hellman elements at `p - 1`, and synchronizing complete RFB pixel-format and encoding transitions with protocol-required ZRLE resets.
+- Finish the audited terminal, credential, runtime, and native-app lifecycle boundaries by explicitly negotiating the generation-fenced GitHub Actions runner protocol, retiring stale and overflowing runner input queues, capturing relay replacement during viewer authorization, fencing retired Go terminal attachments, repairing credential lookup namespaces with rollback-compatible staging, requiring replayable runtime-adapter deletion tombstones, validating Apple Remote Desktop Diffie-Hellman groups, keying desktop publication cleanup by the API host ID, and requiring exact retained identity before uncertain publication recovery; the runner guide now preserves raw fallback, bounds admission before serialized restricted steering, and distinguishes unknown delivery from rejection.
+- Harden session lifecycle concurrency with atomic card claims and duplicate-first claim results, single-winner GitHub Actions credential rotation, monotonic exact authenticated-revision fences on runner writes, terminal session-status fences, revision-fenced lifecycle updates and grant revocation, exclusively claimed rollback recovery for Sandbox credential rotation, rejection of live legacy registration claims during migration without staging renewable legacy claims, staged-rotation fences that block legacy policy mutation while new-worker claims are live but release abandoned rows for rollback compatibility, persisted staged lookup identities across namespace changes with exact current-identity fallback for mixed-version rows, ownership-fenced repair of incomplete and rotated lookup sets before credential rotation, explicit retirement of obsolete durable identities, idempotent recovery after ambiguous committed promotion, R2-clean reservation rollback, preserved Sandbox attachment state, retained registration data for superseded runtime workspace cleanup, and durable observed-deletion markers that terminate cleanup after post-delete crashes.
+- Close final terminal and desktop publication race windows by carrying the initial GitHub Actions runner generation through viewer authorization, translating generation-fenced acknowledgements for legacy framed viewers, serializing and bounding per-runner PTY input by frames, bytes, and age, matching generation-fenced local send failures, ordering raw and confirmed Go client acknowledgements, bounding shutdown when terminal writers block, rejecting malformed desktop recovery IDs as client errors, preserving idempotent publication retries across mixed worker versions, and retaining uncertain Share This Mac publications when older servers lack the recovery route.
+- Make terminal input delivery durable across multiplex subscribers, apply backpressure until an attachment owns initial output while waking blocked readers to discard and acknowledge output for one-shot confirmed messages, retain pre-attach closure, prefer completed input over later transport shutdown, reject denied or unacknowledged input explicitly, prevent delivery into retired attachments and wait for their frame consumers even when input reads cannot be canceled, bound serialized browser input backlog by frame count and bytes while preserving one ordered completion per dropped frame, enforce relay-owned runner generations before forwarding GitHub Actions input and acknowledgements, snapshot SSH connection limits before launching handlers, make confirmation serialization cancelable, bound attachment confirmation waits, serialize every acknowledgement-aware input source and per-subscription completion event, wake uncancelable attachments when their context ends, retire connections after ambiguous confirmation timeouts, negotiate bounded one-shot input acknowledgements across rolling upgrades without waiting on empty payloads, keep configured HTTP timeouts from canceling established sockets, scope rejected writes without dropping live subscriptions, and send attributed commands atomically to prevent interleaving.
+- Add connection-query-negotiated `CFR1` input, output, and acknowledgement frames across GitHub Actions runner and internal viewer relay boundaries, confirm viewer negotiation before leaving raw fallback during mixed deployments, document the independent legacy viewer fallback, buffer split UTF-8 within byte, frame, and age bounds until the string-only Node adapter delivers it to the PTY before acknowledging every contributing frame, define that adapter's UTF-8-only output contract while preserving opaque bytes for byte-oriented adapters, close the runner socket when its PTY exits, prevent binary PTY output from colliding with relay control frames, and keep multiplex dispatch responsive while framed input acknowledgements are pending.
+- Preserve bounded opaque profile IDs for fixed runtime adapters while rejecting unroutable or ambiguous adapter routes only when provisioning depends on them, so mixed migration configuration cannot break unrelated control-plane reads; durably claim and retry superseded workspace cleanup without touching the replacement workspace; also reject malformed encoded session routes, numeric literals that become integers only after precision loss, and invalid-Unicode JSON event values, and reconcile browser history drawers and focus on back/forward navigation.
+- Harden Share This Mac against stale starts and responses, canceled starts stranded in transition, self-connections, leaked subprocess environment, stalled Tailscale and RFB handshakes, successful commands whose descendants retain output pipes, stale desktop registrations including listener-failure, ambiguous committed publication reconciled by stable publication identity, and application-termination races with durably retained cleanup retries, legacy publishers mutating or deleting token-owned registrations, concurrent teardown calls that could outpace application termination, completed teardown operations coalescing a later stop, dropped auto-starts, stuck remote input including releases retained through revoked Accessibility trust and teardown with bounded retries and no retry when no input is held, and destructive non-text or empty clipboard changes while preserving repeated remote text, X11 Unicode input, proxy, custom-CA networking, and validated Crabbox config/state paths.
+- Fence Share This Mac registry cleanup with explicitly negotiated per-registration ownership tokens, require a valid publication identity before selecting token ownership, and return the exact atomically written registration row so delayed or overlapping current publishers cannot displace cleanup authority, while preserving tokenless registration and cleanup for rolling upgrades with legacy clients or servers.
+- Harden the bundled RoyalVNCKit fork across ARD and UltraVNC authentication and parameter validation, composed Unicode keysyms with legacy ASCII scalars, Tight and ZRLE parsing, non-trapping bounded zlib streams, RFB Fence-synchronized color-depth transitions with atomic capability publication, premature-response rejection, and fail-closed legacy handling, CopyRect, EOF handling, reconnects, credential cancellation and release after handoff, and cursor channel preservation.
+- Pin Crabbox coordinator deployment to an immutable source revision and verify downloaded Crabbox release archives before image assembly, always enforcing the repository digest for the default version and requiring an explicit architecture checksum for non-default versions.
 - Add a VideoToolbox-backed Open H.264 RFB pipeline for Share This Mac with up to 60 fps capture, adaptive 1.5–30 Mbit/s rate control, automatic Tight/JPEG fallback, live stream stats, larger resize limits, and a persisted host-enforced view-only mode.
 - Exchange full UTF-8 clipboard text between the native Mac viewer, Share This Mac hosts, and any Extended Clipboard-capable VNC server by completing the RoyalVNCKit fork's extension stub, keeping Latin-1 cut text as the fallback and dropping malformed extension bodies without tearing down the connection.
 - Add persisted send-only and receive-only clipboard directions to the native viewer's focus toolbar; automatic sync respects the direction while the explicit Send and Get actions keep working.

Dockerfile

@@ -3,6 +3,8 @@ FROM docker.io/cloudflare/sandbox:0.10.1
 USER root
 
 ARG CRABBOX_VERSION=0.17.1
+ARG CRABBOX_SHA256_AMD64=
+ARG CRABBOX_SHA256_ARM64=
 
 RUN set -eux; \
   apt-get update; \
@@ -61,10 +63,34 @@ RUN set -eux; \
 
 RUN set -eux; \
   arch="$(dpkg --print-architecture)"; \
-  case "$arch" in amd64|arm64) ;; *) echo "unsupported arch: $arch" >&2; exit 1 ;; esac; \
+  case "$arch" in \
+    amd64) \
+      override_checksum="$CRABBOX_SHA256_AMD64"; \
+      checksum_arg="CRABBOX_SHA256_AMD64"; \
+      pinned_checksum="3c41839257e4622e28bcec8b0f0153f19d78d436fd548894a7c7d7726d922611" \
+      ;; \
+    arm64) \
+      override_checksum="$CRABBOX_SHA256_ARM64"; \
+      checksum_arg="CRABBOX_SHA256_ARM64"; \
+      pinned_checksum="4bf87a0d2365441ee2f8cb34183cfd9ebeb065111697eb2d8dc867b3a627fdd2" \
+      ;; \
+    *) echo "unsupported arch: $arch" >&2; exit 1 ;; \
+  esac; \
+  archive="crabbox_${CRABBOX_VERSION}_linux_${arch}.tar.gz"; \
+  if [ "$CRABBOX_VERSION" = "0.17.1" ]; then \
+    checksum="$pinned_checksum"; \
+  else \
+    checksum="$override_checksum"; \
+    if [ -z "$checksum" ]; then \
+      echo "an explicit $checksum_arg is required for non-default versions" >&2; \
+      exit 1; \
+    fi; \
+  fi; \
+  printf '%s\n' "$checksum" | grep -Eq '^[0-9a-f]{64}$'; \
   curl -fsSL \
-    "https://github.com/openclaw/crabbox/releases/download/v${CRABBOX_VERSION}/crabbox_${CRABBOX_VERSION}_linux_${arch}.tar.gz" \
+    "https://github.com/openclaw/crabbox/releases/download/v${CRABBOX_VERSION}/${archive}" \
     -o /tmp/crabbox.tar.gz; \
+  echo "$checksum  /tmp/crabbox.tar.gz" | sha256sum -c -; \
   tar -xzf /tmp/crabbox.tar.gz -C /usr/local/bin crabbox; \
   chmod +x /usr/local/bin/crabbox; \
   rm -f /tmp/crabbox.tar.gz; \

README.md

@@ -94,14 +94,27 @@ Content-Type: application/json
 {"workKey":"openclaw/crabfleet:pr:42","workKind":"pr_repair","repo":"openclaw/crabfleet","branch":"fix/pr-42","owner":"operator@example.test","sourceUrl":"https://github.com/openclaw/crabfleet/pull/42","runUrl":"https://github.com/openclaw/crabfleet/actions/runs/123","purpose":"repair PR 42","summary":"starting repair"}
 ```
 
-The response contains `{session, agentToken, runnerPtyUrl, browserUrl}`. New registrations and resumes require `owner` to resolve to one active Crabfleet user; resumes must prove the same stable owner subject already recorded on the `workKey`. The stable subject owns browser visibility while the OpenClaw service retains lifecycle authority for its session. `runnerPtyUrl` includes the rotated session-scoped query credential and works directly with Node's global `WebSocket`:
+The response contains `{session, agentToken, runnerPtyUrl, browserUrl}`. New registrations and resumes require `owner` to resolve to one active Crabfleet user; resumes must prove the same stable owner subject already recorded on the `workKey`. The stable subject owns browser visibility while the OpenClaw service retains lifecycle authority for its session. `runnerPtyUrl` includes the rotated session-scoped query credential and can be opened unchanged as the legacy raw duplex byte stream. New runners offer the framed protocol as a WebSocket subprotocol:
 
 ```js
-const terminal = new WebSocket(runnerPtyUrl);
-terminal.onmessage = (event) => process.stdout.write(Buffer.from(event.data));
-process.stdin.on("data", (chunk) => terminal.send(chunk));
+const terminal = new WebSocket(runnerPtyUrl, "cfr1-framed-io-v2");
+terminal.binaryType = "arraybuffer";
+terminal.addEventListener("open", () => {
+  const framed = terminal.protocol === "cfr1-framed-io-v2";
+  // Use CFR1 only when framed is true; otherwise retain raw compatibility.
+});
 ```
 
+Existing runners retain raw input and output by opening the returned URL
+unchanged. A new runner opts into correlated binary `CFR1` input, output, and
+acknowledgement frames only when the relay selects the
+`cfr1-framed-io-v2` WebSocket subprotocol in the upgrade response. Relays that
+ignore the offer leave `WebSocket.protocol` empty, so new runners retain raw
+compatibility. The relay fences negotiated runner input with its connection
+generation. Framed runners acknowledge only after their PTY accepts the input.
+The complete byte-safe encoder, decoder, and Node PTY runner are in
+[`docs/github-actions-sessions.md`](docs/github-actions-sessions.md#runner-pty).
+
 The runner reports heartbeat and durable progress with bearer `agentToken` to `POST /api/agent/interactive-sessions/:id/work-state`. Terminal states are `completed`, `blocked`, `failed`, and `canceled`; active work uses `registered` or `running` plus a specific `phase`.
 
 The full registration, relay, resumption, steering, heartbeat, completion,