Skip to content

feat(locator): show how many candidates each filter step left - #1416

Merged
okwasniewski merged 1 commit into
e2e-inc:mainfrom
DeryFerd:feat/locator-filter-step-counts
Nov 3, 2026
Merged

okwasniewski merged 1 commit into
e2e-inc:mainfrom
DeryFerd:feat/locator-filter-step-counts

Conversation

@DeryFerd

@DeryFerd DeryFerd commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

What and why

A filtered locator fails with one line that names the whole expression, and that is all it says. With a chain like the one below, LOCATOR_NOT_FOUND can mean any of three things: there are no list items yet, the text is spelled differently, or the button is named differently. Working out which step emptied the candidate set means reading the tree by hand, or rewriting the locator one step at a time and rerunning. LOCATOR_AMBIGUOUS only says how many nodes the whole chain matched, so the step that failed to narrow stays anonymous there too.

screen.getByRole('listitem')
  .filter({ hasText: 'Order 1042' })
  .filter({ has: screen.getByRole('button', 'Cancel order') });

For a filtered locator, the two failures now carry the count each step left, in the error message itself:

locator matched no nodes within getByRole("listitem").filter({ hasText: "Order 1042" }).filter({ has: getByRole("button", name: "Cancel order") }); candidates left after each filter step, counted after the failure:
  getByRole("listitem"): 6
  getByRole("listitem").filter({ hasText: "Order 1042" }): 1
  getByRole("listitem").filter({ hasText: "Order 1042" }).filter({ has: getByRole("button", name: "Cancel order") }): 0

The counts are read after the failure, one immediate resolve per prefix on a short fresh deadline, and the message says so, because a page that changes between the failing attempt and the diagnostic pass can disagree with it. The step labels reuse the existing expression rendering, so nothing new learns to describe a locator, and the text goes through the run's redaction at record time like any error message.

A few boundaries keep the message quiet when the lines would say nothing. A locator with no filter step, an index-only chain, and a union root keep today's message. If the diagnostic pass cannot read, the failure stands without the lines, since a diagnostic must not fail the failure. LOCATOR_AMBIGUOUS keeps its matches detail and gains the same lines.

No new API and no wire change. The counts live in the message text, report-v1 bounds the message through serializeError as before, and error codes, exit codes, and the public type surface are unchanged. CONTRIBUTING.md's stability policy does not cover the exact text of error messages.

What changed

  • packages/e2e/src/locator/expression.ts gains filterSpine(expression): the prefixes of a filtered chain, innermost first, following filter and index steps down their source. It returns undefined when no filter sits on the spine, which is what keeps plain queries and or() roots out of the message.
  • packages/e2e/src/locator/engine.ts builds the lines where the two failures are raised. The not-found path in resolveCounted and the ambiguity path both call candidateCounts, which resolves each prefix once through resolveNow on a fresh 500 ms deadline capped by the attempt budget, and returns undefined when any resolve throws, so the message stays as it is today. The old module-level assertSingle became the async singleOf method, so both sites share one ambiguity error.
  • packages/e2e/tests/unit/expression.test.ts covers the spine: the prefixes in order, an index step between filters, the no-filter cases, and a union root.
  • packages/e2e/tests/unit/locator-engine.test.ts adds a fake session that answers per expression, keyed by the rendered locator, so the tests pin exactly which expressions a failure path resolves and in which order. They cover the per-step lines on LOCATOR_NOT_FOUND and LOCATOR_AMBIGUOUS, a locator with no filter step left alone, the plain failure kept when the walk cannot read, and an index step between filters counted under its own label.
  • docs/reference/errors.mdx: the LOCATOR_NOT_FOUND and LOCATOR_AMBIGUOUS entries name the per-step listing.
  • A patch changeset for e2e, since the locator engine ships in the published package.

Issue

Fixes #1293

Verified

Ran it locally: yes

  • The tests were written first and run against the unmodified engine. The 9 new tests failed on exactly the missing feature, and after the change the two touched files pass in full.
