ruby_llm-browser 0.1.0

data/docs/SECURITY_MODEL.md

@@ -0,0 +1,117 @@
+---
+layout: default
+title: Security Model
+description: Understand what the gem enforces and what a deployment must prove independently.
+---
+
+# Security model
+
+Understand what the gem enforces and what a deployment must prove independently.
+
+After reading this guide, you will know:
+
+- Which inputs are trusted.
+- Why local URL validation does not secure a remote browser.
+- How sessions, cancellation, unknown outcomes, and secrets are handled.
+
+## Trust boundaries
+
+The host owns authentication, actor/run authorization, consent, provider configuration,
+source grants, budgets and approval issuance. The model, browser page and provider
+payload are untrusted. A `Context` expresses a host decision; it does not authenticate
+that decision. Unscoped store APIs are for trusted workers, not public controllers.
+
+## Destinations and egress
+
+URL validation rejects unsupported schemes/ports, userinfo, ambiguous numeric IP forms,
+unapproved hosts, and local/private/link-local/metadata/reserved IP answers, including
+IPv6 and IPv4-mapped addresses. Real DNS validation is enabled by default.
+
+These checks run in Ruby. They do **not** enforce a remote browser's DNS view, redirects,
+iframes, popups, WebSockets, subresources, scripts or connection-time rebinding.
+`Policy#authorize_egress!` refuses an unverified backend before starting a session. The
+built-in `StagehandBackend` always reports unverified egress and is unsupported for live
+operations in the first release. No constructor option can change that. A custom backend
+must enforce and evidence its own browser-side egress controls.
+
+Before a host makes that assertion, it must test every request path against a controlled
+public test origin and prove private/metadata addresses remain unreachable at connection
+time. Asset origins must be explicitly approved by the network layer. Also qualify
+local-mode browsers; a local browser is not a sandbox by default.
+
+Stagehand navigation results may be null. The adapter refuses to invent a final URL in
+that case. A live deployment must establish how its actual server reports a verified
+current URL; the SDK schema alone is not evidence. The current release has no supported
+Stagehand deployment. Returned page data remains untrusted.
+
+## Operation identity and recovery
+
+- Reserve operation identity and actor quota before start. Claim reserved-to-starting
+  atomically, checking the exact fence. A duplicate job cannot start a second session.
+- Rails idempotency keys bind the exact payload and budget. Per-actor write-lock rows
+  serialize even the first two reservations when there are no open operation rows.
+- Persist returned session identity before further calls, including a return that races
+  with cancellation. A persistence exception still triggers a cleanup attempt.
+- Disable SDK retries at client and request levels. The SDK's idempotency option is not
+  treated as a provider guarantee: its client has no configured idempotency header.
+- Cancellation cannot undo a dispatched request. It fences stale workers and holds quota
+  in `cleanup_pending` until provider-confirmed closure. A never-started reservation can
+  become terminal immediately.
+- A reaper fences before reconciliation/cleanup. It attempts to close known session IDs
+  even if reconciliation is unavailable. Database/provider failures never count as
+  successful cleanup. A local deadline or idle TTL is not proof of provider expiry.
+- A start whose session ID is unknown cannot be automatically reconciled by the current
+  Stagehand adapter. Hold quota and escalate to host/provider review. Never start a new
+  operation merely to conceal or retry an uncertain outcome.
+
+SQLite concurrency is tested with independent connections. PostgreSQL remains untested
+in this audit. A global reaper must use the same backend configuration as the operations
+it sees; multi-backend routing is not represented in the schema.
+
+## Actions and approvals
+
+**Live Act is disabled at the Engine boundary**, including when a backend advertises
+action support. The first release is read-only; the full live Act protocol is deferred to
+a later version. Offline simulation checks RubyLLM approval integration, read-only grant
+resolution, atomic single-use consumption, actor/run/action/URL and supplied revision
+bindings, expiration, revocation, replay, and unknown dispatch outcomes.
+
+That is not the complete production protocol: operation/session/page bindings are
+optional on the current Approval object; a candidate-action hash is not a DOM/target
+revision; and each Engine call starts a new session. Implement and verify same-session
+host approval and fresh target/policy checks before enabling live Act.
+
+Keyword filters on selectors/descriptions cannot prove semantic safety. An innocuously
+named button can purchase or publish. They are only defense in depth. Purchases,
+posting, account changes, credentials and access-control bypass remain unsupported.
+
+## Output, schema, and secret handling
+
+Extraction data is validated against the host schema before redaction/truncation. Model
+byte requests cannot increase policy ceilings. The retained serialized JSON fits both
+the policy ceiling and remaining operation bytes, including UTF-8 and escaped text.
+These limits do not cap remote browser bandwidth or provider response allocation.
+
+The redactor removes credential-like fields, known credential literals and WebSocket
+DevTools endpoints. URL provenance removes userinfo, fragments and credential-like
+query values. Error messages do not include raw SDK bodies or parser input. Progress
+messages contain no raw URL/selector. Active Job argument logging is disabled.
+
+This is **not a general secret or PII detector**. Arbitrary page secrets, screenshots,
+credentials under innocuous names and secrets not supplied to the redactor cannot be
+reliably identified. Do not browse authenticated/private content; do not put credentials
+in URLs or instructions; prevent host/RubyLLM/HTTP debug logging from recording payloads.
+Queue data and approval action arguments may persist in the host database; encrypt,
+scope and retain them appropriately. No browser cookies/profiles are supplied for reuse.
+
+The adapter passes explicit SDK credentials/base URL and rejects unapproved custom
+headers. Changes to relevant process environment values invalidate qualification.
+Environment injection is for diagnostics/tests; the real SDK reads actual process ENV.
+Do not mutate ENV during concurrent browser work. Session requests disable self-healing,
+CAPTCHA solving and provider recording/logging; actual provider behavior still needs
+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.
+- Review [the release audit]({% link RELEASE_AUDIT.md %}) for evidence and remaining blockers.

