@capagents/forgeqe 2.3.15 → 2.4.0

package/HOW_TO_USE.md

@@ -513,11 +513,17 @@ A card says which it did and why (*Extending PracticeTests.Flow · covers 12 of
 
 **The same flow asked again.** When a session writes tests and you ask for a flow an earlier job already wrote a test for, ForgeQE runs that test first, before any browser run. If it passes in a real browser, that is the answer: no browser run, no Scribe, and no new test file, in the seconds the test takes (*✓ Existing test passed · 19s · no browser run or new test needed*). If it fails, the flow runs in the browser and Scribe updates that test instead of writing another. ForgeQE's agent rewords a goal a little each time, so goals count as the same flow when they share their content words (endings, case, and phrasing aside) and the new goal keeps everything the earlier one checked; the same steps with a different final check, a shorter flow, or another site are a new flow. The agent also compares the earlier goal with your request and runs fresh when you ask for a check the earlier test does not have. Ask for "a fresh run" or "a new test" to skip the reuse.
 
-**When the flow cannot be reproduced.** If ForgeQE's own replay of the run could not reach the run's final page and Scribe's first test fails too, the job stops there and says which replayed step failed and why, instead of spending its remaining attempts on a flow no script can repeat as recorded.
+**The run as a test would do it.** The browser agent works through the same page a test meets, and the handoff tells Scribe everything it did on the way:
+- A click on an element something covers (a confirmation after Add to cart, a pop-up) fails and names what covers it, so the agent closes it as a user would and that step is in the flow; the step after says what covered it, and "What covered the page before a click" lists them. The engine library would otherwise click the element from JavaScript, which a test cannot do. What it still does from a script (a click, typing to the page) is named on its step.
+- Locators are the ones Playwright finds: no link role for an `<a>` without `href` (Chrome calls it a link, Playwright does not), icon-font characters kept out of names (a name with one becomes a `role_pattern`), and a control that repeats on every row or card gets a locator scoped to its row (`#product-1 a.cart_quantity_delete`).
+- An element in a frame says which frame, and the replay reaches it through `frameLocator`. Advertisements (Google's full-page ads, ad frames) are marked, left out of the replay, and "Ads on these pages" says to block the ad hosts in the test instead of closing them.
+- A suite case runs from the state its test starts from: without the saved logins' sessions, so the agent signs in as the test will (`suite.restore_sessions: true` keeps them; a login with no username and password to sign in with keeps its session, the only way in) and from the case's own start page (its URL, first step, description, or preconditions). When a run did start with saved sessions, "State the run started with" says so.
+
+**When the flow cannot be reproduced.** If ForgeQE's own replay of the run could not reach the run's final page and Scribe's test fails too, Scribe is told where the replay stopped and what was open on the page, since that is usually a pop-up, consent banner or ad the browser agent closed, or state its browser already had (signed in, items in a cart), and gets another attempt to handle it. The job stops, saying which replayed step failed and why, only when the test then fails the same way again, instead of spending its remaining attempts on a flow no script can repeat as recorded.
 
 **Why a test failed.** When ForgeQE's run of Scribe's test fails, the ✗ line and the next attempt say why in the test's own words: dotnet test's Error Message, pytest's `E` lines, or the error with its Expected and Received values (Playwright, Jest, JUnit), not the runner's summary line.
 
-**Keeping Scribe's cost down.** ForgeQE reads the repository's test setup itself before Scribe starts (stack, settings files and their browser values, the test id attribute, base classes, page objects and their methods, one test command) and hands it over, so Scribe does not discover it with dozens of file reads. Each attempt after the first starts a fresh session from a summary of the job (handoff, files changed, what each attempt did, the latest failure), so later attempts cost about what the first did. `code.max_attempts` (default 3) and `code.max_tokens` (default 1,500,000; `0` turns it off) cap a job, and the token budget is checked during an attempt too, so one long attempt is stopped when the total passes it. The reviewer sorts its issues into correctness (the test does not test what the goal says, or not reliably) and coding standards (test data or credentials in a page object, naming, hard waits, leftovers). Coding standards never fail a test that works: it is accepted, and the coding agent gets one more round (not counted in `max_attempts`) to fix them; if that round breaks the test, ForgeQE puts back the version that passed and lists the standards issues in the notes (`code.tidy: false` skips the round). A test the reviewer rejects twice for correctness stops the job with its issues, since that usually means the test case and the page disagree. Under each step, the handoff shows that step's part of the page (its section and neighbours, from the replay's page snapshot) instead of whole snapshots. When a test fails, ForgeQE shows the failing element on the test's page at the failure and on the replay's page, so most failures are fixed without opening a browser. Scribe's live browser is switched on only when the same failure repeats, and it does not send a page snapshot after every click or keystroke. `code.max_steps` (default 50) caps the tool calls in one of Scribe's turns. `code.review_profile` runs the reviewer on a cheaper llms.json profile.
+**Keeping Scribe's cost down.** ForgeQE reads the repository's test setup itself before Scribe starts (stack, settings files and their browser values, the test id attribute, base classes, page objects and their methods, one test command) and hands it over, so Scribe does not discover it with dozens of file reads. Each attempt after the first starts a fresh session from a summary of the job (handoff, files changed, what each attempt did, the latest failure), so later attempts cost about what the first did. The summary has a "Tried already, and did not work" list: for each failed attempt, what Scribe said it did (it reports each change in `tried`), how it failed, the locator the test was waiting for and the element that covered it and took the click, both read from the test's output, and whether an earlier attempt already failed on that locator. Scribe must not try those again in the same form and must say what it does differently. `forgeqe heal` keeps the same list across its attempts. `code.max_attempts` (default 3) and `code.max_tokens` (default 1,500,000; `0` turns it off) cap a job, and the token budget is checked during an attempt too, so one long attempt is stopped when the total passes it. The reviewer sorts its issues into correctness (the test does not test what the goal says, or not reliably) and coding standards (test data or credentials in a page object, naming, hard waits, leftovers). Coding standards never fail a test that works: it is accepted, and the coding agent gets one more round (not counted in `max_attempts`) to fix them; if that round breaks the test, ForgeQE puts back the version that passed and lists the standards issues in the notes (`code.tidy: false` skips the round). A test the reviewer rejects twice for correctness stops the job with its issues, since that usually means the test case and the page disagree. When a test passed and the reviewer sent it back, and the changes for the review then break it (or the attempts or the token budget run out first), ForgeQE puts back the version that passed: the result is passed but not approved, with the reviewer's issues in the notes, so you get a working test to finish instead of none. Under each step, the handoff shows that step's part of the page (its section and neighbours, from the replay's page snapshot) instead of whole snapshots. When a test fails, ForgeQE shows the failing element on the test's page at the failure and on the replay's page, so most failures are fixed without opening a browser. Scribe's live browser is switched on only when the same failure repeats, and it does not send a page snapshot after every click or keystroke. `code.max_steps` (default 50) caps the tool calls in one of Scribe's turns. `code.review_profile` runs the reviewer on a cheaper llms.json profile.
 
 **Scribe's rulebook: the same mistake once.** When a job passes after a failed test run or a reviewer's change, Scribe's report gives up to three one-line rules that would have avoided the mistake ("Wait for the cart badge with toHaveText before clicking Checkout; it updates after a request"). ForgeQE keeps them in `.forgeqe/scribe-rules.json` in the repository, and every attempt of later jobs, and every healing session, starts with them. A lesson from a job that did not pass, or that passed at once, is not kept: only a fix that worked becomes a rule. The book stays small, since it is sent with each model call: at most 15 rules of one line each; a lesson learned again is merged into its rule (shown as "learned 3 times") instead of added; when it is full, the rule confirmed least and longest ago goes, and a rule not learned again for 180 days expires. The rules are the coding agent's own words, so a rule with a link, something like a token, a destructive command, or wording that tells an agent to drop its instructions is refused, and the agents are told they are hints that never override their instructions or the team's guardrails. Commit the file to share the rules with the team and see each change in review; edit or delete a rule there (the agents cannot change `.forgeqe`). ForgeQE says each new rule as it learns it (`Learned for next time: …`). `code.rulebook: false` turns it off.
 
