[philmcneely]

scripts/heal.py becomes a client of the heal service (spec: docs/HEAL_SERVICE_SPEC.md, in a separate PR). The framework no longer holds a model URL, a model name, a prompt or any parsing of model replies; a unit test checks that none of them come back.

Do not merge before the heal service's phase 1 is merged. The service is not public yet, so the integration test skips in CI with a stated reason.

What changes

• scripts/heal.py: same flags (-k, --max, --open-pr). It keeps the JUnit parse, the exact-test re-run, revert and the PR flow.
  • It now prints decisions with token usage and a run total, and writes heal-summary.json.
  • A service error or a failure past --max becomes a recorded needs_human decision instead of a crash.
• utils/heal_client.py: builds the request (stack files under the source roots, capped, with sha256), probes the reopened failing route, sends the language signals, and runs the try → result loop.
• utils/heal_fingerprints.py: a pytest plugin, off unless HEAL_FINGERPRINTS=on.
  • It records what each locator hit on a clean green run into .heal/fingerprints.json and writes .heal/.gitignore itself.
  • HEAL_FINGERPRINT_COPY=off stores hashes of page copy instead of the copy.
• utils/heal_locale.py: by_language, for healed copy-based locators on a page in another language.
• utils/heal_probe.js: the in-page probe, vendored and byte-identical to the service's copy.

Treating the service as untrusted

Every patch the service returns is checked before it touches a file. The client applies it only if all of these hold:

• the file's hash matches the base hash;
• the file sits under the source roots by real path, with no symlinks;
• the span holds exactly the old expression, and that expression is one locator chain in the file on disk;
• the new expression is one validated locator expression, with no comment and no control or bidi characters;
• it equals the code the client just checked on the live page (count 1, the expected element), and every other file's patch is checked the same way.

Other safeguards:

• Writes: they are reverted on any failure, and file modes are kept.
• Probe: the client runs its vendored copy and blocks other origins while it runs.
• No input values: they are never sent. Aria snapshots are redacted, and inventory keys go through an allowlist.
• Token over plain http: a bearer token over http:// to a non-localhost host is refused unless HEAL_ALLOW_INSECURE=1.
• PR body: text is markdown-escaped.

A security review of this branch found five HIGH issues. All are fixed, each with a test written first (tests/unit/test_heal_client_security.py).

Tests

• pytest tests/unit: 292 passed.
• ruff check .: clean.
• The integration test runs the real service in process against Chromium, including a French page, when heal-service is installed.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

[github-actions]

✅ All smoke tests passed! View report

[philmcneely]

No changes needed: the only feedback on this PR is the github-actions smoke-pass notice (lint, unit, smoke, setup and semgrep all green) and a Copilot review that didn't run because of quota. There's no review comment to act on, so I made no commit. The full suite is still pending.

[github-actions]

✅ All chromium login tests passed! View report

[github-actions]

✅ All firefox login tests passed! View report

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.