data/docs/SPEC_BASELINE.md

@@ -0,0 +1,107 @@
+---
+layout: default
+title: Specification Baseline and Provenance
+description: Record product intent, evidence sources, and project ownership boundaries.
+llms: false
+---
+
+# Specification baseline and provenance
+
+This repository is the independent implementation of the `ruby_llm-browser` Gem. It is
+the source of truth for code, tests and the WORK ledger. The product intent lives in a
+separate specifications repository; this file records exactly which baseline was used.
+
+## Baseline
+
+| Field | Value |
+| --- | --- |
+| Intent source repository | `yorzi/oddlyniche`, folder `ruby-llm-browser` |
+| Reviewed candidate Q | `22d488987517b10dcd96d2713ed3d47e8818b36b` |
+| H2 approval/content commit C | `678f9faed6dfdd8e55a7c54566f94cfa1ad1bc0a` |
+| Registration commit R | Pending; not registered |
+| Source commit date | 2026-10-18 |
+| Approved Specs candidate version at Q | `0.3.0-draft` (historical label; unchanged) |
+| Implementation and gem release version | `0.1.0` (owner-selected 2026-10-18) |
+| Spec lifecycle | `HANDOFF_READY`; independent H1 complete and owner H2 approved for exact Q |
+| Implementation authorized | 2026-10-17; H2 handoff approved 2026-10-18 |
+| RubyGems publication | Owner instructed release of `0.1.0` on 2026-10-18; this later instruction is separate from H2 |
+| Gem | `ruby_llm-browser` |
+| Namespace | `RubyLLM::Browser` |
+| Require path | `ruby_llm/browser` |
+| Working repository | `yorzi/ruby_llm-browser` |
+
+## Pinned upstream facts used (source-read at the spec baseline)
+
+| Dependency | Pin | Notes |
+| --- | --- | --- |
+| Stagehand Ruby SDK | `stagehand` 3.21.0, tag `v3.21.0` (`b389c6e`) | Ruby `>= 3.2`; REST client, not a sandbox |
+| RubyLLM | 2.0.0 and 2.1.1 | `Chat#with_tools` accepts Tool instances; `requires_approval` since 2.0; `progress`/`defer` since 2.1 |
+
+## S0 decisions recorded here
+
+1. **Hooks:** `Tool#progress` and `Tool.defer` exist only in RubyLLM 2.1+. This Gem
+   **feature-detects** them instead of raising the gemspec floor to `>= 2.1`, so the
+   supported floor stays `>= 2.0, < 3` (matching the 2.0.0 / 2.1.x matrix).
+2. **Stagehand dependency:** declared as a runtime dependency (`~> 3.21`) for the
+   experimental adapter and cleanup path, but **required lazily** so requiring the Gem
+   never reads `STAGEHAND_*`/`BROWSERBASE_*`/`MODEL_API_KEY` environment variables or
+   triggers the SDK's local-server binary download. The adapter is unsupported for live
+   operations in the first release.
+3. **Rails:** optional, loaded only via `require "ruby_llm/browser/rails"`.
+4. **Frame and lib style:** explicit `require_relative` chain (no Zeitwerk loader) so the
+   load graph is fully predictable and the no-Rails guarantee is easy to prove.
+
+## Audit corrections (2026-10-18)
+
+- Restrict Stagehand to `~> 3.21.0`, not all future 3.x minors; add JSONSchemer for
+  schema/instance validation.
+- The Engine now refuses live Act. The full same-session/page/target protocol in this
+  baseline is not implemented; earlier fake-only PASS claims did not establish it.
+- Final URLs are no longer inferred when navigation results omit them. The pinned SDK
+  permits null results, so actual server behavior must be qualified.
+- SQLite's ignored SELECT FOR UPDATE needs an actual write lock; actor-lock rows and
+  atomic start claims now enforce reservations and duplicate-delivery safety.
+- Cancellation holds quota after dispatch until cleanup is confirmed. Prior terminal
+  cancellation and swallowed reaper-write failures were not evidence of safe cleanup.
+- No cost ledger or hard currency cap is implemented. Retained-result limits do not
+  cap provider response allocations or browser bandwidth.
+
+These corrections harden engineering behavior. The owner separately approved exact
+Specs candidate Q `22d488987517b10dcd96d2713ed3d47e8818b36b` at H2 on 2026-10-18;
+that approval does not authorize live use. The owner later authorized release of gem
+version `0.1.0`. The historical candidate label remains `0.3.0-draft` so this record
+does not rewrite the approved Q. See
+[the audit]({% link RELEASE_AUDIT.md %}) for unresolved protocol/product decisions.
+
+## Outstanding blockers (carried from the spec baseline)
+
+These are **not** satisfied by this repository yet. BR-02 blocks live support. The owner
+has authorized the offline-only `0.1.0` release despite the unresolved live blocker; the
+release does not claim to resolve BR-02.
+
+- **BR-02 / live blocker:** a real browser provider must prove browser-side egress
+  isolation across navigation, redirects, iframes, popups, subresources, WebSockets and
+  metadata routes before live mode is enabled. The first release keeps Stagehand
+  unsupported and makes no live calls. Ruby-side URL/DNS checks cannot prove egress.
+- **BR-03 / distribution identity:** the package identifies itself as an unofficial
+  community extension and disclaims endorsement. Recheck name availability at publish
+  time. The dependency license inventory is technical evidence, not legal clearance.
+- **BR-04:** independent H1 and owner H2 are complete for the exact Q above. Baseline
+  registration R remains pending. H2 approved handoff; the owner's later `0.1.0` release
+  instruction authorizes publication separately.
+
+## Owner scope decision (2026-10-18)
+
+The owner selected read-only gem version `0.1.0`, deferred the full live Act protocol to a
+later version, and declined live provider calls. This narrows the first release to the
+offline `FakeBackend` and does not close BR-02 for later live support. Stagehand always
+reports unverified egress, refuses live operations, and sends no provider call including
+cleanup. Unresolved sessions remain `cleanup_pending`. H1/H2 are approved for exact Q;
+registration R remains pending. The later release instruction is recorded separately
+from that historical Specs approval.
+
+## Evidence rule
+
+Every functional requirement case records test ID, exact versions, run command, fixture,
+result (`PASS` / `FAIL` / `NOT RUN`) and date in `docs/WORK.md`. Mocked tests never
+prove remote browser egress. `NOT RUN` is recorded as `NOT RUN`, never as `PASS`.

