browserzap 0.5.5 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.6.0 (2026-10-30)
+
+A replay now waits for what the step is actually blocked on, and retries that step instead of going back.
+
+- **The resolver engine.** When a step fails, or a click lands but changes nothing, BrowserZap works out what it is
+  waiting for — a slow request, a spinner, a target that is not usable yet, a target that has not appeared — waits for
+  exactly that, then retries the **same step**. Up to twice per step and 45 seconds of waiting, inside the run's own
+  limit. A failed step is never replayed from step 1 unless that is where it failed.
+- **Clicks are still never repeated blindly.** A consequential click (submit, pay, delete, or one that needed your
+  approval) is never retried. A click is retried only when it provably did not happen, or when it was reversible,
+  changed nothing at all **and started no request**. A click that started a request is never clicked again.
+- **New wait conditions:** an element is usable (visible, enabled, uncovered and not moving), a spinner or "Loading…"
+  is gone, the page's network is quiet, or a specific request has answered. A 4xx/5xx answers at once instead of
+  waiting. A dashboard that refreshes itself every few seconds no longer looks busy forever, and analytics traffic is
+  ignored.
+- **Learns each step.** After three runs a step's wait budget comes from what it usually needs; a blocker it hit in
+  at least 60 % of its **last 10 runs** is waited for *before* acting, and one that stops happening stops being waited
+  for, so a site that was fixed is not slowed down; a wait that never helps is skipped there. You can override with
+  `patience` (`fast`/`normal`/`patient`) or `maxWaitMs` on a step. The saved workflow is never changed automatically;
+  hints appear in the run result.
+- **Remembers what a step produced.** The recorder saves the dialog that appeared, the request the step started
+  (method plus a path with ids replaced by `*`) and how long the page took to settle. On replay a step is done when
+  that is there, waiting at most the settle the recording measured (or your `maxWaitMs`) — a bounded check that ends
+  as soon as the evidence appears, never a pause. Never a value, a query string or page text.
+- **Re-run failed resumes at the step that failed** when the page has not moved since the last verified step;
+  otherwise at the nearest earlier page load. It first checks, with a short bounded wait, that the failed step's
+  target is really on the page now — a page that moved goes back to the page load, and a workflow with no page load
+  of its own fails that set with `RESUME_UNVERIFIED` rather than acting on a page nobody checked. The batch summary
+  says how many sets resumed.
+- No new tools and no new permission: still 34 tools, and the bridge stays loopback-only and authenticated.
+
 ## 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).

package/bridge-server/background-runs.js

@@ -13,6 +13,8 @@
 'use strict';
 
 const crypto = require('crypto');
+const { LIMITS } = require('./limits');
+const { resolveParams, substitute } = require('./workflows');
 
 /** Finished runs kept for workflow_status and rerunFailed. */
 const MAX_KEPT = 10;
@@ -25,6 +27,85 @@ class RunError extends Error {
   }
 }
 
