Merge pull request #22 from freshtechbro/codex/generalfixes

chore: prepare 0.0.19 release cut

Author: freshtechbro

.github/workflows/release-public.yml

@@ -166,6 +166,15 @@ jobs:
           fi
           npm publish --access public
 
+      - name: Registry consumer smoke
+        if: steps.meta.outputs.publish_npm == 'true'
+        run: |
+          mkdir -p "artifacts/release/v${{ steps.meta.outputs.release_version }}"
+          node scripts/registry-consumer-smoke.mjs \
+            --version "${{ steps.meta.outputs.release_version }}" \
+            --output "artifacts/release/v${{ steps.meta.outputs.release_version }}/registry-consumer-smoke.json"
+          cat "artifacts/release/v${{ steps.meta.outputs.release_version }}/registry-consumer-smoke.json"
+
       - name: Publish GitHub release
         if: steps.meta.outputs.publish_release == 'true'
         uses: softprops/action-gh-release@v2

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.19] - 2026-04-13
+
+### Added
+- Post-publish registry-consumer smoke validation via `scripts/registry-consumer-smoke.mjs`, including fresh-install help/version checks and captured consumer dependency-graph evidence.
+- A concrete browser-scoped computer-use entry command in generated help, onboarding metadata, and release-facing docs.
+
+### Changed
+- Clarified the boundary between local source-tarball validation and published npm proof across README, CLI docs, onboarding, release runbooks, and distribution docs.
+- Clarified the `0.0.18` npm parity investigation chronology so it distinguishes the release-aligned parity snapshot from later local worktree drift.
+
+### Fixed
+- Browser screencast recording no longer schedules a later frame when stop is requested during the first in-flight capture.
+
 ## [0.0.18] - 2026-04-12
 
 ### Added
@@ -173,7 +186,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Core browser management
 - Basic snapshot pipeline
 
-[Unreleased]: https://github.com/freshtechbro/opendevbrowser/compare/v0.0.18...HEAD
+[Unreleased]: https://github.com/freshtechbro/opendevbrowser/compare/v0.0.19...HEAD
+[0.0.19]: https://github.com/freshtechbro/opendevbrowser/compare/v0.0.18...v0.0.19
 [0.0.18]: https://github.com/freshtechbro/opendevbrowser/compare/v0.0.17...v0.0.18
 [0.0.17]: https://github.com/freshtechbro/opendevbrowser/compare/v0.0.16...v0.0.17
 [0.0.16]: https://github.com/freshtechbro/opendevbrowser/compare/v0.0.15...v0.0.16

README.md

@@ -89,9 +89,9 @@ npm install -g opendevbrowser
 opendevbrowser --version
 ```
 
-### Pre-release Local Package (No npm publish required)
+### Local Package Validation
 
-Use this flow to validate first-run local package onboarding before npm publish.
+Use this flow to validate first-run onboarding from a source tarball without relying on the published registry package.
 
 ```bash
 cd <public-repo-root>
@@ -100,11 +100,13 @@ npm pack
 WORKDIR=$(mktemp -d /tmp/opendevbrowser-first-run-XXXXXX)
 cd "$WORKDIR"
 npm init -y
