tewip-ai 0.4.0

package/dist/cli/tewip.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Tewip on the command line. One command, a few verbs:
+//   tewip explain <report>          why each test in a report failed, and what to do next
+//   tewip ci <owner/repo> [--pr N]  the latest Tewip report from a repository's CI
+//   tewip plan "<feature>"          a test plan grounded in the project
+//   tewip write [--only IDs]        tests for a plan's scenarios, kept only when verified
+//   tewip mcp                       serve Tewip to an AI assistant or editor over MCP (stdio)
+//   tewip --version | --help
+// The verbs reuse the same code as the GitHub Action and the MCP server: one engine, many outlets.
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+// cli/ in the source tree, dist/cli/ in the published package: package.json is one or two levels up.
+const ROOT = [join(import.meta.dirname, '..'), join(import.meta.dirname, '..', '..')].find((d) => existsSync(join(d, 'package.json'))) ?? join(import.meta.dirname, '..');
+const version = () => JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
+const HELP = `Tewip - finds why each test failed, for any stack.
+
+Usage:
+  tewip explain <report>            Explain a test report: a JUnit XML or .trx file, a folder of
+                                    them, or a Playwright blob-report folder. Keeps history per
+                                    project, so later runs are judged against earlier ones.
+      --name <project>              Keep this project's history apart from others.
+  tewip ci <owner/repo> [--pr N | --branch B]
+                                    Show the latest report Tewip's GitHub Action uploaded (uses
+                                    your gh login). Without --pr or --branch: the newest run.
+  tewip plan "<feature>" [--diff main...HEAD] [--url <page> ...] [--out plan.md]
+                                    Write a test plan grounded in the project: its existing tests,
+                                    the change, the live pages and Tewip's failure history.
+  tewip write [--plan plan.json] [--only LS-002,LS-003] [--framework playwright] [--runs 3]
+                                    Write tests for the plan's scenarios in the project's own
+                                    framework (Playwright, Cypress, WebdriverIO, Jest, Vitest,
+                                    pytest, JUnit, .NET, Go). Keeps a test only if it passes every
+                                    run and fails when its check is broken on purpose.
+      --move-to <folder>            Move kept tests there afterwards, leaving the project as it was.
+  tewip mcp                         Serve Tewip over MCP (stdio) for an editor or AI assistant.
+  tewip --version                   Print the version.
+
+Reports it reads: Playwright, pytest/unittest, Jest, Vitest, Mocha, node:test, JUnit/TestNG
+(Maven, Gradle), Go (gotestsum), .NET (TRX or JUnit), RSpec, PHPUnit, Rust (nextest).
+Set OPENAI_API_KEY to let the AI layer decide what the rules leave open.`;
+const flag = (args, name) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+async function main() {
+    const [verb, ...args] = process.argv.slice(2);
+    switch (verb) {
+        case 'explain': {
+            // The explain script reads its arguments from process.argv, as when it is run directly.
+            process.argv = [process.argv[0], 'tewip-explain', ...args];
+            // Answers the AI layer already gave are kept with the project, not inside the installed tool.
+            process.env.TEWIP_LLM_CACHE ??= join(process.cwd(), '.tewip', 'llm-cache.jsonl');
+            await import('../scripts/explain.js');
+            return;
+        }
+        case 'ci': {
+            const repo = args.find((a) => /^[\w.-]+\/[\w.-]+$/.test(a));
+            if (!repo)
+                throw new Error('usage: tewip ci <owner/repo> [--pr N | --branch B]');
+            const pr = flag(args, 'pr');
+            const { githubCiReport } = await import('../mcp/github-report.js');
+            console.log(await githubCiReport(repo, pr ? Number(pr) : undefined, flag(args, 'branch')));
+            return;
+        }
+        case 'plan': {
+            const feature = args.filter((a, i) => !a.startsWith('--') && !['--diff', '--url', '--out'].includes(args[i - 1] ?? '')).join(' ').trim();
+            if (!feature)
+                throw new Error('usage: tewip plan "<what the feature does>" [--diff main...HEAD] [--url http://localhost:3000/page ...] [--out plan.md]');
+            const urls = args.flatMap((a, i) => (args[i - 1] === '--url' ? [a] : []));
+            const { runPlan } = await import('../engine/quality/plan-command.js');
+            await runPlan({ feature, root: process.cwd(), diffRange: flag(args, 'diff'), urls, out: flag(args, 'out') });
+            return;
+        }
+        case 'write': {
+            const number = (name, fallback) => (flag(args, name) === undefined ? fallback : Math.max(0, Number(flag(args, name)) || 0));
+            const { runWrite } = await import('../engine/quality/write-command.js');
+            await runWrite({
+                root: process.cwd(),
+                plan: flag(args, 'plan'),
+                only: (flag(args, 'only') ?? '').split(',').map((s) => s.trim()).filter(Boolean),
+                framework: flag(args, 'framework'),
+                urls: args.flatMap((a, i) => (args[i - 1] === '--url' ? [a] : [])),
+                runs: Math.max(1, number('runs', 3)),
+                repairs: number('repairs', 2),
+                max: Math.max(1, number('max', 10)),
+                moveTo: flag(args, 'move-to') ? resolve(flag(args, 'move-to')) : undefined,
+            });
+            return;
+        }
+        case 'mcp':
+            // An editor starts this from any folder, and an installed tool's own folder may be read-only:
+            // the AI answer cache goes to the user's home folder, which is always writable.
+            process.env.TEWIP_LLM_CACHE ??= join(homedir(), '.tewip', 'llm-cache.jsonl');
+            await import('../mcp/server.js');
+            return;
+        case '--version':
+        case '-v':
+            console.log(version());
+            return;
+        case undefined:
+        case '--help':
+        case '-h':
+        case 'help':
+            console.log(HELP);
+            return;
+        default:
+            console.error(`tewip: unknown command "${verb}"\n\n${HELP}`);
+            process.exitCode = 1;
+    }
+}
+try {
+    await main();
+}
+catch (error) {
+    console.error(`tewip: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+}

package/dist/engine/autofix/autofix.js

@@ -0,0 +1,63 @@
+// ACT + VERIFY for LOCATOR_DRIFT (ROADMAP Phase 5): rewrite the drifted locator in the test,
+// re-run that single test, keep the change only if it passes, otherwise restore the file.
+// Safety rules enforced here, not left to callers:
+// - only failures the DECIDE step marked as agent-eligible fix-locator actions (> 0.85)
+// - only files inside `allowedRoot` (a sandbox copy of the tests), never application code
+// - never when the test has no assertion after the rewritten call (a pass would prove nothing)
+// - at most MAX_CANDIDATES attempts; every step is logged with its reason
+import { relative, resolve, sep } from 'node:path';
+import { extractLocator } from '../error-parse.js';
+import { candidatesFor, strictCandidates } from './candidates.js';
+import { failingLine, findLocatorSites, hasAssertionAfter } from './locate.js';
+export const MAX_CANDIDATES = 3;
+function pickSite(sites, line) {
+    if (sites.length <= 1 || line === null)
+        return sites[0];
+    // Prefer the call on the failing line, else the nearest one above it (same test body).
+    return sites.find((s) => s.line === line) ?? [...sites].filter((s) => s.line <= line).sort((a, b) => b.line - a.line)[0] ?? sites[0];
+}
+export async function attemptFix({ record, diagnosis, action, specFile }, deps, { keep = true } = {}) {
+    const title = record.testId.split(' > ').at(-1) ?? record.testId;
+    const result = { testId: record.testId, specFile, status: 'not-eligible', applied: false, attempts: [], log: [] };
+    const stop = (status, why) => ({ ...result, status, log: [...result.log, why] });
+    if (action.kind !== 'fix-locator' || (keep && !action.autonomous)) {
+        return stop('not-eligible', `not an agent-eligible locator fix (${diagnosis.category} at ${diagnosis.confidence.toFixed(2)}, action ${action.kind})`);
+    }
+    const rel = relative(resolve(deps.allowedRoot), resolve(specFile));
+    if (rel.startsWith('..') || rel.startsWith(sep) || /^[a-zA-Z]:/.test(rel))
+        return stop('outside-sandbox', `refused: ${specFile} is outside the sandbox ${deps.allowedRoot}`);
+    const locator = extractLocator(record.errorMessage);
+    const source = deps.readFile(specFile);
+    const site = locator ? pickSite(findLocatorSites(source, locator), failingLine(record.errorStack, specFile)) : undefined;
+    if (!locator || !site)
+        return stop('locator-not-found', `could not find the failing locator ${locator ?? '(none in error)'} in ${specFile}`);
+    result.original = site.text;
+    result.line = site.line;
+    result.log.push(`found ${site.text} at line ${site.line}`);
+    if (!hasAssertionAfter(source, site.line))
+        return stop('no-assertion', 'refused: the test has no expect() after this call, so a passing re-run would not prove the fix');
+    const snapshot = deps.loadSnapshot(record) ?? [];
+    const candidates = [...strictCandidates(diagnosis), ...candidatesFor(locator, snapshot, MAX_CANDIDATES)].slice(0, MAX_CANDIDATES);
+    if (candidates.length === 0)
+        return stop('no-candidate', 'no element on the failure-time page is similar enough to the old locator');
+    for (const c of candidates) {
+        const patched = source.slice(0, site.start) + c.expression + source.slice(site.end);
+        deps.writeFile(specFile, patched);
+        const outcome = await deps.verify(specFile, title);
+        result.attempts.push({ candidate: c.expression, passed: outcome.passed, detail: outcome.detail });
+        result.log.push(`tried ${c.expression} (similarity ${c.score.toFixed(2)}): ${outcome.passed ? 'test passed' : `test still fails (${outcome.detail})`}`);
+        if (outcome.passed) {
+            if (!keep)
+                deps.writeFile(specFile, source);
+            return { ...result, status: 'fixed', applied: keep, replacement: c.expression, log: keep ? result.log : [...result.log, 'suggestion check only: file restored'] };
+        }
+        deps.writeFile(specFile, source);
+    }
+    return stop('all-candidates-failed', `all ${candidates.length} candidate(s) failed verification; original file restored`);
+}
+/** Unified-diff-style summary of an accepted fix, for a PR description. */
+export function fixDiff(fix, displayPath) {
+    if (!fix.applied || !fix.original || !fix.replacement)
+        return '';
+    return [`--- a/${displayPath}`, `+++ b/${displayPath}`, `@@ line ${fix.line} @@`, `-${fix.original}`, `+${fix.replacement}`].join('\n');
+}

package/dist/engine/autofix/candidates.js

@@ -0,0 +1,33 @@
+import { DRIFT_MIN_SIMILARITY } from '../drift-rules.js';
+import { rankCandidates } from '../similarity.js';
+const ROLE_LOCATABLE = new Set(['button', 'link', 'heading', 'textbox', 'checkbox', 'radio', 'combobox', 'tab', 'menuitem', 'option', 'searchbox', 'switch']);
+const quote = (s) => `'${s.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+export function locatorFor(el) {
+    const name = el.name || el.text;
+    if (!name)
+        return null;
+    return ROLE_LOCATABLE.has(el.role) ? `getByRole(${quote(el.role)}, { name: ${quote(name)}, exact: true })` : `getByText(${quote(name)}, { exact: true })`;
+}
+export function candidatesFor(printedLocator, snapshot, max = 3) {
+    const seen = new Set();
+    const out = [];
+    for (const { element, score } of rankCandidates(printedLocator, snapshot)) {
+        if (score < DRIFT_MIN_SIMILARITY || out.length >= max)
+            break;
+        const expression = locatorFor(element);
+        if (!expression || seen.has(expression))
+            continue;
+        seen.add(expression);
+        out.push({ expression, element, score });
+    }
+    return out;
+}
+/** The unique locator Playwright printed for the intended element of a strict-mode violation. */
+export function strictCandidates(d) {
+    return d.evidence.flatMap((e) => {
+        const { replacement, candidate } = (e.data ?? {});
+        if (typeof replacement !== 'string')
+            return [];
+        return [{ expression: replacement, element: { role: candidate?.role ?? '', name: candidate?.name ?? '', text: '' }, score: 1 }];
+    });
+}

package/dist/engine/autofix/locate.js

@@ -0,0 +1,78 @@
+// Finds where a failing locator is written in a spec file, so the auto-fix loop can rewrite
+// exactly that call and nothing else.
+const CALL_START = /\b(?:locator|getBy(?:Role|Text|Label|TestId|Placeholder|Title|AltText))\(/g;
+/** Canonical form for comparing source text with the locator Playwright printed. */
+export function normalizeLocator(s) {
+    return s.replaceAll('"', "'").replace(/\s+/g, '').replace(/,([}\)])/g, '$1');
+}
+/** Index just past the ")" that closes the "(" at `open`, skipping strings; -1 if unbalanced. */
+function closeParen(src, open) {
+    let depth = 0;
+    let quote = null;
+    for (let i = open; i < src.length; i++) {
+        const c = src[i];
+        if (quote) {
+            if (c === '\\')
+                i++;
+            else if (c === quote)
+                quote = null;
+        }
+        else if (c === "'" || c === '"' || c === '`')
+            quote = c;
+        else if (c === '(')
+            depth++;
+        else if (c === ')' && --depth === 0)
+            return i + 1;
+    }
+    return -1;
+}
+/** The last call in a printed chain, e.g. "locator('#a').locator('.b')" -> "locator('.b')". */
+export function lastCall(printed) {
+    const starts = [...printed.matchAll(CALL_START)].map((m) => m.index);
+    if (starts.length === 0)
+        return printed;
+    const start = starts[starts.length - 1];
+    const end = closeParen(printed, printed.indexOf('(', start));
+    return end > 0 ? printed.slice(start, end) : printed.slice(start);
+}
+/** Every call in `source` that is the same locator as `printed` (its last call). */
+export function findLocatorSites(source, printed) {
+    const want = normalizeLocator(lastCall(printed));
+    const sites = [];
+    for (const m of source.matchAll(CALL_START)) {
+        const start = m.index;
+        const end = closeParen(source, start + m[0].length - 1);
+        if (end < 0)
+            continue;
+        const text = source.slice(start, end);
+        if (normalizeLocator(text) === want)
+            sites.push({ start, end, text, line: source.slice(0, start).split('\n').length });
+    }
+    return sites;
+}
+/** Line of `specFile` in a stack trace ("at …/shop.spec.ts:12:5"), or null. */
+export function failingLine(stack, specFile) {
+    const name = specFile.split(/[\\/]/).pop();
+    for (const line of stack.split('\n')) {
+        const m = line.match(/[\\/]([^\\/:]+):(\d+):\d+\)?\s*$/);
+        if (m && m[1] === name)
+            return Number(m[2]);
+    }
+    return null;
+}
+/**
+ * True when the test still checks something after `line`: without an expect() after the
+ * rewritten call, a passing re-run would prove nothing about the fix.
+ */
+export function hasAssertionAfter(source, line) {
+    const lines = source.split('\n');
+    for (let i = line - 1; i < lines.length; i++) {
+        if (i > line - 1 && /^\s*test(\.\w+)?\(/.test(lines[i]))
+            return false;
+        if (/\bexpect\s*\(/.test(lines[i]))
+            return true;
+        if (/^\}\);?\s*$/.test(lines[i]))
+            return false;
+    }
+    return false;
+}