+/** Steps that only read the page: a resume may start at one without a probe. */
+const RESUME_WITHOUT_PROBE = new Set(['wait_for_state', 'page_inspect', 'screenshot_capture', 'page_console', 'page_network']);
+
+/** The nearest `browser_navigate` at or before `index`; -1 when there is none. */
+function navigationAnchor(wf, index) {
+  let found = -1;
+  for (let i = 0; i <= index && Array.isArray(wf?.steps) && i < wf.steps.length; i++) {
+    if (wf.steps[i].tool === 'browser_navigate') found = i;
+  }
+  return found;
+}
+
+/**
+ * Where a set that did not complete may resume (0.6.0). It stays at the failed
+ * step when the page has not navigated since the last verified step; otherwise
+ * it starts at the nearest navigation anchor at or before the failure. Never
+ * step 1 unless that is the anchor.
+ */
+function resumeAtFor(wf, run) {
+  if (!wf || !run || !Number.isInteger(run.stoppedAt)) return 0;
+  const checkpoint = Number.isInteger(run.checkpoint) ? run.checkpoint : -1;
+  const lastNavigation = navigationAnchor(wf, run.stoppedAt);
+  if (checkpoint >= 0 && checkpoint >= lastNavigation) return run.stoppedAt;
+  if (lastNavigation >= 0) return lastNavigation;
+  return 0;
+}
+
+/**
+ * A resume: where to start (`at`), the navigation anchor to fall back to when
+ * the page has moved (`anchor`, -1 when the workflow has none) and the failed
+ * step's own target (`target`), which is what a resume at that step must find
+ * actionable before it runs (A6-09). Values are not substituted here: the
+ * caller resolves them per parameter set.
+ */
+function resumePlan(wf, run) {
+  const at = resumeAtFor(wf, run);
+  const anchor = Number.isInteger(run?.stoppedAt) ? navigationAnchor(wf, run.stoppedAt) : -1;
+  const target = wf?.steps?.[at]?.args?.target;
+  return { at, anchor, target: at > 0 && target && typeof target === 'object' ? target : null };
+}
+
+/**
+ * Prove the page is still where a resume at the failed step expects it.
+ *
+ * A real `wait_for_state { actionable: <the step's target> }` through the
+ * normal tool path, bounded by LIMITS.RESUME_PROBE_MS (a poll that ends as
+ * soon as the target is ready, never a pause). When it does not hold, the set
+ * starts at its navigation anchor instead. With no anchor there is nothing
+ * safe to start from, so it throws RESUME_UNVERIFIED: a set is never resumed
+ * with a real click on a page nobody checked.
+ *
+ * Returns the step to start at.
+ */
+async function probeResume({ wf, plan, params = {}, execute, allowedOrigins = null, timeoutMs = LIMITS.RESUME_PROBE_MS }) {
+  const at = plan?.at ?? 0;
+  if (!(at > 0) || !execute) return at;
+  const tool = wf?.steps?.[at]?.tool;
+  let reason;
+  if (plan?.target) {
+    const target = substitute(plan.target, resolveParams(wf, params));
+    const env = await execute('wait_for_state', { actionable: target, timeoutMs }, { allowedOrigins, index: at });
+    if (env.ok) return at;
+    reason = env.error?.code ?? 'the probe did not hold';
+  } else if (tool === 'browser_navigate' || RESUME_WITHOUT_PROBE.has(tool)) {
+    return at;
+  } else {
+    // A key press with no target (Enter, say) acts on whatever has focus:
+    // there is nothing to probe, so it is never the first thing a resume does.
+    reason = 'the step has no target to check';
+  }
+  if (plan.anchor >= 0) return plan.anchor;
+  throw new RunError(
+    'RESUME_UNVERIFIED',
+    `The page is not where step ${at + 1} of "${wf.name}" expects it (${reason}), ` +
+    'and the workflow has no earlier page load to go back to, so nothing was run.',
+    'Open the page the workflow starts on, or save it with a browser_navigate first, then run it from the start.',
+  );
+}
+
 /**
  * @param {object} deps
  * @param {(job: object) => Promise<object>} deps.execute   runs the batch for a job; resolves with the bulk result
@@ -43,7 +124,7 @@ function createRunRegistry({ execute, onFinish = () => {}, now = Date.now }) {
    * Start a batch. `paramSets` and `labels` are kept in memory only.
    * Throws RunError(TAB_BUSY) while another run is going.
    */
