ruby_llm-browser 0.1.0 → 0.3.0

data/docs/RELEASE_ACTION_PLAN.md

@@ -7,26 +7,41 @@ llms: false
 
 # Release action plan
 
+This is the historical 0.1.0 release record. Use the
+[roadmap to 1.0]({% link _reference/roadmap.md %}) for upcoming development.
+
 The owner selected the offline-only first release as `0.1.0`, authorized its publication,
-and requested tag-based release automation. This plan preserves the live-provider limits
-and records the release checks.
+and requested tag-based release automation. Version `0.1.0` is published. This plan records
+the outcome and preserves the live-provider limits for future work.
 
 ## Current position
 
-- Hardening baseline: `0ec34d4`.
-- Expanded remote CI is green: seven test jobs and the package/install/advisory job.
+- Hardening baseline: `0ec34d4`; release workflow fix: `8f0e8e7`.
+- Expanded remote CI passed before release. Tagged verification and publication passed in
+  [release run 39110148539](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110148539).
+- RubyGems lists [ruby_llm-browser 0.1.0](https://rubygems.org/gems/ruby_llm-browser).
+  Publication used the registered trusted publisher for `yorzi/ruby_llm-browser`,
+  `.github/workflows/release.yml`, and environment `release`; MFA publication is recorded.
+- The [GitHub Release](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0)
+  includes the gem and `SHA256SUMS`. The gem SHA-256 is
+  `0159bf5b4d50fc1a5d129ce8e6d8235ff9a5181704d5e8168c2facb429808ed3`.
+- The post-release Pages build passed in
+  [Docs run 39110265391](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110265391).
+  The [custom-domain docs site]({% link index.md %}) shows `0.1.0 (stable)`.
+- The first publish attempt failed before upload because the action's optional
+  experimental attestation patch activated Ruby's default zlib before Bundler. The
+  unpublished tag was moved to a fix that disables that patch; OIDC publication remains.
 - Owner decision on 2026-10-18: first release is read-only; defer live Act and mark the
   built-in Stagehand backend unsupported until egress and cleanup are qualified.
 - No live provider calls are authorized or were run for this decision.
 - Independent H1 and owner H2 are complete for exact candidate Q
   `22d488987517b10dcd96d2713ed3d47e8818b36b`. H2 approves handoff, not RubyGems publication.
-- The RubyGems page for `ruby_llm-browser` returned 404 during the pre-release check on
-  2026-10-18; that did not reserve the name. The resolved 26-gem runtime license inventory
-  matches installed gemspec metadata; Stagehand is covered by its pinned source MIT text.
-- The owner later instructed publication of gem version `0.1.0`; that instruction is
-  separate from H2's handoff approval. RubyGems MFA is enabled on the signed-in publisher
-  account. Trusted publishing must match this repository's `release.yml` workflow and
-  `release` environment.
+- The pre-release exact-name check returned 404 on 2026-10-18; it did not reserve the
+  name. Version `0.1.0` is now registered on RubyGems. The resolved 26-gem runtime license
+  inventory matches installed gemspec metadata; Stagehand is covered by its pinned source
+  MIT text.
+- The owner instructed publication separately from H2's handoff approval. The gem requires
+  MFA, and RubyGems records the successful publication as MFA-protected.
 
 ## Release scope
 
@@ -42,9 +57,9 @@ exact Q `22d488987517b10dcd96d2713ed3d47e8818b36b`; the approved Specs candidate
 | --- | --- | --- |
 | Release scope / Act | H2 approved the read-only scope and KPI proposal against exact Q. Live Act remains a later-version feature. | Keep the Stagehand adapter disabled and preserve the H2 decision in release docs. |
 | Provider qualification | No live call is authorized for the first release. A later live release needs a named deployment and approval of data-processing/billing owners. | Record the unsupported egress and cleanup guarantees. Do not use a host assertion as qualification. |
-| Name and account | The owner authorized publication as `ruby_llm-browser`; the account has MFA enabled. | Recheck name availability at publication and use the pending trusted publisher configured for this repo and workflow. |
+| Name and account | The owner authorized publication as `ruby_llm-browser`; version `0.1.0` is registered and MFA-protected. | Use the existing trusted publisher for future tags; do not add a long-lived RubyGems API key to GitHub. |
 | Formal approval | H1 and H2 are complete for exact Q; C/R registration and implementation baseline receipt remain pending. | Preserve the historical approval. Do not represent H2 as RubyGems authorization; the owner's later release instruction supplies that authorization. |
-| Publication | Owner instructed publication of package version `0.1.0`. | Verify the matching tag, run the release workflow, then record the RubyGems, GitHub Release and Pages outcomes. |
+| Publication | Version `0.1.0` is published under tag `v0.1.0`; GitHub Release assets and stable Pages are live. | For each later version, align gem/docs/changelog metadata and push the matching tag. The release workflow verifies tests, advisories and package contents before OIDC publishing; Docs deploys after success. |
 
 ## Provider questions to resolve before live tests
 

data/docs/RELEASE_AUDIT.md

@@ -156,3 +156,22 @@ does not authorize provider calls, make Stagehand supported, or implement live A
 approved Specs Q remains identified by its historical candidate label `0.3.0-draft`.
 RubyGems publication and GitHub Pages deployment results are recorded separately from
 this pre-release audit snapshot.
+
+## Publication outcome (2026-10-18)
+
+The owner authorized publishing the offline-only `0.1.0` package after the earlier audit
+snapshot. The RubyGems trusted publisher is registered for repository `yorzi/ruby_llm-browser`,
+workflow `release.yml`, and environment `release`. The corrected tagged workflow
+[39110148539](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110148539) passed
+tagged-package verification and published the gem with GitHub OIDC. RubyGems lists
+[version 0.1.0](https://rubygems.org/gems/ruby_llm-browser), published with MFA metadata;
+the [GitHub Release](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0)
+contains the gem and checksum. The custom-domain [documentation site]({% link index.md %})
+is deployed and shows `0.1.0 (stable)`.
+
+The first tag run, [39109944660](https://github.com/yorzi/ruby_llm-browser/actions/runs/39109944660),
+failed before upload because the action's optional experimental attestation patch loaded
+RubyGems before Bundler and activated Ruby's default zlib. The unpublished tag was moved
+to a workflow fix that disables that optional patch; OIDC publishing remains active.
+This release does not close provider qualification: no live egress, TTL, billing, or
+cleanup calls were made. Stagehand remains unsupported, and full live Act remains deferred.

data/docs/RELEASING.md

@@ -17,6 +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.
+`docs/evidence/V0_3_RELEASE.md` records the exact remote CI, published artifact and
+hosted documentation results. The earlier audit below is historical evidence.
+
 The 2026-10-18 audit runs on Ruby **3.3.5**, arm64 macOS, with Stagehand **3.21.0**,
 JSONSchemer **2.5.0**, and sqlite3 **2.10.0**. Full offline suites cover:
 
@@ -40,6 +44,7 @@ bundle exec rake
 bundle exec bundle-audit check --update
 bundle exec ruby examples/plain_ruby.rb
 bundle exec ruby examples/rails_adapter.rb
+bundle exec ruby examples/rails_results.rb
 
 BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle exec rspec
@@ -47,6 +52,7 @@ BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rspec
 
 bundle exec rake build
+bin/verify-release --candidate # for unreleased development candidates
 bundle exec ruby bin/verify-package --rails --audit
 ```
 
@@ -76,10 +82,10 @@ Verify all of the following:
 - Core require loads no Rails, Active Record, Active Job, or Stagehand client.
 - The optional Rails require loads on demand.
 - The generated migration and all README-linked guides are shipped.
-- Both examples run using the installed artifact.
+- All shipped examples run using the installed artifact.
 - The artifact contains no keys, cookies, dumps, databases, lockfiles, or test fixtures.
 - Dependency/license inventory and known-advisory check match the resolved versions.
-- Record the artifact SHA-256, exact versions, commands and date in the WORK ledger.
+- Record the artifact SHA-256, exact versions, commands and date in the candidate validation note.
 
 ## Release boundaries
 
@@ -101,18 +107,24 @@ made for `0.1.0`.
 ## Releasing a version
 
 For a later version, update the gem version in `lib/ruby_llm/browser/version.rb` and the
-documentation version in `docs/_config.yml` to the same value. Keep `released: false` on
-`main`; the documentation builder uses release tags for the stable site and builds the
-working tree under `/next/`. Add a matching release entry to `CHANGELOG.md` and
-`docs/_reference/release-history.md`.
+documentation version in `docs/_config.yml` to the same value. Keep `released: false`
+while preparing a candidate. Set it to `true` and update `stable_version` when the
+owner authorizes a release. The documentation builder uses release tags
+for the stable site and builds the working tree under `/next/`. Add a matching release
+entry to `CHANGELOG.md` and `docs/_reference/release-history.md`.
+
+During candidate development, keep changes under `Unreleased` in the changelog and
+run `bin/verify-release --candidate`. Before tagging, move them to a dated release
+section and run `bin/verify-release` without that flag. The tag workflow requires
+released metadata; local candidate verification cannot enable publication.
 
 Run the checks above, review the package contents and push the completed commit to
-`main`. Then create and push a matching tag, for example `v0.2.0` for gem version
-`0.2.0`:
+`main`. Then create and push a matching tag, for example `v{{ site.version }}` for gem version
+`{{ site.version }}`:
 
 ```bash
-git tag -a v0.2.0 -m "Release 0.2.0"
-git push origin v0.2.0
+git tag -a v{{ site.version }} -m "Release {{ site.version }}"
+git push origin v{{ site.version }}
 ```
 
 The `Release Gem` workflow rejects a tag that does not match both the gem and docs
@@ -127,5 +139,5 @@ workflow `release.yml`, and environment `release` before the first tag.
 ## Next steps
 
 - Review the requirement evidence in the source repository's `docs/WORK.md` and the [remaining audit findings]({% link RELEASE_AUDIT.md %}).
-- Follow the source repository's `docs/RELEASE_ACTION_PLAN.md` for the selected scope and
-  future version workflow.
+- Follow the [roadmap to 1.0]({% link _reference/roadmap.md %}) for proposed version scope.
+  The source repository's `docs/RELEASE_ACTION_PLAN.md` preserves the 0.1.0 release record.

data/docs/SECURITY_MODEL.md

@@ -113,5 +113,5 @@ qualification. Cleanup and TTL are best-effort, and cost values are advisory.
 
 ## Next steps
 
-- Follow [Rails recovery]({% link RAILS.md %}) to schedule cleanup and protect status access.
+- Follow [Rails recovery]({% link _advanced/rails-integration.md %}) to schedule cleanup and protect status access.
 - Review [the release audit]({% link RELEASE_AUDIT.md %}) for evidence and remaining blockers.

data/docs/WORK.md

@@ -242,6 +242,28 @@ the tag's stable documentation only after that release workflow succeeds. The fi
 is pushed only after the trusted publisher is registered for this repository and the
 `release.yml` workflow under the `release` GitHub environment.
 
+### 0.1.0 publication receipt (2026-10-18)
+
+The first tagged workflow run failed before the gem upload because the action's optional
+experimental attestation patch loaded RubyGems before Bundler and activated Ruby 3.3's
+default zlib instead of the locked patched zlib. No gem was published by that attempt.
+The release action now has attestations disabled; trusted OIDC publishing remains enabled.
+The unpublished `v0.1.0` tag was moved to the workflow-fix commit before retrying.
+
+| Check | Result |
+| --- | --- |
+| Tagged release workflow | PASS: [run 39110148539](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110148539); tagged package verification and RubyGems publish jobs succeeded |
+| RubyGems | PASS: [ruby_llm-browser 0.1.0](https://rubygems.org/gems/ruby_llm-browser); published by `yorzi/ruby_llm-browser` via `.github/workflows/release.yml` and `release` environment; MFA publication is recorded |
+| Gem SHA-256 | `0159bf5b4d50fc1a5d129ce8e6d8235ff9a5181704d5e8168c2facb429808ed3` |
+| GitHub Release | PASS: [v0.1.0](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0) contains the `.gem` file and `SHA256SUMS` |
+| Documentation Pages | PASS: [run 39110265391](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110265391); the [custom-domain docs site]({% link index.md %}) shows `0.1.0 (stable)` |
+| Live provider egress, TTL, billing and cleanup | NOT RUN; Stagehand remains unsupported until provider qualification |
+| Full live Act protocol | NOT IMPLEMENTED; offline simulation only, deferred to a later version |
+
+The published gem metadata reports MFA publication. No long-lived RubyGems API key was
+added to GitHub; the release workflow uses the registered trusted publisher and GitHub
+OIDC. The first failed run was [39109944660](https://github.com/yorzi/ruby_llm-browser/actions/runs/39109944660).
+
 ## Commit log
 
 Small, meaningful commits land one piece at a time. See `git log` for the authoritative

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

@@ -0,0 +1,107 @@
+---
+layout: default
+title: Development and Testing
+nav_order: 3
+description: Verify changes with offline contracts, installed packages, and a local browser workbench.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to run the local verification loop.
+- How to review browser behavior and retain fixture screenshots.
+- What offline, browser, and installed-package checks establish.
+
+## Run the Offline Checks
+
+```sh
+bin/setup
+bin/check
+```
+
+Start a behavior change with a focused failing spec. Implement the smallest public
+contract, update its guide, then run `bin/check`. The command runs specs and RuboCop,
+the RubyLLM 2.0 and Rails 8.0 alternate bundles, and the plain-Ruby and Rails examples.
+Install each alternate bundle first if needed. Database suites run sequentially.
+RuboCop uses the writable `tmp/rubocop` cache. Default tests block unmocked HTTP.
+
+The Rails result suite executes serialized jobs in separate processes against temporary
+SQLite files. It verifies reads after worker exit, actor/run isolation, conflicting
+delivery rejection, persistence failures before and after commit, and the crash gap
+between browser execution and host storage. HTTP stays blocked in those subprocesses.
+A frozen 0.2.0 migration verifies preservation of existing rows and indexes. These
+checks exercise host result delivery without adding a second browser fixture.
+
+Commit each completed change with its docs and checks. Keep the next work item in the
+[roadmap]({% link _reference/roadmap.md %}); do not create a second task ledger.
+
+## Review the Offline Workbench
+
+```sh
+BUNDLE_GEMFILE=gemfiles/browser.gemfile bundle install
+bin/workbench
+# Open http://127.0.0.1:4024, then Ctrl-C to stop.
+```
+
+The single fixture in `dev/workbench.rb` runs the real Ruby tools with FakeBackend,
+a deterministic resolver, and an in-memory operation store. Inspect and Extract show
+their returned hashes and fake start/cleanup counts. Enter an unapproved host to
+exercise a denial, run offline Doctor, or check that Stagehand remains blocked. The
+Stagehand diagnostic uses synthetic fixture credentials and never calls the provider.
+
+The host serves local HTML and CSS, escapes returned content, requires a form token,
+and accepts loopback Host values only. It is a development fixture, not a production
+controller or a new public gem API. It does not load the requested page or use provider
+credentials. The fixture and browser libraries are excluded from the gem.
+
+## Run Browser Tests
+
+```sh
+bin/check-browser
+# Or include browser tests after the offline checks:
+bin/check --browser
+```
+
+Use installed Chrome. `CHROME_BIN` can select its binary; `CHROMEDRIVER` can select an
+installed matching driver to avoid Selenium Manager's driver resolution. Screenshots
+go into the printed, ignored `tmp/browser/` directory. The runner fails if tests fail
+or no screenshot is produced. CI retains fixture screenshots for seven days.
+
+Browser scenarios cover inspect/extract, denial before dispatch, keyboard recovery at
+a 390px device viewport, and offline/blocked-Stagehand Doctor output. Capture screenshots before closing the
+active session, including on assertion failures. Inspect failure artifacts before
+retrying. Screenshots support visual review; assertions establish the expected behavior.
+
+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.
+Stop manual previews and verify no task-owned service remains after your review.
+
+## Verify a Candidate Package
+
+```sh
+bin/check --browser --package
+bin/verify-release --candidate
+docs/bin/build.sh
+```
+
+The package option builds the gem and runs `bin/verify-package --rails --audit`. It
+installs into an empty GEM_HOME outside the checkout, resolves dependencies from the
+registry, runs shipped examples, tests the generated migration, and audits the activated
+runtime. Refresh the advisory database first with `bundle exec bundle-audit check --update`.
+Package verification needs registry access; offline test success cannot replace it.
+
+`bin/verify-release --candidate` checks version alignment, the Unreleased changelog,
+the unreleased docs flag, and package exclusions. Without `--candidate`, it requires
+released docs and a dated changelog; the tag workflow never passes the candidate flag.
+The install verifier copies the input artifact before testing and prints that snapshot's
+SHA-256. A later build cannot replace the file under verification.
+
+Record the exact artifact hash, dependency versions, checks, and not-run boundaries in
+the candidate validation note. Local browser tests prove fixture application wiring.
+They do not establish real provider egress, session TTL, cleanup, billing, external
+adoption, remote CI success, or publication. Follow the
+[release checklist]({% link RELEASING.md %}) before releasing.

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

@@ -34,6 +34,11 @@ built-in Stagehand backend as unsupported: `egress_isolation` remains `:unverifi
 the Engine refuses to start a session. The host cannot override this status with a
 constructor option. A custom backend must enforce its own browser-side network boundary.
 
+The fake report has `mode: :offline` and skips provider credential and SDK checks.
+Stagehand reports `mode: :live` even though it remains unsupported; mode describes
+the backend, not its qualification. See [Checking Configuration]({% link _core_features/diagnostics.md %})
+for the report fields and checks applied to each backend.
+
 Browserbase's documented [Allowed Domains feature](https://docs.browserbase.com/platform/browser/security/allowed-domains)
 applies to top-frame navigations. It does not block iframe or subresource requests such
 as scripts, images, and XHR. That setting alone cannot qualify provider egress. Any future

data/docs/_advanced/rails-integration.md

@@ -1,56 +1,174 @@
 ---
 layout: default
-title: Running work in Rails
+title: Rails Jobs and Recovery
 nav_order: 1
-description: Run durable inspect and extract operations with the Rails 8 adapter.
+redirect_from:
+  - /RAILS/
+description: Run bounded read-only operations with durable state and independently scheduled cleanup.
 ---
 
-# {{ page.title }}
+# Rails jobs and recovery
 
-{{ page.description }}
-{: .fs-6 .fw-300 }
+Run bounded read-only operations with durable state and independently scheduled cleanup.
 
 After reading this guide, you will know:
 
-* Which framework versions and components the adapter expects.
-* How to install its tables.
-* What the host must own in background jobs and cleanup.
+- How to install the adapter's tables.
+- How to build a freshly authorized job context with matching budgets.
+- How to deliver results to host storage.
+- How to inspect status, cancel work, and recover orphaned sessions.
 
-## Install the Adapter
+## Installing the adapter
 
-The adapter is optional. Add Rails 8 Active Record and Active Job to the host application,
-then require the Rails entry point and install its migration:
+Your application supplies Rails 8, Active Record, Active Job, and a database adapter.
+They are not runtime dependencies of the plain-Ruby gem.
 
 ```ruby
 require "ruby_llm/browser/rails"
 ```
 
-```sh
+```bash
 bin/rails generate ruby_llm:browser:install
 bin/rails db:migrate
 ```
 
-The generator creates durable operation and approval tables plus per-actor reservation
-locks. The jobs accept `inspect` and `extract`; Act is not available in background jobs.
+The generator creates operations, approvals, and per-actor reservation-lock tables.
+SQLite and PostgreSQL are accepted by the store, but only SQLite concurrency is tested
+locally. MySQL is not supported by this adapter's partial indexes/locking contract.
+Use a database timeout appropriate to your workload. Database lock failures fail closed;
+they must not be handled by retrying a browser call with a new operation ID.
 
-## Keep Authorization in the Host
+`Schema.create!` is for disposable fixtures, not production migrations or schema upgrades.
+The [offline Rails example](https://github.com/yorzi/ruby_llm-browser/blob/main/examples/rails_adapter.rb) requires no full Rails app.
 
-The context factory runs in the worker and must reload trusted records, recheck actor and
-run authorization, and use the same operation store and budget limits as the reservation.
-Never put provider credentials or authorization decisions in model arguments or job
-payloads. Protect queue storage because URLs, instructions, and schemas are persisted.
+## Configuring the trusted context factory
 
-## Schedule Recovery
+```ruby
+# config/initializers/ruby_llm_browser.rb
+require "ruby_llm/browser/rails"
+
+browser_budget = RubyLLM::Browser::Budget.new(max_seconds: 30, max_steps: 6)
+RubyLLM::Browser::Rails.context_factory = lambda do |actor_id:, run_id:|
+  # Resolve authenticated host records and recheck authorization, consent and revocation.
+  # Build policy/backend from those records, never from job or model-supplied credentials.
+  RubyLLM::Browser::Context.new(
+    actor_id: actor_id, run_id: run_id,
+    backend: qualified_backend, source_policy: policy,
+    operation_store: RubyLLM::Browser::Rails.operation_store,
+    budget: browser_budget
+  )
+end
+```
+
+`qualified_backend` and `policy` above are host objects, not global APIs supplied by the
+gem. The factory must use the **same operation-store instance and budget limits** as
+the queued reservation. Construct different budgets per run only from trusted records
+that the factory can retrieve again. An optional approval store does not enable Act in
+jobs; `OperationJob` accepts only `inspect` and `extract`.
+
+## Enqueuing a read-only operation
+
+```ruby
+operation = RubyLLM::Browser::Rails::OperationJob.enqueue(
+  actor_id: current_user.id.to_s, run_id: research_run.id.to_s,
+  kind: :inspect, url: "https://docs.example.com/",
+  budget: browser_budget, idempotency_key: "research-#{research_run.id}"
+)
+```
+
+For extraction, pass `kind: :extract` and a host-pinned JSON `schema:`. Optional
+`instruction:` and `max_bytes:` have the same meaning as on the tools.
+
+One actor/run/key identifies one exact payload and budget. A changed payload using the
+same key is rejected. Repeated enqueue calls may add duplicate queue deliveries, but
+they attach to the same durable operation. Starting is atomically claimed once. A job
+that sees a started, unknown, pending-cleanup, or terminal operation cannot start it
+again. No automatic browser retry is configured.
+
+Reservation and queue insertion are separate transactions. If enqueueing fails, retain
+the returned operation identity when available and use the same idempotency key after
+investigation. Schedule the reaper to reclaim expired reservations that never started.
 
-Run `RubyLLM::Browser::Rails::Reaper` on a separate schedule. Worker cleanup alone cannot
-recover sessions left by a killed process. Do not free quota for an unknown or pending
-session based only on elapsed time. The job does not durably store result bodies, so the
-host must implement authorized result storage and delivery if it needs them.
+Configure `RubyLLM::Browser::Rails.job_queue = :browser` if you need a separate queue.
+Jobs suppress argument logging, but queues still persist URLs, instructions and schemas.
+Protect queue access, storage, retention and encryption in the host application.
+
+## Reading status and progress
+
+```ruby
+store = RubyLLM::Browser::Rails.operation_store
+operation = store.fetch!(operation_id)
+# Authorize this read against the authenticated actor/run before returning anything.
+summary = operation.summary
+```
+
+`summary` omits provider session IDs and budget internals. It reports state, steps,
+bytes, fence, timestamps, error code and cancellation flag. It is coarse progress,
+not a percentage-complete promise. To persist a result body, opt in to
+`RubyLLM::Browser::Rails.result_delivery`. The callback receives `operation:` and
+`result:` after execution and cleanup. Your application owns storage and authorized
+retrieval. Read [Rails result delivery]({% link _advanced/result-delivery.md %}) for
+failure handling and recovery. Do not rely on an Active Job return value after
+asynchronous execution.
+
+The stores are trusted server APIs, not tenant-safe controllers. They expose unscoped
+fetch/sweep methods for workers; never expose them directly to model arguments or HTTP.
+Tool progress callbacks are feature-detected on RubyLLM 2.1+, and contain no raw URL.
+
+## Cancelling and reaping
+
+```ruby
+store.cancel(operation_id, actor_id: current_user.id.to_s,
+             run_id: research_run.id.to_s, now: Time.now.utc)
+RubyLLM::Browser::Rails::Reaper.new(backend: qualified_backend).sweep
+```
+
+Cancellation of a never-started reservation is terminal immediately. Otherwise it sets
+`cancel_requested`, fences stale workers, and remains `cleanup_pending` with quota held.
+It cannot undo an in-flight provider request. A returned session ID is persisted even
+if cancellation raced with session creation.
+
+Run a reaper regularly in an independent scheduler, not only in the operation worker's
+ensure block. A reaper fences workers **before** reconciliation/cleanup, tries to end
+known sessions even when provider reconciliation is unavailable, and reports `failed`
+rather than claiming a database write succeeded. `ttl_seconds:` is an optional positive
+idle threshold, not proof that the provider's billable session has expired.
+
+Stagehand exposes no correlation endpoint here. An unknown start without a session ID
+remains unknown and holds quota until the host supplies provider-confirmed evidence.
+Alert on unknown/pending/failed entries. Never free quota just because enough local time
+passed. An unknown action outcome remains in the result/error code even if session
+cleanup succeeds; do not replay it.
+
+One reaper/backend instance must cover only operations belonging to that provider
+configuration. The current table has no backend credential-configuration binding.
+Multi-provider/multi-credential deployments need a host-scoped store or a future schema
+extension before a global sweep is safe.
+
+## Upgrading an earlier development snapshot
+
+If you installed the generator from an earlier development snapshot, preserve your data
+and add an explicit migration for these new fields instead of rerunning `create_table`
+or dropping the database:
+
+```ruby
+class HardenBrowserBookkeeping < ActiveRecord::Migration[8.1]
+  def change
+    create_table :ruby_llm_browser_actors, id: :string do |t|
+      t.integer :sequence, null: false, default: 0
+    end
+    add_column :ruby_llm_browser_operations, :cancel_requested, :boolean, default: false, null: false
+    add_column :ruby_llm_browser_operations, :request_digest, :string
+  end
+end
+```
 
-SQLite concurrency is exercised locally. PostgreSQL still needs separate qualification,
-and MySQL is not supported by the adapter's locking contract. See the [full Rails guide]({% link RAILS.md %}) for a context factory, enqueueing, status access, migration recovery, and reaper details.
+Adapt this migration if any additions already exist. Drain workers during the upgrade.
+Legacy rows without request digests are not payload-bound, so do not reuse their
+idempotency keys for new work. Inspect earlier terminal cancellations for sessions that
+may not have been confirmed closed before reclaiming them.
 
-## Next Steps
+## Next steps
 
-* [Bounding operation work]({% link _core_features/operation-lifecycle.md %}) - understand budgets and state transitions.
-* [Qualifying a live backend]({% link _advanced/live-backend-qualification.md %}) - review provider requirements.
+- Review [the API]({% link _reference/api-and-configuration.md %}) for result interpretation and budget semantics.
+- Review [release blockers]({% link RELEASE_AUDIT.md %}) before production deployment.