Reactive dependency auto-heal

What it is

The app's checks — the build, the tests, the lint run — work against a folder of dependencies. Occasionally an install is interrupted and leaves a package present but broken: the folder is there, but a file inside it is missing, so the check dies with a "cannot find module" error that names an absolute path into that folder. That is not a failure of your code; it is a torn dependency.

Reactive dependency auto-heal treats that as a repairable state. It reads the broken package's name out of the failure, repairs that one package (removing its tree and re-downloading it from the registry so the missing file comes back), and runs the check once more. If the check was only failing because of the tear, it now passes; if it was a genuine failure, the real failure comes back unchanged.

Where to find it

There is no screen for it — it is automatic. You meet it inside the checks the app runs for a branch, and in the one log line it writes when it repairs something: the check "failed naming torn package(s): X — repairing, then retrying once". On the app's own side, when one of its cloud features fails to start because a local dependency is corrupted, you meet it as a single inbox card that tells you to reinstall.

How it behaves

• It runs only after a failure. A check that passes is byte-for-byte the same as before; the repair never runs on a passing check.
• It names the package from the failure's own output rather than a fixed sentinel list, so any torn runtime package can be caught, not just the handful an install pre-check knows about.
• It repairs only the named package(s), scoped: that package's tree is removed and reinstalled without the offline preference, so the missing file is fetched again rather than restored from a store that no longer has it.
• It retries exactly once. There is a hard one-retry cap — never a loop, and never a masked error. A genuine failure is returned untouched.
• It fails closed. A repair that does not complete returns the original failure; and because a repair removes the tree before reinstalling, an interrupted repair can leave the package missing rather than merely broken, so it says that loudly and points at the full repair command instead of exiting as if nothing changed.
• It is bounded. Only packages pinned in the lockfile are repaired, and more than five packages named as missing is treated as a bulk problem rather than a surgical tear, so it stands down.
• A check the watchdog killed has timed out — a wedge, not a torn dependency — so it is never retried.
• The repair is off with a single switch (AMC_DISABLE_DEP_HEAL=1), and the app's own corrupted-dependency card is suppressed from error reporting and raised only once per session.

For agents

• The healer is scripts/lib/reactive-dep-heal.mjs; runWithDepHeal() wraps a check's own run and healTornPackages() shells scripts/ensure-node-modules.js --repair <pkg…> with an argv array (the package names come from untrusted failure text, so no shell).
• It wraps the local checks: scripts/checks/build-verify.mjs and scripts/run-lint-gated.mjs, the gated test run, and the cloud run path.
• The main-process companion is src/main/services/corrupt-dependency-error.ts (the pure classifier), surfaced as one inbox card by src/main/services/install/corrupt-dependency-alert.ts through the rate-limited error logger.

Related

• where-checks-run.md — the setting that decides where these checks run
• agent-git-paved-road.md — the CLI route that repairs a broken dependency folder
• crash-recovery.md — recovering from a broken state after an interrupted run
• dev-pipeline-maintenance.md — keeping the machine's build tools current