-npm install <public-repo-root>/opendevbrowser-0.0.18.tgz
+npm install <public-repo-root>/opendevbrowser-0.0.19.tgz
 npx --no-install opendevbrowser --help
 npx --no-install opendevbrowser help
 ```
 
+Published npm consumer proof is tracked separately in [docs/RELEASE_RUNBOOK.md](docs/RELEASE_RUNBOOK.md) through `scripts/registry-consumer-smoke.mjs`.
+
 See [docs/FIRST_RUN_ONBOARDING.md](docs/FIRST_RUN_ONBOARDING.md) for the full onboarding checklist, [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md) for runtime inventory, and [docs/SURFACE_REFERENCE.md](docs/SURFACE_REFERENCE.md) for the live CLI and tool surface.
 
 Successful installs reconcile daemon auto-start on supported platforms so the relay is available on login. If the current CLI entrypoint lives under a transient temp-root path such as a first-run `/tmp` or `/private/tmp` workspace, OpenDevBrowser refuses to persist that path as auto-start. Rerun `opendevbrowser daemon install`, or `npx --no-install opendevbrowser daemon install` from a persistent local package install, from a stable install location if you want login auto-start; remove it later with `opendevbrowser daemon uninstall`.
@@ -244,7 +246,7 @@ Start every surface check from generated help when you need the current public l
 
 - `screencast / browser replay`: `screencast-start`, `screencast-stop`
 - `desktop observation`: `desktop-status`, `desktop-windows`, `desktop-active-window`, `desktop-capture-desktop`, `desktop-capture-window`, `desktop-accessibility-snapshot`
-- `computer use / browser-scoped computer use`: `--challenge-automation-mode off|browser|browser_with_helper` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`; `review` and `session-inspector` remain the quickest proof surfaces, and the optional helper stays browser-scoped rather than becoming a desktop agent
+- `computer use / browser-scoped computer use`: `--challenge-automation-mode off|browser|browser_with_helper` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`; start with `npx opendevbrowser research run --topic "account recovery flow" --source-selection auto --challenge-automation-mode browser --mode json --output-format json` when you need the first entry point, and use `review` plus `session-inspector` as the quickest proof surfaces while the optional helper stays browser-scoped rather than becoming a desktop agent
 
 ## Challenge Handling Boundary
 
@@ -262,14 +264,13 @@ Start every surface check from generated help when you need the current public l
 
 ## Recent Features
 
-### v0.0.18 (Latest)
+### v0.0.19 (Current release prep)
 
-- **Canvas and workflow surfaces are materially stronger after `v0.0.17`**: adapter-plugin validation, starter or inventory lanes, framework-adapter code sync, review/session-inspector flows, and direct-run release probes all landed on `main`.
-- **Generated public-surface manifests and onboarding metadata now drive help, docs parity, release evidence, and mirrored website inputs** instead of leaving those surfaces hand-maintained.
-- **Challenge automation and browser-scoped computer-use controls are tighter** with explicit `challengeAutomationMode` precedence and a clearer browser-only helper boundary.
-- **Browser replay screencasts and public desktop observation now ship on the active public surface** with manager-owned replay artifacts, dedicated desktop permission or audit coverage, and no desktop agent claim.
-- **Public read-only desktop observation now ships as a sibling runtime** with dedicated permission and audit coverage while staying outside the public relay or `/ops` plane.
-- **Release and distribution operations were refreshed for `v0.0.18`** across GitHub release assets, npm packaging, Chrome Web Store prep, regenerated live store assets, and private website sync inputs.
+- npm latest remains `0.0.18` until the next tag is pushed and published.
+- **Registry-consumer release proof is now first-class** with a post-publish smoke lane that installs the published package in a fresh temp workspace, verifies help/version, and captures the resolved consumer dependency graph.
+- **Browser-scoped computer use is easier to discover** because help, onboarding, and release-facing docs now expose a concrete workflow entry command instead of relying only on `--challenge-automation-mode` as a hidden modifier.
+- **Browser replay screencast shutdown is safer under load** because stop requests during the first in-flight capture no longer allow a later scheduled frame to sneak through.
+- **The `0.0.18` npm parity investigation is now explicit about chronology**: the published package matched the release-aligned source, while later local worktree drift and semver-based consumer dependency drift explain the mismatch reports.
 
 ### v0.0.16
 

docs/AGENTS.md

@@ -64,7 +64,7 @@ When release-gate automation changes:
 - `docs/RELEASE_RUNBOOK.md`
 - `docs/EXTENSION_RELEASE_RUNBOOK.md`
 - `docs/DISTRIBUTION_PLAN.md`
-- the current version-scoped release evidence doc (for this release: `docs/RELEASE_0.0.18_EVIDENCE.md`)
+- the current version-scoped release evidence doc (for this release: `docs/RELEASE_0.0.19_EVIDENCE.md`)
 - older ledgers stay historical-only and should receive explicit status clarifications only
 - automation scripts:
   - `scripts/audit-zombie-files.mjs`

docs/ARCHITECTURE.md

@@ -457,7 +457,7 @@ When hub mode is enabled, the hub daemon is the **sole relay owner** and enforce
 - **Parity gate** via `tests/parity-matrix.test.ts` (contract coverage for CLI/tool/runtime surface checks + mode coverage).
 - **Provider performance gate** via `tests/providers-performance-gate.test.ts` (deterministic fixture SLO checks).
 - **Strict live release gates** via `node scripts/provider-direct-runs.mjs --release-gate` and `node scripts/live-regression-direct.mjs --release-gate` (active live release proof layer).
-- **Release checklist** in `docs/RELEASE_RUNBOOK.md` with evidence tracking in the current version-scoped release ledger (for this cycle: `docs/RELEASE_0.0.18_EVIDENCE.md`).
+- **Release checklist** in `docs/RELEASE_RUNBOOK.md` with evidence tracking in the current version-scoped release ledger (for this cycle: `docs/RELEASE_0.0.19_EVIDENCE.md`).
 - **Benchmark fixture manifest** in `docs/benchmarks/provider-fixtures.md`.
 - **First-run onboarding checklist** in `docs/FIRST_RUN_ONBOARDING.md`.
 

docs/CLI.md

@@ -2,18 +2,18 @@
 
 Command-line interface for installing and managing the OpenDevBrowser plugin, plus automation commands for agents.
 Status: active  
-Last updated: 2026-04-12
+Last updated: 2026-04-13
 
 OpenDevBrowser exposes 65 `opendevbrowser_*` tools; see `README.md` and `docs/SURFACE_REFERENCE.md` for the full inventories.
 Generated help is the primary first-contact inventory and onboarding surface. Agent runs should start with `opendevbrowser_prompting_guide` or `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"` before low-level browser commands, then load `opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"` when they need the currently proven transcript, research, and shopping workflows. Load `opendevbrowser-design-agent` immediately after that baseline for frontend, screenshot-to-code, or `/canvas` design work. Use continuity guidance only for long-running handoff or compaction.
-That generated help surface now leads with a `Find It Fast` block that uses the exact lookup terms `screencast / browser replay`, `desktop observation`, and `computer use / browser-scoped computer use`. It maps replay to `screencast-start` / `screencast-stop`, desktop observation to the public read-only `desktop-*` family, and browser-scoped computer use to `--challenge-automation-mode` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`.
+That generated help surface now leads with a `Find It Fast` block that uses the exact lookup terms `screencast / browser replay`, `desktop observation`, and `computer use / browser-scoped computer use`. It maps replay to `screencast-start` / `screencast-stop`, desktop observation to the public read-only `desktop-*` family, and browser-scoped computer use to `--challenge-automation-mode` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`, with `research run --topic ... --challenge-automation-mode browser` as the first entry command.
 Tool-only commands `opendevbrowser_prompting_guide`, `opendevbrowser_skill_list`, and `opendevbrowser_skill_load` run locally via the skill loader. They are onboarding helpers, not browser-runtime commands, and they do not require relay or daemon bootstrap.
 CLI-only power command `rpc` intentionally has no tool equivalent; it is an internal daemon escape hatch behind an explicit safety flag and should be used with extreme caution.
 Public-surface metadata now flows from `src/public-surface/source.ts` through `scripts/generate-public-surface-manifest.mjs` into `src/public-surface/generated-manifest.ts` and `src/public-surface/generated-manifest.json`, which are consumed by `src/cli/help.ts`, `src/cli/args.ts`, inventory scripts, mirrored website inputs, and re-export paths in `src/tools/index.ts`. Onboarding literals still live in `src/cli/onboarding-metadata.json`, and runtime execution authority remains `src/cli/args.ts` plus `src/tools/index.ts`.
 The generated first-contact inventory mirrored into downstream website and release flows is tracked in `docs/ASSET_INVENTORY.md`.
 
 Dependency inventory: `docs/DEPENDENCIES.md`
-First-run pre-release onboarding: `docs/FIRST_RUN_ONBOARDING.md`
+First-run local-artifact onboarding: `docs/FIRST_RUN_ONBOARDING.md`
 
 Parity and skill-pack gates:
 
@@ -45,7 +45,7 @@ npm install -g opendevbrowser
 opendevbrowser --version
 ```
 