@@ -1498,6 +1504,7 @@ forgeqe suite cases.yaml --no-code --no-write-back --out .forgeqe/reports/smoke
 suite:
   parallel: 1        # browsers at once
   code: true         # with a repo set, passed cases go to Scribe
+  restore_sessions: false   # true: each case starts signed in from the saved logins' sessions
   out_dir: ./.forgeqe/reports/suites
 ```
 

package/README.md

@@ -27,6 +27,8 @@ Everything else is downloaded on first use into `~/.forgeqe/tools` (`%USERPROFIL
 
 `forgeqe setup` does all of this up front; otherwise the first command that needs a piece fetches it. Upgrading is `forgeqe update`: it updates every `forgeqe` on PATH (bun, npm and pip installs) and waits while the registries catch up with a new release. A release that pins a newer Bun, agent runtime, uv or engine library downloads it on the next run and removes the old one. Deleting `~/.forgeqe` removes everything ForgeQE downloaded. Behind a proxy, set `HTTPS_PROXY`. The npm launcher's Bun download also needs `NODE_USE_ENV_PROXY=1` (Node 24+); on older Node, use the pip launcher or install Bun yourself.
 
+**Coming from WebPilot** (`@capagents/webpilot`, ForgeQE's name before the rename): remove it first with `npm uninstall -g @capagents/webpilot`. npm refuses to install ForgeQE while the old package owns the `webpilot` command (`EEXIST ... npm\webpilot`). Your settings, sign-ins, `WEBPILOT_*` variables and `webpilot.yaml` files keep working. The npm package installs only the `forgeqe` command; the pip launcher still installs `webpilot` too. Install with `-g`, not with `npm install @capagents/forgeqe` inside a folder: `npx forgeqe` runs that folder copy, and `forgeqe update` does not change it (it prints how to replace it).
+
 From this repo:
 
 ```bash

package/THIRD_PARTY_NOTICES.md

@@ -2,7 +2,7 @@
 
 ForgeQE contains and installs the open source software below. Each is the work of its own authors and is used under its own licence, which is reproduced here as that licence asks. These notices are generated from the installed packages by `bun scripts/gen-notices.ts`; do not edit.
 
-Most of these libraries are inside `dist/forgeqe.js`, the bundle ForgeQE ships; `@opentui/core` and its platform builds are installed beside it. axe-core (MPL-2.0) is shipped unmodified as `dist/vendor/axe.min.js`; its source is at the address given with it.
+Most of these libraries are inside `dist/forgeqe.js`, the bundle ForgeQE ships; `@opentui/core` and its platform builds are installed beside it. axe-core (MPL-2.0) is shipped unmodified as `dist/vendor/axe.min.js`; its source is at the address given with it. The web app (`dist/web`) credits the libraries inside it in `dist/web/THIRD_PARTY_NOTICES.md`.
 
 ## Packages