-  function start({ wf, paramSets, labels = [], onError = 'continue' }) {
+  function start({ wf, paramSets, labels = [], onError = 'continue', resume = [] }) {
     const running = active();
     if (running) {
       throw new RunError('TAB_BUSY', `"${running.workflow}" is still running in the background (${running.runId}).`,
@@ -57,6 +138,7 @@ function createRunRegistry({ execute, onFinish = () => {}, now = Date.now }) {
       total: paramSets.length,
       paramSets,
       labels,
+      resume,
       wf,
       onError,
       state: 'running',
@@ -130,15 +212,19 @@ function createRunRegistry({ execute, onFinish = () => {}, now = Date.now }) {
       throw new RunError('TAB_BUSY', `"${job.workflow}" (${runId}) is still running.`, 'Wait for it to finish, or cancel it.');
     }
     const runs = job.result?.evidence?.runs ?? [];
-    const finished = new Map(runs.map((r) => [r.index, r.ok]));
+    const finished = new Map(runs.map((r) => [r.index, r]));
     const indexes = [];
-    for (let i = 0; i < job.total; i++) if (finished.get(i) !== true) indexes.push(i);
+    for (let i = 0; i < job.total; i++) if (finished.get(i)?.ok !== true) indexes.push(i);
     return {
       job,
       indexes,
       paramSets: indexes.map((i) => job.paramSets[i]),
       // A set keeps its name from the first run ("#3" stays "#3").
       labels: indexes.map((i) => job.labels[i] ?? `#${i + 1}`),
+      // Where each set may resume (0.6.0): the failed step, or the nearest
+      // navigation anchor when the page has moved since the last verified step.
+      // A resume at the failed step is probed first (probeResume, A6-09).
+      resume: indexes.map((i) => resumePlan(job.wf, finished.get(i))),
     };
   }
 
@@ -194,6 +280,7 @@ function compactBatch(result) {
     needAttention: ev.needAttention ?? attention.length,
     notRun: ev.notRun ?? 0,
     skippedSteps: (ev.runs ?? []).reduce((n, r) => n + (r.skipped?.length ?? 0), 0),
+    resolvedSteps: (ev.runs ?? []).reduce((n, r) => n + (r.resolvedSteps ?? 0), 0),
     recovered: (ev.runs ?? []).filter((r) => r.recoveries?.length).length,
     elapsedMs: ev.elapsedMs ?? null,
     report: ev.report ?? null,
@@ -201,4 +288,4 @@ function compactBatch(result) {
   };
 }
 
-module.exports = { createRunRegistry, compactBatch, RunError };
+module.exports = { createRunRegistry, compactBatch, resumeAtFor, resumePlan, navigationAnchor, probeResume, RunError };

package/bridge-server/cli-run.js

@@ -75,6 +75,8 @@ function describe(env) {
       `${f?.likelyCause ? `, ${f.likelyCause}` : ''}${f?.screenshot ? `\n    screenshot: ${f.screenshot}` : ''}`);
   }
   if (env.evidence?.report) lines.push(`Report: ${env.evidence.report} (browserzap --runs)`);
+  const resolved = runs.reduce((n, r) => n + (r.resolvedSteps ?? 0), 0);
+  if (resolved) lines.push(`  ${resolved} step(s) resolved in place (a wait, then the same step again).`);
   if (!runs.length && !env.ok && env.nextAction) lines.push(env.nextAction);
   return lines.join('\n');
 }

package/bridge-server/limits.js

@@ -26,6 +26,13 @@ const LIMITS = Object.freeze({
   SETTLE_QUIET_MS: 500,
   /** How long that settle waits for a busy page (it costs nothing on a quiet one). */
   SETTLE_MAX_MS: 5000,
+  /** A wait whose condition makes no progress for this long ends early: a page that is stuck does not get better. */
+  STALL_MS: 3000,
+  /**
+   * Before "Re-run failed" resumes at the step that failed, that step's target
+   * must be actionable within this. A bounded probe, not a pause (A6-09).
+   */
+  RESUME_PROBE_MS: 3000,
   /** Longest per-step pacing a person may set on a saved workflow step. */
   MAX_STEP_PACING_MS: 30000,
   /** A tab with no agent action for this long is detached, so Chrome's "debugging" bar goes away (D-35). */
@@ -60,6 +67,16 @@ const STATUS_DEADLINE_MS = 4_000;
  */
 const RUN_DEADLINE_MS = 600_000;
 
+/**
+ * Resolver engine bounds (`bridge-server/resolvers.js`, 0.6.0, D-37).
+ * A step may spend at most MAX_STEP_RESOLVE_MS resolving blockers in place,
+ * across at most MAX_RESOLVER_ATTEMPTS attempts, and a reversible click with
+ * no effect at all is repeated at most MAX_INPLACE_CLICK_RETRIES times (AU-08).
+ */
+const MAX_STEP_RESOLVE_MS = 45_000;
+const MAX_RESOLVER_ATTEMPTS = 2;
+const MAX_INPLACE_CLICK_RETRIES = 2;
+
 /**
  * How long the caller waits for the extension to answer one call: the sum of
  * every wait the call can do, plus a margin, and never less than
@@ -97,4 +114,13 @@ function callDeadlineMs(tool, args = {}) {
   return Math.max(CALL_DEADLINE_MS, waits + DEADLINE_MARGIN_MS);
 }
 
-module.exports = { LIMITS, CALL_DEADLINE_MS, STATUS_DEADLINE_MS, RUN_DEADLINE_MS, callDeadlineMs };
+module.exports = {
+  LIMITS,
+  CALL_DEADLINE_MS,
+  STATUS_DEADLINE_MS,
+  RUN_DEADLINE_MS,
+  MAX_STEP_RESOLVE_MS,
+  MAX_RESOLVER_ATTEMPTS,
+  MAX_INPLACE_CLICK_RETRIES,
+  callDeadlineMs,
+};

package/bridge-server/mcp-server.js

@@ -41,7 +41,7 @@ const workflows = require('./workflows');
 const screenshots = require('./screenshots');
 const feedback = require('./feedback');
 const downloads = require('./downloads');
-const { createRunRegistry, compactBatch, RunError } = require('./background-runs');
+const { createRunRegistry, compactBatch, probeResume, RunError } = require('./background-runs');
 
 const { WorkflowError, Recorder } = workflows;
 
@@ -929,7 +929,7 @@ async function runTool(requestId, traceId, args, progress) {
  * redaction as screenshot_capture).
  */
 async function runBatchOrOnce({
-  wf, params, paramSets, labels, onError, startAt = 0, approvalId, signal,
+  wf, params, paramSets, labels, onError, startAt = 0, approvalId, signal, resume = [],
   onCall = () => {}, onStep = () => {}, onSet = () => {}, onSetDone = () => {},
 }) {
   const execute = async (tool, stepArgs, { allowedOrigins }) => {
@@ -946,14 +946,14 @@ async function runBatchOrOnce({
     const { env } = await executeTool('screenshot_capture', {}, { allowedOrigins: ALLOWED_ORIGINS });
     return env.ok ? env.screenshotPath ?? null : null;
   };
-  const runOnce = async (setParams, first) => {
+  const runOnce = async (setParams, first, setStartAt = 0) => {
     const startedAt = new Date().toISOString();
     const history = workflows.runHistory(wf);
     const result = await workflows.run(wf, {
       history,
       onStep,
       params: setParams,
-      startAt: first ? startAt : 0,
+      startAt: setStartAt || (first ? startAt : 0),
       approvalId: first ? approvalId : undefined,
       execute,
       capture,
@@ -964,7 +964,7 @@ async function runBatchOrOnce({
     service.recordRun({ wf, result, params: setParams, startedAt });
     return result;
   };
-  if (paramSets === undefined) return runOnce(params, true);
+  if (paramSets === undefined) return runOnce(params, true, startAt);
   let first = true;
   return pro.runBulk({
     wf,
@@ -972,9 +972,22 @@ async function runBatchOrOnce({
     labels,
     onError,
     signal,
+    resume,
+    // A resume at the failed step is probed first, as a real wait_for_state
+    // through executeTool; the page has moved, so the set starts at the
+    // navigation anchor instead (A6-09). With no anchor it fails without acting.
+    resumeStart: ({ plan, params: setParams }) => probeResume({
+      wf, plan, params: setParams, execute, allowedOrigins: ALLOWED_ORIGINS,
+    }),
     onSet,
     onSetDone,
-    runOnce: (setParams) => { const r = runOnce(setParams, first); first = false; return r; },
+    // A re-run of the sets that failed resumes at the step that failed where
+    // the page allows it (0.6.0), instead of starting every set at step 1.
+    runOnce: (setParams, setStartAt) => {
+      const r = runOnce(setParams, first, setStartAt ?? 0);
+      first = false;
+      return r;
+    },
   });
 }
 
@@ -985,6 +998,7 @@ const backgroundRuns = createRunRegistry({
     paramSets: job.paramSets,
     labels: job.labels,
     onError: job.onError,
+    resume: job.resume,
     signal: job.controller.signal,
     onCall: (c) => { job.call = c; },
     onStep: ({ index }) => backgroundRuns.progress(job, { stepIndex: index }),
@@ -1040,14 +1054,16 @@ function statusOfRuns(traceId, args) {
 }
 
 function rerunFailedTool(traceId, args) {
-  const { job: previous, paramSets, labels } = backgroundRuns.failedSets(args.rerunFailed);
+  const { job: previous, paramSets, labels, resume } = backgroundRuns.failedSets(args.rerunFailed);
   if (previous.workflow !== args.name) {
     return errorEnvelope(traceId, 'INVALID_ARGUMENT', `${previous.runId} ran "${previous.workflow}", not "${args.name}".`);
   }
   if (paramSets.length === 0) return okEnvelope(traceId, `Every set of ${previous.runId} completed; nothing to run again.`);
-  const job = backgroundRuns.start({ wf: workflows.load(previous.workflow), paramSets, labels, onError: 'continue' });
+  const job = backgroundRuns.start({ wf: workflows.load(previous.workflow), paramSets, labels, onError: 'continue', resume });
+  const resumed = resume.filter((plan) => plan?.at > 0).length;
   return okEnvelope(traceId,
-    `Running the ${paramSets.length} set(s) of ${previous.runId} that did not complete, from the start, in the background (${job.runId}).`,
+    `Running the ${paramSets.length} set(s) of ${previous.runId} that did not complete` +
+    `${resumed ? `, ${resumed} from the step that failed` : ''}, in the background (${job.runId}).`,
     { runId: job.runId }, { paramSets: paramSets.length, rerunOf: previous.runId });
 }
 

package/bridge-server/panel.js

@@ -38,6 +38,7 @@ const { CALL_DEADLINE_MS } = require('./limits');
 const { createWorkflowService, checkStep, stepLogEntry } = require('./workflow-service');
 const { createSessionLog, describeResult } = require('./session-log');
 const { parseParamSets } = require('./param-sets');
+const { resumePlan, probeResume } = require('./background-runs');
 const screenshots = require('./screenshots');
 const feedback = require('./feedback');
 
@@ -218,7 +219,13 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
           if (ok) current.batch.done += 1;
           else current.batch.failed += 1;
         },
-        runOnce: (setParams) => runOnce(setParams, 0),
+        // "Re-run failed" probes the failed step's target before resuming there,
+        // as a real wait_for_state; a page that has moved starts at the
+        // navigation anchor, and with no anchor the set fails without acting (A6-09).
+        resumeStart: ({ plan, params: setParams }) => probeResume({
+          wf, plan, params: setParams, execute, allowedOrigins: wf.origins,
+        }),
+        runOnce: (setParams, setStartAt) => runOnce(setParams, setStartAt ?? 0),
       });
       const runs = result.evidence?.runs ?? [];
       lastBatch = {
@@ -226,6 +233,9 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
         paramSets: batch.paramSets,
         labels: batch.labels,
         unfinished: batch.paramSets.map((_, i) => i).filter((i) => !runs.some((r) => r.index === i && r.ok)),
+        // Where each set may resume when the person presses "Re-run failed" (0.6.0):
+        // the plan a probe proves before it is used (A6-09).
+        resumeByIndex: Object.fromEntries(runs.filter((r) => !r.ok).map((r) => [r.index, resumePlan(wf, r)])),
       };
       // What the person needs to find each problem: step, cause, screenshot. Never values.
       const attention = runs.filter((r) => !r.ok).map((r) => ({
@@ -241,7 +251,7 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
         status: result.ok ? 'completed' : controller.signal.aborted ? 'cancelled' : 'failed',
         summary: result.summary,
         code: result.error?.code ?? null,
-        nextAction: lastBatch.unfinished.length ? `${lastBatch.unfinished.length} set(s) did not complete. "Re-run failed" runs just those, from the start.` : null,
+        nextAction: lastBatch.unfinished.length ? `${lastBatch.unfinished.length} set(s) did not complete. "Re-run failed" runs just those, from the step that failed where the page allows it.` : null,
         canContinueFrom: null,
         batch: { ...current.batch, attention, report: result.evidence?.report ?? null, canRerun: lastBatch.unfinished.length > 0 },
         finishedAt: new Date().toISOString(),
@@ -396,7 +406,8 @@ function createPanelRunner({ deliver, toExtension, log = () => {} }) {
           const wf = workflows.load(lastBatch.workflow);
           const paramSets = lastBatch.unfinished.map((i) => lastBatch.paramSets[i]);
           const labels = lastBatch.unfinished.map((i) => lastBatch.labels[i] ?? `#${i + 1}`);
-          runWorkflow(wf, {}, 0, profile, { paramSets, labels }).catch((err) => log('panel_run_error', { message: err.message }));
+          const resume = lastBatch.unfinished.map((i) => lastBatch.resumeByIndex?.[i] ?? null);
+          runWorkflow(wf, {}, 0, profile, { paramSets, labels, resume }).catch((err) => log('panel_run_error', { message: err.message }));
           return { ok: true, data: { runId: current.runId, sets: paramSets.length } };
         }
         case 'run':

package/bridge-server/resolvers.js

@@ -0,0 +1,287 @@
+'use strict';
+
+const { LIMITS } = require('./limits');
+
+/**
+ * Resolver engine — the registry (0.6.0, D-37).
+ *
+ * Pure: no I/O, no page access, no timers, no clocks. Given a failed (or
+ * ineffective) workflow step and the envelope the extension returned, say what
+ * the step is blocked on and what would clear it. The runner then waits for
+ * that condition as an ordinary `wait_for_state` call and retries the same
+ * step — so every wait and every retry still goes through the normal tool path
+ * and extension policy.
+ *
+ * Design: docs/NEXT_RELEASE_SCOPE_0.6.md (§3 of the 0.5 doc);
+ * the wait kinds it relies on: docs/ADR/ADR-007-waiting-and-timeouts.md.
+ *
+ * Adding a resolver is one entry here plus a fixture that fails without it.
+ * The validation rules at the bottom are checked by tests/resolvers.test.mjs.
+ */
+
+/** A change here that alters behaviour resets learned demotions (step profile). */
+const REGISTRY_VERSION = 1;
+
+/**
+ * Codes that are never auto-resolved: a person, a policy, or a unique target is
+ * needed. A resolver that claimed one of these would be guessing.
+ */
+const FORBIDDEN_CODES = Object.freeze([
+  'USER_CONFIRMATION_REQUIRED',
+  'USER_ACTION_REQUIRED',
+  'POLICY_BLOCKED',
+  'TARGET_AMBIGUOUS',
+]);
+
+/** Risks that must never be repeated in place (audit AU-08). */
+const CONSEQUENTIAL_RISKS = new Set(['external_side_effect', 'destructive', 'financial']);
+
+/** Tools a resolver may retry in place. A read-only tool is never a workflow step. */
+const RETRYABLE_TOOLS = new Set([
+  'browser_navigate', 'element_click', 'field_fill', 'select_option', 'wait_for_state', 'browser_press_key',
+]);
+
+/**
+ * Failures that prove the action never ran: the target was missing, unusable or
+ * a stale ref. Only these may be retried for a click or a key press; anything
+ * else may already have submitted something (AU-08).
+ */
+const ACTION_DID_NOT_RUN_CODES = new Set(['TARGET_NOT_FOUND', 'TARGET_NOT_INTERACTABLE', 'STALE_SNAPSHOT']);
+
+/**
+ * Failures a resolver may act on: the page has not got there yet. Anything else
+ * — a bad argument, a Pro gate, a missing workflow, a cancelled run — is
+ * deterministic, and waiting for the page cannot change it (ADR-007: only
+ * failures that can clear up are waited on). A successful call that changed
+ * nothing has no code at all and is classified by its evidence.
+ */
+const TRANSIENT_CODES = Object.freeze([
+  'TIMEOUT', 'TARGET_NOT_FOUND', 'TARGET_NOT_INTERACTABLE', 'STALE_SNAPSHOT',
+  'NAVIGATION_FAILED', 'BRIDGE_DISCONNECTED', 'POSTCONDITION_NOT_MET', 'SITE_ERROR',
+]);
+
+/** The wait kinds the extension understands (registered in doWaitFor). */
+const WAIT_KINDS = Object.freeze(['urlContains', 'text', 'target', 'targetGone', 'actionable', 'indicatorGone', 'networkQuiet', 'requestDone']);
+
+/**
+ * Ordered: the more specific answer wins. The condition hierarchy follows the
+ * design — the step's own expectation, then actionability, then a specific
+ * request, then a UI signal, then global network quiet (as a fallback only).
+ */
+const RESOLVERS = Object.freeze([
+  {
+    id: 'expectation_unmet',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    // About what the step produced, so it can never be a pre-wait: an
+    // expectation cannot be there before the step that produces it runs.
+    promotable: false,
+    budgetMs: { floor: 500, default: 5000, ceiling: 30000 },
+    matches: ({ evidence, step }) => Boolean(step.expect) && evidence.expectationMet === false,
+    wait: ({ step }) => waitForRecordedExpectation(step.expect),
+  },
+  {
+    id: 'click_no_effect',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 3000, ceiling: 10000 },
+    // The narrow AU-08 exception: reversible, nothing visible changed, and no
+    // request went out. A click that started a request is waited on instead.
+    matches: ({ evidence, step }) => step.tool === 'element_click'
+      && evidence.noObservableChange === true
+      && evidence.risk === 'reversible'
+      && Number(evidence.requestsStarted ?? 0) === 0,
+    wait: ({ step }) => ({ actionable: step.args.target, networkQuiet: true }),
+  },
+  {
+    id: 'target_not_ready',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 5000, ceiling: 20000 },
+    matches: ({ code }) => code === 'TARGET_NOT_INTERACTABLE',
+    wait: ({ step }) => ({ actionable: step.args.target }),
+  },
+  {
+    id: 'target_late',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 8000, ceiling: 30000 },
+    matches: ({ code, evidence }) => code === 'TARGET_NOT_FOUND'
+      && (Number(evidence.pendingRequests ?? 0) > 0 || Boolean(evidence.busyIndicator)),
+    wait: ({ step }) => ({ target: step.args.target }),
+  },
+  {
+    id: 'api_pending',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 1000, default: 15000, ceiling: 45000 },
+    matches: ({ evidence }) => evidence.likelyCause === 'server_slow'
+      || Number(evidence.pendingRequests ?? 0) > 0
+      || Boolean(evidence.slowestRequest),
+    // The step's own recorded request is the strongest signal; global quiet is
+    // only the capped fallback.
+    wait: ({ step }) => (step.expect && step.expect.request
+      ? { requestDone: step.expect.request }
+      : { networkQuiet: true }),
+  },
+  {
+    id: 'still_rendering',
+    safety: 'retry_reversible',
+    then: 'retry_step',
+    budgetMs: { floor: 500, default: 10000, ceiling: 30000 },
+    matches: ({ evidence }) => Boolean(evidence.busyIndicator) || evidence.likelyCause === 'still_rendering',
+    wait: () => ({ indicatorGone: true }),
+  },
+  {
+    id: 'site_error',
+    safety: 'group',
+    then: 'retry_group',
+    budgetMs: { floor: 0, default: 0, ceiling: 0 },
+    matches: ({ code, evidence }) => code === 'SITE_ERROR' || evidence.likelyCause === 'site_error',
+    wait: () => null,
+  },
+  {
+    id: 'context_lost',
+    safety: 'group',
+    then: 'retry_group',
+    budgetMs: { floor: 0, default: 0, ceiling: 0 },
+    matches: ({ evidence }) => evidence.contextLost === true,
+    wait: () => null,
+  },
+]);
+
+/** The wait args for a recorded expectation (`appears` and `request` can combine). */
+function waitForRecordedExpectation(expect) {
+  if (!expect) return null;
+  const args = {};
+  if (expect.appears) args.target = expect.appears;
+  if (expect.request && expect.request.pathContains) args.requestDone = expect.request;
+  return Object.keys(args).length > 0 ? args : null;
+}
+
+/**
+ * How long the recorded-expectation wait may look for its evidence: the
+ * person's `maxWaitMs` when set, otherwise the settle the recorder measured
+ * (the learned pace for that step), otherwise the default expectation timeout.
+ * It is the budget of a bounded poll that ends the moment the evidence is
+ * there — never a pause (A6-10). Clamped to the shared limits.
+ */
+function expectBudgetMs(expect, maxWaitMs = null) {
+  const asked = Number.isFinite(maxWaitMs) && maxWaitMs > 0 ? maxWaitMs : null;
+  const recorded = Number.isFinite(expect?.settleMs) && expect.settleMs > 0 ? expect.settleMs : null;
+  const ms = asked ?? recorded ?? LIMITS.DEFAULT_EXPECT_TIMEOUT_MS;
+  return Math.max(LIMITS.SETTLE_QUIET_MS, Math.min(ms, LIMITS.MAX_WAIT_MS));
+}
+
+/** The failure a classifier works from, normalised from either envelope shape. */
+function normalise(env) {
+  return {
+    code: env?.error?.code ?? env?.code ?? null,
+    evidence: env?.evidence ?? {},
+    state: env?.state ?? (env?.ok === false ? 'failed' : 'completed'),
+  };
+}
+
+/**
+ * What is this step blocked on? Returns `{ id, safety, then, wait, budgetMs }`,
+ * or null when nothing safe could clear it (a person, a policy, ambiguity, or
+ * an unknown failure). A resolver whose `wait` is null only selects the
+ * existing group-recovery path.
+ */
+function classify(env, step, options = {}) {
+  const failure = normalise(env);
+  if (!step || !RETRYABLE_TOOLS.has(step.tool)) return null;
+  if (failure.code && FORBIDDEN_CODES.includes(failure.code)) return null;
+  if (failure.code && !TRANSIENT_CODES.includes(failure.code)) return null;
+  const demoted = Array.isArray(options.demoted) ? options.demoted : [];
+  for (const resolver of RESOLVERS) {
+    if (demoted.includes(resolver.id)) continue;
+    if (!resolver.matches({ ...failure, step })) continue;
+    const wait = resolver.wait({ step, evidence: failure.evidence });
+    if (resolver.then === 'retry_step' && !wait) return null;
+    return {
+      id: resolver.id,
+      safety: resolver.safety,
+      then: resolver.then,
+      wait,
+      budgetMs: resolveBudget(resolver, options),
+    };
+  }
+  return null;
+}
+
+/** One resolver by id, for a step profile that learned to pre-wait. */
+function resolverById(id) {
+  return RESOLVERS.find((resolver) => resolver.id === id && resolver.then === 'retry_step') ?? null;
+}
+
+/** The wait args for a resolver id applied to this step (promotion from the step profile). */
+function waitArgsFor(id, step) {
+  const resolver = resolverById(id);
+  return resolver ? resolver.wait({ step, evidence: {} }) : null;
+}
+
+/**
+ * May a step profile wait for this blocker *before* acting? Only a blocker about
+ * what the step is waiting on — never one about what it produces.
+ */
+function promotable(id) {
+  const resolver = resolverById(id);
+  return Boolean(resolver) && resolver.promotable !== false;
+}
+
+/**
+ * How long to wait for this resolver, in this order: the resolver's own default,
+ * the step's learned p95 × 1.5 (once it has ≥ 3 runs), the person's patience,
+ * an explicit cap, then the resolver's floor/ceiling.
+ */
+function resolveBudget(resolver, { learnedMs = null, patience = 'normal', maxWaitMs = null } = {}) {
+  const { floor, default: fallback, ceiling } = resolver.budgetMs;
+  let ms = fallback;
+  if (Number.isFinite(learnedMs) && learnedMs > 0) ms = Math.round(learnedMs * 1.5);
+  const factor = patience === 'fast' ? 0.5 : patience === 'patient' ? 3 : 1;
+  ms = Math.round(ms * factor);
+  if (Number.isFinite(maxWaitMs) && maxWaitMs > 0) ms = Math.min(ms, maxWaitMs);
+  return Math.max(floor, Math.min(ms, ceiling));
+}
+
+/**
+ * May this step be retried in place under AU-08?
+ *
+ * - the resolver must actually retry the step;
+ * - its tool must be one a workflow may repeat;
+ * - a consequential step is never repeated, whatever the failure code;
+ * - a click or key press is repeated only when the action provably did not run,
+ *   or under the click_no_effect resolver's own narrow rule;
+ * - everything else (fills, selects, navigations, waits) is safe to repeat.
+ */
+function mayRetryInPlace(resolver, env, step) {
+  if (!resolver || resolver.then !== 'retry_step') return false;
+  if (!step || !RETRYABLE_TOOLS.has(step.tool)) return false;
+  const { code, evidence } = normalise(env);
+  if (CONSEQUENTIAL_RISKS.has(evidence.risk)) return false;
+  if (resolver.id === 'click_no_effect') return true;
+  if (step.tool === 'element_click' || step.tool === 'browser_press_key') {
+    return ACTION_DID_NOT_RUN_CODES.has(code);
+  }
+  return true;
+}
+
+module.exports = {
+  REGISTRY_VERSION,
+  FORBIDDEN_CODES,
+  CONSEQUENTIAL_RISKS,
+  RETRYABLE_TOOLS,
+  ACTION_DID_NOT_RUN_CODES,
+  TRANSIENT_CODES,
+  WAIT_KINDS,
+  RESOLVERS,
+  classify,
+  resolveBudget,
+  mayRetryInPlace,
+  resolverById,
+  promotable,
+  waitArgsFor,
+  waitForRecordedExpectation,
+  expectBudgetMs,
+};