-### Pre-release local package onboarding (no npm publish)
+### Local package onboarding from a source tarball
 
 ```bash
 cd <public-repo-root>
@@ -54,7 +54,7 @@ npm pack
 WORKDIR=$(mktemp -d /tmp/opendevbrowser-first-run-XXXXXX)
 cd "$WORKDIR"
 npm init -y
-npm install <public-repo-root>/opendevbrowser-0.0.18.tgz
+npm install <public-repo-root>/opendevbrowser-0.0.19.tgz
 npx --no-install opendevbrowser --help
 npx --no-install opendevbrowser help
 ```
@@ -78,6 +78,12 @@ Installer inventory:
 
 `OPENCODE_CONFIG_DIR` changes config lookup, but the extracted unpacked-extension copy created by `--full` still lives at `~/.config/opencode/opendevbrowser/extension`.
 
+Published npm consumer proof is a separate release gate:
+
+```bash
+node scripts/registry-consumer-smoke.mjs --version X.Y.Z --output artifacts/release/vX.Y.Z/registry-consumer-smoke.json
+```
+
 ### Skill discovery order
 
 The skill loader discovers skills in this order (first match wins):
@@ -256,7 +262,7 @@ npx opendevbrowser -v
 
 `--help` and `help` print the same generated first-contact inventory:
 - A `Find It Fast` block that uses the exact lookup terms `screencast / browser replay`, `desktop observation`, and `computer use / browser-scoped computer use`.
