tracegrove 0.0.0-stage → 0.3.0

package/dist/authoring/heal.js

@@ -0,0 +1,723 @@
+/**
+ * `tracegrove heal`: look at what went wrong, fix what is safe to fix, prove each fix by
+ * re-running, and keep only fixes that verify. Setup mistakes (wrong health path, missing
+ * interpreter) are fixed deterministically in the config. Failing assertions go to the coding
+ * agent, which must decide per case whether the test drifted or the product is wrong; a product
+ * bug is reported, never papered over. Guards reject edits that delete steps, drop expectations
+ * or flip an expected success into a failure (or back). Every kept change is backed up so
+ * `tracegrove heal --undo <id>` restores it.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { delimiter, dirname, join, relative, resolve, sep } from 'node:path';
+import { parse as parseYaml, parseDocument } from 'yaml';
+import { Blocked } from "../core/errors.js";
+import { CONFIG_FILE, STATE_DIR, compileProject, loadAuthoringConfig } from "./compile.js";
+import { runTests } from "./run.js";
+import { checkProject, discoverProject } from "./workspace.js";
+import { detectAgents, resolveAgentSettings, runAgent, tracegroveCommand } from "./agent.js";
+import { requireRealDirectory, syncDirectory, writeExclusiveDurable } from "../core/atomicFiles.js";
+export const HEALS_DIR = 'heals';
+const VERDICT_TAG = 'TRACEGROVE_VERDICT';
+const HEALTH_WORDS = /^\/(?:api\/)?(?:health|healthz|healthcheck|ready|readyz|readiness|livez|live|liveness|status|ping|up)(?:\/[\w-]*)?$/;
+function stamp(date) { return date.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/:/g, '-'); }
+function sha(text) { return createHash('sha256').update(text).digest('hex'); }
+function readText(path) { try {
+    return readFileSync(path, 'utf8');
+}
+catch {
+    return null;
+} }
+/** Cooperative heal/undo ownership only; not a fence against arbitrary external editors. */
+function acquireMutation(root) {
+    const state = join(root, STATE_DIR);
+    mkdirSync(state, { recursive: true });
+    requireRealDirectory(state);
+    const lock = join(state, 'heal-mutation.lock');
+    try {
+        mkdirSync(lock, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        throw new Blocked([{ code: 'heal_mutation_in_progress', detail: lock, action: 'wait for the owning heal/undo; if it exited, preserve the lock and inspect its edits before manual recovery' }]);
+    }
+    writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+    return () => rmSync(lock, { recursive: true });
+}
+/** A small line diff (LCS) good enough for config and flow files. */
+export function lineDiff(before, after, name) {
+    const a = before.split('\n');
+    const b = after.split('\n');
+    const n = a.length;
+    const m = b.length;
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    const rows = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            rows.push([' ', a[i]]);
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1])
+            rows.push(['-', a[i++]]);
+        else
+            rows.push(['+', b[j++]]);
+    }
+    while (i < n)
+        rows.push(['-', a[i++]]);
+    while (j < m)
+        rows.push(['+', b[j++]]);
+    const keep = rows.map((row, index) => row[0] !== ' ' || rows.slice(Math.max(0, index - 2), index + 3).some((r) => r[0] !== ' '));
+    const out = [`--- a/${name}`, `+++ b/${name}`];
+    let skipped = false;
+    rows.forEach((row, index) => {
+        if (keep[index]) {
+            out.push(`${row[0]}${row[1]}`);
+            skipped = false;
+        }
+        else if (!skipped) {
+            out.push('@@');
+            skipped = true;
+        }
+    });
+    return out.join('\n');
+}
+/** Turn a run report (and compile issues) into findings a person or agent can act on. */
+export function classify(report, issues) {
+    const findings = [];
+    const open = (f) => { findings.push({ ...f, status: 'open' }); };
+    for (const issue of issues) {
+        const interpreter = issue.code === 'launch_executable_missing' || issue.code === 'application_runtime_unrecognized';
+        const file = issue.detail.match(/^(\S+\.(?:flow|fixture)\.yaml)/)?.[1] ?? (interpreter ? CONFIG_FILE : null);
+        open({ kind: interpreter ? 'setup' : 'authoring', caseId: null, file, step: null, detail: `${issue.code}: ${issue.detail}`, fix: interpreter ? 'point app.python at an interpreter that has the app\'s dependencies' : issue.action });
+    }
+    if (!report)
+        return findings;
+    for (const b of report.blockers)
+        open({ kind: 'setup', caseId: null, file: CONFIG_FILE, step: null, detail: `${b.code}: ${b.detail}`, fix: b.action });
+    for (const c of report.cases) {
+        if (c.outcome === 'passed' || !c.failure)
+            continue;
+        const ready = c.failure.message.match(/did not become ready at https?:\/\/[^/\s]+(\/\S*) within/);
+        if (c.failure.step === '(app startup)') {
+            open({ kind: 'setup', caseId: c.caseId, file: CONFIG_FILE, step: null, detail: c.failure.message,
+                fix: ready ? `make app.health a GET path that answers 2xx once the app is up (now ${ready[1]})` : 'the app exited or failed to start; run it by hand with the same env to see why' });
+        }
+        else if (c.outcome === 'assertion_failed') {
+            open({ kind: 'assertion', caseId: c.caseId, file: c.file, step: c.failure.step, detail: `${c.failure.message}${c.failure.observed ? `\n${c.failure.observed}` : ''}`, fix: 'decide whether the test drifted or the product regressed' });
+        }
+        else {
+            open({ kind: c.outcome === 'infrastructure_failed' ? 'infrastructure' : 'setup', caseId: c.caseId, file: c.file, step: c.failure.step, detail: c.failure.message, fix: 'rerun; if it repeats, inspect the run folder' });
+        }
+    }
+    if (report.bundleVerified === false)
+        open({ kind: 'evidence', caseId: null, file: null, step: null, detail: 'the evidence bundle failed verification', fix: `read ${relative(report.runDir, join(report.runDir, 'bundle-problems.txt'))} in the run folder; evidence is never repaired, only re-recorded by a fresh run` });
+    // One startup finding per distinct message is enough.
+    const seen = new Set();
+    return findings.filter((f) => { if (f.kind !== 'setup')
+        return true; const key = f.detail.replace(/127\.0\.0\.1:\d+/, 'HOST'); if (seen.has(key))
+        return false; seen.add(key); return true; });
+}
+function backup(ctx, abs) {
+    if (ctx.backups.has(abs))
+        return;
+    const text = readText(abs);
+    if (text !== null)
+        ctx.backups.set(abs, text);
+}
+function editConfig(ctx, set) {
+    const before = readFileSync(ctx.configPath, 'utf8');
+    const doc = parseDocument(before);
+    set(doc);
+    const after = doc.toString({ flowCollectionPadding: false });
+    writeFileSync(ctx.configPath, after);
+    return { before, after };
+}
+async function rerun(ctx, grep) {
+    try {
+        const { report } = await runTests({ configPath: ctx.configPath, ...(grep ? { grep } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
+        return { report, issues: [] };
+    }
+    catch (error) {
+        if (error instanceof Blocked)
+            return { report: null, issues: error.reasons.map((r) => ({ code: r.code, detail: r.detail, action: r.action })) };
+        throw error;
+    }
+}
+function startupFailed(report, caseId) {
+    if (!report)
+        return true;
+    return report.cases.some((c) => (caseId === null || c.caseId === caseId) && c.failure?.step === '(app startup)');
+}
+function walkFiles(dir, accept, out = [], depth = 0) {
+    if (depth > 6 || !existsSync(dir))
+        return out;
+    for (const name of readdirSync(dir)) {
+        if (['node_modules', '.git', STATE_DIR, '.venv', 'venv', '__pycache__', 'dist', 'build'].includes(name))
+            continue;
+        const path = join(dir, name);
+        let st;
+        try {
+            st = statSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            walkFiles(path, accept, out, depth + 1);
+        else if (accept(name) && st.size < 512_000)
+            out.push(path);
+    }
+    return out;
+}
+/** Health paths the app plausibly serves: declared GET routes first, then string literals in its source. */
+export function healthCandidates(root, config, current) {
+    const found = [];
+    const add = (path) => { if (path !== current && !found.includes(path))
+        found.push(path); };
+    try {
+        for (const r of discoverProject(root, null).routes)
+            if (r.method === 'GET' && HEALTH_WORDS.test(r.path))
+                add(r.path);
+    }
+    catch { /* discovery is a hint */ }
+    const appRoot = resolve(root, config.app.root);
+    for (const file of walkFiles(appRoot, (n) => /\.(?:m?js|cjs|ts|py|go|rb|java|kt|rs)$/.test(n))) {
+        const text = readText(file) ?? '';
+        for (const m of text.matchAll(/["'`](\/(?:api\/)?[a-z][\w/-]{0,30})["'`]/g))
+            if (HEALTH_WORDS.test(m[1]))
+                add(m[1]);
+    }
+    return found.slice(0, 4);
+}
+/** Interpreters worth trying for fastapi/django, in the order a developer would expect. */
+export function pythonCandidates(root, config) {
+    const appRoot = resolve(root, config.app.root);
+    const local = [appRoot, root].flatMap((dir) => ['.venv', 'venv', 'env', '.env'].map((v) => join(dir, v, 'bin', 'python')));
+    const onPath = (process.env.PATH ?? '').split(delimiter).filter(Boolean).flatMap((dir) => ['python3', 'python'].map((n) => join(dir, n)));
+    const probe = config.app.adapter === 'django' ? 'import django' : 'import fastapi, uvicorn';
+    const seen = new Set();
+    return [...local, ...onPath].filter((p) => { if (seen.has(p) || !existsSync(p) || p === config.app.python)
+        return false; seen.add(p); return true; })
+        .filter((p) => spawnSync(p, ['-c', probe], { timeout: 10_000, stdio: 'ignore' }).status === 0)
+        .map((p) => (p.startsWith(`${root}/`) ? relative(resolve(root, config.app.root), p) || p : p))
+        .slice(0, 3);
+}
+async function fixHealth(ctx, finding, config, dryRun) {
+    const candidates = healthCandidates(ctx.root, config, config.app.health);
+    if (candidates.length === 0) {
+        finding.fix = `${finding.fix}. No health-like GET route was found in the app source; add one (e.g. GET /health returning 200) or set app.health`;
+        return;
+    }
+    backup(ctx, ctx.configPath);
+    for (const path of candidates) {
+        ctx.progress('Trying a fix', `app.health: ${config.app.health} → ${path}`);
+        const { before, after } = editConfig(ctx, (doc) => doc.setIn(['app', 'health'], path));
+        const diff = lineDiff(before, after, CONFIG_FILE);
+        if (dryRun) {
+            writeFileSync(ctx.configPath, before);
+            ctx.changes.push({ file: CONFIG_FILE, reason: `health check ${config.app.health} never answered; ${path} is served by the app`, diff, status: 'reverted', by: 'tracegrove', note: 'dry run: not applied' });
+            return;
+        }
+        const { report } = await rerun(ctx, finding.caseId ?? undefined);
+        if (!startupFailed(report, finding.caseId)) {
+            ctx.changes.push({ file: CONFIG_FILE, reason: `health check ${config.app.health} never answered; the app is ready at ${path}`, diff, status: 'kept', by: 'tracegrove', note: 'verified: the app now starts' });
+            finding.status = 'fixed';
+            return;
+        }
+        writeFileSync(ctx.configPath, before);
+        ctx.changes.push({ file: CONFIG_FILE, reason: `tried app.health ${path}`, diff, status: 'reverted', by: 'tracegrove', note: 'the app still did not become ready' });
+    }
+}
+async function fixPython(ctx, finding, config, dryRun) {
+    if (config.app.adapter !== 'fastapi' && config.app.adapter !== 'django')
+        return;
+    ctx.progress('Looking for a Python interpreter', `with ${config.app.adapter === 'django' ? 'django' : 'fastapi and uvicorn'} installed`);
+    const candidates = pythonCandidates(ctx.root, config);
+    if (candidates.length === 0) {
+        finding.fix = `create a virtualenv with the app's dependencies (python3 -m venv .venv && .venv/bin/pip install -r requirements.txt), then rerun heal`;
+        return;
+    }
+    backup(ctx, ctx.configPath);
+    for (const python of candidates) {
+        ctx.progress('Trying a fix', `app.python → ${python}`);
+        const { before, after } = editConfig(ctx, (doc) => doc.setIn(['app', 'python'], python));
+        const diff = lineDiff(before, after, CONFIG_FILE);
+        if (dryRun) {
+            writeFileSync(ctx.configPath, before);
+            ctx.changes.push({ file: CONFIG_FILE, reason: `${config.app.python ?? 'the default interpreter'} is unusable; ${python} imports the app's framework`, diff, status: 'reverted', by: 'tracegrove', note: 'dry run: not applied' });
+            return;
+        }
+        const check = checkProject(ctx.root);
+        if (!check.issues.some((i) => i.code === 'launch_executable_missing' || i.code === 'application_runtime_unrecognized')) {
+            ctx.changes.push({ file: CONFIG_FILE, reason: `${config.app.python ?? 'the default interpreter'} is unusable; ${python} imports the app's framework`, diff, status: 'kept', by: 'tracegrove', note: 'verified: the interpreter is recognized' });
+            finding.status = 'fixed';
+            return;
+        }
+        writeFileSync(ctx.configPath, before);
+        ctx.changes.push({ file: CONFIG_FILE, reason: `tried app.python ${python}`, diff, status: 'reverted', by: 'tracegrove', note: 'still not recognized' });
+    }
+}
+function flowShape(text) {
+    try {
+        const doc = parseYaml(text);
+        if (!doc || !Array.isArray(doc.steps))
+            return null;
+        return { steps: doc.steps.map((s, i) => ({ key: typeof s.name === 'string' ? s.name : `#${i}`, expect: s.expect })) };
+    }
+    catch {
+        return null;
+    }
+}
+function statusOf(expect) {
+    if (typeof expect === 'number')
+        return expect;
+    if (expect && typeof expect === 'object' && typeof expect.status === 'number')
+        return expect.status;
+    return null;
+}
+function expectWeight(expect) {
+    if (expect === undefined || expect === null)
+        return 0;
+    if (typeof expect === 'number')
+        return 1;
+    const e = expect;
+    return (e.status === undefined ? 0 : 1) + ['json', 'count'].reduce((n, k) => n + Object.keys(e[k] ?? {}).length, 0) + ['present', 'absent'].reduce((n, k) => n + (e[k]?.length ?? 0), 0) + (e.text === undefined ? 0 : 1);
+}
+/** Why an agent's edit to a flow would weaken it, or null when it keeps the test's strength. */
+export function guardFlowEdit(before, after) {
+    const a = flowShape(before);
+    const b = flowShape(after);
+    if (!b)
+        return 'the edited flow no longer parses as a flow';
+    if (!a)
+        return null;
+    if (b.steps.length < a.steps.length)
+        return `steps were deleted (${a.steps.length} → ${b.steps.length})`;
+    const byKey = new Map(b.steps.map((s) => [s.key, s]));
+    for (const step of a.steps) {
+        const next = byKey.get(step.key);
+        if (!next)
+            return `step "${step.key}" was removed or renamed`;
+        if (expectWeight(next.expect) < expectWeight(step.expect))
+            return `step "${step.key}" checks less than before`;
+        const was = statusOf(step.expect);
+        const now = statusOf(next.expect);
+        if (was !== null && now !== null && (was < 400) !== (now < 400))
+            return `step "${step.key}" flipped from expecting ${was} to ${now}; that changes what the product is allowed to do`;
+    }
+    return null;
+}
+export function parseVerdicts(output) {
+    const line = output.split('\n').reverse().find((l) => l.includes(VERDICT_TAG));
+    if (!line)
+        return [];
+    try {
+        const parsed = JSON.parse(line.slice(line.indexOf('{')));
+        return (parsed.cases ?? []).filter((c) => typeof c.caseId === 'string' && ['test_drift', 'product_bug', 'unsure'].includes(String(c.verdict)))
+            .map((c) => ({ caseId: c.caseId, verdict: c.verdict, reason: typeof c.reason === 'string' ? c.reason.slice(0, 400) : '' }));
+    }
+    catch {
+        return [];
+    }
+}
+function editAdmission(output, knownCases) {
+    const last = output.trim().split('\n').at(-1) ?? '';
+    const reject = () => ({ verdicts: [], problem: 'a final, valid verdict with unique known case IDs is required' });
+    if (!last.startsWith(`${VERDICT_TAG} `))
+        return reject();
+    try {
+        const value = JSON.parse(last.slice(VERDICT_TAG.length + 1));
+        if (!Array.isArray(value.cases) || value.cases.length === 0)
+            return reject();
+        const seen = new Set();
+        const verdicts = [];
+        for (const entry of value.cases) {
+            if (!entry || typeof entry !== 'object')
+                return reject();
+            const candidate = entry;
+            if (typeof candidate.caseId !== 'string' || !knownCases.has(candidate.caseId) || seen.has(candidate.caseId)
+                || !['test_drift', 'product_bug', 'unsure'].includes(String(candidate.verdict)) || typeof candidate.reason !== 'string')
+                return reject();
+            seen.add(candidate.caseId);
+            verdicts.push({ caseId: candidate.caseId, verdict: candidate.verdict, reason: candidate.reason.slice(0, 400) });
+        }
+        return { verdicts, problem: null };
+    }
+    catch {
+        return reject();
+    }
+}
+export function buildHealPrompt(input) {
+    const tg = (input.tracegrove ?? tracegroveCommand()).join(' ');
+    const cases = input.failing.map((c) => {
+        const text = readText(join(input.root, c.file)) ?? '(file missing)';
+        const steps = c.steps.map((s) => `    ${s.result.padEnd(9)} ${s.name}: ${s.method} ${s.path}${s.status !== null ? ` -> ${s.status}` : ''}`).join('\n');
+        return [`### ${c.caseId} (${join(input.root, c.file)})`, `Failed at "${c.failure?.step}": ${c.failure?.message}`, c.failure?.observed ? `Observed: ${c.failure.observed}` : '', 'Steps:', steps, 'Flow file:', '```yaml', text.trim(), '```'].filter(Boolean).join('\n');
+    });
+    const issues = input.issues.map((i) => `- ${i.code}: ${i.detail} (fix: ${i.action})`);
+    return [
+        `Project folder: ${input.root}. Work only inside it; every path below is absolute.`,
+        'You are repairing tracegrove behaviour tests. tracegrove drives the real app; a failing test means either the TEST drifted from intended behaviour, or the PRODUCT regressed.',
+        'Your job is to tell those apart, honestly. Hiding a product bug by editing the test is the worst possible outcome.',
+        '',
+        ...(issues.length ? ['Authoring issues reported by `check` (fix these in the named flow files):', ...issues, ''] : []),
+        ...(cases.length ? ['Failing cases:', ...cases, ''] : []),
+        'Rules:',
+        '1. Read the route handlers, recent changes (git log -p, git diff) and docs to learn the INTENDED behaviour before deciding.',
+        '2. test_drift: the app\'s current behaviour is clearly intended (renamed field, new status code for the same outcome, changed route, new required field) and the flow is out of date. Edit only that flow file to match. Keep every step and every check; you may update values, paths, request bodies or add checks.',
+        '3. product_bug: the app behaves wrongly (a denial now succeeds, data is lost, a 5xx, wrong data returned). Do NOT edit the flow. Explain the bug in one sentence.',
+        '4. unsure: you cannot tell. Do not edit.',
+        '5. Never create files, and never edit application code, the config, fixtures or flows not listed above. Never delete steps or expectations, never change an expected 2xx/3xx into a 4xx/5xx or back.',
+        `6. After editing, run \`${tg} check --json\` until it reports ok. Do not run the tests yourself; tracegrove re-runs them and keeps only edits that pass.`,
+        `7. Your LAST line must be exactly: ${VERDICT_TAG} {"cases":[{"caseId":"<id>","verdict":"test_drift|product_bug|unsure","reason":"<one sentence>"}]}`,
+    ].join('\n');
+}
+function snapshot(files) {
+    const map = new Map();
+    for (const f of files) {
+        const t = readText(f);
+        if (t !== null)
+            map.set(f, t);
+    }
+    return map;
+}
+async function healWithAgent(ctx, input) {
+    const settings = resolveAgentSettings(ctx.root, input.config, input.overrides);
+    const testDir = resolve(ctx.root, input.config?.testDir ?? 'tracegrove');
+    const allowed = new Set([...input.failing.map((c) => join(ctx.root, c.file)), ...input.issues.map((i) => i.detail.match(/^(\S+\.(?:flow|fixture)\.yaml)/)?.[1]).filter((f) => !!f).map((f) => join(ctx.root, f))]);
+    const appRoot = resolve(ctx.root, input.config?.app.root ?? '.');
+    const watched = [...new Set([ctx.configPath, ...walkFiles(testDir, (n) => n.endsWith('.yaml')), ...walkFiles(appRoot, (n) => /\.(?:m?js|cjs|ts|tsx|py|json|ya?ml|html|css)$/.test(n))])];
+    const before = snapshot(watched);
+    const existed = new Set(walkFiles(ctx.root, () => true));
+    ctx.progress('Asking the agent', `${settings.provider}${settings.model ? ` · ${settings.model}` : ''}: ${input.failing.length} failing case(s), ${input.issues.length} authoring issue(s)`);
+    let result;
+    try {
+        result = await runAgent({ root: ctx.root, testDir, settings, prompt: buildHealPrompt({ root: ctx.root, failing: input.failing, issues: input.issues }), ...(input.onOutput ? { onOutput: input.onOutput } : {}), ...(input.onActivity ? { onActivity: input.onActivity } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
+    }
+    catch (error) {
+        // Admission has not succeeded: restore watched edits even when the agent aborts or throws.
+        for (const [file, text] of before)
+            if (readText(file) !== text) {
+                ctx.changes.push({ file: relative(ctx.root, file), reason: 'agent failed before edit admission', diff: lineDiff(text, readText(file) ?? '', relative(ctx.root, file)), status: 'rejected', by: 'agent', note: 'restored' });
+                writeFileSync(file, text);
+            }
+        for (const file of walkFiles(ctx.root, () => true))
+            if (!existed.has(file))
+                rmSync(file, { force: true });
+        return { provider: settings.provider, model: settings.model, exitCode: ctx.signal?.aborted ? 4 : 3, verdicts: [], summary: `agent did not complete; edits restored: ${error.message}` };
+    }
+    const admission = editAdmission(result.output, new Set(input.failing.map(c => c.caseId)));
+    const verdicts = admission.verdicts;
+    try {
+        const verdictFor = new Map(verdicts.map((v) => [v.caseId, v]));
+        for (const f of input.findings) {
+            if (f.kind !== 'assertion' || !f.caseId)
+                continue;
+            const v = verdictFor.get(f.caseId);
+            if (v?.verdict === 'product_bug') {
+                f.kind = 'product_bug';
+                f.status = 'reported';
+                f.fix = v.reason || 'the app regressed; fix the product, not the test';
+            }
+            else if (v?.verdict === 'test_drift') {
+                f.kind = 'test_drift';
+                f.fix = v.reason || f.fix;
+            }
+            else if (v)
+                f.fix = `agent unsure: ${v.reason}`;
+        }
+        // Undo anything outside the allowed flow files, then guard what remains.
+        const candidates = [];
+        for (const [file, text] of before) {
+            const now = readText(file);
+            if (now === text)
+                continue;
+            const rel = relative(ctx.root, file);
+            if (!allowed.has(file)) {
+                writeFileSync(file, text);
+                ctx.changes.push({ file: rel, reason: 'the agent edited a file it was not allowed to touch', diff: lineDiff(text, now ?? '', rel), status: 'rejected', by: 'agent', note: 'restored' });
+                continue;
+            }
+            const caseId = input.failing.find((c) => join(ctx.root, c.file) === file)?.caseId;
+            const v = caseId ? verdictFor.get(caseId) : undefined;
+            const matching = verdicts.filter(value => value.caseId === caseId);
+            const guard = result.exitCode !== 0 || ctx.signal?.aborted ? 'agent did not complete successfully; edits are not admitted'
+                : admission.problem ? admission.problem
+                    : !caseId || matching.length !== 1 ? 'exactly one matching case verdict is required before an edit can be admitted'
+                        : v?.verdict !== 'test_drift' ? `the agent did not judge this case to be test drift`
+                            : guardFlowEdit(text, now ?? '');
+            if (guard || input.dryRun) {
+                writeFileSync(file, text);
+                ctx.changes.push({ file: rel, reason: v?.reason || 'agent repair', diff: lineDiff(text, now ?? '', rel), status: guard ? 'rejected' : 'reverted', by: 'agent', note: guard ?? 'dry run: not applied' });
+                if (guard) {
+                    const f = input.findings.find((x) => x.caseId === caseId);
+                    if (f && f.kind === 'test_drift') {
+                        f.kind = 'assertion';
+                        f.fix = `agent edit rejected: ${guard}`;
+                    }
+                }
+                continue;
+            }
+            ctx.backups.set(file, ctx.backups.get(file) ?? text);
+            candidates.push(file);
+        }
+        // Files the agent created (scratch scripts, new flows) are outside the brief.
+        for (const file of walkFiles(ctx.root, () => true)) {
+            if (existed.has(file))
+                continue;
+            const rel = relative(ctx.root, file);
+            ctx.changes.push({ file: rel, reason: 'the agent created a new file during a repair', diff: lineDiff('', readText(file) ?? '', rel), status: 'rejected', by: 'agent', note: 'removed' });
+            rmSync(file, { force: true });
+        }
+        if (candidates.length) {
+            ctx.progress('Re-running to prove the repairs', candidates.map((f) => relative(ctx.root, f)).join(', '));
+            const check = checkProject(ctx.root);
+            const { report } = check.ok ? await rerun(ctx) : { report: null };
+            for (const file of candidates) {
+                const rel = relative(ctx.root, file);
+                const original = before.get(file);
+                const edited = readText(file) ?? '';
+                const caseId = input.failing.find((c) => join(ctx.root, c.file) === file)?.caseId;
+                const passes = check.ok && (caseId ? report?.cases.find((c) => c.caseId === caseId)?.outcome === 'passed' : true);
+                const finding = input.findings.find((f) => (caseId ? f.caseId === caseId : f.file === rel));
+                if (passes) {
+                    ctx.changes.push({ file: rel, reason: (caseId && verdictFor.get(caseId)?.reason) || 'repaired authoring issue', diff: lineDiff(original, edited, rel), status: 'kept', by: 'agent', note: caseId ? 'verified: the case now passes' : 'verified: check is clean' });
+                    if (finding) {
+                        finding.status = 'fixed';
+                        if (finding.kind === 'assertion')
+                            finding.kind = 'test_drift';
+                    }
+                }
+                else {
+                    writeFileSync(file, original);
+                    ctx.backups.delete(file);
+                    ctx.changes.push({ file: rel, reason: (caseId && verdictFor.get(caseId)?.reason) || 'agent repair', diff: lineDiff(original, edited, rel), status: 'reverted', by: 'agent', note: check.ok ? 'the case still fails with this edit' : 'the edit does not compile' });
+                }
+            }
+        }
+        return { provider: result.provider, model: result.model, exitCode: result.exitCode, verdicts, summary: result.output.split('\n').filter((l) => !l.includes(VERDICT_TAG)).join('\n').trim().slice(-2000) };
+    }
+    finally {
+        // A verification exception cannot leave an unretained candidate edit behind.
+        for (const [file, text] of before) {
+            const rel = relative(ctx.root, file);
+            if (ctx.changes.some(change => change.file === rel && change.status === 'kept') || readText(file) === text)
+                continue;
+            const edited = readText(file) ?? '';
+            writeFileSync(file, text);
+            ctx.backups.delete(file);
+            ctx.changes.push({ file: rel, reason: 'edit was not retained by verification', diff: lineDiff(text, edited, rel), status: 'reverted', by: 'agent', note: 'restored' });
+        }
+    }
+}
+function snap(report, issues) {
+    return report ? { outcome: report.outcome, exitCode: report.exitCode, runDir: report.runDir, totals: report.totals, issues: issues.length }
+        : { outcome: issues.length ? 'blocked' : 'not_run', exitCode: 2, runDir: null, totals: null, issues: issues.length };
+}
+/** Diagnose, repair what is safe, verify, and write .tracegrove/heals/<id>/report.json. */
+export async function heal(options) {
+    const release = acquireMutation(resolve(options.dir));
+    try {
+        return await healOwned(options);
+    }
+    finally {
+        release();
+    }
+}
+async function healOwned(options) {
+    const root = resolve(options.dir);
+    const configPath = join(root, CONFIG_FILE);
+    if (!existsSync(configPath))
+        throw new Blocked([{ code: 'config_not_found', detail: configPath, owner: 'operator', action: 'run tracegrove init first' }]);
+    const startedAt = new Date();
+    const id = `${stamp(startedAt)}_${randomUUID()}`;
+    const healDir = join(root, STATE_DIR, HEALS_DIR, id);
+    const progress = options.onProgress ?? (() => { });
+    const ctx = { root, configPath, healDir, changes: [], backups: new Map(), progress, signal: options.signal };
+    const dryRun = options.dryRun === true;
+    progress('Checking flows and config');
+    let issues = checkProject(root).issues;
+    let report = options.report ?? null;
+    if (!report && issues.length === 0) {
+        progress('Running the suite to see what fails');
+        ({ report, issues } = await rerun(ctx));
+    }
+    const before = snap(report, issues);
+    const findings = classify(report, issues);
+    let config = null;
+    try {
+        config = loadAuthoringConfig(configPath);
+    }
+    catch {
+        config = null;
+    }
+    if (config) {
+        for (const f of findings.filter((x) => x.kind === 'setup' && x.status === 'open')) {
+            if (/did not become ready at/.test(f.detail))
+                await fixHealth(ctx, f, config, dryRun);
+            else if (/^(launch_executable_missing|application_runtime_unrecognized)/.test(f.detail))
+                await fixPython(ctx, f, config, dryRun);
+            try {
+                config = loadAuthoringConfig(configPath);
+            }
+            catch { /* keep previous */ }
+        }
+    }
+    let after = before;
+    // Once setup is repaired the real failures can show; look again before calling the agent.
+    if (ctx.changes.some((c) => c.status === 'kept')) {
+        progress('Re-running after setup fixes');
+        issues = checkProject(root).issues;
+        if (issues.length === 0)
+            ({ report, issues } = await rerun(ctx));
+        const fixed = findings.filter((f) => f.status === 'fixed');
+        findings.splice(0, findings.length, ...fixed, ...classify(report, issues).filter((f) => !fixed.some((x) => x.detail === f.detail)));
+        after = snap(report, issues);
+    }
+    let agent = null;
+    const failing = (report?.cases ?? []).filter((c) => c.outcome === 'assertion_failed');
+    const authoring = issues.filter((i) => !['launch_executable_missing', 'application_runtime_unrecognized'].includes(i.code));
+    const settings = resolveAgentSettings(root, config, options.overrides ?? {});
+    const installed = settings.provider !== 'none' && !!detectAgents()[settings.provider];
+    if (options.agent !== false && (failing.length || authoring.length)) {
+        if (installed)
+            agent = await healWithAgent(ctx, { failing, issues: authoring, config, overrides: options.overrides ?? {}, onOutput: options.onAgentOutput, onActivity: options.onAgentActivity, findings, dryRun });
+        else
+            for (const f of findings.filter((x) => x.kind === 'assertion'))
+                f.fix = `${f.fix}: ${settings.provider === 'none' ? 'enable an agent in tracegrove settings' : `${settings.provider} is not installed`}, or read the failure and edit ${f.file}`;
+    }
+    const kept = ctx.changes.filter((c) => c.status === 'kept');
+    if (kept.some((c) => c.by === 'agent') && !dryRun) {
+        progress('Final verification run');
+        issues = checkProject(root).issues;
+        if (issues.length === 0)
+            ({ report, issues } = await rerun(ctx));
+        after = snap(report, issues);
+    }
+    const bugs = findings.filter((f) => f.kind === 'product_bug');
+    const openOnes = findings.filter((f) => f.status === 'open');
+    const outcome = options.signal?.aborted ? 'cancelled' : findings.length === 0 ? 'healthy'
+        : bugs.length ? 'product_bugs'
+            : openOnes.length === 0 ? 'healed'
+                : kept.length ? 'partly_healed' : 'needs_human';
+    const next = [];
+    if (kept.length)
+        next.push({ command: `tracegrove heal --undo ${id}`, why: 'put every kept change back the way it was' });
+    if (bugs.length)
+        next.push({ command: 'tracegrove show --run latest', why: `${bugs.length} product bug(s) to fix in the app; the tests stay red until then` });
+    if (openOnes.some((f) => f.kind === 'assertion') && !installed)
+        next.push({ command: 'tracegrove settings --agent claude', why: 'let a coding agent tell drift from regressions' });
+    if (outcome === 'healed' || outcome === 'healthy')
+        next.push({ command: 'tracegrove test', why: 'everything is green; run it in CI' });
+    if (dryRun && ctx.changes.length)
+        next.push({ command: 'tracegrove heal', why: 'apply the proposed fixes for real' });
+    mkdirSync(healDir, { recursive: true });
+    const backupDir = join(healDir, 'backup');
+    for (const [abs, text] of ctx.backups) {
+        const rel = relative(root, abs);
+        if (!kept.some((c) => c.file === rel))
+            continue;
+        mkdirSync(dirname(join(backupDir, rel)), { recursive: true });
+        writeFileSync(join(backupDir, rel), text);
+    }
+    const result = {
+        schemaVersion: 'tracegrove.heal/v1', id, root, startedAt: startedAt.toISOString(), finishedAt: new Date().toISOString(),
+        outcome, exitCode: outcome === 'cancelled' ? 4 : outcome === 'healthy' || outcome === 'healed' ? 0 : bugs.length ? 1 : 2,
+        before, after, findings, changes: ctx.changes, agent, next, reportPath: join(healDir, 'report.json'),
+        fileBindings: [...ctx.backups].filter(([abs]) => kept.some(change => change.file === relative(root, abs)))
+            .map(([abs, original]) => ({ file: relative(root, abs), beforeSha256: sha(original), afterSha256: sha(readFileSync(abs, 'utf8')) })),
+    };
+    writeFileSync(result.reportPath, `${JSON.stringify(result, null, 2)}\n`);
+    progress('Done', outcome);
+    return result;
+}
+export function listHeals(root) {
+    const dir = join(resolve(root), STATE_DIR, HEALS_DIR);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).flatMap((name) => {
+        try {
+            return [JSON.parse(readFileSync(join(dir, name, 'report.json'), 'utf8'))];
+        }
+        catch {
+            return [];
+        }
+    }).sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+}
+/** Restore every file a heal kept a change to. Refuses when the file changed again since. */
+export function undoHeal(dir, id) {
+    const release = acquireMutation(resolve(dir));
+    try {
+        return undoHealOwned(dir, id);
+    }
+    finally {
+        release();
+    }
+}
+function undoHealOwned(dir, id) {
+    const root = resolve(dir);
+    if (id !== 'latest' && !/^[A-Za-z0-9_.:-]+$/.test(id))
+        throw new Blocked([{ code: 'heal_not_found', detail: id }]);
+    const healDir = join(root, STATE_DIR, HEALS_DIR, id === 'latest' ? (listHeals(root)[0]?.id ?? '') : id);
+    const path = join(healDir, 'report.json');
+    if (!existsSync(path))
+        throw new Blocked([{ code: 'heal_not_found', detail: id, owner: 'operator', action: 'run tracegrove heal --json to list heal ids, or pass --undo latest' }]);
+    const report = JSON.parse(readFileSync(path, 'utf8'));
+    const restored = [];
+    const skipped = [];
+    const files = [...new Set(report.changes.filter((c) => c.status === 'kept').map((c) => c.file))];
+    for (const file of files) {
+        const target = resolve(root, file);
+        if (!target.startsWith(root + sep)) {
+            skipped.push({ file, why: 'file is outside the project' });
+            continue;
+        }
+        const bindings = report.fileBindings?.filter(binding => binding.file === file) ?? [];
+        if (bindings.length !== 1) {
+            skipped.push({ file, why: 'report has no unique complete file binding; undo by hand' });
+            continue;
+        }
+        const binding = bindings[0];
+        const saved = readText(join(healDir, 'backup', file));
+        if (saved === null) {
+            skipped.push({ file, why: 'no backup was recorded' });
+            continue;
+        }
+        const current = readText(target);
+        if (sha(saved) !== binding.beforeSha256 || current === null || sha(current) !== binding.afterSha256) {
+            skipped.push({ file, why: 'complete file or backup differs from the recorded heal; undo by hand' });
+            continue;
+        }
+        requireRealDirectory(dirname(target));
+        if (!lstatSync(target).isFile() || lstatSync(target).isSymbolicLink()) {
+            skipped.push({ file, why: 'target is not a regular file' });
+            continue;
+        }
+        const temporary = join(dirname(target), `.tracegrove-undo-${randomUUID()}`);
+        try {
+            writeExclusiveDurable(temporary, Buffer.from(saved));
+            // Cooperating heals/undos hold the project lock; arbitrary editors must leave this tree quiescent.
+            if (sha(readFileSync(target, 'utf8')) !== binding.afterSha256) {
+                skipped.push({ file, why: 'file changed during undo; undo by hand' });
+                continue;
+            }
+            renameSync(temporary, target);
+            syncDirectory(dirname(target));
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+        restored.push(file);
+    }
+    writeFileSync(join(healDir, 'undone.json'), `${JSON.stringify({ at: new Date().toISOString(), restored, skipped, digest: sha(restored.join('\n')) }, null, 2)}\n`);
+    return { id: report.id, restored, skipped };
+}
+//# sourceMappingURL=heal.js.map