ruby_llm-browser 0.3.0 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c1e32269fa76e278df596a6e63e30d28506a9e7e3ada269703bad06ba870fef
-  data.tar.gz: d103e32333352508883d3794dd6e37a4aa3058d4f2e5842ccd174c6b2b43b11e
+  metadata.gz: fc13ef270cc86b7c259964fe10fc0b512fa2bd4c9ba4c8b66a6af827e30478ad
+  data.tar.gz: d0ba262e6456375b2efbfe833203befe32fb1aae197f9584e12e0d09fcdc9e24
 SHA512:
-  metadata.gz: 39769537e3c05f25231657f2b56ab72bda7690ac2b7e144149cac85a8d2d7de7b29e73f45a4dd41fe8e6718aa0f1535d6c2d77d5f4203469474b4a64e018dc4d
-  data.tar.gz: 1ff61fb1a7fe9017be814634d6763938e6a6652814df76386b43ca90217f2ffad2f51429a5edec1855a431300802182c8d2ad7c9a9eb00890a6612ba9ccd7da4
+  metadata.gz: '0385b825edf09eeb25391c7ce77d424c022bad3ed65e0e7933b9e76232ae98705e4a99ec07a08c56be9c5f2f7896743eb147339adcbc2b9be45cdca78a0ec8ac'
+  data.tar.gz: 7cf3f08b5ce9128d5978d0b4a80883c91bed38f11ad51bb554970fb48494d0b3017181721b135a1f0778a2da81a455ba3461a10ab37ab954c53e82eeb8785b09

data/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to
 follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.4.4] - 2026-10-21
+
+### Added
+
+- Pinned local Stagehand SDK feasibility contracts and `bin/check-local-stagehand`.
+  The runner starts no Stagehand server and makes no model or provider call.
+- Opt-in workbench network canaries for redirects, fetch, images, scripts, frames,
+  popups, Worker fetch, and WebSocket upgrade requests. Chrome tests calibrate
+  unrestricted and partial-denial controls, retain screenshots and request receipts,
+  and run in offline browser CI. They do not qualify deployment isolation.
+
+### Fixed
+
+- Require an explicit local Stagehand executable matching `server_binary_sha256`
+  before reporting a binary pin or constructing a local SDK client. Version labels
+  alone can select stale cached binaries or trigger downloads in Stagehand 3.21.0.
+  Doctor rechecks the executable without starting it; live support remains disabled.
+- Set the gem's `documentation_uri` to the hosted documentation site so RubyGems
+  displays its documentation link after the next release.
+
 ## [0.3.0] - 2026-10-19
 
 ### Added

data/README.md