-- That block maps replay to `screencast-start` / `screencast-stop`, desktop observation to the public `desktop-*` family, and browser-scoped computer use to `--challenge-automation-mode` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`.
+- That block maps replay to `screencast-start` / `screencast-stop`, desktop observation to the public `desktop-*` family, and browser-scoped computer use to `--challenge-automation-mode` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`, with a concrete `research run --topic ... --challenge-automation-mode browser` entry command.
 - An `Agent Quick Start` block that tells agents to start with `opendevbrowser_prompting_guide` or `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"` before low-level browser commands.
 - A follow-up `validated_lanes` entry that points agents to `opendevbrowser_skill_load opendevbrowser-best-practices "validated capability lanes"` for the current reliable transcript, research, and shopping runbook.
 - A direct pointer to `opendevbrowser_skill_list` when an agent needs a different local skill lane.
@@ -267,7 +273,7 @@ npx opendevbrowser -v
 Quick lookup terms from generated help:
 - `screencast / browser replay`: `screencast-start`, `screencast-stop`
 - `desktop observation`: `desktop-status`, `desktop-windows`, `desktop-active-window`, `desktop-capture-desktop`, `desktop-capture-window`, `desktop-accessibility-snapshot`
-- `computer use / browser-scoped computer use`: `--challenge-automation-mode off|browser|browser_with_helper` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`
+- `computer use / browser-scoped computer use`: `--challenge-automation-mode off|browser|browser_with_helper` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`; entry command `npx opendevbrowser research run --topic "account recovery flow" --source-selection auto --challenge-automation-mode browser --mode json --output-format json`
 
 These first-contact assets are also mirrored as release and website inputs through `src/cli/onboarding-metadata.json`, `src/public-surface/generated-manifest.ts`, and `src/public-surface/generated-manifest.json`.
 
@@ -1645,7 +1651,7 @@ npm run test -- tests/providers-performance-gate.test.ts
 
 These commands are release guards, not the live release-proof lane. Use the direct-run harness commands above for release evidence.
 
-Release gate source of truth: `docs/RELEASE_RUNBOOK.md` and `docs/RELEASE_0.0.18_EVIDENCE.md`.
+Release gate source of truth: `docs/RELEASE_RUNBOOK.md` and `docs/RELEASE_0.0.19_EVIDENCE.md`.
 Benchmark fixture manifest: `docs/benchmarks/provider-fixtures.md`.
 
 ---

