@qa-gentic/stlc-agents 1.0.27 → 1.0.29

package/src/stlc_agents/agent_playwright_generator/server.py

@@ -2267,7 +2267,7 @@ def _gen_page_object(page_class, kebab, camel, gherkin, healing_strategy,
         f' * {page_class}Page — Three-Layer Self-Healing Page Object\n'
         f' *\n'
         f' * Layer 1 — Locator Healing ({healing_strategy}):\n'
-        f' *   primary selector → role-based → label-based → text-based → playwright-cli + Claude AI Vision\n'
+        f' *   primary selector → role-based → label-based → text-based → ariaSnapshot + Claude AI Vision\n'
         f' *   → DevToolsHealer AX tree (CDPSession) → DevToolsHealer bounding box (CDPSession)\n'
         f' *   Healed selectors persisted in LocatorRepository — zero overhead on repeat runs.\n'
         f' *\n'
@@ -2954,6 +2954,7 @@ def _scaffold_locator_repository(
     if enable_visual_regression:
         files[f"{output_dir}/VisualIntentChecker.ts"] = _gen_visual_checker_cls(repository_path, dashboard_port)
     files[f"{output_dir}/HealingDashboard.ts"] = _gen_healing_dashboard_cls(repository_path, dashboard_port)
+    files[f"{output_dir}/dashboard-server.ts"] = _gen_dashboard_server_cls()
 
     strategies = [
         "1. Healed selector from LocatorRepository (zero overhead on repeat runs)",
@@ -2964,7 +2965,7 @@ def _scaffold_locator_repository(
     ]
     if enable_ai_vision:
         strategies.append(
-            "6. playwright-cli snapshot → AI Vision (provider: anthropic | copilot | claude-code) "
+            "6. ariaSnapshot → AI Vision (provider: anthropic | copilot | claude-code) "
             "→ healed selector persisted  [skip with ENABLE_AI_HEALING=false]"
         )
     if enable_timing_healing:
@@ -2998,7 +2999,7 @@ def _scaffold_locator_repository(
 
 
 def _gen_locator_healer_cls(enable_ai_vision):
-    ai_import  = 'import { execSync } from "child_process";' if enable_ai_vision else ""
+    ai_import  = ""
 
     # ------------------------------------------------------------------
     # AI Vision method — emitted only when enable_ai_vision=True.
@@ -3094,7 +3095,7 @@ def _gen_locator_healer_cls(enable_ai_vision):
     const provider = (process.env.AI_HEALING_PROVIDER ?? "anthropic").toLowerCase();
     this.logger.warn(`⚕ AI Vision [${provider}]: key="${key}" intent="${intent}"`);
     try {
-      const snapshot = execSync("playwright-cli snapshot", { encoding: "utf8", timeout: 10_000 });
+      const snapshot = await this.page.locator("body").ariaSnapshot();
       const { url, authHeader, bodyMapper } = this._aiVisionEndpoint();
       const prompt = `DOM snapshot:\\n${snapshot.slice(0, 3500)}\\nFind: "${intent}". Return ONLY a CSS selector, no explanation.`;
 
@@ -3141,14 +3142,59 @@ import {{ LocatorRepository }} from "./LocatorRepository";
 /**
  * LocatorHealer — Multi-Strategy Locator Healing
  *
- * Chain: cached-healed → primary → role → label → text → AI Vision (6)
+ * Chain: cached-healed → primary → attribute → type-hint → role → label → text → AI Vision
  *
- * All healed selectors persisted in LocatorRepository (instant on repeat runs).
+ * Form fields (username, password, email, …) heal via the attribute pass —
+ * the most reliable strategy for inputs that have no accessible name. The
+ * AI Vision step is optional and only fires when every CSS / Playwright
+ * heuristic has been exhausted; it requires an Anthropic API key.
+ *
+ * All healed selectors are persisted to LocatorRepository so repeat runs
+ * skip the entire chain after the first successful heal.
+ */
+/**
+ * Identifiers for the fallback strategies the resolver runs after the
+ * primary selector fails. Used by HEAL_STRATEGY_ORDER (CSV env var) to
+ * reorder or disable specific strategies without forking the scaffold.
+ *
+ * Order in this list is the historical default chain.
  */
+const DEFAULT_HEAL_STRATEGY_ORDER = [
+  "attribute",
+  "type-hint",
+  "role",
+  "label",
+  "text",
+] as const;
+type HealStrategyName = typeof DEFAULT_HEAL_STRATEGY_ORDER[number];
+
+function _resolveStrategyOrder(): HealStrategyName[] {{
+  const raw = (process.env.HEAL_STRATEGY_ORDER ?? "").trim();
+  if (!raw) return [...DEFAULT_HEAL_STRATEGY_ORDER];
+  const known = new Set<string>(DEFAULT_HEAL_STRATEGY_ORDER);
+  const picked: HealStrategyName[] = [];
+  for (const part of raw.split(/[,\\s]+/).filter(Boolean)) {{
+    const norm = part.toLowerCase();
+    if (known.has(norm)) picked.push(norm as HealStrategyName);
+  }}
+  // Empty / all-invalid CSV → fall back to defaults to keep the chain useful.
+  return picked.length ? picked : [...DEFAULT_HEAL_STRATEGY_ORDER];
+}}
+
 export class LocatorHealer {{
+  // Original scaffold defaults — preserved verbatim. LOCATOR_TIMEOUT, when
+  // set, overrides the per-strategy attach probe (ATTACH_TO); TIMEOUT and
+  // HEAL_TO retain their historical values so action timeouts don't shift
+  // for existing tests that depend on them.
   private static readonly TIMEOUT   = 8_000;
   private static readonly HEAL_TO   = 15_000;
-  private static readonly ATTACH_TO = 3_000;
+  private static readonly ATTACH_TO = Number(process.env.LOCATOR_TIMEOUT ?? 3_000);
+  // Cap on the number of healing strategies the resolver will try BEFORE
+  // falling through to AI Vision. 0 = unlimited (whole chain runs, original
+  // behavior). Set LOCATOR_HEAL_ATTEMPTS=N to bound it.
+  private static readonly MAX_ATTEMPTS = Number(process.env.LOCATOR_HEAL_ATTEMPTS ?? 0);
+  // Ordered list of fallback strategies — read once from HEAL_STRATEGY_ORDER.
+  private static readonly STRATEGY_ORDER = _resolveStrategyOrder();
 
   constructor(
     private readonly page:   Page,
@@ -3196,30 +3242,187 @@ export class LocatorHealer {{
       this.logger.warn(`⚕ Primary failed: ${{key}}`);
       this.repo.incrementFailure(key);
     }}
-    const words = intent.split(" ").slice(0, 3).join("|");
-    for (const role of ["button", "link", "textbox", "combobox"] as const) {{
+
+    // Per-call attempt counter for LOCATOR_HEAL_ATTEMPTS. When set to a
+    // positive number, the chain stops trying fallback strategies after N
+    // attempts and falls through to AI Vision (or throws if AI is disabled).
+    let attempts = 0;
+    const capReached = () => LocatorHealer.MAX_ATTEMPTS > 0 && attempts >= LocatorHealer.MAX_ATTEMPTS;
+
+    // Strategy dispatcher — iteration order is set by HEAL_STRATEGY_ORDER
+    // (parsed once into LocatorHealer.STRATEGY_ORDER). Each strategy gets a
+    // consume() callback to bump the attempts counter so LOCATOR_HEAL_ATTEMPTS
+    // bounds *probes* (not just strategies).
+    for (const strategy of LocatorHealer.STRATEGY_ORDER) {{
+      if (capReached()) break;
+      const result = await this._runStrategy(strategy, key, intent, () => {{ attempts++; }});
+      if (result) return result;
+    }}
+
+    // Final stage: AI Vision (needs API key — see _aiVisionEndpoint).
+    return this.healViaAiVision(key, intent);
+  }}
+
+  /**
+   * Run one named healing strategy. Returns the matched Locator or null.
+   *
+   * `consume` is invoked once per probe so LOCATOR_HEAL_ATTEMPTS bounds the
+   * total work across the chain — even strategies that loop internally
+   * (role, type-hint) count one slot per probe.
+   */
+  private async _runStrategy(
+    strategy: HealStrategyName,
+    key: string,
+    intent: string,
+    consume: () => void,
+  ): Promise<Locator | null> {{
+    if (strategy === "attribute") {{
+      const keyword = intent.split(" ").find(w => w.length > 2) ?? intent;
+      const attrSel = [
+        `[name*="${{keyword}}" i]`,
+        `[placeholder*="${{keyword}}" i]`,
+        `[id*="${{keyword}}" i]`,
+        `[aria-label*="${{keyword}}" i]`,
+        `[data-testid*="${{keyword}}" i]`,
+        `[data-test*="${{keyword}}" i]`,
+        `[autocomplete*="${{keyword}}" i]`,
+      ].join(", ");
+      consume();
       try {{
-        const l = this.page.getByRole(role, {{ name: new RegExp(words, "i") }});
+        const l = this.page.locator(attrSel).first();
         await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
-        this.repo.updateHealed(key, `[role:${{role}}]`, intent, "role");
-        this.logger.warn(`⚕ Role-healed: ${{key}}`);
+        const specific = await this._resolveSpecificSelector(l, attrSel);
+        this.repo.updateHealed(key, specific, intent, "attr");
+        this.logger.warn(`⚕ Attribute-healed: ${{key}} → ${{specific}}`);
         return l;
       }} catch {{}}
+      return null;
     }}
+
+    if (strategy === "type-hint") {{
+      const lower = intent.toLowerCase();
+      const typeHints: Array<[RegExp, string]> = [
+        [/\\bpassword\\b/, 'input[type="password"]'],
+        [/\\bemail\\b/, 'input[type="email"], input[autocomplete="email"]'],
+        [/\\bsearch\\b/, 'input[type="search"], [role="search"] input'],
+        [/\\bphone\\b/, 'input[type="tel"], input[autocomplete*="tel"]'],
+        [/\\bcheckbox\\b/, 'input[type="checkbox"]'],
+        [/\\bradio\\b/, 'input[type="radio"]'],
+        [/\\b(submit|login|sign\\s?in|save|continue|next|confirm)\\b/,
+          'button[type="submit"], input[type="submit"]'],
+      ];
+      for (const [re, sel] of typeHints) {{
+        if (!re.test(lower)) continue;
+        consume();
+        try {{
+          const l = this.page.locator(sel).first();
+          await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+          const specific = await this._resolveSpecificSelector(l, sel);
+          this.repo.updateHealed(key, specific, intent, "type-hint");
+          this.logger.warn(`⚕ Type-hint healed: ${{key}} → ${{specific}}`);
+          return l;
+        }} catch {{}}
+      }}
+      return null;
+    }}
+
+    if (strategy === "role") {{
+      const words = intent.split(" ").slice(0, 3).join("|");
+      for (const role of ["button", "link", "textbox", "combobox", "checkbox", "radio"] as const) {{
+        consume();
+        try {{
+          const l = this.page.getByRole(role, {{ name: new RegExp(words, "i") }});
+          await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+          const specific = await this._resolveSpecificSelector(l, `[role:${{role}}]`);
+          this.repo.updateHealed(key, specific, intent, "role");
+          this.logger.warn(`⚕ Role-healed: ${{key}} → ${{specific}}`);
+          return l;
+        }} catch {{}}
+      }}
+      return null;
+    }}
+
+    if (strategy === "label") {{
+      consume();
+      try {{
+        const l = this.page.getByLabel(intent, {{ exact: false }});
+        await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+        const specific = await this._resolveSpecificSelector(l, "[label-healed]");
+        this.repo.updateHealed(key, specific, intent, "label");
+        this.logger.warn(`⚕ Label-healed: ${{key}} → ${{specific}}`);
+        return l;
+      }} catch {{}}
+      return null;
+    }}
+
+    if (strategy === "text") {{
+      consume();
+      try {{
+        const w = intent.split(" ").find(w => w.length > 3) ?? intent;
+        const l = this.page.getByText(w, {{ exact: false }});
+        await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
+        const specific = await this._resolveSpecificSelector(l, "[text-healed]");
+        this.repo.updateHealed(key, specific, intent, "text");
+        this.logger.warn(`⚕ Text-healed: ${{key}} → ${{specific}}`);
+        return l;
+      }} catch {{}}
+      return null;
+    }}
+
+    return null;
+  }}
+
+  /**
+   * Inspect the actually-matched element and return the most stable
+   * SINGLE selector that uniquely identifies it on the live page.
+   *
+   * The healer's search selectors are deliberately broad (CSS unions, role
+   * queries, etc.) so the chain has the best chance of finding *some*
+   * matching element when the original primary selector breaks. But once
+   * we've matched, we don't want to persist the union — we want the one
+   * concrete locator that actually pinned the element. That's what the
+   * qa-playwright-generator agent emits at generation time, and it's
+   * what the operator wants to see in the heal store.
+   *
+   * Preference order (most stable first):
+   *   1. `data-testid` / `data-test`     — purpose-built test hooks
+   *   2. `id`                            — unique by HTML spec
+   *   3. `name`                          — typical for form fields
+   *   4. `placeholder`                   — visible-only forms
+   *   5. `aria-label`                    — accessible name
+   *   6. `autocomplete`                  — semantic hint
+   *   7. The fallback selector passed in — used when none of the above
+   *      are present (rare; means the element is genuinely anonymous).
+   */
+  private async _resolveSpecificSelector(loc: Locator, fallback: string): Promise<string> {{
     try {{
-      const l = this.page.getByLabel(intent, {{ exact: false }});
-      await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
-      this.repo.updateHealed(key, "[label-healed]", intent, "label");
-      return l;
-    }} catch {{}}
-    try {{
-      const w = intent.split(" ").find(w => w.length > 3) ?? intent;
-      const l = this.page.getByText(w, {{ exact: false }});
-      await l.waitFor({{ state: "attached", timeout: LocatorHealer.ATTACH_TO }});
-      this.repo.updateHealed(key, "[text-healed]", intent, "text");
-      return l;
+      const attrs = await loc.evaluate((el: Element) => {{
+        const get = (name: string) => el.getAttribute(name) ?? null;
+        return {{
+          tag:           el.tagName.toLowerCase(),
+          id:            (el as HTMLElement).id || null,
+          name:          get("name"),
+          placeholder:   get("placeholder"),
+          ariaLabel:     get("aria-label"),
+          dataTestId:    get("data-testid"),
+          dataTest:      get("data-test"),
+          autocomplete:  get("autocomplete"),
+          type:          get("type"),
+        }};
+      }});
+      const esc = (v: string) => v.replace(/(["\\\\])/g, "\\\\$1");
+      if (attrs.dataTestId)     return `[data-testid="${{esc(attrs.dataTestId)}}"]`;
+      if (attrs.dataTest)       return `[data-test="${{esc(attrs.dataTest)}}"]`;
+      if (attrs.id)             return `#${{attrs.id.replace(/([^\\w-])/g, "\\\\$1")}}`;
+      if (attrs.name)           return `${{attrs.tag}}[name="${{esc(attrs.name)}}"]`;
+      if (attrs.placeholder)    return `${{attrs.tag}}[placeholder="${{esc(attrs.placeholder)}}"]`;
+      if (attrs.ariaLabel)      return `[aria-label="${{esc(attrs.ariaLabel)}}"]`;
+      if (attrs.autocomplete)   return `${{attrs.tag}}[autocomplete="${{esc(attrs.autocomplete)}}"]`;
+      // Element has no identifying attribute — fall back to type+tag if it's a typed input.
+      if (attrs.tag === "input" && attrs.type)
+        return `input[type="${{esc(attrs.type)}}"]`;
     }} catch {{}}
-    return this.healViaAiVision(key, intent);
+    return fallback;
   }}
 {ai_method}
 }}
@@ -3240,31 +3443,182 @@ export interface LocatorEntry {{
   lastBoundingBox?: BoundingBox;
   /** Pending AI suggestion awaiting HealingDashboard approval before commit */
   pendingSuggestion?: {{ selector:string; strategy:string; suggestedAt:string }};
+  /** Set by HealingDashboard.approve — confirms a human signed off on the heal. */
+  approvedAt?: string;
+  /** Set when HealingDashboard.approve also wrote the healed selector back to the locator .ts file. */
+  appliedToSourceAt?: string;
+}}
+
+/** Current persisted-file schema version. Bumped when the on-disk shape changes. */
+export const HEAL_STORE_VERSION = 1;
+
+/**
+ * Resolve the heal-store path with env-var precedence:
+ *   1. constructor argument                      (explicit override)
+ *   2. HEAL_STORE_PATH                           (operator override)
+ *   3. compile-time default ("{repository_path}")
+ *
+ * If `ENV` or `HELIX_ENV` is set, the chosen path is auto-suffixed with the
+ * env slug — e.g. `./self-heals/healed-locators.json` →
+ * `./self-heals/healed-locators.qa4.json` — so parallel runs against
+ * different test environments don't trample each other's healed selectors.
+ */
+function _resolveHealStorePath(override?: string): string {{
+  const base = override ?? process.env.HEAL_STORE_PATH ?? "{repository_path}";
+  const envTag = (process.env.ENV ?? process.env.HELIX_ENV ?? "").trim().toLowerCase();
+  if (!envTag) return base;
+  const ext = path.extname(base);
+  if (ext) return base.slice(0, -ext.length) + "." + envTag + ext;
+  return base + "." + envTag;
 }}
 
 /**
  * LocatorRepository — Shared state store for all healing layers.
- * Persists to "{repository_path}".
+ *
+ * Persisted on-disk format (HEAL_STORE_VERSION=1):
+ *   {{ "_version": 1, "entries": {{ <key>: LocatorEntry, ... }} }}
+ *
+ * Legacy v0 files (flat {{ <key>: LocatorEntry, ... }}) are still readable.
+ * On first write after load, the file is upgraded to the v1 envelope.
+ *
+ * History retention is controlled by ENABLE_LOCATOR_VERSIONING:
+ *   • unset / "true"  → keep the full healingHistory[] of every heal (default)
+ *   • "false"         → keep only the latest heal entry (lighter file)
+ *
+ * History length is capped by HEAL_HISTORY_CAP (default 50). Setting to 0
+ * disables the cap; otherwise the array keeps the most recent N entries so
+ * heavily-healed locators don't grow the file unboundedly.
+ *
+ * Writes are coalesced with a {{LOCATOR_REPO_DEBOUNCE_MS}}ms debounce — every
+ * mutation schedules a flush rather than writing synchronously. A flush is
+ * forced on process exit so no in-flight state is lost.
+ *
  * queueSuggestion / approveSuggestion / rejectSuggestion power the HealingDashboard.
  */
+const LOCATOR_REPO_DEBOUNCE_MS = 500;
+
+// Process-wide registry of every LocatorRepository instance, keyed by
+// resolved file path. A single set of exit hooks is registered on first
+// instantiation and flushes all known instances on shutdown. Required
+// because every page object instantiates its own LocatorRepository — if
+// each instance registered its own SIGINT/beforeExit listeners we'd hit
+// Node's MaxListenersExceededWarning at ~4 instances, and if each instance
+// only knew about its own state we'd lose data when the *last* instance to
+// write overwrote everyone else's heals.
+const _LIVE_REPOSITORIES: Map<string, LocatorRepository[]> = (() => {{
+  const g = globalThis as any;
+  if (!g.__locatorRepoRegistry) g.__locatorRepoRegistry = new Map();
+  return g.__locatorRepoRegistry as Map<string, LocatorRepository[]>;
+}})();
+
+let _exitHooksInstalled = false;
+function _installProcessExitHooks(): void {{
+  if (_exitHooksInstalled) return;
+  _exitHooksInstalled = true;
+  const flushAll = () => {{
+    _LIVE_REPOSITORIES.forEach(group => group.forEach(r => {{
+      try {{ r.flush(); }} catch {{}}
+    }}));
+  }};
+  process.once("beforeExit", flushAll);
+  process.once("SIGINT",     () => {{ flushAll(); process.exit(130); }});
+  process.once("SIGTERM",    () => {{ flushAll(); process.exit(143); }});
+}}
+
 export class LocatorRepository {{
   private readonly store = new Map<string, LocatorEntry>();
-  constructor(private readonly filePath = "{repository_path}") {{ this.load(); }}
+  // Versioning defaults to ON — matches the scaffold's historical behavior
+  // of always appending to healingHistory. Set ENABLE_LOCATOR_VERSIONING=false
+  // to keep only the latest heal entry.
+  private readonly versioningEnabled = process.env.ENABLE_LOCATOR_VERSIONING !== "false";
+  private readonly historyCap = (() => {{
+    const n = Number(process.env.HEAL_HISTORY_CAP ?? 50);
+    return Number.isFinite(n) && n >= 0 ? n : 50;
+  }})();
+  private flushTimer: NodeJS.Timeout | null = null;
+  readonly filePath: string;
+
+  constructor(filePath?: string) {{
+    this.filePath = _resolveHealStorePath(filePath);
+    this.load();
+    const group = _LIVE_REPOSITORIES.get(this.filePath) ?? [];
+    group.push(this);
+    _LIVE_REPOSITORIES.set(this.filePath, group);
+    _installProcessExitHooks();
+  }}
 
   register(key: string, selector: string, intent: string, stability = 0): void {{
-    if (!this.store.has(key))
+    const existing = this.store.get(key);
+    if (!existing) {{
       this.store.set(key, {{ selector, intent, stability, healingHistory: [], successCount: 0, failureCount: 0 }});
-    else {{ this.store.get(key)!.intent = intent; this.store.get(key)!.stability = stability; }}
+      return;
+    }}
+    // Always re-sync the baseline `selector` so the heal-store stays in
+    // step with source-code edits (e.g. dashboard Confirm just wrote a
+    // healed selector back into the locator .ts file — next register call
+    // should reflect that). If the new baseline now equals the previously
+    // healed selector, drop the heal state: the source has caught up and
+    // the entry's just a baseline registration again.
+    existing.intent = intent;
+    existing.stability = stability;
+    if (existing.healedSelector && existing.healedSelector === selector) {{
+      delete existing.healedSelector;
+      delete existing.lastHealed;
+      delete existing.approvedAt;
+      existing.healingHistory = [];
+    }}
+    existing.selector = selector;
   }}
 
   getHealed(key: string): string | undefined {{ return this.store.get(key)?.healedSelector; }}
 
   updateHealed(key: string, sel: string, intent: string, strategy = "unknown"): void {{
     const e = this.store.get(key); if (!e) return;
-    e.healingHistory.push({{ from: e.healedSelector ?? e.selector, to: sel,
-                             timestamp: new Date().toISOString(), strategy }});
+    const entry = {{ from: e.healedSelector ?? e.selector, to: sel,
+                     timestamp: new Date().toISOString(), strategy }};
+    if (this.versioningEnabled) {{
+      e.healingHistory.push(entry);
+      // Trim oldest entries when history exceeds the cap so the JSON file
+      // stays bounded even for locators that heal hundreds of times.
+      if (this.historyCap > 0 && e.healingHistory.length > this.historyCap) {{
+        e.healingHistory = e.healingHistory.slice(-this.historyCap);
+      }}
+    }} else {{
+      // Keep only the most recent heal so the JSON file stays small. The
+      // current selector is on `healedSelector` itself; the single-element
+      // history exists just so consumers (dashboard, exportJson) still see
+      // *something* in the array.
+      e.healingHistory = [entry];
+    }}
     e.healedSelector = sel; e.lastHealed = new Date().toISOString();
-    delete e.pendingSuggestion; this.persist();
+    delete e.pendingSuggestion;
+    this._appendHealLog(key, strategy, sel);
+    // Force-flush on heal events so the operator can see the healed
+    // selector in the JSON file immediately — debouncing is fine for
+    // incrementSuccess / incrementFailure (which fire on every step) but
+    // would hide the heal-store change behind a 500ms delay an interrupted
+    // test run could miss.
+    this.flush();
+  }}
+
+  /**
+   * Append a one-line record per heal to `./self-heals/heal.log`
+   * (override path via HEAL_LOG_PATH). Format is tab-separated:
+   *
+   *   <ISO timestamp>\\t<key>\\t<strategy>\\t<selector>
+   *
+   * Set HEAL_LOG_PATH=/dev/null (or HEAL_LOG_DISABLED=true) to skip.
+   */
+  private _appendHealLog(key: string, strategy: string, selector: string): void {{
+    if (process.env.HEAL_LOG_DISABLED === "true") return;
+    try {{
+      const logPath = process.env.HEAL_LOG_PATH
+        ?? path.join(path.dirname(this.filePath), "heal.log");
+      if (logPath === "/dev/null") return;
+      fs.mkdirSync(path.dirname(logPath), {{ recursive: true }});
+      const line = `${{new Date().toISOString()}}\\t${{key}}\\t${{strategy}}\\t${{selector}}\\n`;
+      fs.appendFileSync(logPath, line, "utf8");
+    }} catch {{}}
   }}
 
   queueSuggestion(key: string, suggestedSelector: string, strategy: string): void {{
@@ -3317,27 +3671,119 @@ export class LocatorRepository {{
     }};
   }}
 
+  /** Predicate: should this entry be written to disk? */
+  private _isPersistable(v: LocatorEntry): boolean {{
+    // Only entries with an actual heal recorded (healedSelector) or a
+    // pending suggestion awaiting review qualify. Pure-registered baseline
+    // entries (`register(...)` was called on construction but the locator
+    // has never needed healing) stay in memory only — keeps the JSON file
+    // focused on what humans actually need to look at.
+    return Boolean(v.healedSelector) || Boolean(v.pendingSuggestion);
+  }}
+
   exportJson(): string {{
-    const o: Record<string, LocatorEntry> = {{}};
-    this.store.forEach((v, k) => {{ o[k] = v; }});
-    return JSON.stringify(o, null, 2);
+    const entries: Record<string, LocatorEntry> = {{}};
+    this.store.forEach((v, k) => {{
+      if (this._isPersistable(v)) entries[k] = v;
+    }});
+    return JSON.stringify({{
+      _version: HEAL_STORE_VERSION,
+      _writtenAt: new Date().toISOString(),
+      entries,
+    }}, null, 2);
   }}
 
+  /**
+   * Schedule a debounced flush of the in-memory store to disk. Multiple
+   * mutations within {{LOCATOR_REPO_DEBOUNCE_MS}}ms coalesce into one write —
+   * a big speedup for parallel runs that previously triggered a synchronous
+   * file write on every step.
+   */
   private persist(): void {{
+    if (this.flushTimer) return;
+    this.flushTimer = setTimeout(() => {{
+      this.flushTimer = null;
+      this._writeNow();
+    }}, LOCATOR_REPO_DEBOUNCE_MS);
+    // Keep node alive long enough for the flush; cleared on _writeNow.
+    this.flushTimer.unref?.();
+  }}
+
+  /** Force an immediate synchronous write — used by exit hooks and tests. */
+  flush(): void {{
+    if (this.flushTimer) {{ clearTimeout(this.flushTimer); this.flushTimer = null; }}
+    this._writeNow();
+  }}
+
+  private _writeNow(): void {{
     try {{
       fs.mkdirSync(path.dirname(this.filePath), {{ recursive: true }});
-      fs.writeFileSync(this.filePath, this.exportJson(), "utf8");
+      // Read-modify-write: merge in-memory state on top of whatever's on
+      // disk so concurrent LocatorRepository instances (one per page object
+      // class, plus per-worker copies in parallel cucumber runs) don't
+      // trample each other's heals. Last writer still wins per-key, but
+      // *keys this instance has never touched* are preserved.
+      const merged = this._mergeWithDisk();
+      fs.writeFileSync(this.filePath, merged, "utf8");
     }} catch {{}}
   }}
 
-  private load(): void {{
+  /**
+   * Serialize the on-disk state, overlay this instance's in-memory changes,
+   * and return the resulting JSON string. Preserves entries the current
+   * instance doesn't know about (held by sibling LocatorRepository instances
+   * or written by a previous test run).
+   */
+  private _mergeWithDisk(): string {{
+    let onDisk: Record<string, LocatorEntry> = {{}};
     try {{
       if (fs.existsSync(this.filePath)) {{
         const raw = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
-        Object.entries(raw).forEach(([k, v]) => this.store.set(k, v as LocatorEntry));
+        if (raw && typeof raw === "object" && "entries" in raw && raw.entries) {{
+          onDisk = raw.entries as Record<string, LocatorEntry>;
+        }} else if (raw && typeof raw === "object") {{
+          for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {{
+            if (!k.startsWith("_")) onDisk[k] = v as LocatorEntry;
+          }}
+        }}
+      }}
+    }} catch {{}}
+    // Overlay this instance's state, then filter to only the entries worth
+    // persisting (healed or pending). Pure-registered baseline entries drop
+    // out of the file, while heals from sibling LocatorRepository instances
+    // remain (read from disk above).
+    this.store.forEach((v, k) => {{ onDisk[k] = v; }});
+    const filtered: Record<string, LocatorEntry> = {{}};
+    for (const [k, v] of Object.entries(onDisk)) {{
+      if (this._isPersistable(v)) filtered[k] = v;
+    }}
+    return JSON.stringify({{
+      _version: HEAL_STORE_VERSION,
+      _writtenAt: new Date().toISOString(),
+      entries: filtered,
+    }}, null, 2);
+  }}
+
+  private load(): void {{
+    try {{
+      if (!fs.existsSync(this.filePath)) return;
+      const raw = JSON.parse(fs.readFileSync(this.filePath, "utf8"));
+      // v1 envelope: {{ _version, entries: {{...}} }}
+      if (raw && typeof raw === "object" && "entries" in raw && raw.entries) {{
+        Object.entries(raw.entries as Record<string, unknown>).forEach(([k, v]) => {{
+          this.store.set(k, v as LocatorEntry);
+        }});
+        return;
       }}
+      // Legacy v0 (flat map). Read it; the next persist() upgrades the file.
+      Object.entries(raw as Record<string, unknown>).forEach(([k, v]) => {{
+        // Defensive: skip top-level metadata keys that happen to start with "_".
+        if (k.startsWith("_")) return;
+        this.store.set(k, v as LocatorEntry);
+      }});
     }} catch {{}}
   }}
+
 }}
 '''
 
@@ -3460,7 +3906,7 @@ export class VisualIntentChecker {{
         return;
       }}
       const screenshot = await loc.screenshot({{ timeout: 5_000 }});
-      fs.writeFileSync(actual, screenshot);
+      fs.writeFileSync(actual, new Uint8Array(screenshot));
       if (!fs.existsSync(baseline)) {{
         fs.copyFileSync(actual, baseline);
         this.logger.info(`📸 VisualIntent: new baseline saved for "${{key}}"`);
@@ -3493,6 +3939,34 @@ export class VisualIntentChecker {{
 '''
 
 
+def _gen_dashboard_server_cls():
+    """
+    Standalone launcher for the HealingDashboard HTTP server.
+
+    Invoked by the `healix:dashboard` and `healix:review` npm scripts. Loads
+    .env first so HEAL_STORE_PATH / HEALING_DASHBOARD_PORT / HEALIX_REVIEW_PORT
+    are honored without re-running the whole test suite.
+    """
+    return '''import "dotenv/config";
+import { HealingDashboard } from "./HealingDashboard";
+
+const dash = new HealingDashboard();
+dash.start();
+
+function shutdown(code: number): void {
+  try { dash.stop(); } catch {}
+  process.exit(code);
+}
+
+process.on("SIGINT",  () => shutdown(130));
+process.on("SIGTERM", () => shutdown(143));
+
+// Idle for ever — Node would otherwise exit because the HTTP server's only
+// effective work happens inside its event loop.
+setInterval(() => {}, 1 << 30);
+'''
+
+
 def _gen_healing_dashboard_cls(repository_path, dashboard_port):
     return f'''import * as fs   from "fs";
 import * as path from "path";
@@ -3502,56 +3976,184 @@ import * as url  from "url";
 /**
  * HealingDashboard — CI/CD Telemetry for AI-Suggested Changes
  *
- * Zero-dependency HTTP server displaying all pending suggestions from:
- *   • LocatorHealer  → AI Vision selector suggestions
- *   • TimingHealer   → auto-adjusted timeout suggestions
- *   • VisualIntentChecker → visual baseline update suggestions
+ * Two-server design:
+ *
+ *   1. **Dashboard server** (HEALING_DASHBOARD_PORT, default {dashboard_port}) —
+ *      full read/write UI for engineers; serves the HTML dashboard and the
+ *      approve / reject endpoints that commit changes to the heal store.
+ *      Set HEALING_DASHBOARD_PORT=0 to disable.
+ *
+ *   2. **Review server** (HEALIX_REVIEW_PORT, optional) — read-only mirror
+ *      for QA leads / managers / external dashboards. Serves the same JSON
+ *      endpoints (`/api/healed`, `/api/pending`, `/api/analytics`,
+ *      `/api/heal-log`) but rejects any POST. Off by default — set
+ *      HEALIX_REVIEW_PORT=<port> to enable.
  *
- * Endpoints:
+ * Dashboard endpoints (read/write):
  *   GET  /                  → HTML dashboard (auto-refreshes every 10s)
- *   GET  /api/pending       → JSON pending suggestions
+ *   GET  /api/healed        → JSON of all healed locators (current state)
+ *   GET  /api/pending       → JSON pending AI suggestions
  *   GET  /api/analytics     → JSON healing analytics
- *   POST /api/approve/:key  → Approve → commit to {repository_path}
+ *   GET  /api/heal-log      → Tail of the heal log (recent heals, plain text)
+ *   POST /api/approve/:key  → Approve → commit to the heal store
  *   POST /api/reject/:key   → Reject → discard
  *   GET  /api/visual/:key   → Serve actual PNG for visual diff review
  *
- * Set HEALING_DASHBOARD_PORT=0 to disable the HTTP server in CI pipelines.
- * Suggestions are still written to {repository_path} for async review.
+ * Suggestions are written to the heal store regardless of dashboard state,
+ * so async review still works even when both servers are disabled.
+ */
+/**
+ * Locate the `<bareKey>: {{ selector: "<oldSelector>", ... }}` entry inside a
+ * `*.locators.ts` source string and rewrite the `selector` field to point at
+ * `newSelector`. Idempotent — if the entry isn't present or the selector
+ * doesn't match `oldSelector`, the content is returned unchanged.
+ *
+ * Quote handling: TypeScript locator files use double-quoted strings by
+ * convention (this matches `locator_registrar.py`'s `_quote` preference),
+ * but we also accept single-quoted and back-ticked forms for robustness.
+ * The rewrite preserves the quote style.
+ *
+ * Lives at module scope (not inside the class) so the surrounding Python
+ * f-string template doesn't have to deal with the regex backslashes that
+ * a class method would require — they get tangled into invalid syntax
+ * once the f-string evaluates.
+ */
+function LocatorHealer_rewriteEntrySelector(
+  content: string, bareKey: string, oldSelector: string, newSelector: string,
+): string {{
+  if (oldSelector === newSelector) return content;
+  const REGEX_META = ".*+?^${{}}()|[]\\\\";
+  const escForRegex = (s: string) => {{
+    let out = "";
+    for (const c of s) {{
+      if (REGEX_META.indexOf(c) >= 0) out += "\\\\";
+      out += c;
+    }}
+    return out;
+  }};
+  const escForStringBody = (s: string, quote: string) => {{
+    let out = "";
+    for (const c of s) {{
+      if (c === "\\\\" || c === quote) out += "\\\\";
+      out += c;
+    }}
+    return out;
+  }};
+  let result = content;
+  for (const quote of ['"', "'", "`"]) {{
+    // Allow the source `oldSelector` to use either a literal quote or an
+    // escaped one. We don't try to be exhaustive — most real heal entries
+    // contain neither.
+    const oldEscaped = escForRegex(oldSelector);
+    const pattern = new RegExp(
+      "(\\\\b" + escForRegex(bareKey) + "\\\\s*:\\\\s*\\\\{{\\\\s*selector\\\\s*:\\\\s*" +
+      quote + ")" + oldEscaped + "(" + quote + ")",
+      "g",
+    );
+    result = result.replace(pattern, (_m, prefix: string, q: string) => {{
+      return prefix + escForStringBody(newSelector, q) + q;
+    }});
+  }}
+  return result;
+}}
+
+/**
+ * Resolve the heal-store path with the same env-suffix logic the
+ * LocatorRepository uses, so the dashboard reads the file the test run
+ * actually wrote (e.g. `healed-locators.qa4.json` when ENV=qa4).
+ *
+ * Inlined rather than imported from LocatorRepository.ts to keep the
+ * dashboard server self-contained — it can boot without ever loading the
+ * full repository class (which would also install exit hooks etc.).
+ */
+function _resolveDashboardStorePath(override?: string): string {{
+  const base = override ?? process.env.HEAL_STORE_PATH ?? "{repository_path}";
+  const envTag = (process.env.ENV ?? process.env.HELIX_ENV ?? "").trim().toLowerCase();
+  if (!envTag) return base;
+  const ext = path.extname(base);
+  if (ext) return base.slice(0, -ext.length) + "." + envTag + ext;
+  return base + "." + envTag;
+}}
+
+/**
+ * List every heal-store sibling of `primary` — i.e. files in the same
+ * directory whose basename starts with the same stem (e.g. given
+ * `./self-heals/healed-locators.json`, return `healed-locators.json`,
+ * `healed-locators.qa4.json`, `healed-locators.dev1.json`, ...). Lets the
+ * dashboard show heals from all environments when the operator launches
+ * `healix:dashboard` without an explicit ENV.
  */
+function _siblingStoreFiles(primary: string): string[] {{
+  try {{
+    const dir = path.dirname(primary);
+    const base = path.basename(primary);
+    const ext = path.extname(base);
+    const stem = ext ? base.slice(0, -ext.length) : base;
+    // Strip any existing `.<env>` suffix so siblings of `*.qa4.json`
+    // resolve as well as siblings of `*.json`.
+    const root = stem.split(".")[0];
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(name => name.startsWith(root + ".") || name === root + (ext || ".json"))
+      .filter(name => name.endsWith(ext || ".json"))
+      .map(name => path.join(dir, name));
+  }} catch {{
+    return [];
+  }}
+}}
+
 export class HealingDashboard {{
   private server: http.Server | null = null;
+  private reviewServer: http.Server | null = null;
   private readonly port: number;
-
-  constructor(
-    private readonly repoPath = "{repository_path}",
-    port = {dashboard_port},
-  ) {{
-    this.port = Number(process.env.HEALING_DASHBOARD_PORT ?? port);
+  private readonly reviewPort: number;
+  private readonly repoPath: string;
+
+  constructor(repoPathOverride?: string, port = {dashboard_port}) {{
+    this.repoPath   = _resolveDashboardStorePath(repoPathOverride);
+    this.port       = Number(process.env.HEALING_DASHBOARD_PORT ?? port);
+    // Review server is opt-in (default 0 = disabled) so we don't grab a
+    // random port without the operator asking for it.
+    this.reviewPort = Number(process.env.HEALIX_REVIEW_PORT ?? 0);
   }}
 
   start(): void {{
-    if (this.port === 0) return;
-    this.server = http.createServer((req, res) => this._route(req, res));
-    this.server.listen(this.port, () => {{
-      console.log(`\\n🩺 HealingDashboard running at http://localhost:${{this.port}}`);
-      console.log(`   Approve or reject AI-suggested changes before committing.\\n`);
-    }});
+    if (this.port !== 0) {{
+      this.server = http.createServer((req, res) => this._route(req, res, /* readOnly */ false));
+      this.server.listen(this.port, () => {{
+        console.log(`\\n🩺 HealingDashboard running at http://localhost:${{this.port}}`);
+        console.log(`   Approve or reject AI-suggested changes before committing.\\n`);
+      }});
+    }}
+    if (this.reviewPort !== 0 && this.reviewPort !== this.port) {{
+      this.reviewServer = http.createServer((req, res) => this._route(req, res, /* readOnly */ true));
+      this.reviewServer.listen(this.reviewPort, () => {{
+        console.log(`👁  HealingReview (read-only) at http://localhost:${{this.reviewPort}}\\n`);
+      }});
+    }}
   }}
 
-  stop(): void {{ this.server?.close(); }}
+  stop(): void {{ this.server?.close(); this.reviewServer?.close(); }}
 
-  private _route(req: http.IncomingMessage, res: http.ServerResponse): void {{
+  private _route(req: http.IncomingMessage, res: http.ServerResponse, readOnly: boolean): void {{
     const p = url.parse(req.url ?? "/").pathname ?? "/";
     const m = req.method ?? "GET";
     res.setHeader("Access-Control-Allow-Origin", "*");
     if (m === "OPTIONS") {{ res.writeHead(204); res.end(); return; }}
 
-    if (m === "GET"  && p === "/")              {{ res.writeHead(200, {{"Content-Type":"text/html"}}); res.end(this._html()); return; }}
+    if (m === "GET"  && p === "/")              {{ res.writeHead(200, {{"Content-Type":"text/html"}}); res.end(this._html(readOnly)); return; }}
+    if (m === "GET"  && p === "/api/healed")    {{ res.writeHead(200, {{"Content-Type":"application/json"}}); res.end(JSON.stringify(this._healed(), null, 2)); return; }}
     if (m === "GET"  && p === "/api/pending")   {{ res.writeHead(200, {{"Content-Type":"application/json"}}); res.end(JSON.stringify(this._pending(), null, 2)); return; }}
     if (m === "GET"  && p === "/api/analytics") {{ res.writeHead(200, {{"Content-Type":"application/json"}}); res.end(JSON.stringify(this._analytics(), null, 2)); return; }}
+    if (m === "GET"  && p === "/api/heal-log")  {{ res.writeHead(200, {{"Content-Type":"text/plain"}}); res.end(this._healLogTail()); return; }}
 
     const am = p.match(/^[/]api[/](approve|reject)[/](.+)$/);
     if (m === "POST" && am) {{
+      if (readOnly) {{
+        res.writeHead(403, {{"Content-Type":"application/json"}});
+        res.end(JSON.stringify({{ error: "read-only review server" }}));
+        return;
+      }}
       const ok = am[1] === "approve"
         ? this._approve(decodeURIComponent(am[2]))
         : this._reject(decodeURIComponent(am[2]));
@@ -3571,12 +4173,127 @@ export class HealingDashboard {{
     res.writeHead(404); res.end("Not found");
   }}
 
+  /** All healed locators (current state). Used by the dashboard UI and `/api/healed`. */
+  private _healed(): Array<{{ key: string; selector: string; healedSelector: string; intent: string; lastHealed?: string; strategy?: string }}> {{
+    return Object.entries(this._load())
+      .filter(([, v]) => (v as any).healedSelector)
+      .map(([k, v]) => {{
+        const entry = v as any;
+        const lastHistory = entry.healingHistory?.[entry.healingHistory.length - 1];
+        return {{
+          key: k,
+          selector:        entry.selector,
+          healedSelector:  entry.healedSelector,
+          intent:          entry.intent,
+          lastHealed:      entry.lastHealed,
+          strategy:        lastHistory?.strategy,
+        }};
+      }});
+  }}
+
+  /** Tail of the heal log (./self-heals/heal.log by default). Plain text. */
+  private _healLogTail(): string {{
+    try {{
+      const logPath = process.env.HEAL_LOG_PATH
+        ?? path.join(path.dirname(this.repoPath), "heal.log");
+      if (!fs.existsSync(logPath)) return "";
+      const content = fs.readFileSync(logPath, "utf8");
+      // Return only the last ~500 lines so the response stays small.
+      const lines = content.split("\\n");
+      return lines.slice(-500).join("\\n");
+    }} catch {{
+      return "";
+    }}
+  }}
+
+  // Per-key source-file map populated by `_load()`. Required so dashboard
+  // approve/reject (`_save()`) writes the entry back to the SAME file it
+  // came from when multiple heal stores (e.g. healed-locators.qa4.json and
+  // healed-locators.dev1.json) coexist in the same directory.
+  private _entrySource: Map<string, string> = new Map();
+
+  /** Read a single heal-store file, returning its `entries` map (or {{}}). */
+  private _readStore(filePath: string): Record<string, any> {{
+    try {{
+      const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+      if (raw && typeof raw === "object" && "entries" in raw && raw.entries) {{
+        return raw.entries as Record<string, any>;
+      }}
+      // Legacy flat shape — strip top-level metadata keys (`_*`).
+      const out: Record<string, any> = {{}};
+      for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {{
+        if (!k.startsWith("_")) out[k] = v;
+      }}
+      return out;
+    }} catch {{
+      return {{}};
+    }}
+  }}
+
+  /**
+   * Load heal entries — primary file first, then sibling env-suffixed
+   * files in the same directory (so a single dashboard process shows heals
+   * from `healed-locators.qa4.json`, `healed-locators.dev1.json`, etc.
+   * without the operator having to set ENV).
+   *
+   * Each entry's source file is remembered in `_entrySource` so subsequent
+   * approve/reject calls (`_save()`) write the updated entry back to the
+   * exact file it came from.
+   */
   private _load(): Record<string, any> {{
-    try {{ return JSON.parse(fs.readFileSync(this.repoPath, "utf8")); }} catch {{ return {{}}; }}
+    this._entrySource.clear();
+    const merged: Record<string, any> = {{}};
+    const candidates = new Set<string>([this.repoPath, ..._siblingStoreFiles(this.repoPath)]);
+    for (const file of candidates) {{
+      if (!fs.existsSync(file)) continue;
+      const entries = this._readStore(file);
+      for (const [k, v] of Object.entries(entries)) {{
+        merged[k] = v;
+        // Last file wins on key conflict — should never happen since
+        // env-suffixed files describe different environments.
+        this._entrySource.set(k, file);
+      }}
+    }}
+    return merged;
   }}
-  private _save(d: Record<string, any>): void {{
-    fs.mkdirSync(path.dirname(this.repoPath), {{ recursive: true }});
-    fs.writeFileSync(this.repoPath, JSON.stringify(d, null, 2), "utf8");
+
+  /**
+   * Persist the post-approve/reject state.
+   *
+   * Entries get grouped by their original source file (tracked in
+   * `_entrySource`) and each file is re-emitted in the v1 envelope shape
+   * with the heal-only filter applied. Entries we have no source for
+   * (shouldn't happen in practice — they came from `_load()`) fall back
+   * to the configured `repoPath`.
+   */
+  private _save(entries: Record<string, any>): void {{
+    const buckets: Map<string, Record<string, any>> = new Map();
+    for (const [k, v] of Object.entries(entries)) {{
+      const source = this._entrySource.get(k) ?? this.repoPath;
+      let bucket = buckets.get(source);
+      if (!bucket) {{ bucket = {{}}; buckets.set(source, bucket); }}
+      bucket[k] = v;
+    }}
+    // Make sure every file that originally had entries gets a re-emit
+    // (so deletions / reverts actually persist) — even if every entry was
+    // rejected.
+    for (const source of this._entrySource.values()) {{
+      if (!buckets.has(source)) buckets.set(source, {{}});
+    }}
+    for (const [file, fileEntries] of buckets) {{
+      fs.mkdirSync(path.dirname(file), {{ recursive: true }});
+      const filtered: Record<string, any> = {{}};
+      for (const [k, v] of Object.entries(fileEntries)) {{
+        const vv = v as any;
+        if (vv?.healedSelector || vv?.pendingSuggestion) filtered[k] = vv;
+      }}
+      const envelope = {{
+        _version: 1,
+        _writtenAt: new Date().toISOString(),
+        entries: filtered,
+      }};
+      fs.writeFileSync(file, JSON.stringify(envelope, null, 2), "utf8");
+    }}
   }}
 
   private _pending(): any[] {{
@@ -3609,33 +4326,130 @@ export class HealingDashboard {{
     }};
   }}
 
+  /**
+   * Approve a heal or a pending suggestion.
+   *
+   * Two flows converge here:
+   *   • Pending suggestion (AI Vision, etc.) — commits suggestion.selector to
+   *     healedSelector and clears the pending state.
+   *   • Already-healed entry (automatic strategy succeeded mid-test) — stamps
+   *     `approvedAt` on the most recent history record so future runs know
+   *     a human has signed off; the selector itself is unchanged.
+   *
+   * Either way, the healed selector is propagated back to the source
+   * locator `.ts` file by `_writeBackToLocatorFile` so the next test run
+   * starts with the corrected primary selector (no healing chain probe
+   * needed until the page changes again).
+   *
+   * Returns false only when the key isn't in the store at all.
+   */
   private _approve(key: string): boolean {{
     const d = this._load(); const e = d[key];
-    if (!e?.pendingSuggestion) return false;
-    e.healingHistory.push({{
-      from: e.healedSelector ?? e.selector, to: e.pendingSuggestion.selector,
-      timestamp: new Date().toISOString(), strategy: e.pendingSuggestion.strategy + ":dashboard-approved",
-    }});
-    e.healedSelector = e.pendingSuggestion.selector;
-    delete e.pendingSuggestion;
-    this._save(d);
-    console.log(`✅ HealingDashboard: approved "${{key}}"`);
-    return true;
+    if (!e) return false;
+    if (e.pendingSuggestion) {{
+      e.healingHistory = e.healingHistory ?? [];
+      e.healingHistory.push({{
+        from: e.healedSelector ?? e.selector, to: e.pendingSuggestion.selector,
+        timestamp: new Date().toISOString(), strategy: e.pendingSuggestion.strategy + ":dashboard-approved",
+      }});
+      const oldSelector = e.healedSelector ?? e.selector;
+      e.healedSelector = e.pendingSuggestion.selector;
+      delete e.pendingSuggestion;
+      const wrote = this._writeBackToLocatorFile(key, oldSelector, e.healedSelector);
+      if (wrote) e.appliedToSourceAt = new Date().toISOString();
+      this._save(d);
+      console.log(`✅ HealingDashboard: approved suggestion for "${{key}}"${{wrote ? " + applied to locator file" : ""}}`);
+      return true;
+    }}
+    if (e.healedSelector) {{
+      // Confirm an automatically-applied heal — record the approval AND
+      // propagate the healed selector back to the locator .ts file so the
+      // primary probe on next run uses the corrected value.
+      e.approvedAt = new Date().toISOString();
+      if (e.healingHistory?.length) {{
+        e.healingHistory[e.healingHistory.length - 1].strategy += ":dashboard-approved";
+      }}
+      const wrote = this._writeBackToLocatorFile(key, e.selector, e.healedSelector);
+      if (wrote) e.appliedToSourceAt = new Date().toISOString();
+      this._save(d);
+      console.log(`✅ HealingDashboard: confirmed heal for "${{key}}"${{wrote ? " + applied to locator file" : ""}}`);
+      return true;
+    }}
+    return false;
   }}
 
+  /**
+   * Rewrite the `selector:` field for a single locator entry inside a
+   * `*.locators.ts` file. Matches by `<key>: {{ selector: "<oldSelector>", ...`
+   * so we only touch the exact entry the heal came from — bare-key callers
+   * (e.g. heal key = `"usernameInput"`) still resolve because the locator
+   * file uses bare keys inside the `xxxLocators = {{ ... }}` object literal.
+   *
+   * Handles all three TypeScript string forms — `"..."`, `'...'`, and
+   * `` `...` `` — and preserves the quote style when writing back.
+   *
+   * Scans every `*.ts` file under `LOCATOR_FILES_DIR` (default
+   * `./src/locators`). Returns true if any file was modified.
+   */
+  private _writeBackToLocatorFile(key: string, oldSelector: string, newSelector: string): boolean {{
+    if (!oldSelector || !newSelector || oldSelector === newSelector) return false;
+    const dir = process.env.LOCATOR_FILES_DIR ?? "./src/locators";
+    if (!fs.existsSync(dir)) return false;
+    const bareKey = key.includes(".") ? (key.split(".").pop() ?? key) : key;
+    let updated = false;
+    const visit = (d: string): void => {{
+      for (const entry of fs.readdirSync(d, {{ withFileTypes: true }})) {{
+        const p = path.join(d, entry.name);
+        if (entry.isDirectory()) {{ visit(p); continue; }}
+        if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
+        let content = fs.readFileSync(p, "utf8");
+        const next = LocatorHealer_rewriteEntrySelector(content, bareKey, oldSelector, newSelector);
+        if (next !== content) {{
+          fs.writeFileSync(p, next, "utf8");
+          updated = true;
+          console.log(`  ✓ wrote new selector for "${{bareKey}}" → ${{p}}`);
+        }}
+      }}
+    }};
+    try {{ visit(dir); }} catch {{}}
+    return updated;
+  }}
+
+  /**
+   * Reject a heal or pending suggestion. The entry is reverted to its
+   * baseline (only `selector`/`intent`/`stability` remain) and *not*
+   * persisted by the next write — the LocatorRepository filter keeps only
+   * entries with healedSelector or pendingSuggestion. Effectively, reject
+   * makes the bad heal disappear from the file.
+   */
   private _reject(key: string): boolean {{
     const d = this._load(); const e = d[key];
-    if (!e?.pendingSuggestion) return false;
-    console.log(`❌ HealingDashboard: rejected "${{key}}"`);
+    if (!e) return false;
+    const had = Boolean(e.pendingSuggestion) || Boolean(e.healedSelector);
+    if (!had) return false;
     delete e.pendingSuggestion;
+    delete e.healedSelector;
+    delete e.lastHealed;
+    delete e.approvedAt;
+    e.healingHistory = [];
     this._save(d);
+    // Re-save filters: an entry with no heal state no longer qualifies,
+    // so the file no longer mentions this key. The page-object's
+    // constructor will re-register the baseline on the next process start.
+    console.log(`❌ HealingDashboard: rejected heal for "${{key}}"`);
     return true;
   }}
 
-  private _html(): string {{
+  private _html(readOnly: boolean = false): string {{
     const pending   = this._pending();
+    const healed    = this._healed();
     const analytics = this._analytics();
-    const rows = pending.map(p => `
+    const actionsCell = (key: string, kind: string, visualLink: boolean) => readOnly
+      ? `<small style="color:#64748b">read-only</small>${{visualLink ? ` &middot; <a href="/api/visual/${{encodeURIComponent(key)}}" target="_blank" style="color:#818cf8">View diff</a>` : ""}}`
+      : `<button onclick="act('approve','${{encodeURIComponent(key)}}')" style="background:#22c55e;color:#000;border:none;padding:4px 10px;border-radius:3px;cursor:pointer">${{kind === "pending" ? "Approve" : "Confirm"}}</button>
+          <button onclick="act('reject','${{encodeURIComponent(key)}}')"  style="background:#ef4444;color:#fff;border:none;padding:4px 10px;border-radius:3px;cursor:pointer;margin-left:4px">${{kind === "pending" ? "Reject" : "Revert"}}</button>
+          ${{visualLink ? `<a href="/api/visual/${{encodeURIComponent(key)}}" target="_blank" style="color:#818cf8;margin-left:6px">View diff</a>` : ""}}`;
+    const pendingRows = pending.map(p => `
       <tr>
         <td><code>${{p.key}}</code></td>
         <td>${{p.intent}}</td>
@@ -3643,11 +4457,17 @@ export class HealingDashboard {{
         <td><code style="color:#f59e0b">${{p.suggestion.selector}}</code></td>
         <td>${{p.suggestion.strategy}}</td>
         <td><small>${{new Date(p.suggestion.suggestedAt).toLocaleString()}}</small></td>
-        <td>
-          <button onclick="act('approve','${{enc(p.key)}}')" style="background:#22c55e;color:#000;border:none;padding:4px 10px;border-radius:3px;cursor:pointer">Approve</button>
-          <button onclick="act('reject','${{enc(p.key)}}')"  style="background:#ef4444;color:#fff;border:none;padding:4px 10px;border-radius:3px;cursor:pointer;margin-left:4px">Reject</button>
-          ${{p.key.startsWith("visual:") ? `<a href="/api/visual/${{enc(p.key)}}" target="_blank" style="color:#818cf8;margin-left:6px">View diff</a>` : ""}}
-        </td>
+        <td>${{actionsCell(p.key, "pending", p.key.startsWith("visual:"))}}</td>
+      </tr>`).join("");
+    const healedRows = healed.map(h => `
+      <tr>
+        <td><code>${{h.key}}</code></td>
+        <td>${{h.intent}}</td>
+        <td><code style="color:#888">${{h.selector}}</code></td>
+        <td><code style="color:#22c55e">${{h.healedSelector}}</code></td>
+        <td>${{h.strategy ?? ""}}</td>
+        <td><small>${{h.lastHealed ? new Date(h.lastHealed).toLocaleString() : ""}}</small></td>
+        <td>${{actionsCell(h.key, "healed", h.key.startsWith("visual:"))}}</td>
       </tr>`).join("");
     return `<!DOCTYPE html>
 <html lang="en">
@@ -3657,12 +4477,13 @@ export class HealingDashboard {{
   <style>
     body {{ font-family: monospace; background:#0f172a; color:#e2e8f0; padding:24px }}
     h1   {{ color:#38bdf8; margin-bottom:4px }}
+    h2   {{ color:#94a3b8; margin:24px 0 8px; font-size:13px; letter-spacing:1px; text-transform:uppercase }}
     .sub {{ color:#64748b; font-size:12px; display:block; margin-bottom:20px }}
     .stats {{ display:flex; gap:12px; margin-bottom:20px }}
     .stat {{ background:#1e293b; border:1px solid #334155; border-radius:6px; padding:10px 16px }}
     .sv  {{ font-size:26px; font-weight:700; color:#38bdf8 }}
     .sl  {{ font-size:9px; color:#64748b; letter-spacing:1px }}
-    table{{ width:100%; border-collapse:collapse; background:#1e293b; border-radius:6px; overflow:hidden }}
+    table{{ width:100%; border-collapse:collapse; background:#1e293b; border-radius:6px; overflow:hidden; margin-bottom:24px }}
     th   {{ background:#0f172a; padding:9px 12px; font-size:9px; letter-spacing:1px; color:#64748b; text-align:left }}
     td   {{ padding:9px 12px; border-bottom:1px solid #334155; font-size:11px }}
   </style>
@@ -3671,25 +4492,39 @@ export class HealingDashboard {{
   <h1>🩺 Healing Dashboard</h1>
   <span class="sub">
     Auto-refreshes every 10s &middot;
-    <a href="/api/analytics" style="color:#818cf8">Analytics JSON</a> &middot;
-    Approve or reject AI suggestions before they are committed to the repository
+    <a href="/api/healed"    style="color:#818cf8">Healed JSON</a> &middot;
+    <a href="/api/pending"   style="color:#818cf8">Pending JSON</a> &middot;
+    <a href="/api/analytics" style="color:#818cf8">Analytics</a> &middot;
+    <a href="/api/heal-log"  style="color:#818cf8">Heal log</a>
   </span>
   <div class="stats">
-    <div class="stat"><div class="sv">${{analytics.pendingApprovals}}</div><div class="sl">PENDING</div></div>
     <div class="stat"><div class="sv">${{analytics.healedLocators}}</div><div class="sl">HEALED</div></div>
+    <div class="stat"><div class="sv">${{analytics.pendingApprovals}}</div><div class="sl">PENDING</div></div>
     <div class="stat"><div class="sv">${{analytics.timingSuggestions}}</div><div class="sl">TIMING</div></div>
     <div class="stat"><div class="sv">${{analytics.visualSuggestions}}</div><div class="sl">VISUAL</div></div>
   </div>
+
+  <h2>Healed locators</h2>
+  <table>
+    <thead>
+      <tr><th>Key</th><th>Intent</th><th>Original</th><th>Healed</th><th>Strategy</th><th>Last healed</th><th>Action</th></tr>
+    </thead>
+    <tbody>
+      ${{healedRows || '<tr><td colspan="7" style="padding:24px;text-align:center;color:#64748b">✓ No healed locators yet</td></tr>'}}
+    </tbody>
+  </table>
+
+  <h2>Pending AI suggestions</h2>
   <table>
     <thead>
       <tr><th>Key</th><th>Intent</th><th>Current</th><th>Suggested</th><th>Strategy</th><th>Time</th><th>Action</th></tr>
     </thead>
     <tbody>
-      ${{rows || '<tr><td colspan="7" style="padding:24px;text-align:center;color:#64748b">✓ No pending suggestions — all AI changes approved or no healing events yet</td></tr>'}}
+      ${{pendingRows || '<tr><td colspan="7" style="padding:24px;text-align:center;color:#64748b">✓ No pending suggestions</td></tr>'}}
     </tbody>
   </table>
+
   <script>
-    function enc(s) {{ return encodeURIComponent(s); }}
     async function act(action, key) {{
       await fetch("/api/" + action + "/" + key, {{ method: "POST" }});
       location.reload();