before: 9 failed | 79 passed (88)
after:  88 passed (88)   tests/unit/expression.test.ts + tests/unit/locator-engine.test.ts
  • The unit suite of packages/e2e fails the same 22 files on this branch as on the commit the branch was cut from, checked by diffing the failing-file sets of two tests/unit runs:
branch:  Tests 61 failed | 2973 passed | 34 skipped (3068)
main:    the same 22 failing files, none added, none gone

Those failures are this machine's Windows baseline, CRLF checkouts, symlink privilege, and path separators, and they are identical on both sides. The locator-adjacent files all pass: expression, locator-engine, resolve-expression, locate, locator-action-options, locator-basics, locator-union, and locator-wait-for, 296 tests together.

  • tsc --noEmit in packages/e2e is clean, which includes the tests/types/sdk-types.ts assertions. oxlint reports 0 warnings and 0 errors on the four touched files.
  • node scripts/check-error-codes.ts reports 87 codes in source, all documented, with the two updated entries in the set. node scripts/check-peer-ranges.ts passes, and node scripts/check-changeset-bumps.ts reports the new changeset in the pending set with no unannounced 0.x minor or major.
  • Integration tests did not run on this machine: their fixtures import the runner from dist, which needs a full rebuild this box has not done. They run in spec.yml on every pull request.

Checklist

  • Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
  • Breaking change: title carries !, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md).
  • Docs updated in the same PR: the docs/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
  • Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
  • Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.

View guided diff

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/reference/errors.mdx">

<violation number="1" location="docs/reference/errors.mdx:109">
P2: The docs say a filtered locator's message always lists the per-step counts, but the counts are omitted when the post-failure diagnostic pass cannot read the page or when the message would exceed the 8192-character cap. Qualify both rows so readers know the counts can be absent.</violation>
</file>

<file name="packages/e2e/src/locator/expression.ts">

<violation number="1" location="packages/e2e/src/locator/expression.ts:136">
P2: A filter applied to `locator.or(...)` still produces candidate-count diagnostics because the walk accepts the union as its base. Preserve the existing union-root message by returning `undefined` when `current.kind === 'union'` as well as when no filter was found.</violation>
</file>

Heads up: you’ve reached your flex budget. Increase your flex budget or wait for usage to reset.

View guided diff | Re-trigger cubic

Comment thread docs/reference/errors.mdx Outdated
| `APP_NOT_OPEN` | An operation needed an open app: `app.open()` had not run, or the engine reported invalid state | test | 1 |
| `LOCATOR_NOT_FOUND` | No matching node within the deadline, or an agent action refers to a node that is no longer available | test | 1 |
| `LOCATOR_AMBIGUOUS` | More than one match for a single-node operation. Fails at once, with no polling. | test | 1 |
| `LOCATOR_NOT_FOUND` | No matching node within the deadline, or an agent action refers to a node that is no longer available. For a filtered locator the message lists how many candidates each filter step left, counted after the failure | test | 1 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: The docs say a filtered locator's message always lists the per-step counts, but the counts are omitted when the post-failure diagnostic pass cannot read the page or when the message would exceed the 8192-character cap. Qualify both rows so readers know the counts can be absent.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/reference/errors.mdx, line 109:

<comment>The docs say a filtered locator's message always lists the per-step counts, but the counts are omitted when the post-failure diagnostic pass cannot read the page or when the message would exceed the 8192-character cap. Qualify both rows so readers know the counts can be absent.</comment>

<file context>
@@ -106,8 +106,8 @@ category a blocked verdict reports as the obstacle.
 | `APP_NOT_OPEN` | An operation needed an open app: `app.open()` had not run, or the engine reported invalid state | test | 1 |
-| `LOCATOR_NOT_FOUND` | No matching node within the deadline, or an agent action refers to a node that is no longer available | test | 1 |
-| `LOCATOR_AMBIGUOUS` | More than one match for a single-node operation. Fails at once, with no polling. | test | 1 |
+| `LOCATOR_NOT_FOUND` | No matching node within the deadline, or an agent action refers to a node that is no longer available. For a filtered locator the message lists how many candidates each filter step left, counted after the failure | test | 1 |
+| `LOCATOR_AMBIGUOUS` | More than one match for a single-node operation. Fails at once, with no polling, and for a filtered locator lists how many candidates each filter step left, counted after the failure | test | 1 |
 | `ACTION_FAILED` | Actionability failure, operation timeout, or an action that may already have committed | test | 1 |