docs/DISTRIBUTION_PLAN.md

@@ -90,6 +90,7 @@ git push origin vX.Y.Z
 
 5. `release-public.yml` publishes:
 - npm package (`npm publish --access public`)
+- registry-consumer smoke (`node scripts/registry-consumer-smoke.mjs --version X.Y.Z --output artifacts/release/vX.Y.Z/registry-consumer-smoke.json`)
 - GitHub release with:
   - `opendevbrowser-extension.zip`
   - `opendevbrowser-extension.zip.sha256`

docs/EXTENSION_RELEASE_RUNBOOK.md

@@ -1,6 +1,6 @@
 # Extension Release Runbook
 
-Last updated: 2026-04-12
+Last updated: 2026-04-13
 
 Operational runbook for publishing extension artifacts from the public repo.
 
@@ -47,8 +47,9 @@ Configure in public GitHub repo secrets:
 ## Lane A execution
 
 1. Run tag-driven public release flow (`docs/RELEASE_RUNBOOK.md`).
-2. Confirm GitHub release includes extension zip + checksum.
-3. Verify checksum locally if required:
+2. Confirm the release workflow completed the registry-consumer smoke lane for the published npm package before treating the extension artifact as fully released.
+3. Confirm GitHub release includes extension zip + checksum.
+4. Verify checksum locally if required:
 
 ```bash
 shasum -a 256 opendevbrowser-extension.zip
@@ -115,6 +116,7 @@ If a bad extension release is published:
 ## Evidence to retain
 
 - workflow run URL(s)
+- registry-consumer smoke JSON or run-log excerpt proving the published npm package passed fresh install validation for the same release
 - listing-copy snapshot or generated-asset review note confirming the release-facing browser replay, desktop observation, and browser-scoped computer-use boundary wording used for the release
 - upload/publish JSON output summary
 - store listing URL and visible version

docs/FIRST_RUN_ONBOARDING.md

@@ -1,9 +1,9 @@
-# First-Run Onboarding (Pre-Release)
+# First-Run Onboarding (Local Artifact Validation)
 
 Status: active  
-Last updated: 2026-04-12
+Last updated: 2026-04-13
 
-This guide is the shipping checklist for validating OpenDevBrowser as a new user **before npm distribution is live**.
+This guide is the shipping checklist for validating OpenDevBrowser as a new user from a local package artifact. Use `docs/RELEASE_RUNBOOK.md` for the separate published npm registry-consumer proof lane.
 
 ## What this validates
 
@@ -27,7 +27,7 @@ This guide is the shipping checklist for validating OpenDevBrowser as a new user
 ```bash
 cd <public-repo-root>
 npm pack
-# -> opendevbrowser-0.0.18.tgz
+# -> opendevbrowser-0.0.19.tgz
 ```
 
 ## 2) Simulate a brand-new user workspace
@@ -36,7 +36,7 @@ npm pack
 WORKDIR=$(mktemp -d /tmp/opendevbrowser-first-run-XXXXXX)
 cd "$WORKDIR"
 npm init -y
-npm install <public-repo-root>/opendevbrowser-0.0.18.tgz
+npm install <public-repo-root>/opendevbrowser-0.0.19.tgz
 npx --no-install opendevbrowser version --output-format json
 ```
 
@@ -58,6 +58,7 @@ Expected:
 - the block maps replay to `screencast-start` / `screencast-stop`
 - the block maps desktop observation to the public `desktop-*` family
 - the block maps browser-scoped computer use to `--challenge-automation-mode` on `research run`, `shopping run`, `product-video run`, and `macro-resolve --execute`
+- the block includes a concrete browser-scoped entry command such as `npx opendevbrowser research run --topic "account recovery flow" --source-selection auto --challenge-automation-mode browser --mode json --output-format json`
 - help then opens the `Agent Quick Start` block
 - the block explicitly points agents to `opendevbrowser_prompting_guide`
 - the block explicitly points agents to `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"`