@@ -3,7 +3,7 @@
 An unofficial [RubyLLM](https://rubyllm.com) extension for read-only browser inspection
 and schema-checked extraction, with an optional Rails 8 adapter.
 
-**0.3.0 supports offline use only.** `FakeBackend` runs without credentials or network
+**0.4.4 supports offline use only.** `FakeBackend` runs without credentials or network
 requests. The experimental Stagehand adapter refuses live operations; `Act` is an
 offline simulation. This project is not maintained or endorsed by RubyLLM or Browserbase.
 
@@ -16,7 +16,7 @@ offline simulation. This project is not maintained or endorsed by RubyLLM or Bro
 Use Ruby 3.2+ and RubyLLM 2.x. Add to your Gemfile, then run `bundle install`:
 
 ```ruby
-gem "ruby_llm-browser", "~> 0.3.0"
+gem "ruby_llm-browser", "~> 0.4.4"
 ```
 
 ## Try it offline

data/docs/README.md

@@ -5,6 +5,8 @@ stable release. The [next-version site](https://rubyllm-browser.wangyaodi.com/ne
 follows `main`. The Markdown files below are the source for those guides and ship in
 the gem.
 
+- [What's New in 0.4](_getting_started/whats-new-in-0-4.md): the 0.4.4 offline hardening release.
+- [Local Stagehand feasibility](_advanced/local-stagehand-deployment.md): pinned SDK contracts and browser network canaries.
 - [Getting started](_getting_started/getting-started.md): installation and an offline example.
 - [Configuration](_getting_started/configuration.md): host inputs and process defaults.
 - [Inspect and Extract](_core_features/inspect-extract.md): tools and result handling.

data/docs/RELEASING.md

@@ -17,7 +17,10 @@ After reading this guide, you will know:
 
 ## Compatibility evidence
 
-The source repository's `docs/evidence/V0_3_VALIDATION.md` records local 0.3.0 checks.
+The source repository's `docs/evidence/V0_4_4_VALIDATION.md` records local 0.4.4 checks.
+The 0.4.4 release ships offline executable hardening and development fixtures;
+live-deployment qualification remains incomplete. Historical 0.3.0 checks remain in
+`docs/evidence/V0_3_VALIDATION.md`.
 `docs/evidence/V0_3_RELEASE.md` records the exact remote CI, published artifact and
 hosted documentation results. The earlier audit below is historical evidence.
 
@@ -80,6 +83,7 @@ inventory are retained in the temporary evidence directory printed by the comman
 Verify all of the following:
 
 - Core require loads no Rails, Active Record, Active Job, or Stagehand client.
+- The built gem's `documentation_uri` points to the hosted documentation site.
 - The optional Rails require loads on demand.
 - The generated migration and all README-linked guides are shipped.
 - All shipped examples run using the installed artifact.

data/docs/_advanced/development-and-testing.md

@@ -61,7 +61,9 @@ credentials. The fixture and browser libraries are excluded from the gem.
 
 ```sh
 bin/check-browser
-# Or include browser tests after the offline checks:
+# Include the optional loopback network canaries:
+bin/check-browser --network
+# Include all browser tests after the offline checks:
 bin/check --browser
 ```
 
@@ -75,6 +77,14 @@ a 390px device viewport, and offline/blocked-Stagehand Doctor output. Capture sc
 active session, including on assertion failures. Inspect failure artifacts before
 retrying. Screenshots support visual review; assertions establish the expected behavior.
 
+`--network` adds same-origin and cross-origin canaries, partial image denial on mobile,
+and independent redirected-URL checks. CI and `bin/check --browser` include this option.
+The opt-in `bin/check-local-stagehand` runner also pins the SDK feasibility bundle and
+runs its HTTP contracts without starting Stagehand. See
+[Local Stagehand feasibility]({% link _advanced/local-stagehand-deployment.md %}) for
+request coverage and the remaining deployment gaps. Canary receipts and screenshots
+are review evidence; they do not qualify network isolation.
+
 The Puma host and Selenium port probe bind loopback. Browser test HTTP clients allow
 loopback only; this is not a Chrome network firewall. No live provider request is part
 of this suite. Tests close their driver sessions, and Puma ends with the test process.

data/docs/_advanced/live-backend-qualification.md

@@ -75,5 +75,6 @@ requests, and returned page text remains untrusted data. Review the [security mo
 
 ## Next Steps
 
+* [Local Stagehand feasibility]({% link _advanced/local-stagehand-deployment.md %}) - run pinned SDK contracts and loopback canaries without a provider.
 * [Controlling source access]({% link _core_features/source-policy.md %}) - set host URL policy.
 * [Running work in Rails]({% link _advanced/rails-integration.md %}) - protect durable jobs and recovery.

data/docs/_advanced/local-stagehand-deployment.md

@@ -0,0 +1,118 @@
+---
+layout: default
+title: Local Stagehand feasibility
+nav_order: 5
+description: Run offline checks for a pinned local Stagehand deployment and identify the remaining isolation requirements.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to run the local SDK contracts and browser canaries without a provider.
+- Which parts of a local deployment need separate host controls.
+- What still blocks supported live browsing.
+
+## Run the Offline Fixtures
+
+```sh
+BUNDLE_GEMFILE=gemfiles/local_stagehand.gemfile bundle install
+bin/check-local-stagehand
+```
+
+The source-checkout runner pins the Ruby SDK to `stagehand 3.21.0`. It runs the
+local HTTP contracts, executable identity regressions, and Chrome network canaries.
+It does not start Stagehand, download a server binary, or call a model. HTTP contracts
+use empty or synthetic credentials. Use `CHROME_BIN` and `CHROMEDRIVER` to select installed browser binaries.
+Installing dependencies may access the package registry. Once dependencies and a
+matching driver are installed, fixture execution needs only loopback access.
+
+The runner prints an ignored `tmp/local-stagehand/` directory containing screenshots
+and per-case JSON receipts. Each receipt declares `qualified: false`, the Chrome
+version, expected received request kinds, and actual server counters. A successful
+run establishes fixture calibration and SDK serialization, not a supported deployment.
+The fixture has no user-supplied destination URL and both origins point to loopback.
+
+You can also run `bin/check-browser --network` to combine the canaries with the
+existing workbench workflows. `bin/check --browser` includes them. The network routes
+are enabled only for the test instance of `dev/workbench.rb`. Normal `bin/workbench`
+does not expose them. All browser dependencies remain outside runtime dependencies.
+
+## Understand the Controls
+
+The same-origin control sends seven request types: fetch, image, script, iframe,
+popup, Worker fetch, and a WebSocket upgrade. The cross-origin control changes the
+destination from `127.0.0.1` to `localhost` on the same loopback server. An unrestricted
+Chrome must reach every canary. This detects tests that appear to deny a request only
+because the browser never sent it.
+
+A third control blocks the image through the current Chrome target's CDP network
+settings. The image fails while the other six canaries still arrive. The mobile test
+uses keyboard activation and checks overflow. This is a partial-denial calibration;
+CDP URL blocking is not the deployment's security boundary. A redirect scenario
+reads the resulting URL from Chrome and checks that the destination server received
+the request.
+
+The WebSocket endpoint records the HTTP upgrade request, then returns `426`. It does
+not open a tunnel. These tests do not qualify a successful WebSocket connection,
+WSS, HTTPS CONNECT, DNS changes, service workers, QUIC, IPv6 routing, or a production
+firewall. A later isolation run must test positive connectivity and forbidden
+destinations through the actual browser namespace, including every child target.
+
+## Account for the Pinned SDK
+
+The local HTTP suite uses the real SDK serializer with stubbed HTTP. It intercepts
+the SDK's server manager before process creation. The assertions establish these
+properties of SDK 3.21.0:
+
+| SDK behavior | Deployment consequence |
+| --- | --- |
+| `browser: { type: :local, cdp_url: ... }` serializes an attached browser without Browserbase credentials | You can investigate a separately supervised Chrome instead of letting Stagehand launch it |
+| Omitting the local browser type requires Browserbase credentials | A future adapter must explicitly select the local browser |
+| Local mode replaces a supplied `base_url` with its managed server endpoint | Passing a local URL does not attach to an externally supervised Stagehand server |
+| Navigation accepts `result: nil` | The host needs an independent, same-session final-URL check |
+| Ending a session returns `success` without terminal state | The host must confirm browser termination separately |
+| A lost start response raises after one request when retries are disabled | Recovery must retain quota until the supervisor resolves the owned browser |
+
+Read the pinned [SDK source](https://github.com/browserbase/stagehand-ruby/tree/v3.21.0/lib/stagehand)
+when changing these contracts. A stubbed response does not prove that a particular
+server binary implements the serialized options. Server compatibility still needs
+an offline, controlled deployment run before any model call.
+
+The gem's `StagehandBackend` remains unsupported. These SDK experiments do not add
+local browser attachment or Browserbase-free construction to its public API. Its
+local executable diagnostic requires an absolute `STAGEHAND_SEA_BINARY` and the
+host-approved `server_binary_sha256:`. See
+[API and configuration]({% link _reference/api-and-configuration.md %}) for the pinning
+contract and filesystem trust boundary.
+
+## Build the Deployment Boundary Next
+
+The selected direction is local Stagehand with a host-controlled browser network.
+Use a separately owned Linux browser namespace or equivalent enforced boundary. Keep
+the Stagehand model connection outside that namespace. The browser must have no
+direct route around the host's egress gateway, including loopback, host services,
+IPv6, UDP, and new browser targets. A Chrome proxy flag alone does not establish this.
+
+The gateway must enforce approved hosts and ports at connection time, reject private
+and mixed public/private DNS answers, and connect to the validated numeric address.
+Test denied redirects and every canary against the actual boundary. Fix the server
+binary hash, browser artifact, network configuration, and gateway version in the
+qualification evidence. No such deployment is qualified yet.
+
+An independent supervisor must own the browser before the Stagehand start request,
+bind it to the durable operation, enforce expiry after worker death, and confirm
+process and network teardown. A lost start response must remain reconcilable without
+a second start. A successful end response or a closed CDP connection alone cannot
+release quota. Keep unresolved operations visible for host review.
+
+Complete these offline deployment checks before requesting a separate live run.
+Keep Stagehand and live Act disabled until the
+[live-deployment acceptance criteria]({% link _reference/roadmap.md %}) pass.
+
+## Next Steps
+
+- Read [Qualifying a live backend]({% link _advanced/live-backend-qualification.md %}) for the full acceptance boundary.
+- Follow [Development and Testing]({% link _advanced/development-and-testing.md %}) for the regression and package checks.

data/docs/_config.yml

@@ -108,6 +108,6 @@ code_language: ruby
 # and {{ site.examples.NAME }}. Candidates remain unreleased; the docs builder
 # reads stable docs from the latest release tag and main under /next/.
 released: true
-version: "0.3.0"
-stable_version: "0.3.0"
+version: "0.4.4"
+stable_version: "0.4.4"
 examples: {}

data/docs/_data/navigation.yml

@@ -9,6 +9,6 @@
   collections:
     - reference
 - title: "What's New"
-  url: /whats-new-in-0-3/
+  url: /whats-new-in-0-4/
 - title: Releases
   url: https://github.com/yorzi/ruby_llm-browser/releases

data/docs/_getting_started/whats-new-in-0-4.md

@@ -0,0 +1,81 @@
+---
+layout: default
+title: What's New in 0.4
+redirect_from:
+  - /whats-new/
+nav_order: 4
+description: Verify local Stagehand executable identity and calibrate offline browser tests in the 0.4.4 release.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How local executable identity checks change.
+- How to run the pinned SDK and browser fixtures.
+- Which live-deployment requirements remain incomplete.
+
+## Verify the Local Executable
+
+Version 0.4.4 requires a host-approved checksum for local diagnostics:
+
+```ruby
+backend = RubyLLM::Browser::StagehandBackend.new(
+  browserbase_api_key: "diagnostic-placeholder",
+  model_api_key: "diagnostic-placeholder",
+  model_name: "diagnostic-model",
+  server: :local,
+  server_binary_sha256: reviewed_sha256
+)
+report = RubyLLM::Browser::Doctor.new(backend: backend).report
+```
+
+Set `STAGEHAND_SEA_BINARY` in the process environment to the absolute path of the
+reviewed executable. `reviewed_sha256` is its host-approved lowercase SHA-256. The
+diagnostic reads the file without running it. A missing, nonexecutable, changed, or
+mismatched file fails the binary check. A version label or unchecked path is no
+longer accepted as a pin. The SDK can otherwise use an existing cache or download
+a server binary. See [API and configuration]({% link _reference/api-and-configuration.md %}).
+
+The placeholders above are for diagnostics only. A passing executable check does
+not enable live calls. Doctor still reports Stagehand as unsupported.
+
+## Calibrate the Offline Fixtures
+
+From the source checkout, install the development bundle and run:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/local_stagehand.gemfile bundle install
+bin/check-local-stagehand
+```
+
+The runner pins Ruby SDK 3.21.0 and tests its HTTP serializer without starting
+Stagehand. Chrome canaries cover redirects, fetch, images, scripts, frames, popups,
+Worker fetch, and WebSocket upgrade requests. Same-origin and cross-origin controls
+confirm that requests actually arrive. A partial-denial control blocks only the image.
+The runner retains screenshots and request receipts with `qualified: false`.
+
+Read [Local Stagehand feasibility]({% link _advanced/local-stagehand-deployment.md %})
+for setup, coverage, and gaps. `bin/check-browser --network` and browser CI also run
+the canary calibration. These tools and dependencies are development-only.
+
+## Find the Documentation from RubyGems
+
+The gem's `documentation_uri` now points to the hosted documentation site. The
+packaged guides and examples remain available as Markdown. Runtime dependencies
+and the Rails database schema do not change in this release.
+
+## Live Support Remains Incomplete
+
+Version 0.4.4 supports offline operations through FakeBackend. It does not complete
+the original live-deployment milestone. Enforced browser egress, connection-time
+DNS/IP checks, an independent lifecycle supervisor, expiry, and confirmed cleanup
+still need deployment-specific evidence. Stagehand and live Act remain disabled.
+No real provider calls or live billing qualification form part of this release.
+
+## Next Steps
+
+- Follow [Upgrading]({% link _reference/upgrading.md %}) for the local diagnostic change.
+- Review [the roadmap]({% link _reference/roadmap.md %}) before preparing live tests.

data/docs/_reference/api-and-configuration.md

@@ -150,11 +150,25 @@ TTL, billing, final-URL reporting, or cleanup. `end_session` sends no request in
 release and returns `false`; the operation remains `cleanup_pending`.
 
 The constructor accepts `server: :remote`, `base_url:`, `timeout: 60.0`,
-`custom_headers_approved: false`, `env: ENV`, and an injected `client:` for internal
+`server_binary_sha256: nil`, `custom_headers_approved: false`, `env: ENV`, and an injected `client:` for internal
 contract tests. A future live implementation must verify all relevant environment
 settings, egress across every browser request path, TTL and closure status, and provider
 billing controls before it can advertise support.
 
+For local diagnostics, set process-level `STAGEHAND_SEA_BINARY` to an absolute path
+and supply the host-approved lowercase SHA-256 as `server_binary_sha256:`. The file
+must be a regular executable. The adapter checks its current bytes when reporting
+capabilities and before constructing the SDK client. An injected `env:` must select
+the same path as the real process environment. These checks do not execute the file.
+
+`STAGEHAND_SERVER_VERSION` alone does not establish a pin. Stagehand 3.21.0 checks
+its version-independent server cache before consulting that variable, and may download
+on a cache miss. An explicit matching executable avoids both paths. Obtain the expected
+digest through your host's artifact review; computing a digest of an untrusted file
+does not establish trust. Protect the executable and its parent directories from
+replacement during use. Hash checks do not provide filesystem isolation or make the
+unsupported adapter live-ready.
+
 ## Configuration diagnostics
 
 For diagnostics without network requests, use `Doctor.new(backend:).report`. It

data/docs/_reference/release-history.md

@@ -18,7 +18,8 @@ release notes to identify the exact source for this version.
 
 | Release | Date | Highlights |
 | --- | --- | --- |
-| [0.3.0]({% link _getting_started/whats-new-in-0-3.md %}) | 2026-10-19 | Opt-in Rails result delivery, durable host example, recovery and upgrade verification |
+| [0.4.4]({% link _getting_started/whats-new-in-0-4.md %}) | 2026-10-21 | Verified local executable identity, pinned SDK contracts, and offline browser network canaries |
+| [0.3.0]({% link _reference/whats-new-in-0-3.md %}) | 2026-10-19 | Opt-in Rails result delivery, durable host example, recovery and upgrade verification |
 | [0.2.0]({% link _reference/whats-new-in-0-2.md %}) | 2026-10-19 | Read-only tool factory, backend-aware Doctor, and agent development/browser verification |
 | [0.1.0](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0) | 2026-10-18 | Offline read-only Inspect and Extract, Rails adapter, and Act simulation; live Stagehand and live Act are unsupported |
 

data/docs/_reference/roadmap.md

@@ -42,14 +42,15 @@ feedback to settle the public API.
 | --- | --- | --- |
 | 0.2.0 | Easier tool setup and clearer offline diagnostics | Two additive features, tested with no provider requests |
 | 0.3.0 | Usable Rails result delivery | A host can retrieve a job's result after the worker exits |
-| 0.4.0 | One supported live read-only deployment | Egress, final URL, session expiry and cleanup qualified on that deployment |
+| 0.4.4 | Offline local Stagehand groundwork | Executable identity checks and calibrated browser fixtures |
+| Next live milestone | One supported live read-only deployment | Egress, final URL, session expiry and cleanup qualified on that deployment |
 | 0.5.0 | Pilot feedback and recovery hardening | Plain-Ruby and Rails workflows exercised outside the test suite |
 | 1.0.0-rc.1 | Stable API candidate | Feature freeze, complete upgrade instructions, candidate package verified |
 | 1.0.0 | Supported read-only integration | All acceptance criteria below pass on the release candidate |
 
 ### 0.2.0: Two Small Features
 
-Version `0.2.0` adds both features below. Milestones after 0.3 remain proposed scope. See
+Version `0.2.0` adds both features below. Live-deployment milestones remain proposed scope. See
 [What's New]({% link _reference/whats-new-in-0-2.md %}) for usage and
 [development and testing]({% link _advanced/development-and-testing.md %}) for validation.
 
@@ -75,7 +76,7 @@ validation precede the release tag and publication.
 
 Version `0.3.0` implements `Rails.result_delivery`, typed
 host-delivery failures, and a runnable SQLite host example with separate workers.
-Read [What's New in 0.3]({% link _getting_started/whats-new-in-0-3.md %}) and
+Read [What's New in 0.3]({% link _reference/whats-new-in-0-3.md %}) and
 [Rails Result Delivery]({% link _advanced/result-delivery.md %}) for the current API.
 The source repository's `docs/evidence/V0_3_VALIDATION.md` records local candidate
 checks. `docs/evidence/V0_3_RELEASE.md` records remote verification and publication.
@@ -91,7 +92,15 @@ A delivery failure must be visible and must never cause the browser operation to
 again. Document delivery semantics, duplicate handling, and recovery separately from
 the operation's session state. Verify generator upgrades preserve existing records.
 
-### 0.4.0: Qualify One Live Read-only Deployment
+### 0.4.4: Offline Local Stagehand Groundwork
+
+Version 0.4.4 includes the executable identity fix, pinned SDK contracts,
+browser canaries, and hosted documentation metadata fix. Read
+[What's New in 0.4]({% link _getting_started/whats-new-in-0-4.md %}). This release ships the offline
+foundation; the original live-deployment milestone remains open. It does not satisfy
+the live acceptance criteria below or advance the project to the pilot stage.
+
+### Next Live Milestone: Qualify One Read-only Deployment
 
 Begin with a feasibility check of the pinned SDK and a named deployment. Determine
 whether the deployment can enforce every required browser request boundary and report
@@ -108,6 +117,13 @@ Prepare the fixtures and opt-in qualification runner offline first. Live runs re
 separate owner authorization for the deployment, data, and spending. Keep default CI
 offline. Report provider billing controls separately from the advisory cost field.
 
+The selected target is a pinned local Stagehand deployment with a host-controlled
+browser network. Version 0.4.4 includes executable checksum checks, local SDK
+HTTP contracts, and calibrated loopback browser canaries. See
+[Local Stagehand feasibility]({% link _advanced/local-stagehand-deployment.md %}). These
+are offline foundations. The browser namespace, egress gateway, independent lifecycle
+supervisor, server artifact compatibility, and live acceptance remain incomplete.
+
 If the deployment cannot meet the required controls, stop this milestone and record
 the gap. Keep live support disabled. Do not replace qualification with a boolean flag
 or promote an offline-only package to 1.0 under this plan.

data/docs/_reference/upgrading.md

@@ -2,7 +2,7 @@
 layout: default
 title: Upgrading
 nav_order: 2
-description: Upgrade from 0.2.0 while preserving operation data and configuring optional Rails result delivery.
+description: Upgrade from 0.3.0 and configure verified local Stagehand executable identity for offline diagnostics.
 ---
 
 # {{ page.title }}
@@ -11,11 +11,11 @@ description: Upgrade from 0.2.0 while preserving operation data and configuring
 
 After reading this guide, you will know:
 
-- How to update an application from 0.2.0.
-- How to preserve existing data and enable result delivery.
-- Which result and worker behaviors change.
+- How to update an application from 0.3.0.
+- Why local binary diagnostics require a checksum.
+- Which existing workflows stay supported.
 
-## Upgrade from 0.2.0
+## Upgrade from 0.3.0
 
 Update your Gemfile and bundle:
 
@@ -27,41 +27,40 @@ gem "ruby_llm-browser", "~> {{ site.version }}"
 bundle update ruby_llm-browser
 ```
 
-This release adds no gem-managed database migration or runtime dependency. Preserve all
-operation, approval, and actor-lock rows. Do not rerun the install generator on an
-existing installation. Result storage belongs to your application.
+This release adds no runtime dependency or gem-managed database migration. Preserve
+all operation, approval, and actor-lock rows. Do not rerun the install generator on
+an existing installation. FakeBackend and opt-in Rails result delivery retain their
+existing contracts.
 
-## Enable Result Delivery When Needed
+## Supply Local Executable Identity
 
-`RubyLLM::Browser::Rails.result_delivery` defaults to `nil`. Existing job return values
-remain supported. To retain results after a worker exits, follow
-[Rails Result Delivery]({% link _advanced/result-delivery.md %}). Configure persistence,
-authorized reads, idempotent writes, and recovery before enabling the callback.
+The local adapter no longer treats `STAGEHAND_SERVER_VERSION` or an unchecked
+`STAGEHAND_SEA_BINARY` path as a binary pin. Configure an absolute executable path in
+the SDK process environment and pass `server_binary_sha256:` with its host-approved
+lowercase SHA-256 when constructing `StagehandBackend`.
 
-A callback failure raises `Rails::ResultDeliveryError`. Queue retries do not redeliver
-a result. The error retains the result only in process; it is not durable storage.
-Recover delivery separately from browser execution. A crash before host persistence
-can still lose the result, so do not treat this hook as guaranteed delivery.
+The local binary diagnostic fails for missing, nonexecutable, changed, or mismatched
+files. An injected `env:` must select the same path as the actual process environment.
+The adapter checks current file bytes without executing the file. Obtain the expected
+digest through your artifact review and protect the executable during use. See
+[API and configuration]({% link _reference/api-and-configuration.md %}) for the full
+contract. Remote diagnostics do not require this option.
 
-## Account for Immutable Results and Fenced Workers
-
-`Result` now also copies and freezes operation ID, error code and error message strings,
-consistent with its other fields. Mutating these attributes raises `FrozenError`;
-duplicate a string before changing it in host code. Caller-owned inputs stay mutable.
-
-A worker fenced during browser execution now returns `:fenced_out` and cannot deliver
-its stale result. Cancelled work never invokes the delivery hook, including while
-cleanup remains pending. Delivery failures do not change the session state or free
-quota. Stagehand and live Act remain unsupported.
+Stagehand remains unsupported even when the binary check passes. Do not replace the
+live qualification gate with a capability override. The new browser canaries calibrate
+offline fixtures; they do not establish production isolation or cleanup.
 
 ## Earlier Versions
 
-For upgrades from 0.1.0 and earlier development snapshots, first follow the
+For upgrades from 0.2.0, first read the
+[0.3.0 upgrading guide](https://github.com/yorzi/ruby_llm-browser/blob/v0.3.0/docs/_reference/upgrading.md)
+for result delivery, immutable results, worker fencing, and delivery recovery.
+For upgrades from 0.1.0, start with the
 [0.2.0 upgrading guide](https://github.com/yorzi/ruby_llm-browser/blob/v0.2.0/docs/_reference/upgrading.md).
 Preserve operation data and use additive migrations where required.
 
 ## Next Steps
 
-- Read [What's New in 0.3]({% link _getting_started/whats-new-in-0-3.md %}).
-- Review [release history]({% link _reference/release-history.md %}) and
-  [live-backend qualification]({% link _advanced/live-backend-qualification.md %}).
+- Read [What's New in 0.4]({% link _getting_started/whats-new-in-0-4.md %}).
+- Review [local deployment feasibility]({% link _advanced/local-stagehand-deployment.md %})
+  and [release history]({% link _reference/release-history.md %}).

data/docs/{_getting_started → _reference}/whats-new-in-0-3.md

@@ -1,9 +1,8 @@
 ---
 layout: default
 title: What's New in 0.3
-redirect_from:
-  - /whats-new/
-nav_order: 4
+parent: Release History
+nav_order: 3
 description: Deliver Rails background results to host storage without repeating browser work on delivery failure.
 ---
 

data/lib/ruby_llm/browser/doctor.rb

@@ -98,11 +98,11 @@ module RubyLLM
         return nil unless backend&.capabilities&.local_mode?
 
         if backend.capabilities.local_binary_pinned?
-          check(:local_binary, :pass, "local mode uses a host-pinned server binary or version")
+          check(:local_binary, :pass, "local mode reports a verified host-pinned executable")
         else
           check(:local_binary, :fail,
-                "local mode has no host-pinned #{StagehandBackend::PINNED_BINARY_ENV} or " \
-                "#{StagehandBackend::PINNED_VERSION_ENV}; the SDK would download a binary")
+                "local mode requires an absolute executable #{StagehandBackend::PINNED_BINARY_ENV} " \
+                "matching server_binary_sha256 in the SDK process environment")
         end
       end
 

data/lib/ruby_llm/browser/stagehand_backend.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module RubyLLM
   module Browser
     # An experimental {Backend} adapter for the official `stagehand` Ruby SDK.
@@ -13,8 +15,8 @@ module RubyLLM
     #   the SDK otherwise retries errors and timeouts
     # - never returns `cdp_url`, cookies or credentials, and reports the pinned API keys
     #   as secret literals so they are scrubbed from page text and results
-    # - refuses to construct a live client in local mode unless a host-pinned server
-    #   binary or version is present, so it never triggers the SDK's runtime download
+    # - refuses to construct a client in local mode unless an explicit executable
+    #   matches the host's SHA-256, avoiding the SDK's download and version cache
     #
     # The SDK is required lazily, inside {#client}, so requiring this Gem never reads
     # Stagehand environment variables and never starts or downloads a server.
@@ -38,13 +40,15 @@ module RubyLLM
       # @param base_url [String, nil] explicit endpoint; defaults to the official remote
       #   endpoint. Never read from the environment.
       # @param timeout [Numeric] per-request timeout in seconds
+      # @param server_binary_sha256 [String, nil] host-approved lowercase SHA-256 of
+      #   the executable selected by process-level `STAGEHAND_SEA_BINARY`
       # @param custom_headers_approved [Boolean] whether the host approved the SDK's
       #   always-merged `STAGEHAND_CUSTOM_HEADERS`
       # @param env [Hash] environment to inspect; injectable for tests
       # @param client [Object, nil] an already-built client (tests/advanced hosts)
       def initialize(browserbase_api_key:, model_api_key:, model_name:,
                      server: :remote, base_url: nil, timeout: 60.0,
-                     custom_headers_approved: false, env: ENV, client: nil)
+                     server_binary_sha256: nil, custom_headers_approved: false, env: ENV, client: nil)
         super()
         @browserbase_api_key = presence!(browserbase_api_key, :browserbase_api_key)
         @model_api_key = presence!(model_api_key, :model_api_key)
@@ -52,22 +56,14 @@ module RubyLLM
         @server = server_mode!(server)
         @base_url = base_url.nil? ? default_base_url : presence!(base_url, :base_url)
         @timeout = positive_number!(timeout, :timeout)
+        @server_binary_sha256 = checksum!(server_binary_sha256)
         @env = env
         @environment_snapshot = relevant_environment(env)
         @process_environment_snapshot = relevant_environment(ENV)
         @custom_headers_present = !env[CUSTOM_HEADERS_ENV].to_s.empty? || !ENV[CUSTOM_HEADERS_ENV].to_s.empty?
         @custom_headers_approved = !!custom_headers_approved
-        @local_binary_pinned = local? && pinned_binary?
         @client_mutex = Mutex.new
         @client = client
-        @capabilities = Capabilities.new(
-          server_mode: local? ? :local : :remote,
-          egress_isolation: :unverified,
-          local_binary_pinned: @local_binary_pinned,
-          custom_headers_present: @custom_headers_present,
-          custom_headers_approved: @custom_headers_approved,
-          act_supported: false
-        )
       end
 
       # The pinned credential literals, so the redactor scrubs them from any page text
@@ -75,10 +71,11 @@ module RubyLLM
       def secrets = [ @browserbase_api_key, @model_api_key ]
 
       def capabilities
-        return @capabilities if environment_unchanged?
-
+        unchanged = environment_unchanged?
         Capabilities.new(server_mode: local? ? :local : :remote, egress_isolation: :unverified,
-                         custom_headers_present: true, custom_headers_approved: false,
+                         local_binary_pinned: local? && unchanged && pinned_binary?,
+                         custom_headers_present: unchanged ? @custom_headers_present : true,
+                         custom_headers_approved: unchanged && @custom_headers_approved,
                          act_supported: false)
       end
 
@@ -178,8 +175,8 @@ module RubyLLM
 
       def build_client
         raise UnsupportedSecurityCapability, "Stagehand environment changed; rebuild the backend" unless environment_unchanged?
-        if local? && ENV[PINNED_BINARY_ENV].to_s.empty? && ENV[PINNED_VERSION_ENV].to_s.empty?
-          raise UnsupportedSecurityCapability, "local mode requires a process-level server pin"
+        if local? && !pinned_binary?
+          raise UnsupportedSecurityCapability, "local mode requires an executable matching the host checksum"
         end
         require "stagehand"
         Stagehand::Client.new(
@@ -279,7 +276,24 @@ module RubyLLM
       end
 
       def pinned_binary?
-        !@env[PINNED_BINARY_ENV].to_s.empty? || !@env[PINNED_VERSION_ENV].to_s.empty?
+        return false unless @server_binary_sha256
+
+        path = @env[PINNED_BINARY_ENV].to_s
+        return false unless path.start_with?("/") && path == ENV[PINNED_BINARY_ENV]
+        return false unless File.file?(path) && File.executable?(path)
+
+        Digest::SHA256.file(path).hexdigest == @server_binary_sha256
+      rescue SystemCallError, IOError
+        false
+      end
+
+      def checksum!(value)
+        return nil if value.nil?
+        unless value.is_a?(String) && /\A[0-9a-f]{64}\z/.match?(value)
+          raise InvalidInput, "server_binary_sha256 must be a lowercase SHA-256 digest"
+        end
+
+        value.dup.freeze
       end
 
       def default_base_url

data/lib/ruby_llm/browser/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Browser
     # The Gem version. Development happens ahead of any public release: the packaged
     # version is not a RubyGems publication claim.
-    VERSION = "0.3.0"
+    VERSION = "0.4.4"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-browser
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.4
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -173,6 +173,7 @@ files:
 - docs/WORK.md
 - docs/_advanced/development-and-testing.md
 - docs/_advanced/live-backend-qualification.md
+- docs/_advanced/local-stagehand-deployment.md
 - docs/_advanced/rails-integration.md
 - docs/_advanced/result-delivery.md
 - docs/_config.yml
@@ -187,7 +188,7 @@ files:
 - docs/_getting_started/configuration.md
 - docs/_getting_started/getting-started.md
 - docs/_getting_started/overview.md
-- docs/_getting_started/whats-new-in-0-3.md
+- docs/_getting_started/whats-new-in-0-4.md
 - docs/_plugins/versioned_docs.rb
 - docs/_reference/api-and-configuration.md
 - docs/_reference/api-reference.md
@@ -195,6 +196,7 @@ files:
 - docs/_reference/roadmap.md
 - docs/_reference/upgrading.md
 - docs/_reference/whats-new-in-0-2.md
+- docs/_reference/whats-new-in-0-3.md
 - docs/bin/build-api.sh
 - docs/bin/build.sh
 - docs/bin/export-api-markdown.rb
@@ -251,6 +253,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/yorzi/ruby_llm-browser
+  documentation_uri: https://rubyllm-browser.wangyaodi.com
   changelog_uri: https://github.com/yorzi/ruby_llm-browser/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/yorzi/ruby_llm-browser/issues
   rubygems_mfa_required: 'true'