Heal

---
name: heal
description: Sweep every repo you are working on for vulnerabilities an attacker can actually reach, prove each one is reachable, and fix the ones that survive. One word starts the whole operation.
when_to_use: "Invoked when the user says \"heal\", \"sweep\", \"fix all the bugs\", \"check every app\", \"are we exposed\", or asks for a periodic security pass across projects."
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, Workflow, Task
model: opus
user-invocable: true
argument-hint: "[repo names, or nothing for the active ones]"
---

# Heal

One word, a whole operation. A bug found in one app is a bug suspected in every
app, so this runs the shared registry across all of them at once rather than one
repo at a time.

**The default filter is REACHABLE FROM OUTSIDE.** That is deliberate and it is the
thing that makes the output worth reading. Define untrusted actors at the actual
boundary, including authenticated low-privilege users when they can cross a
permission boundary. Do not equate “reachable” with “unauthenticated only”; that
would omit tenant-isolation and privilege-escalation defects. Keep style findings
separate from security claims.

## Run it

```
Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT}/scripts/heal-sweep.workflow.js",
  args: [ /* one entry per repo — see below */ ]
})
```

Three stages per repo, pipelined so one repo can be fixing while another is still
looking: **find → adversarially verify → fix in an isolated worktree.** Roughly
three agents per repo, so keep it to three or four repos unless the user raises the
cap.

## Building `args` — this is the whole job

```js
{
  name: 'myapp',
  path: '/absolute/path/to/repo',
  gate: 'npm run preflight',      // the repo's own verification command
  surface: '...'                  // REQUIRED — see below
}
```

**`surface` is the quality lever and the script refuses to run without it.** It
tells the agent what "reachable from outside" *means* for this particular repo.
Get it wrong and you get a confident report about an attack surface that does not
exist — a published CLI has no HTTP routes, and an agent sent looking for them will
either find nothing or invent something.

Write two or three sentences naming the real entry points. A web app: its serverless
routes, its edge functions, the database surface an anon key can touch, its webhook
receivers, its OAuth callbacks. A published package or plugin: what a stranger can
read in the tree, what a consumer executes on install, and any CI workflow that runs
untrusted code from a fork. A CLI: its argument parsing and anything it fetches.

Say which one is revenue-bearing or handles personal data. Severity is not a property
of the code alone.

## Picking the repos

Ask what is actually being worked on, or read it off the fleet:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/fleet-status.js" --days 2
```

Intersect observed activity with the current authorized repository scope.
Activity is a prioritization signal, not permission to mutate every visible repo.
Include older affected repositories when the shared defect or mandate calls for it.

**Never sweep a client repo into a shared report.** Check `git remote get-url origin`
first and exclude anything that is not the user's own.

## What comes back

Per repo: the enumerated attack surface with counts, the findings that survived
adversarial verification, the ones that were **refuted** and why, what was fixed with
its mutation test, what was skipped as needing a human call, and the gate result.

**Read the refuted list.** It is not filler — it is how you tell a real sweep from a
generator. Zero refutations alone says nothing about verification quality; read
the actual adversarial checks and controls. A detector that repeatedly cries wolf
needs its inputs and criteria corrected.

**Read `couldNotCheck` before you believe any zero.** A static read cannot see
runtime, live RLS policies, or deployed configuration. Silence must never be reported
as clean.

## The worktree trap — read this before the fix stage

`isolation: 'worktree'` on an agent creates the worktree from **the session's own
repo**, not from the repo the agent is being pointed at. If the session's cwd is not
a git repository, every fix agent dies with *"Cannot create agent worktree: not in a
git repository"* — after the find and verify stages have already been paid for.

That is exactly what happened on the first real run, 2026-08-22: two fix agents
errored on a session rooted in a directory that held only `.claude/` state and no
`.git`. The findings survived in the journal, but the fix stage was lost.

**The worse case is the one that does NOT error.** When the session's cwd *is* a
git repo, the agent gets a worktree of the wrong repo, notices nothing, and edits
the target's main clone — precisely where other live sessions keep uncommitted
work. A crash is recoverable; a silent write into somebody else's tree is not.

**Fixed in the script 2026-08-26.** This document prescribed the remedy from the
day the trap was found, and the script did not carry it for four days, because no
suite read that file. The 2026-08-26 sweep worked around it by hand in all four
fix agents before it was fixed properly. `tooling/test-workflow-isolation.js` now
fails any workflow that points an agent at a caller-supplied `repo.path` while
asking for `isolation: 'worktree'`, so the next such workflow is covered the day
it lands rather than the day it misfires. Written as a rule about the pattern, not
an allowlist of filenames.

The fix agent creates its own worktree explicitly, inside the target repo:

```bash
cd "<target repo>"
git status --short    # a dirty tree you did not dirty means another session is here
git worktree add .claude/worktrees/<topic> -b fix/<topic>
```

Add `.claude/worktrees/` to that repo's `.gitignore` first if it is not there — a
nested git directory sitting untracked in a repo where sessions run `git add -A` is
one careless stage from being committed.

## Fixes commit, they do not push

Each fix agent works in its own git worktree, because other sessions have
uncommitted work in the main clone. Default delivery is a locally verified commit.
If the existing mandate includes publishing, continue through `ship` after its
checks; otherwise retain the publish boundary as pending. Resolve whether push
or merge deploys before executing it. Authorization persists across turns.

## Feeding the registry

Anything found in two or more repos is a **class**, not an incident, and belongs in
the shared registry with a runnable detection and a known positive:

```bash
cat ~/claude-memory/BUG-CLASSES.md
```

A described bug does not travel between sessions. A grep does. If you cannot write a
detection for it, record that limitation in the entry rather than omitting the class.