</file context>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in a11af50. Both rows now qualify the listing: the counts appear when the post-failure diagnostic pass can read the chain. The 8192-character report bound the message is serialized under drops the lines on an over-long chain, which keeps the failure valid without them.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8c5b55b (amended, supersedes a11af50): both rows now qualify the listing so readers know the counts can be absent when the diagnostic pass cannot read or the message exceeds the cap.

current = current.source;
}
if (!filtered) return undefined;
return [current, ...steps.toReversed()];

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: A filter applied to locator.or(...) still produces candidate-count diagnostics because the walk accepts the union as its base. Preserve the existing union-root message by returning undefined when current.kind === 'union' as well as when no filter was found.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/e2e/src/locator/expression.ts, line 136:

<comment>A filter applied to `locator.or(...)` still produces candidate-count diagnostics because the walk accepts the union as its base. Preserve the existing union-root message by returning `undefined` when `current.kind === 'union'` as well as when no filter was found.</comment>

<file context>
@@ -116,6 +116,26 @@ export function indexExpression(
+    current = current.source;
+  }
+  if (!filtered) return undefined;
+  return [current, ...steps.toReversed()];
+}
+
</file context>
Suggested change
return [current, ...steps.toReversed()];
if (!filtered || current.kind === 'union') return undefined;
return [current, ...steps.toReversed()];

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in a11af50. filterSpine now returns undefined when the chain bottoms out in a union as well, so a filter over or() keeps today's message, and a test covers a filter sitting on a union.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8c5b55b (amended): filterSpine now returns the union root as a single base entry, so a filter over or() counts the union once and never descends into its sides, with a unit test.

Comment thread packages/e2e/src/locator/engine.ts Resolved
@mintlify

mintlify Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit a11af50.

Approve preview

@DeryFerd
DeryFerd force-pushed the feat/locator-filter-step-counts branch from 2517f76 to a11af50 Compare October 27, 2026 20:42

@okwasniewski okwasniewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @DeryFerd. The diagnostic is useful and the tests do real work: with engine.ts reverted to main, 4 of the new engine tests fail. Against apps/testbed on web I got the output the PR describes:

locator matched no nodes within getByRole("listitem").filter({ hasText: "urgent" }).filter({ has: getByRole("button", name: "Close C") }); candidates left after each filter step, counted after the failure:
  getByRole("listitem"): 4
  getByRole("listitem").filter({ hasText: "urgent" }): 2
  ...: 0

On web the walk added about 75 ms to a 1 s not-found, and an ambiguous failure still came back in about 23 ms. pnpm check passes. The cubic points about waitedMs and the union root are handled.

Must fix

  1. packages/e2e/src/locator/engine.ts:267: the "fresh 500 ms deadline" does not limit the walk on mobile. packages/mobile/src/surface.ts locate() takes a full agent-device snapshot on every call, listening only to operation.signal and never reading operation.timeoutMs, and the session guard (engine/session.ts) adds no timeout. So a 3-step chain costs 3 extra full snapshots after every filtered failure, each running to completion. That matters most on LOCATOR_AMBIGUOUS, which the docs promise "fails at once". Please either:

    • bound the walk as a whole (one shared deadline for the whole walk, not a fresh one per prefix), or
    • state the mobile cost and add a unit test pinning the walk's total time against a session that ignores timeoutMs.

    Either way, please measure one failure on an iOS or Android sim and post the number.

  2. engine.ts:617 MESSAGE_MAX_LENGTH: remove it. internal/errors.ts:417 MAX_MESSAGE_BYTES already caps every message in serializeError. The new copy counts characters where the existing cap counts bytes, and is applied only on the ambiguous path.