package/dist/engine/corrections.js

@@ -0,0 +1,66 @@
+// LEARN step: what people told the agent it got wrong. A correction is a human's category for
+// one failure, written where the agent posted its answer (a PR comment, an issue comment) as
+// "/triage CATEGORY reason". It is stored with the run history and applied to later failures of
+// the same test that fail the same way, so the agent does not repeat a mistake a person already
+// corrected. Corrections decide the category only: they never authorise a code change on their
+// own, because a person's category is not a verified replacement locator.
+import { join } from 'node:path';
+import { ROOT_CAUSES } from '../reporters/types.js';
+import { appendJsonl, readJsonl } from '../reporters/store.js';
+import { errorShape, truncate } from './signature.js';
+export const CORRECTIONS_FILE = 'corrections.jsonl';
+const file = (dir) => join(dir, CORRECTIONS_FILE);
+export const loadCorrections = (dir) => readJsonl(file(dir));
+/** Appends corrections that are not already stored (same test, shape, category and author). */
+export function saveCorrections(dir, corrections) {
+    const existing = loadCorrections(dir);
+    const seen = new Set(existing.map((c) => `${c.testId}|${c.errorShape}|${c.category}|${c.by}`));
+    const fresh = corrections.filter((c) => !seen.has(`${c.testId}|${c.errorShape}|${c.category}|${c.by}`));
+    if (fresh.length > 0)
+        appendJsonl(file(dir), fresh);
+    return fresh;
+}
+/** The most recent correction for this test failing this way, if a person made one. */
+export function correctionFor(record, corrections) {
+    const shape = errorShape(record.errorMessage);
+    const matches = corrections.filter((c) => c.testId === record.testId && c.errorShape === shape);
+    return matches.sort((a, b) => a.at.localeCompare(b.at)).at(-1) ?? null;
+}
+/**
+ * Applies a person's correction to a diagnosis. The category becomes theirs, at full confidence,
+ * and the agent's own answer is kept as evidence so the disagreement stays visible.
+ */
+export function applyCorrection(diagnosis, correction) {
+    const said = `${diagnosis.category} at ${diagnosis.confidence.toFixed(2)}`;
+    return {
+        ...diagnosis,
+        category: correction.category,
+        confidence: 1,
+        source: 'human',
+        evidence: [
+            {
+                source: 'human',
+                message: `@${correction.by} corrected this to ${correction.category}${correction.reason ? `: ${truncate(correction.reason, 160)}` : ''}${correction.source ? ` (${correction.source})` : ''}`,
+                data: { correctedAt: correction.at, was: said },
+            },
+            ...diagnosis.evidence,
+        ],
+    };
+}
+const COMMAND = /(?:^|\s)\/triage\s+([A-Z_]+)\b[ \t]*(.*)$/gim;
+/**
+ * Reads "/triage CATEGORY reason" commands out of a comment. A comment may correct several
+ * failures, each line naming the board number it means: "/triage TIMING #3 flaky in CI".
+ */
+export function parseCorrectionCommands(body) {
+    const out = [];
+    for (const [, word, rest] of body.matchAll(COMMAND)) {
+        const category = ROOT_CAUSES.find((c) => c === word.toUpperCase());
+        if (!category)
+            continue;
+        const ref = rest.match(/(?:^|\s)([\w.-]+)?#(\d+)/);
+        const reason = (ref ? rest.replace(ref[0], ' ') : rest).trim();
+        out.push({ category, reason: reason || undefined, item: ref ? Number(ref[2]) : undefined, ...(ref?.[1] ? { suite: ref[1] } : {}) });
+    }
+    return out;
+}

package/dist/engine/dataset.js

@@ -0,0 +1,41 @@
+// Loading a dataset and turning failed attempts into cases. Shared by the eval, the
+// evidence harvester and the outlets.
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { datasetFiles, PROJECT_ROOT, readJsonl, readRunSummaries, readTriageRecords } from '../reporters/store.js';
+/**
+ * One case per failed test per run: its last failed attempt. Retries of the same failure
+ * share one cause, so counting each would weight a test by its retry count.
+ */
+export function lastFailedAttempts(records) {
+    const last = new Map();
+    for (const r of records) {
+        const key = `${r.runId} ${r.testId}`;
+        const seen = last.get(key);
+        if (!seen || r.retry > seen.retry)
+            last.set(key, r);
+    }
+    return [...last.values()];
+}
+/** Harvested datasets predate RunSummary.branch: fill it from the harvester's runs-meta.jsonl. */
+function withBranches(summaries, dir) {
+    const metaFile = join(dir, 'runs-meta.jsonl');
+    if (!existsSync(metaFile))
+        return summaries;
+    const branch = new Map(readJsonl(metaFile).map((m) => [m.runId, m.branch ?? '']));
+    return summaries.map((s) => (s.branch || !branch.get(s.runId) ? s : { ...s, branch: branch.get(s.runId) }));
+}
+/** Records + run summaries from a dataset dir, or from every dataset directly under it. */
+export function loadDataset(dir) {
+    const files = datasetFiles(dir);
+    if (!dir || existsSync(files.triage)) {
+        return { records: readTriageRecords(files.triage), summaries: withBranches(readRunSummaries(files.runs), files.dir), label: relative(PROJECT_ROOT, files.dir).replaceAll('\\', '/') || '.' };
+    }
+    const subdirs = readdirSync(files.dir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync(join(files.dir, d.name, 'triage.jsonl')));
+    const parts = subdirs.map((d) => datasetFiles(join(files.dir, d.name)));
+    return {
+        records: parts.flatMap((p) => readTriageRecords(p.triage)),
+        summaries: parts.flatMap((p) => withBranches(readRunSummaries(p.runs), p.dir)),
+        label: subdirs.map((d) => relative(PROJECT_ROOT, join(files.dir, d.name)).replaceAll('\\', '/')).join(', '),
+    };
+}

package/dist/engine/decide.js

@@ -0,0 +1,130 @@
+/** Above this, code fixes (locator / wait) may be applied by the agent itself. */
+export const AUTO_FIX_ABOVE = 0.85;
+/** Below this, the diagnosis is too weak to act on: a human takes over. */
+export const ESCALATE_BELOW = 0.5;
+const pct = (n) => n.toFixed(2);
+/**
+ * VERIFY -> DECIDE: what re-running the test with the suggested locator says about a drift
+ * diagnosis. Passing confirms the suggestion; failing with every candidate means the element was
+ * probably not renamed, so a human should check whether the feature itself broke.
+ */
+export function reviseAfterVerification(action, outcome) {
+    if (action.kind !== 'fix-locator')
+        return { action, note: null };
+    if (outcome.status === 'fixed' && outcome.replacement) {
+        return {
+            action: { ...action, summary: `Verified by re-running the test: with ${outcome.replacement} it passes. ${action.summary}`, reason: `${action.reason}; suggestion verified by a re-run` },
+            note: `re-running the test with ${outcome.replacement} passed`,
+        };
+    }
+    if (outcome.status === 'all-candidates-failed') {
+        return {
+            action: {
+                kind: 'escalate',
+                owner: 'sdet',
+                autonomous: false,
+                summary: 'The test still fails with the most similar elements on the page, so this is probably not a renamed element: check whether the feature itself still works (possible real bug) before touching the test.',
+                reason: `${action.reason}; every suggested locator failed a re-run`,
+            },
+            note: 'every suggested replacement locator failed when the test was re-run',
+        };
+    }
+    if (outcome.status === 'no-assertion') {
+        return {
+            action: { ...action, summary: `${action.summary} Cannot be verified automatically: the test has no assertion after this step, so check by hand that the new element is the intended one.` },
+            note: 'the suggestion cannot be verified: the test has no assertion after the failing step',
+        };
+    }
+    return { action, note: null };
+}
+export function decide(d, hints = {}) {
+    const conf = `${d.category} at confidence ${pct(d.confidence)}`;
+    const target = hints.locator ? ` ${hints.locator}` : '';
+    if (d.category === 'UNKNOWN' || d.confidence < ESCALATE_BELOW) {
+        return {
+            kind: 'escalate',
+            owner: 'sdet',
+            autonomous: false,
+            summary: 'Needs a human decision: the agent could not classify this confidently. Start from the evidence below.',
+            reason: d.category === 'UNKNOWN' ? 'no rule or model decided' : `${conf} is below ${ESCALATE_BELOW}`,
+        };
+    }
+    switch (d.category) {
+        case 'ENV':
+            return {
+                kind: 'rerun-and-notify',
+                owner: 'devops',
+                autonomous: true,
+                summary: 'Do not touch the test. Re-run it once; if it fails again, check the failing dependency named in the evidence and send one grouped notice.',
+                reason: `${conf}: environment problems are re-run and reported, never fixed in test code`,
+            };
+        case 'REAL_BUG':
+            return {
+                kind: 'file-bug',
+                owner: 'developer',
+                autonomous: true,
+                summary: `File a bug${hints.component ? ` against ${hints.component}` : ''}${hints.commit ? ` for commit ${hints.commit.slice(0, 8)}` : ''}${hints.tracePath ? ` with the trace (${hints.tracePath}) attached` : ' with the failure output attached'}; do not change the test.`,
+                reason: `${conf}: the application is broken, so the test stays as it is`,
+            };
+        case 'LOCATOR_DRIFT': {
+            // On real CI data the AI alone called real bugs "drift" at 0.88-0.96, while every correct
+            // lab fix came from the deterministic rule that found the renamed element on the page.
+            // So code changes need that rule's match, not just a high confidence.
+            const matched = d.source === 'rules' && (d.ruleId === 'locator-drift' || d.ruleId === 'locator-drift-strict');
+            const auto = d.confidence > AUTO_FIX_ABOVE && matched;
+            // A locator that now matches several elements needs narrowing, not renaming.
+            const fix = hints.strictMatches && hints.suggestedLocator
+                ? `Change the locator${target} to ${hints.suggestedLocator}: it now matches ${hints.strictMatches} elements, and this is the one the test means`
+                : hints.strictMatches
+                    ? `Make the locator${target} more specific: it now matches ${hints.strictMatches} elements (add the element's name, a parent, or exact: true)`
+                    : hints.suggestedLocator
+                        ? `Update the locator${target} to ${hints.suggestedLocator}`
+                        : `Update the locator${target} to match the renamed element`;
+            return {
+                kind: 'fix-locator',
+                owner: 'sdet',
+                autonomous: auto,
+                summary: `${fix}, re-run the test, and open a PR only if it passes.`,
+                reason: auto
+                    ? `${conf} is above ${AUTO_FIX_ABOVE} and the page has a matching renamed element: auto-fix eligible`
+                    : d.source === 'human'
+                        ? // A person's category is authoritative, but it does not name a replacement locator
+                            // that a re-run has proved, which is what the agent needs before editing test code.
+                            'a person corrected this to LOCATOR_DRIFT, which settles the cause but not the new locator: an SDET writes the fix'
+                        : !matched
+                            ? `${conf}, but no deterministic match of a renamed element on the page: an SDET reviews the fix`
+                            : `${conf} is below ${AUTO_FIX_ABOVE}: an SDET reviews the fix`,
+            };
+        }
+        case 'TIMING': {
+            const auto = d.confidence > AUTO_FIX_ABOVE && Boolean(hints.hardWait);
+            return hints.hardWait
+                ? {
+                    kind: 'fix-wait',
+                    owner: 'sdet',
+                    autonomous: auto,
+                    summary: `Replace the fixed wait (${hints.hardWait}) with a web-first assertion on the element it waits for, re-run, and open a PR only if it passes.`,
+                    reason: auto ? `${conf} is above ${AUTO_FIX_ABOVE}: auto-fix eligible (Phase 5)` : `${conf}: an SDET reviews the fix`,
+                }
+                : {
+                    kind: 'stabilize-test',
+                    owner: 'sdet',
+                    autonomous: false,
+                    summary: hints.locator
+                        ? `Make the step${target} wait for the element's ready state (e.g. await expect(locator).toBeVisible()) before acting; quarantine the test if it keeps flaking.`
+                        : // Not a browser step (a unit or API test in any language): the race is in shared state,
+                            // ordering or timing, and the fix is to wait for the condition instead of hoping.
+                            'Find what the test races against (shared state, test order, a timer, a service still starting) and make it wait for that condition instead of a fixed delay; quarantine the test if it keeps flaking.',
+                    reason: `${conf}: race without a hard-coded wait to replace, so there is no safe automatic fix`,
+                };
+        }
+        case 'TEST_DATA':
+            return {
+                kind: 'fix-precondition',
+                owner: 'sdet',
+                autonomous: false,
+                summary: 'Fix the test setup: create or reset the data the test assumes (see evidence) before it runs; do not change the assertion.',
+                reason: `${conf}: the product is fine, the test's starting data is wrong`,
+            };
+    }
+}

package/dist/engine/device-errors.js

@@ -0,0 +1,45 @@
+// Deterministic readers for mobile test failures that are about the device, not the app: no
+// emulator or simulator, the app never installed or crashed on launch, the driver could not be
+// reached, the test sandbox could not be built. These are environment problems, the same kind as a
+// refused connection, and they say nothing about the code under test.
+// Checked against real messages pasted into public issues (Appium, Espresso, Detox, XCUITest,
+// xcodebuild, Robolectric); every pattern below came from one of them.
+const DEVICE_PATTERNS = [
+    // No device or simulator to run on: Appium, Flutter, Maestro, xcodebuild.
+    {
+        kind: 'no-device',
+        confidence: 0.9,
+        pattern: /Could not find a connected (?:Android|iOS) device[^\n]*|Device \S+ was not in the list of connected devices|No connected devices|Unable to boot the Simulator|Failed to prepare device [^\n]*for impending launch|no devices found|adb: device offline|device unauthorized|An unknown server-side error occurred[^\n]*Could not find a \w+ device/i,
+    },
+    // The app under test never started, or died during the run.
+    {
+        kind: 'app-crashed',
+        confidence: 0.85,
+        pattern: /The application under test with bundle id [^\n]*is not running, possibly crashed|WDAError\(status=889[^\n]*|your main activity has crashed prematurely|Application is not running, possibly crashed|instrumentation process (?:crashed|is not responding)/i,
+    },
+    // The build or test runner could not be put on the device.
+    {
+        kind: 'install-failed',
+        confidence: 0.85,
+        pattern: /Failed to install or launch the test runner|INSTALL_FAILED_\w+|Failed to run application on the device|Could not install [^\n]*apk|Unable to install [^\n]*\.app/i,
+    },
+    // The automation server itself is unreachable (Appium, WebDriverAgent).
+    { kind: 'driver-unreachable', confidence: 0.85, pattern: /Failed to connect to the appium server[^\n]*|Could not proxy command to the remote server|WebDriverAgent[^\n]*(?:failed to start|is not reachable)/i },
+    // The test sandbox could not be built at all: a toolchain mismatch, not a test failure.
+    { kind: 'sandbox', confidence: 0.9, pattern: /Failed to create a Robolectric sandbox[^\n]*|Android SDK \d+ requires Java \d+ \(have Java \d+\)/i },
+];
+/**
+ * A mobile failure caused by the device, the install or the driver, strongest first. Detox prints
+ * the same error for a crash and for a test timeout, telling them apart only in its HINT line, so
+ * that line decides: a timed-out test is the test's problem and gets no device signal here.
+ */
+export function deviceEnvSignal(message) {
+    if (/your tests have timed out and called detox\.cleanup\(\)/i.test(message))
+        return null;
+    for (const { kind, confidence, pattern } of DEVICE_PATTERNS) {
+        const match = message.match(pattern)?.[0];
+        if (match)
+            return { kind, confidence, match: match.replace(/\s+/g, ' ').trim().slice(0, 160) };
+    }
+    return null;
+}