data/docs/WORK.md

@@ -0,0 +1,260 @@
+---
+layout: default
+title: WORK Ledger
+description: Track requirement evidence with exact fixtures, commands, dependency versions, and limits.
+llms: false
+---
+
+# WORK ledger
+
+The implementation repository owns this ledger. Each functional requirement records the
+test ID, exact dependency versions, run command, fixture, result and date. The rule is
+simple: `NOT RUN` is written as `NOT RUN`, never as `PASS`.
+
+## Environment used for local runs
+
+| Field | Value |
+| --- | --- |
+| Ruby | 3.3.5 (arm64-darwin) |
+| RubyLLM | 2.1.1 |
+| Stagehand | 3.21.0 (development only; never called live) |
+| Rails / Active Job | active_record 8.1.4 + active_job 8.1.4, in-memory SQLite (adapter now exercised) |
+| Command | `bundle exec rspec` and `bundle exec rubocop` |
+
+## Progress slices (S0 → S4)
+
+| Slice | Deliverable | State |
+| --- | --- | --- |
+| S0 | Bootstrap: gemspec, version, Ruby-only fixture, CI, OSS docs, baseline record | DONE |
+| S1 | Read-only `Inspect`/`Extract` core with fake backend, policy, bounded results | DONE |
+| S2 | Stagehand adapter, durable operation store, quotas, TTL/reaper, reconciliation | PARTIAL: Stagehand disabled for first release; live egress/final-URL/TTL/cleanup and unknown-start correlation unqualified |
+| S3 | Opt-in `Act` with one-use approvals, Rails 8 jobs, cancellation, negative tests | PARTIAL: read-only Rails jobs tested; offline Act simulation only; full live protocol deferred |
+| S4 | Full matrix, clean install, security/compat/license docs, human-approved release | PARTIAL (Gem builds and clean-installs; compatibility matrix + public release pending) |
+
+## Functional-requirement evidence
+
+All rows start as `NOT RUN` and are filled in as tests land. Columns: test file(s), run
+command, result, date. Every `PASS` below is a **fake-backend / offline** result; no row
+proves remote browser egress and no live Stagehand call has been run.
+
+| FR | Positive | Denial / fault | Result | Date |
+| --- | --- | --- | --- | --- |
+| FR-01 Tool + configuration | `spec/ruby_llm/browser/inspect_spec.rb`, `spec/ruby_llm/browser/extract_spec.rb`, `spec/ruby_llm/browser/context_spec.rb` | `spec/ruby_llm/browser/inspect_spec.rb`, `spec/ruby_llm/browser/extract_spec.rb`, `spec/integration/require_spec.rb` | PASS (fake, no Rails) | 2026-10-17 |
+| FR-02 session/operation | `spec/ruby_llm/browser/engine_spec.rb`, `spec/ruby_llm/browser/fake_backend_spec.rb` | `spec/ruby_llm/browser/engine_spec.rb`, `spec/ruby_llm/browser/in_memory_operation_store_spec.rb` | PASS (fake lifecycle); live Stagehand NOT RUN | 2026-10-17 |
+| FR-03 read-only inspect | `spec/ruby_llm/browser/engine_spec.rb`, `spec/security/url_guard_spec.rb` | `spec/ruby_llm/browser/engine_spec.rb`, `spec/security/url_guard_spec.rb` | PASS (policy/engine); remote-browser egress NOT RUN | 2026-10-17 |
+| FR-04 structured extract | `spec/ruby_llm/browser/extract_spec.rb`, `spec/ruby_llm/browser/engine_spec.rb` | same | PASS (fake) | 2026-10-17 |
+| FR-05 approved Act | `spec/ruby_llm/browser/act_spec.rb`, `spec/ruby_llm/browser/engine_spec.rb` | same, `spec/security/release_audit_spec.rb` | PASS for offline simulation only; live Act deferred, same-session protocol NOT IMPLEMENTED | 2026-10-18 |
+| FR-06 Rails jobs | `spec/rails/operation_job_spec.rb`, `spec/rails/reaper_spec.rb`, `spec/rails/active_record_operation_store_spec.rb`, `spec/rails/active_record_approval_store_spec.rb` | same (wrong actor, fenced-out worker, cancel-mid-session, cleanup_pending visible) | PASS (fake backend + in-memory SQLite) | 2026-10-17 |
+| FR-07 failure/budget/audit | `spec/ruby_llm/browser/engine_spec.rb` (budget, redaction), `spec/ruby_llm/browser/stagehand_backend_spec.rb` | `spec/integration/stagehand_http_spec.rb` (stubbed HTTP; default live calls refused; cleanup ACK not closure), `spec/ruby_llm/browser/doctor_spec.rb` | Offline contract tests only; live Stagehand calls NOT RUN and unsupported | 2026-10-18 |
+| FR-08 full delivery | Build/install evidence below, `spec/integration/documentation_spec.rb` | Core/Rails require, generator/migration and compatibility suites | Package checks PASS; H1/H2 approved for exact Q; owner later authorized the offline-only `0.1.0` release; release outcome is recorded separately | 2026-10-18 |
+
+Run command for every row: `bundle exec rspec` (and `bundle exec rubocop`). Environment is
+the pinned local table above.
+
+### FR-08 delivery evidence (2026-10-17)
+
+```text
+$ gem build ruby_llm-browser.gemspec
+  Successfully built RubyGem
+  Name: ruby_llm-browser
+  Version: 0.1.0
+  File: ruby_llm-browser-0.1.0.gem
+
+# Clean install into an isolated GEM_HOME, then require from the built gem:
+$ gem install --local ./ruby_llm-browser-0.1.0.gem --install-dir "$PKG" --ignore-dependencies
+$ GEM_HOME="$PKG" GEM_PATH="$PKG:$(gem env gempath)" ruby -e 'require "ruby_llm/browser"'
+framework_loaded=[]        # no railties / active_record / active_job on the core path
+core=0.1.0
+$ ... ruby -e 'require "ruby_llm/browser/rails"'
+rails=RubyLLM::Browser::Rails::OperationJob
+```
+
+The packaged gem contains the plain-Ruby core, the opt-in Rails adapter and the install
+generator. At the time of this initial package check, RubyGems publication was blocked on
+BR-03 (name/license clearance).
+
+The original install above used `--ignore-dependencies` and borrowed the development
+GEM_PATH. It proved loading the artifact, **not** clean dependency resolution. The later
+audit's fresh-GEM_HOME installation is the stronger check.
+
+## Release-hardening audit (2026-10-18)
+
+The previous 270-example green suite did not cover several release-critical negative
+paths. The initial new audit regressions failed on output ceilings, malformed schemas,
+missing result validation, stale starts and early quota release. Those are now fixed.
+See the [release audit]({% link RELEASE_AUDIT.md %}) for findings, corrections and remaining gates.
+
+Evidence commands (all provider HTTP is stubbed or disabled):
+
+```bash
+bundle exec rake
+BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle exec rspec
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rspec
+bundle exec bundle-audit check --update
+bundle exec ruby examples/plain_ruby.rb
+bundle exec ruby examples/rails_adapter.rb
+bundle exec rake build
+```
+
+Additional fixtures exercise independent SQLite connections, duplicate start claims,
+atomic grant consumption, actual SIGKILL of a fake-backend worker followed by recovery
+in a fresh process, post-start persistence errors, real-clock timestamp precision,
+Stagehand HTTP retries/serialization, the Rails generator's reversible migration, local
+Markdown links, shipped files and executable offline README examples.
+
+| Check | Versions / fixture | Result |
+| --- | --- | --- |
+| Full default suite | Ruby 3.3.5, RubyLLM 2.1.1, AR/AJ 8.1.4, Stagehand 3.21.0, SQLite 2.10.0 | PASS: 302 examples, 0 failures |
+| Minimum RubyLLM | Same, RubyLLM 2.0.0 | PASS: 302 examples, 0 failures |
+| Rails 8.0 | Ruby 3.3.5, RubyLLM 2.0.0, AR/AJ 8.0.5.1 | PASS: 302 examples, 0 failures |
+| RuboCop | `bundle exec rubocop . bin/verify-package` | PASS: 89 files, 0 offenses |
+| Runtime dependency advisories | ruby-advisory-db `fa2295251efb3b0d1a300e5ce8ad700ff1f1b485` | No known vulnerabilities found |
+| Live provider egress / TTL / billing / final URL | No live session authorized or run | NOT RUN |
+| PostgreSQL concurrency | No PostgreSQL fixture run | NOT RUN |
+| Expanded remote CI | Linux Ruby 3.2/3.3/3.4, RubyLLM 2.0.0/2.1.1, Rails 8.1 plus Rails 8.0 row | PASS for `0ec34d4`: seven test jobs plus build/install/advisory job |
+| Public release at initial hardening audit | H1/H2 for exact Q, BR-03 naming/license, exact artifact | HOLD at that time; H1/H2 passed, distribution clearance and artifact approval remained open |
+
+### Stronger package-install evidence
+
+```bash
+bundle exec rake build
+bundle exec bundle-audit check --update
+bundle exec ruby bin/verify-package --rails --audit
+```
+
+The verifier installs the actual package and resolves dependencies in a new GEM_HOME
+with no borrowed GEM_PATH and no `--ignore-dependencies`. It runs outside the checkout,
+checks the activated entrypoint, loads shipped guides/examples, proves core loading has
+no eager framework/client, then installs optional Rails dependencies and runs the
+installed generator's migration up/down. Output markers:
+
+```text
+CORE_PACKAGE_PASS
+CLEAN_RUNTIME_ADVISORIES_PASS
+RAILS_PACKAGE_PASS
+```
+
+The initial fresh install exposed vulnerable default CGI/Resolv/URI/zlib versions that
+the project's lockfile scan omitted. After adding patched runtime floors, both the
+lockfile scan and a check of the actually activated clean core runtime report no known
+advisories. Local resolved security libraries: CGI 0.5.2, Resolv 0.8.1, URI 1.1.2 and
+zlib 3.2.4. Native Ruby/system-library security is a separate host responsibility.
+
+Full installer/smoke logs and `activated-versions.json` remain in the temporary evidence
+directory printed by the verifier. The verifier prints the artifact SHA-256; a local
+`pkg/SHA256SUMS` accompanies the final artifact. Build/install is not publication.
+
+### Submission evidence (2026-10-18)
+
+The hardening is committed and pushed as `0ec34d4b48e0e3ab88bb893c4c731777d2aa24af`.
+[CI run 39086570934](https://github.com/yorzi/ruby_llm-browser/actions/runs/39086570934)
+completed successfully: all seven test jobs report `302 examples, 0 failures`, and
+the package job reports no known dependency advisories plus all three clean-install
+success markers. No RubyGems release or paid provider call was performed. Publication
+remains NO-GO for the other recorded gates.
+
+### No-provider-dispatch cleanup follow-up (2026-10-18)
+
+The owner selected an offline read-only first release, deferred the full live Act
+protocol, and declined live provider calls. The Stagehand adapter refuses every live
+operation. Its end_session method returns false without invoking the SDK; stubbed HTTP
+tests assert that neither normal cleanup nor partial-start cleanup sends an end request.
+This follow-up is local evidence; it is not covered by the CI run above.
+
+| Check | Result |
+| --- | --- |
+| `RUBOCOP_CACHE_ROOT=/private/tmp/ruby_llm_browser_rubocop_cache bundle exec rake` (Ruby 3.3.5, RubyLLM 2.1.1, AR/AJ 8.1.4, Stagehand 3.21.0, SQLite 2.10.0) | PASS: 305 examples, 0 failures; RuboCop inspected 94 files, 0 offenses |
+| `BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle exec rspec` | PASS: 305 examples, 0 failures; RubyLLM 2.0.0 |
+| `BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rspec` | PASS: 305 examples, 0 failures; RubyLLM 2.0.0 and Rails/Active Job 8.0.5.1 |
+| `./docs/bin/build.sh` | PASS: Jekyll built the working tree |
+| `bundle exec rake build` | PASS: built `ruby_llm-browser-0.1.0.gem` |
+| `bundle exec ruby bin/verify-package --rails --audit` | PASS: `CORE_PACKAGE_PASS`, `CLEAN_RUNTIME_ADVISORIES_PASS`, `RAILS_PACKAGE_PASS`; final artifact SHA-256 is in ignored `pkg/SHA256SUMS` |
+| Live provider egress, TTL, billing, and cleanup | NOT RUN; no live calls authorized |
+| Current working-tree remote CI | NOT RUN; the passing CI above is for `0ec34d4` |
+| RubyGems publication | NOT ATTEMPTED; H1/H2 passed for exact Q, but name/account/MFA, owner clearance and exact-artifact approval remain open |
+
+The clean package verifier needed network access to resolve gems from RubyGems. It ran
+from an isolated temporary GEM_HOME outside the checkout. Its network use was limited to
+gem installation; all example execution used the fake backend. The sandbox-only first
+attempt could not resolve `rubygems.org` and made no install; the permitted retry
+completed successfully. The verifier's SHA-256 output is captured in the local, ignored
+`pkg/SHA256SUMS` sidecar after the final build so this document does not contain a
+self-referential artifact checksum.
+
+### Offline Act single-use race and docs (2026-10-18)
+
+The first release supports Act only as an offline FakeBackend simulation. It consumes a
+host-issued grant once; competing calls yield one recorded action and stale denials.
+Stagehand remains unsupported, no provider cleanup request is sent, and the full live Act
+protocol remains a later-version feature. The new feature guide explains grant issuance,
+revocation, binding, concurrency, denial results, and this boundary.
+
+| Check | Result |
+| --- | --- |
+| `RUBOCOP_CACHE_ROOT=/private/tmp/ruby_llm_browser_rubocop_cache bundle exec rake` | PASS: 306 examples, 0 failures; RuboCop inspected 94 files, 0 offenses |
+| Offline Act guide example via `bundle exec ruby -Ilib -` | PASS: returned `ok` and the issued approval ID; FakeBackend only, no model or provider call |
+| `python3 /Users/andy/.codex/skills/project-docs/scripts/docs.py check --dir docs` | PASS: 12 guides, 0 errors, 0 warnings |
+| `./docs/bin/build.sh` | PASS: Jekyll built the working tree |
+| `bundle exec rake build` | PASS: built `ruby_llm-browser-0.1.0.gem` |
+| `bundle exec ruby bin/verify-package --rails --audit` | PASS: `CORE_PACKAGE_PASS`, `CLEAN_RUNTIME_ADVISORIES_PASS`, and `RAILS_PACKAGE_PASS`; isolated clean install |
+| Live provider egress, TTL, billing, and terminal cleanup | NOT RUN; no live calls authorized |
+| RubyGems publication | NOT ATTEMPTED at this audit snapshot, before the later owner instruction to release version `0.1.0` |
+
+These local checks do not qualify browser-side egress, provider TTL, billing, or remote
+cleanup. They validate a local unpublished candidate, not a release. Rebuild the exact
+artifact after any release metadata changes and only after the H1/H2 gates.
+
+### H2 handoff and distribution inventory (2026-10-18)
+
+The owner approved the offline read-only v1 scope and KPI proposal against exact Specs
+candidate Q `22d488987517b10dcd96d2713ed3d47e8818b36b`. The approval is recorded in
+OddlyNiche content commit C `678f9faed6dfdd8e55a7c54566f94cfa1ad1bc0a`. H1/H2 passed;
+registration R and this repository's final baseline receipt remain pending. H2 does not
+authorize RubyGems publication.
+
+| Check | Result |
+| --- | --- |
+| Resolved runtime dependency license inventory | PASS: 26 dependencies' exact lockfile versions and installed gemspec license metadata match NOTICE; Stagehand's missing metadata is covered by its pinned upstream MIT text |
+| RubyGems exact-name query | HTTP 404 on 2026-10-18; unregistered at check time, not reserved |
+| Runtime dependency license inventory | PASS: 26 exact lockfile versions and installed gemspec licenses match NOTICE; Stagehand source MIT text is pinned |
+| Project docs checker | PASS: 12 guide pages, 0 errors, 0 warnings |
+| Jekyll build | PASS: `./docs/bin/build.sh` built the working tree |
+| Local package review | PASS: version 0.1.0, 83 files, 7 runtime dependencies, MFA metadata present, no blocked paths |
+| RubyGems MFA requirement | Gem metadata requires publisher MFA; enable MFA before the first push |
+| RubyGems publication / live provider call | NOT ATTEMPTED; publication awaits exact-artifact approval and distribution clearance; no provider calls were made |
+
+The license inventory is a point-in-time metadata check, not legal clearance. Recheck
+name availability and the final built artifact immediately before any release.
+
+### 0.1.0 release decision and automation (2026-10-18)
+
+After the initial publication hold above, the owner selected gem version `0.1.0`,
+instructed the matching `v0.1.0` tag and RubyGems release, and requested automation for
+future version tags. This instruction authorizes the offline-only package release; it is
+separate from H2 handoff approval. The approved Specs Q keeps its historical candidate
+label `0.3.0-draft`. Stagehand remains unsupported, live Act remains deferred, and no
+provider calls were authorized or made.
+
+The repository release workflow runs tests, the dependency advisory scan and isolated
+package verification before RubyGems trusted publishing. It then creates a GitHub Release
+with the generated gem, checksum and matching changelog section. The Docs workflow builds
+the tag's stable documentation only after that release workflow succeeds. The first tag
+is pushed only after the trusted publisher is registered for this repository and the
+`release.yml` workflow under the `release` GitHub environment.
+
+## Commit log
+
+Small, meaningful commits land one piece at a time. See `git log` for the authoritative
+history; notable slices:
+
+1. Scaffold: gemspec, version, Ruby-only fixture, CI, OSS docs and the baseline record.
+2. Core: typed errors, redaction, budgets, results and configuration.
+3. Policy: capabilities, URL guard and source/schema/action policy.
+4. Lifecycle: operation, approval and in-memory stores.
+5. Runtime: backend contract, FakeBackend, Context, Engine and the Inspect/Extract/Act
+   tools, with FR-01/03/04/05 evidence (fake backend).
+6. Backend: the Stagehand adapter and preflight Doctor (FR-02/03/07 offline evidence).
+7. Engine seam: a caller-reserved operation for the Rails job and cleanup bookkeeping
+   that tolerates a fenced or cancelled writer.
+8. Rails adapter: durable ActiveRecord operation/approval stores, schema and migration.
+9. Rails jobs: scoped Active Job, cleanup reaper and the install generator (FR-06).

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

@@ -0,0 +1,74 @@
+---
+layout: default
+title: Qualifying a live backend
+nav_order: 2
+description: Review the host and provider guarantees required before a live browser session.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+After reading this guide, you will know:
+
+* Why `StagehandBackend` is unsupported in the first release.
+* Which egress and cleanup controls need qualification before live use.
+* Why the full live Act protocol is deferred to a later version.
+
+## Run a Local Diagnostic
+
+`Doctor` checks local configuration without a network request or browser session. This
+fake-backend example reports its exact boundary:
+
+```ruby
+require "ruby_llm/browser"
+
+backend = RubyLLM::Browser::FakeBackend.new
+puts RubyLLM::Browser::Doctor.new(backend: backend).report[:summary]
+# => "configuration checks passed; live provider guarantees are not verified"
+```
+
+The diagnostic is local and makes no provider request. In this release it reports the
+built-in Stagehand backend as unsupported: `egress_isolation` remains `:unverified`, and
+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.
+
+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
+deployment must separately verify DNS at connection time, redirects, frames, popups,
+WebSockets, scripts, and all other request paths.
+
+## Verify Provider Behavior Separately
+
+Before considering live use, independently establish provider-side egress restrictions,
+final URL reporting, session TTL, unknown-start recovery, billing controls, and confirmed
+cleanup. The gem does not provide a browser firewall or a hard cost cap. The Doctor does
+not call the provider and cannot establish these properties.
+
+Cleanup needs a status check. Stagehand 3.21's `SessionEndResponse.success` reports that
+the end request succeeded; it does not report the session's final status. Browserbase's
+[`REQUEST_RELEASE` endpoint](https://docs.browserbase.com/reference/api/update-a-session)
+requests completion and may return a session still marked `PENDING`. The
+[`Get a Session` endpoint](https://docs.browserbase.com/reference/api/get-a-session)
+exposes status and `endedAt`, but the Stagehand Ruby SDK does not expose that lookup.
+The adapter cannot start a live session in this release. Its `end_session` method returns
+`false` without calling the SDK. An operation whose cleanup is not confirmed stays
+`cleanup_pending`; the Gem does not claim terminal cleanup.
+
+## Current Project Status
+
+The repository's [release audit]({% link RELEASE_AUDIT.md %}) records no live provider
+qualification and marks the built-in Stagehand backend unsupported. The first release
+uses read-only tools; the full live Act protocol is deferred to a later version. The
+Engine refuses non-fake Act calls until same-session host approval and target binding are
+implemented.
+
+Read-only tools do not dispatch browser actions. A page can still run scripts and initiate
+requests, and returned page text remains untrusted data. Review the [security model]({% link SECURITY_MODEL.md %}) before designing a host deployment.
+
+## Next Steps
+
+* [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/rails-integration.md

@@ -0,0 +1,56 @@
+---
+layout: default
+title: Running work in Rails
+nav_order: 1
+description: Run durable inspect and extract operations with the Rails 8 adapter.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+{: .fs-6 .fw-300 }
+
+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.
+
+## Install 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:
+
+```ruby
+require "ruby_llm/browser/rails"
+```
+
+```sh
+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.
+
+## Keep Authorization in the Host
+
+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.
+
+## Schedule Recovery
+
+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.
+
+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.
+
+## 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.