browserzap 0.6.1 → 0.8.0

package/CHANGELOG.md

@@ -1,8 +1,207 @@
 # Changelog
 
+## 0.8.0 — the connection fix and chat (draft until the store publishes it)
+
+Compared with the last public release (0.7.0). Only finished, tested work is listed. Everything is free during early
+access; nothing that keeps you safe (approvals, hand-off, Stop) will ever be paid.
+
+**It connects, and stays connected**
+- **The side panel no longer sticks on "Connecting…".** If the connection came up before the panel started listening,
+  0.7.0 could show "Connecting…" forever while everything underneath worked. The panel now always picks it up.
+- **The bridge comes back by itself after the extension reloads or updates.** Chrome updating BrowserZap no longer
+  leaves it waiting until your agent's next call or a manual `browserzap --bridge`.
+- **Profile names stay put.** An unnamed profile keeps its number ("Profile 1") across reconnects and restarts, and
+  renaming one profile never changes another.
+
+**Chat with your agent in the side panel**
+- **Type to your agent in any tab's panel**, or point at elements and ask about them in the same message.
+- **Your agent can listen** (`feedback_wait`): ask it to "listen to me in BrowserZap" and it answers as soon as you
+  write; the panel shows when it is listening. It replies in the tab you wrote from (`chat_reply`).
+- **Each message goes to the agent working in that tab**, never to another agent you have open.
+- **Each tab group's panel shows its own conversation**, not everything the agent did elsewhere.
+- **A message is never lost because the agent went away.** If the agent you wrote to has ended, the message is handed
+  to the next agent for that tab instead of sitting unread. The panel tells you which happened: "Sent to … — it reads
+  this on its next step", or "Saved. No agent is connected to this tab right now; the next one reads it."
+- **You can see it working.** The panel shows a one-line status ("● Claude is working: Clicking “Submit”") while a
+  call is in flight, and flips to a reply in the same tab as soon as the agent answers.
+- **The conversation stays with the tab.** Close the panel, switch tabs, or restart Chrome and the tab's chat is still
+  there, stored on your computer and compressed (Settings → Chat history: 7 days, 30 days, or off). Clear conversation
+  really clears it.
+- **And only with that tab.** Close a tab and its chat goes with it; reopen the tab (Ctrl+Shift+T) or let Chrome
+  restore it and the chat comes back. A new tab on the same site starts a fresh conversation.
+- **Answers arrive as soon as you send.** A listening agent is told the moment you press Send, instead of noticing on
+  its next check.
+- **A calmer conversation.** Connection messages stay in the header, and a long run of agent steps folds to its last
+  two, with the earlier ones a click away.
+
+**Free during early access**
+- **No limit on saved workflows** (0.7.0 kept 10).
+
+**Clearer approvals**
+- **The approval card says who presses the button:** "Press Approve once here — the agent then presses the button
+  itself."
+- **Picking a tab, radio button or option no longer asks for approval** because its label says "Approve" or "Delete";
+  buttons, links and consent checkboxes still do.
+
+**Settings, redesigned**
+- Clear sections for this browser (connection, version, the profile name agents see), the plan, help links, and the
+  advanced pairing options.
+
+**Also in this release**
+
+**Work with your agent in more than one tab**
+- **Open BrowserZap on any tab and it joins your agent.** With one agent connected, opening the side panel on a tab
+  gives the agent that tab as a new workspace: its own Chrome tab group labelled "<agent> · <site>", up to four per
+  agent. The agent is told and switches to it when it needs it; nothing moves under it.
+- **Several agents side by side.** Run two agents (two Claude Code or Codex windows) and each keeps to its own tab
+  groups. When you open the panel on a new tab, it asks which agent the tab is for. One agent can never act in
+  another's tabs.
+- **Your tabs stay yours.** Tabs you bring in from the panel are never closed or trimmed by the agent, and closing a
+  tab's panel hands that tab back as it is.
+- **No more duplicate tabs after a restart.** When Chrome restarts BrowserZap's background service (after a while
+  idle, or when the extension updates), your agent takes back its own tab and group instead of opening new ones.
+
+**Clearer on the page**
+- **The approval card never covers a form field.** Approve once / Deny sits beside or below the button it asks
+  about, on the button's row, clear of every input.
+- **A new agent cursor:** a gold arrow (Lucide's mouse pointer). While the agent types, the arrow steps aside and the
+  field's own blinking caret shows where the text goes, with the field's name beside it — never the value.
+- **Panels on other tabs say where your agent is** ("working in another tab", with Show), and every tab whose panel
+  is open is marked **ON** in the toolbar.
+- **Two copies of BrowserZap in one profile are called out** (for example the store version and a developer build),
+  with which one to turn off. Unnamed Chrome profiles get distinct names.
+- First visit explains Chrome's "BrowserZap started debugging this browser" bar, and that pressing Cancel stops the
+  agent. The status pills in Workflows are easier to read (higher contrast), and the panel uses Lucide icons.
+
+**More accurate results**
+- A click that submits a form now reports a navigation that happens a moment later, instead of "no change".
+- Chrome's debugging bar no longer flickers mid-task (BrowserZap lets go after 5 idle minutes, and at once when the
+  agent finishes).
+
+**For developers**
+- `browserzap setup` names the store extension id it registered in store-only mode.
+- `npm run release:changes`, `release:public` and `release:internal` (docs/RELEASE_CHECKLIST.md).
+
+## 0.8.0 (internal)
+
+**Internal only.** Built and installed from the checkout for the owner's own use (`browserzap-0.8.0.tgz`, packed
+locally); never published to npm, the Chrome Web Store or the website. Branch `integration/0.8` → `release/0.8`.
+Full browser suite and unit tests: see docs/releases/0.8.0-internal.md.
+
+### Tabs, workspaces and several agents
+- **Workspaces.** Opening the side panel on a tab with one agent connected adds the tab to that session as a new
+  workspace group "<agent> · <site>" (≤ 4 groups per session, `MAX_WORKSPACES_PER_SESSION`). Panels already open when
+  an agent connects join it too. The agent gets a note on its next call; `browser_list_tabs` returns
+  `role: "workspace"` and `workspace: "<label>"` (read back from Chrome after a restart). Workspace tabs are the
+  person's (`sharedTabs`): never trimmed, kept and ungrouped when the session ends, released when their panel closes.
+- **Several agents.** With more than one agent connected the panel shows a picker (`join_tab`); nothing joins on its
+  own. `tabBelongs` checks the session's group and its workspace groups; another session's tab is
+  `PERMISSION_REQUIRED`. Proven with two real MCP clients interleaving navigate, fill, chat, approval and click (B-04,
+  `concurrent-agents.e2e.mjs`).
+- **"Work here".** Sharing a tab when exactly one agent is connected moves that agent there (`giveTabToAgent`): the
+  tab joins its group, becomes its session tab, and the next page action is stopped once with the reason
+  (`tabNotice`, D-21). Panels on tabs without an agent name the agent busy elsewhere, with Show; the header says
+  "N agents in another tab".
+- **Reclaim after a restart.** The saved session map is merged, not overwritten (`persistSessions`), so the first
+  session to come back after a service-worker restart no longer erases the others; an entry is removed only when its
+  session ends (`forgetSavedSession`). A debugger attachment left by the previous worker is taken back
+  (`reclaimOwnAttachment`: only our own attachment can be detached) instead of failing with "Another debugger is
+  already attached".
+- **The bridge comes back by itself (B-10).** After an extension reload, a paired extension now asks the native
+  helper to start the bridge when its connection fails, instead of waiting for an agent or a manual
+  `browserzap --bridge`. The helper runs ensure-bridge, the extension reconnects, and it stops asking while the
+  connection is healthy.
+- **Debugger hold on the action's tab.** The no-detach-mid-action hold now covers the tab an action actually runs on
+  (a session's first tab, or one switched to mid-call), not only the session tab at the start of the call.
+
+### Side panel and page
+- **Chat (internal, Pro).** The message box is on in internal builds (`src/sidepanel/features.ts`); a message is a
+  feedback batch with `kind: "message"`; every tool result reminds the agent until `feedback_get`; `chat_reply`
+  answers in the panel (offered with `BROWSERZAP_EXPERIMENTAL=chat`). Before any public release it must be off or
+  gated by the licence.
+- **Approval card placement** (B-01): every candidate spot is first moved on screen, then judged by what it covers
+  (other controls and the marked element itself); if none is clear it slides along the same rows until it is; on a
+  page with no clear spot it takes the one that covers least. Rules unchanged: trusted clicks only, `tabIndex = -1`,
+  out of the agent's reach.
+- **Cursor:** Lucide `mouse-pointer-2`, gold (`#f5b335`) with a dark outline. The drawn I-beam caret is removed: a
+  typing step hides the arrow (decided by the step, not by focus) and shows only the field's name.
+- **Icons:** `lucide-preact` (ISC) for the panel's settings, send, pin, copy and close; brand marks unchanged.
+- **ON badge** on every tab whose panel is open (B-03); duplicate-build warning and never-reused profile numbers
+  (B-05); the debugging bar explained on first visit (B-08); darker text on the status pills (axe contrast).
+- The panel subscribes to state in a layout effect and connects its tab port at load, so a panel that has not painted
+  yet still receives updates and hands its tab back when closed.
+- Late navigation after a click that started a request is reported (B-02, `NAVIGATION_FOLLOW_MS`).
+
+### Tests and release tooling
+- **Browser suite: ~15 → ~12 minutes** for the full lane: compile-time E2E build (`build:e2e` → `extension-e2e/`,
+  short `DEBUGGER_IDLE_MS` / `TAB_TRIM_IDLE_MS` / `SESSION_GRACE_MS`; production values pinned by the contract test),
+  `expect` on clicks, `until()` instead of fixed sleeps, grouped files, lanes `test:e2e:fast`, `test:e2e`,
+  `test:e2e:real-timers`. The debugger idle case dropped from 5 min to ~5 s.
+- **New checks:** console/exception guard on BrowserZap's own pages and worker, panel layout at 320/420/600 px,
+  axe-core accessibility, keyboard flow, service-worker suspension, orphan-process and redaction scans, failure
+  bundles in `artifacts/e2e-failures/`, JSON timings.
+- **Build guard:** the E2E build compiles into `dist/chrome-e2e` with a marker the store packager refuses.
+- **Fixed traps:** the harness no longer attaches to web pages (it made every tab look "debugged" and held up new
+  tabs); `test:e2e` always runs every test — re-running only failures is `test:e2e:rerun-failed`, never a release
+  lane.
+- Store records per release (`docs/store/`, browser view `docs/store/index.html`) and the public/internal release
+  checklist (`docs/RELEASE_CHECKLIST.md`) — shipped with 0.7.0's records.
+
+### Cleanup
+- 13 finished worktrees and 46 merged local branches removed; 33 merged remote branches deleted (backup bundle first);
+  GitHub deletes head branches on merge. Finished plans and reports moved to `docs/archive/` (links updated).
+  Branch, worktree and push-batching rules in `docs/DEVELOPMENT_WORKFLOW.md`. Architecture plan:
+  `docs/design/FEATURE_MODULES.md`.
+
+## 0.7.0 — public launch
+
+BrowserZap is public: free, and installed from the Chrome Web Store.
+
+- **The extension comes from the Chrome Web Store:**
+  <https://chromewebstore.google.com/detail/bbnmhaonicbmljhbahimpgfafbjoijpe>. Chrome keeps it updated. There is no
+  folder to load and no Developer mode.
+- **The npm package no longer includes the extension.** `npm install -g browserzap` brings the bridge, the native
+  messaging helper and the MCP server — not `extension/`. `browserzap setup` prints the store link when the extension
+  is missing, and `--extension` (a developer option) now says so instead of installing nothing.
+- **The helper accepts only the store extension by default.** `browserzap setup --dev` adds a developer's unpacked
+  build to the allowed ids and remembers the choice; a plain `setup` goes back to store-only and says so.
+- **`browserzap doctor` works on an npm install** with no bundled extension: it names the store id and passes.
+- **The bridge knows which extension it is talking to.** `hello` carries the extension's version, `browser_status`
+  shows it, and a store build older than the bridge gets a notice — never a refused connection. Chrome updates the
+  extension on its own; to update now, open `chrome://extensions` and press **Update**.
+- **A new side panel, built to be understood on first sight** (Preact, still compiled locally with Tailwind):
+  - **Chat** shows what the agent does in this tab as a conversation, and a first-visit guide in three steps with
+    prompts to copy. **Workflows** holds saved tasks. The Comment tab is gone: **Point at page** at the bottom of the
+    panel does the same.
+  - **Notes reach the agent sooner.** Every tool result now tells the agent that notes are waiting until it calls
+    `feedback_get` (it used to be `browser_status` only).
+  - **Take over / Hand back** replaces the Collab/AI/User switch. Approvals and "Your turn" hand-offs sit at the
+    bottom, always in reach; a decision waiting in another tab says so with a **Show** button.
+  - A half-typed hand-off note is no longer wiped while the agent works, and the conversation stops jumping to the
+    bottom while you read further up.
+- **Give your agent the tab you are on.** **Let the agent use this tab** in that tab's panel: the agent's next request
+  works there instead of opening a new tab, and an agent already working sees it in `browser_list_tabs` (role
+  `shared-available`) and can `browser_switch_tab` to it. An agent never takes a tab nobody shared. A shared tab stays
+  yours: when the session ends it is kept, not closed.
+- **Chrome's "BrowserZap started debugging this browser" bar no longer flickers between steps.** BrowserZap now lets go
+  of a tab after 5 minutes without an agent action (was 60 s), and still at once when the session ends, when you take
+  over, hand off or close the panel.
+- **The panel says "Connecting…" while Chrome wakes BrowserZap up**, instead of "offline".
+- **The side panel belongs to one tab.** It opens where you click the toolbar icon (and is available on the agent's
+  tabs) and hides when you switch to another tab. The toolbar badge reads **ON** only on tabs BrowserZap controls, or
+  the number of decisions waiting there.
+- **Closing the side panel hands the tab back.** Comment mode ends (it used to come back on every reload), a recording
+  is dropped, and an agent working there lets go of the tab: it leaves the group, stays open as it is, its overlays go
+  and the debugger detaches. The agent's next page action is told the person took the tab back.
+- **An existing upload is detected** (#65): `file_upload` reports the file already on the input instead of asking for
+  a second approval, and tells the agent to ask before replacing it.
+- **Comment screenshots show context** (#66): each element crop now includes the surrounding page instead of a tight
+  cut-out.
+- No new tools and no new permission; the protocol stays 4, and approvals, hand-off and Stop stay free.
+
 ## 0.6.1 (2026-10-30)
 
-The changes from three real-Chrome runs in the owner's own browser (docs/REVIEW_LATER.md, K-7…K-10). Checked in the
+The changes from three real-Chrome runs in the owner's own browser (docs/archive/REVIEW_LATER.md, K-7…K-10). Checked in the
 owner's Chrome: `npm run check:chrome` 9/9, approval through the page card, the test tab closed at session end.
 
 - **No more tabs left behind.** The tab group is the contract: while the agent is connected its tabs stay open in the
@@ -58,7 +257,7 @@ A replay now waits for what the step is actually blocked on, and retries that st
 
 ## 0.5.5 (2026-10-30)
 
-Comment mode, debugging tools, files, Edge and WSL, a much better doctor, and the Chrome Web Store build. Known items to review are listed in docs/REVIEW_LATER.md (upload approval visibility, a file the person picks themselves, a download re-test, wider Comment screenshots, a calmer side panel).
+Comment mode, debugging tools, files, Edge and WSL, a much better doctor, and the Chrome Web Store build. Known items to review are listed in docs/archive/REVIEW_LATER.md (upload approval visibility, a file the person picks themselves, a download re-test, wider Comment screenshots, a calmer side panel).
 
 - No more stuck file dialogs: when the agent clicks a page's "Choose file" control, no Windows file picker opens; the result says the page asked for a file and to use `file_upload`. Your own clicks open the picker as usual. If Chrome is set to ask where to save each download, `browserzap doctor` and `browser_downloads` say so and how to turn it off (an extension cannot skip that dialog).
 - Messages for people who installed from npm: the side panel, the extension and the agent no longer point to source-only commands (`npm run health`, `npm run bridge:restart`, …) but to `browserzap doctor`, `browserzap restart-bridge`, `browserzap --print-token`. When a bridge from another install holds the port, the side panel now says so and shows the fix instead of staying grey.

package/README.md

@@ -28,26 +28,30 @@ browser, no copied cookies and no new login: the agent works in your real tab, a
 
 ## Install
 
-```cmd
-npm install -g browserzap
-browserzap setup
-```
+1. **Add the extension from the Chrome Web Store:**
+   <https://chromewebstore.google.com/detail/bbnmhaonicbmljhbahimpgfafbjoijpe>. Chrome keeps it updated for you.
+
+2. **Install the companion program** (the bridge and the MCP server; it needs Node.js 22 or newer):
+
+   ```cmd
+   npm install -g browserzap
+   ```
 
-`browserzap setup` does three things, and is safe to run again:
+3. **Run setup once:**
+
+   ```cmd
+   browserzap setup
+   ```
+
+`browserzap setup` does two things, and is safe to run again:
 
 1. Registers a small helper with Chrome and Edge for your Windows user only (no administrator rights), so the
-   extension connects by itself. There is no token to copy.
-2. Copies the BrowserZap extension to `%USERPROFILE%\BrowserZap\extension` and prints that path.
-3. Finds Claude Code, Codex CLI and Cursor, shows the exact entry it would add for BrowserZap, and adds it only after
+   extension connects by itself and can start the companion program. There is no token to copy.
+2. Finds Claude Code, Codex CLI and Cursor, shows the exact entry it would add for BrowserZap, and adds it only after
    you answer `y`.
 
-Then add the extension to Chrome:
-
-- **From the Chrome Web Store** (in review; this link works once it is published):
-  <https://chromewebstore.google.com/detail/bbnmhaonicbmljhbahimpgfafbjoijpe>. Chrome keeps it updated.
-- **Until then, load it unpacked** (Chrome does not allow this step to be automated):
-  1. Open `chrome://extensions` and turn on **Developer mode**.
-  2. Click **Load unpacked** and choose the folder `setup` printed.
+The npm package ships the bridge, the native helper and the MCP server — **not** the extension. If the extension is
+not installed yet, `setup` prints the store link.
 
 Click the BrowserZap icon to open the side panel. It turns green when it is connected. Check everything with:
 
@@ -58,6 +62,13 @@ browserzap doctor
 Using Claude Code inside WSL? BrowserZap stays on Windows; in WSL run
 `claude mcp add browserzap -- cmd.exe /c browserzap` (details: <https://browserzap.com/docs/platforms>).
 
+### Developers
+
+From a source checkout, `npm run build` still writes `extension/`, which you can load with **Load unpacked** in
+`chrome://extensions` (turn on **Developer mode**). Run `browserzap setup --dev` so the helper accepts that build;
+`setup` without `--dev` goes back to the store extension only. From a checkout without a global install, the same
+command is `node bridge-server/index.js setup --dev`.
+
 ## Use it
 
 Restart your MCP client and ask for something in the browser, for example: *"Open example.com and tell me what the
@@ -88,7 +99,7 @@ Start with `browserzap doctor`: every failed line says what to do.
 | Doctor: *a bridge with a different pairing secret holds 127.0.0.1:9334* | `browserzap restart-bridge`, then **Reconnect** in the side panel |
 | Doctor: *Launcher finds Node and the helper* fails | Node moved (a version switch with fnm, Volta or nvm): run `browserzap setup` again |
 | Doctor: *Not blocked by Chrome policy* fails | Your computer is managed; ask IT to allow the helper `com.browserzap.bridge` and the extension |
-| Chrome says *Disable developer mode extensions* on start-up | Expected while the extension is loaded unpacked. Choose **Keep**; the Chrome Web Store version does not show it |
+| Chrome says *Disable developer mode extensions* on start-up | Only with a developer's unpacked copy: choose **Keep**. The Chrome Web Store install never shows it |
 | A bar says *"BrowserZap" started debugging this browser* | Expected while an agent can act; it goes away when the agent ends or after a minute idle |
 | Your agent does not list BrowserZap's tools | Restart the agent app after `browserzap setup`. To add it by hand, `browserzap --help` prints the exact MCP configuration |
 | A step stops with *"needs you"* | The page asked for a password, a code or an approval. Do it, press **Done**, and the agent continues |
@@ -104,7 +115,7 @@ More: <https://browserzap.com/docs/troubleshooting>.
 | `browserzap doctor` | Checks the helper registration, the launcher, Chrome policy, the extension id and the connection |
 | `browserzap restart-bridge` | Replaces a bridge that will not pair (another install's secret or an old version) |
 | `browserzap run <workflow> --params rows.csv` | Runs a saved workflow without an agent (one row on the free plan) |
-| `browserzap uninstall` | Removes the helper registration and the extension copy; keeps your data |
+| `browserzap uninstall` | Removes the helper registration (and a developer's unpacked copy); keeps your data |
 | `browserzap uninstall --purge` | Also removes your BrowserZap data folder (cannot be undone) |
 
 Environment variables (allowed sites, profile, upload folder, retention, …): <https://browserzap.com/docs/configuration>.
@@ -116,8 +127,9 @@ npm install -g browserzap@latest
 browserzap setup
 ```
 
-A Web Store install updates itself; an unpacked one needs the reload icon on its card in `chrome://extensions`. Your
-workflows, run reports and settings are kept.
+Chrome updates the extension from the Chrome Web Store by itself. Your workflows, run reports and settings are kept.
+If the extension is older than the companion program, the agent's status result says so: Chrome retries on its own, or
+open `chrome://extensions` and press **Update**.
 
 ## Free and Pro
 

package/THIRD_PARTY_NOTICES.md

@@ -78,6 +78,8 @@ No copyleft, source-available-restricted or non-commercial licences are present
 | Package | Licence | Purpose |
 |---|---|---|
 | `ws` | MIT | WebSocket transport for the local bridge |
+| `preact` | MIT | Side-panel UI, bundled into the extension's `sidepanel.js` (Copyright (c) 2015-present Jason Miller) |
+| `lucide-preact` | ISC | Side-panel icons, bundled into `sidepanel.js`; the page cursor draws Lucide's `mouse-pointer-2` path (Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as part of Feather (MIT); all other copyright (c) for Lucide are held by Lucide Contributors 2022) |
 
 ### Build-time only (not redistributed)
 
@@ -85,9 +87,8 @@ No copyleft, source-available-restricted or non-commercial licences are present
 `copy-webpack-plugin`, `@types/chrome` and their transitive dependencies — including all
 packages listed above as Apache-2.0, BSD and CC-BY-4.0.
 
-The extension bundle emitted by webpack contains first-party source plus the webpack
-runtime only; verified from the production build log (`cacheable modules 85.7 KiB`, all
-`./src/...`).
+The extension bundle emitted by webpack contains first-party source, the webpack runtime and,
+since 0.7.0, `preact` in the side panel's `sidepanel.js` (MIT; listed above).
 
 ---
 

package/bridge-server/background-runs.js

@@ -257,7 +257,7 @@ function createRunRegistry({ execute, onFinish = () => {}, now = Date.now }) {
 /**
  * The part of a finished batch an agent needs: counts and, per set that did not
  * complete, where and why. Everything else is in the report. Kept well under
- * 700 bytes per set (docs/NEXT_RELEASE_SCOPE.md P0-5).
+ * 700 bytes per set (docs/archive/NEXT_RELEASE_SCOPE.md P0-5).
  */
 function compactBatch(result) {
   const ev = result?.evidence ?? {};

package/bridge-server/entitlements.js

@@ -2,9 +2,8 @@
  * BrowserZap — plan and entitlements (docs/ADR/ADR-006-free-pro-boundary.md).
  *
  * The free core is everything that keeps an agent safe and useful on its own:
- * every browser tool, approvals, handoff, honest errors and basic workflows.
- * Pro adds workflow history, bulk runs, run reports and more than
- * FREE_LIMITS.workflows saved workflows. Nothing here ever gates a safety check.
+ * every browser tool, approvals, handoff, honest errors and workflows.
+ * Pro adds workflow history, bulk runs and run reports. Nothing here ever gates a safety check.
  *
  * A licence is a signed token issued by the licence service after payment:
  *
@@ -36,15 +35,18 @@ const LICENSE_FILENAME = 'license';
 const GRACE_DAYS = 14;
 const DAY_S = 24 * 60 * 60;
 
-/** Limits that apply without a licence. */
-const FREE_LIMITS = Object.freeze({ workflows: 10 });
+/**
+ * Limits that apply without a licence. Early access (owner decision 2026-11-03, docs/DECISIONS.md D-0.8-1): no
+ * limit on saved workflows; the site promises every shipped feature free. A cap returns only with notice on the site.
+ */
+const FREE_LIMITS = Object.freeze({});
 
 /** Every Pro feature, with the text shown when it is missing. */
 const PRO_FEATURES = Object.freeze({
   'workflow.history': 'keeps every saved version of a workflow and can run or restore an older one',
   'workflow.bulk': 'runs one workflow over many parameter sets in a single call',
   'workflow.reports': 'keeps a local report of every workflow run',
-  'workflow.unlimited': `saves more than ${FREE_LIMITS.workflows} workflows`,
+  'workflow.unlimited': 'saves any number of workflows',
 });
 
 const PLAN_FEATURES = Object.freeze({

package/bridge-server/extension-id.js

@@ -10,7 +10,8 @@
  * The Chrome Web Store signs its own build and does not accept a manifest
  * `key`, so the store build may get a different id. Fill in
  * STORE_EXTENSION_ID from the developer dashboard after the first upload; the
- * native host then lets both builds in (docs/RELEASE.md §3b).
+ * native host then lets both builds in, once `setup --dev` allows the unpacked
+ * one (docs/RELEASE.md §3b).
  *
  * Everything that has to name the extension — the native messaging host
  * manifest's allowed_origins, `browserzap doctor`, the tests — reads the id
@@ -18,11 +19,20 @@
  * changed key fails `doctor` and the tests instead of silently breaking native
  * messaging.
  *
+ * The store build is the only build a user has (D3), so the store id is the
+ * only one allowed by default. `browserzap setup --dev` saves
+ * `{ "allowDevExtension": true }` in the config dir (next to the pairing
+ * secret, user-only permissions) and the unpacked id is allowed on top of it.
+ * Chrome starts the native host itself, so an env var in the user's shell can
+ * never carry that choice (F2): the file can.
+ *
  * Derived from the manifest key in src/manifest.json. Chrome computes:
  *   id = SHA-256(SPKI DER public key), first 16 bytes, each hex nibble 0-f → a-p
  */
 
 const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
 
 /** chrome-extension://gienkaoaimdjmcjdejjanmbkpfakmkno/ */
 const EXTENSION_ID = 'gienkaoaimdjmcjdejjanmbkpfakmkno';
@@ -36,6 +46,9 @@ const ALLOWED_EXTENSION_IDS = Object.freeze([EXTENSION_ID, STORE_EXTENSION_ID].f
 /** Name Chrome uses for the native messaging host; also the registry key's leaf. */
 const HOST_NAME = 'com.browserzap.bridge';
 
+/** Written by `browserzap setup --dev` in the config dir; its absence means store only. */
+const DEV_FLAG_FILENAME = 'allow-dev-extension';
+
 function extensionOrigin(id = EXTENSION_ID) {
   return `chrome-extension://${id}/`;
 }
@@ -45,6 +58,52 @@ function allowedOrigins(ids = ALLOWED_EXTENSION_IDS) {
   return ids.map((id) => extensionOrigin(id));
 }
 
+/**
+ * Whether the saved dev flag in `dir` allows the unpacked developer build.
+ *
+ * Fail closed: a missing, unreadable or malformed file means store only (D4).
+ */
+function devExtensionAllowed(dir) {
+  if (typeof dir !== 'string' || !dir) return false;
+  try {
+    const saved = JSON.parse(fs.readFileSync(path.join(dir, DEV_FLAG_FILENAME), 'utf8'));
+    return saved?.allowDevExtension === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Save (or clear) the dev flag. `setup` calls this before it writes the host
+ * manifest, so the manifest and the host's own check read the same answer.
+ */
+function setDevExtensionAllowed(dir, allowed) {
+  if (typeof dir !== 'string' || !dir) return false;
+  const file = path.join(dir, DEV_FLAG_FILENAME);
+  if (!allowed) {
+    try { fs.rmSync(file, { force: true }); } catch { /* already gone */ }
+    return false;
+  }
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, '{"allowDevExtension":true}\n', { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return true;
+}
+
+/**
+ * Every extension id the native host may let in: the store id, plus the
+ * unpacked id when `setup --dev` saved the flag.
+ *
+ * `dir` defaults to the config dir, resolved lazily so importing this module
+ * never reads the filesystem or triggers the legacy-folder check.
+ */
+function allowedExtensionIds({ dir } = {}) {
+  const configDir = dir === undefined ? require('./secret').configDir() : dir;
+  const ids = devExtensionAllowed(configDir) ? [EXTENSION_ID, STORE_EXTENSION_ID] : [STORE_EXTENSION_ID];
+  return ids.filter(Boolean);
+}
+
 /**
  * Chrome's extension id for a manifest `key` value (base64 SPKI DER).
  * Returns null when the key is missing or is not a valid public key.
@@ -72,7 +131,11 @@ module.exports = {
   STORE_EXTENSION_ID,
   ALLOWED_EXTENSION_IDS,
   HOST_NAME,
+  DEV_FLAG_FILENAME,
   extensionOrigin,
   allowedOrigins,
+  devExtensionAllowed,
+  setDevExtensionAllowed,
+  allowedExtensionIds,
   extensionIdFromKey,
 };

package/bridge-server/extension-version.js

@@ -0,0 +1,65 @@
+'use strict';
+/**
+ * The extension version the bridge expects (WP5, F4).
+ *
+ * The Chrome Web Store ships the extension and updates it on its own schedule,
+ * so after the 0.7.0 launch the store build will often lag the npm bridge by a
+ * review cycle. The extension's `hello` carries `extensionVersion` (an additive
+ * field; the protocol stays 4), the bridge stores it per profile, and
+ * `browser_status` says plainly when the connected build is older than this
+ * bridge expects.
+ *
+ * Nothing here ever refuses a connection or a call: a missing version means an
+ * older build (≤ 0.6.1), which is exactly the case the notice is for.
+ */
+
+/** The oldest extension build this bridge describes as current. */
+const MIN_EXTENSION_VERSION = '0.7.0';
+
+/**
+ * One numeric part per dot-separated segment. Anything that is not a version at
+ * all counts as 0, so a short, long or odd string still compares instead of
+ * throwing.
+ */
+function versionParts(version) {
+  let text = '';
+  if (typeof version === 'string') text = version.trim();
+  else if (typeof version === 'number' && Number.isFinite(version)) text = String(version);
+  if (!text) return [0];
+  return text.split('.').map((segment) => {
+    const match = /^\d+/.exec(segment.trim());
+    return match ? Number(match[0]) : 0;
+  });
+}
+
+/**
+ * Numeric dot comparison: 0.7.0 > 0.6.1, 0.7 > 0.7.0, 0.7.0.1 > 0.7.0.
+ * Returns -1 when `a` is older, 0 when equal, 1 when newer.
+ */
+function compareVersions(a, b) {
+  const left = versionParts(a);
+  const right = versionParts(b);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i++) {
+    const x = left[i] ?? 0;
+    const y = right[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * True only for a real version string that is older than `minimum`. A missing
+ * or non-string version answers false: "unknown" is not the same as "old", and
+ * the caller decides what to say about it.
+ */
+function isOlderThan(version, minimum) {
+  if (typeof version !== 'string' || !version.trim()) return false;
+  return compareVersions(version, minimum) < 0;
+}
+
+module.exports = {
+  MIN_EXTENSION_VERSION,
+  compareVersions,
+  isOlderThan,
+};