Nits

  1. candidateCounts returns string[] | undefined and both callers write steps === undefined ? '' : stepLines(steps). Return the finished suffix ('' when there is nothing to show) and stepLines, the optional and both ternaries go away.
  2. expression.ts filterSpine: dropping the lines when a filter sits on a union (a.or(b).filter(...)) has no clear reason. The union is one base expression and can get one count like any other base; only the walk itself needs to stop there.
  3. screenshot-capture.ts:60 catches LOCATOR_NOT_FOUND from performUntil(scrollIntoView) and discards it, so on that path the walk is pure cost. Fine once (1) bounds the walk.
  4. The catch {} in candidateCounts also swallows cancellation. Harmless today, but if (this.signal.aborted) throw would make the intent explicit.

For the maintainer

#1293 is a feature request with no maintainer reply yet. Community policy asks for agreement on the issue before a feature PR.

This was an automated review.

@DeryFerd
DeryFerd force-pushed the feat/locator-filter-step-counts branch from a11af50 to 8c5b55b Compare October 28, 2026 05:49
@github-actions github-actions Bot added the size:L Up to 499 changed lines, not counting tests, fixtures, or the lockfile label Oct 28, 2026
@DeryFerd

Copy link
Copy Markdown
Contributor Author

Thanks for the careful review — all must-fix items landed in 8c5b55b7.

  1. The walk is now bounded by one shared deadline (STEP_COUNT_BUDGET_MS capped by the attempt budget), not a fresh deadline per prefix. On mobile, where session.locate() ignores operation.timeoutMs, a multi-step chain walk now costs at most one short budget instead of one per step. Each prefix read is an immediate snapshot pass with no polling, so mobile's per-prefix cost is unchanged from before for any single prefix, and the walk stops as soon as the shared deadline expires.
  2. MESSAGE_MAX_LENGTH is removed; serializeError in internal/errors.ts:417 caps every message at MAX_MESSAGE_BYTES (8192 bytes) on every path, so the ambiguous and not-found messages are bounded the same way every other error is.
  3. candidateCounts returns a finished suffix string ('' when there is nothing to show); both callers interpolate it directly, so the optional and both ternaries are gone.
  4. filterSpine now returns a union root as a single base entry like any other base, so a.or(b).filter(...) counts the union once, and the walk still never descends into the union's sides.
  5. The catch now re-throws abortError / cancelledError when the signal is aborted instead of swallowing cancellation.

On measuring a failure on an iOS or Android sim: I can't run simulators on this Windows machine, and this PR does not touch mobile engine code, so I can't post a real number from a device here. The bound is structural instead — one shared deadline caps the whole walk regardless of chain length, and each prefix read is a single immediate snapshot pass with no polling. Happy to post a number if there is a sim-backed run you would like me to compare against, or if CI's mobile deterministic suite exercises the path.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 3 files (changes from recent commits).

Heads up: you’ve reached your flex budget. Increase your flex budget or wait for usage to reset.

View guided diff | Re-trigger cubic

Comment thread packages/e2e/src/locator/engine.ts Resolved

@okwasniewski okwasniewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @DeryFerd. I re-checked at 8c5b55b7a. Status of the earlier asks:

  • (1) Walk bound: done. One shared deadline now covers the whole walk (engine.ts:266). I accept that you can't measure on a simulator. With the shared deadline the cost is now bounded by design.
  • (2) MESSAGE_MAX_LENGTH: removed.
  • (3) candidateCounts returns the finished suffix: done.
  • (4) A union at the base counts once: done.
  • (6) Cancellation is rethrown: done.

pnpm check fails, though, and the new bound has no test.

Must fix

  1. packages/e2e/src/locator/engine.ts:274: oxlint fails with Catch parameter 'cause' is caught but never used, so CI check and spec gate are red. Use } catch {.

  2. Add a test for the shared deadline. I mutated candidateCounts in three ways, and all 72 engine tests still passed each time:

    • a fresh new Deadline(STEP_COUNT_BUDGET_MS) per prefix
    • the if (deadline.expired()) break; line deleted
    • the abort rethrow deleted

    The current test only checks that each prefix's timeoutMs is <= 500, which a fresh per-prefix deadline also passes. Please add a session whose locate() ignores timeoutMs and takes, say, 300 ms (fake time is fine), and assert that a 3-step chain stops after 2 resolves. Also add a test where the signal is aborted mid-walk and the error is CANCELLED.

  3. A walk that stops early prints only part of the list. If the deadline breaks the loop, or a later prefix throws (the point cubic raised at :276), the message still says "candidates left after each filter step" but lists only the steps it read. On mobile this will be the common case: one full snapshot can use up the 500 ms budget, so usually only the base count shows. Either drop the lines when the walk did not reach the full chain, or say that it stopped (for example "walk stopped after 1 of 3 steps").

Nits

  1. engine.ts:64: the STEP_COUNT_BUDGET_MS JSDoc still says "fresh deadline one diagnostic prefix resolve ... gets". It is now the budget for the whole walk.
  2. The candidateCounts JSDoc says the walk "cannot cost more than one short budget even on mobile". A snapshot that starts just before the deadline still runs to completion, so the real bound is the budget plus one snapshot. Please say that.
  3. filterSpine could return [] instead of undefined when there is no filter step. Then candidateCounts needs only one emptiness check, and the return type loses its optional.

This was an automated review.

@DeryFerd
DeryFerd force-pushed the feat/locator-filter-step-counts branch from 8c5b55b to 38c1dad Compare October 31, 2026 04:59
@DeryFerd

Copy link
Copy Markdown
Contributor Author

All three must-fixes and all three nits are in the new head 38c1dad49e:

Must fix

  1. The unused cause binding is gone: } catch { at the walk's catch. oxlint is clean on all four files, so check and spec gate are back to green.
  2. Shared-deadline tests, written the way you asked:
    • bounds the whole walk by one shared deadline when locate ignores the operation timeout — a session whose locate() ignores operation.timeoutMs and takes 300 ms per call, on a 3-step chain: the failing resolve polls once, the walk resolves base then texted, and the third prefix is refused. Asserts resolved === [chain, base, texted] and the message contains walk stopped after 2 of 3 steps.
    • surfaces cancellation when the signal aborts mid-walk — the controller aborts during the walk's second prefix; the rejection is CANCELLED.
    • Plus drops the counts when a later prefix cannot be read for the cubic thread at :276: base read, next prefix throws, message has no counted after the failure at all.
      I then re-ran your mutations against the new suite: deleting if (deadline.expired()) break; fails 1 test (1 failed | 74 passed), and deleting the abort rethrow fails 1 test (1 failed | 74 passed). The third mutation, a fresh new Deadline(STEP_COUNT_BUDGET_MS) per prefix, never reports expired at the check so all three prefixes resolve — the same resolved === [chain, base, texted] assertion fails the same way, since three walk entries are one too many.
  3. A walk that stops early no longer claims the full list. On a deadline break the header reads candidates left after each filter step, walk stopped after 1 of 3 steps, counted after the failure (your option b, so mobile, where one snapshot usually spends the budget, still shows the base count). On a later prefix read failure the lines are dropped entirely and the plain failure stands (cubic's ask).

Nits

  1. STEP_COUNT_BUDGET_MS JSDoc now describes the budget for the whole walk.
  2. The candidateCounts JSDoc now says the bound is the budget plus one snapshot — a snapshot that starts just before the deadline still runs to completion.
  3. filterSpine returns [] instead of undefined when there is no filter step, so candidateCounts has one emptiness check and neither return type is optional. The four expression.test.ts assertions moved from toBeUndefined() to toEqual([]).

Verified locally: locator-engine.test.ts 75/75, expression.test.ts 17/17 (92 together), tsc --noEmit exit 0, oxlint 0 warnings 0 errors on the four changed files.

@DeryFerd
DeryFerd requested a review from okwasniewski October 31, 2026 06:42
@okwasniewski
okwasniewski dismissed stale reviews from themself October 31, 2026 10:10

Asks addressed, see re-review comment.

@okwasniewski

Copy link
Copy Markdown
Member

Re-review at 38c1dad49: all must-fix asks done, ready for human review.

  • Catch param removed, oxlint clean.
  • Each of the three mutations from last time (fresh deadline per prefix, no expired() break, no abort rethrow) now fails a test. Two more mutations are caught too: dropping the "stopped" suffix, and keeping a partial list when a later read throws.
  • A walk that stops early now says walk stopped after 2 of 3 steps. A read that throws drops the counts. JSDoc nits and filterSpine returning [] are done. CI green.

Optional nits:

  • engine.ts:68: the JSDoc has an em dash ("completion — the real bound"). Please use a plain hyphen or a full stop.
  • docs/reference/errors.mdx:110: LOCATOR_AMBIGUOUS still says "Fails at once". It now runs a diagnostic pass of up to ~500 ms (plus one snapshot on mobile) first.
  • Changeset: the last sentence, "The message says the counts were read then.", is vague. Drop it or say "counted after the failure".
  • A weaker mutation survives: a shared deadline for the break check, but each resolve gets a fresh 500 ms timeout. Asserting the second diagnostic timeoutMs is <= 200 would catch it.
  • The shared-deadline and abort tests copy the session setup. A per-call hook option on makeCountingEngine would remove the copy.

This was an automated review.

@okwasniewski

Copy link
Copy Markdown
Member

[claude-opus-5-5] automated review on behalf of @okwasniewski

@DeryFerd heads up: this now conflicts with main in packages/e2e/src/locator/engine.ts after #1464 (operation budget for mobile reads) landed. Could you merge main and resolve it? The review verdict stands, so the label stays.

This was an automated review.

A filtered locator's LOCATOR_NOT_FOUND and LOCATOR_AMBIGUOUS now list how
many candidates each filter step left, read in one immediate pass after
the failure on a fresh short deadline, and the message says the counts
were read then. A chain whose diagnostic walk cannot read keeps the
plain failure. The prefixes come from filterSpine in the expression
module.

Fixes e2e-inc#1293
@DeryFerd
DeryFerd force-pushed the feat/locator-filter-step-counts branch from 38c1dad to c57d113 Compare November 2, 2026 06:51
@DeryFerd

DeryFerd commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto latest main (720947dc) — the engine-protocol refactor moved deadline: Deadline to reads: ReadWindow, so resolveOnce, resolveNow, and readOne now take a ReadWindow in both the diagnostic walk and the ambiguous-read path. The walk's shared budget wraps its Deadline in a ReadWindow per prefix; candidateCounts and the walk stopped after N of M steps message are unchanged.

Verified after the rebase: tsc --noEmit exit 0, locator-engine.test.ts + expression.test.ts 102/102 pass, oxlint clean on all four touched files. Head is c57d1133, single commit; GitHub should turn mergeability green once it rechecks.

@okwasniewski

Copy link
Copy Markdown
Member

[claude-opus-5-5] automated review on behalf of @okwasniewski

Re-reviewed the rebase (c57d113 on main 720947d). The ReadWindow wiring is correct. Each prefix gets new ReadWindow(deadline) with the shared deadline as its cap, which matches main's own resolveNow default. The expired() break still bounds the whole walk, and the normal resolve path is unchanged. Unit tests pass (102/102 touched, 3260 full e2e suite), tsc and oxlint are clean, CI is green. Relabeling Ready for Human Review.

Small cleanups left over from the rebase (optional, not blocking):

  • engine.ts:262 and engine.ts:407 start at column 0 after the conflict resolution. Please re-indent them.
  • engine.ts:64-69, the candidateCounts JSDoc at engine.ts:277 and the test name at locator-engine.test.ts:830 still say mobile session.locate() ignores the operation timeout. fix(mobile): bound reads by operation budget with last-read grace #1464 changed that: mobile now passes operation.timeoutMs into inputBudget. Please reword to "an engine whose locate ignores the timeout". The em dash at engine.ts:68 is still there too.
  • Tests only assert that each diagnostic read gets timeoutMs <= 500, so a fresh 500ms window per prefix (about 2x the budget on web) still passes. One assert that the per-prefix timeoutMs goes down would catch that.

@okwasniewski okwasniewski left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks!

@okwasniewski
okwasniewski merged commit 79e2e13 into e2e-inc:main Nov 3, 2026
25 checks passed
@github-actions github-actions Bot mentioned this pull request Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Ready for Human Review size:L Up to 499 changed lines, not counting tests, fixtures, or the lockfile

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Locator failures: show how many candidates each filter step left

2 participants