@mjasnikovs/pi-task 0.40.50 → 0.42.0

package/dist/task/gate-resolution.js

@@ -0,0 +1,120 @@
+/** Attempts a class whose defect an implementation re-run can actually move. */
+const REATTEMPTABLE_BUDGET = 3;
+/**
+ * How many UNATTENDED implementation re-runs each FAIL class is worth.
+ *
+ * Zero is a statement, not a disabled feature: an absent tool is not installed by
+ * re-running the work that needed it, and a verification pass that could not run
+ * is not repaired by changing the code it failed to judge. Spending three turns
+ * on either is how a run burns an hour to arrive where round one already was.
+ */
+export const AUTOFIX_BUDGET = {
+    'repo-health': REATTEMPTABLE_BUDGET,
+    'static-checks': REATTEMPTABLE_BUDGET,
+    'model-verdict': REATTEMPTABLE_BUDGET,
+    unobserved: 0,
+    'harness-fault': 0
+};
+/**
+ * How many times the /task-auto loop will START one plan entry before abandoning it.
+ *
+ * Derived, not chosen: one run to reach the gate at all, plus the re-runs the most
+ * forgiving fail class is worth inside that run. An entry that comes back for a
+ * further attempt has already spent a full autofix budget without converging, and
+ * the plan's remaining entries are worth more than its next round. Raising a class
+ * budget raises this with it, which is the relationship that should hold.
+ */
+export const ENTRY_ATTEMPT_BUDGET = 1 + Math.max(...Object.values(AUTOFIX_BUDGET));
+/** The budget in force, honouring an UNOBSERVED flag on any class. */
+export function autofixBudget(i) {
+    return i.unobserved ? 0 : AUTOFIX_BUDGET[i.failClass];
+}
+export function contradictionReason(c) {
+    const criterion = c.criterion.trim();
+    return (`spec contradiction — \`${c.frozenPath}\` is frozen by this task's spec and `
+        + `${criterion.length > 0 ? criterion : 'the failing check'} cannot be satisfied `
+        + 'without editing it; no re-run under the same freeze converges');
+}
+/**
+ * The two ends of the ladder that are NOT an autofix: ask a human, or — when
+ * there is no human — accept and write the defect down under the origin that says
+ * a machine decided.
+ */
+function terminal(i, rule, reason) {
+    return i.unattended ?
+        { rule, action: 'accept', debtOrigin: 'yolo-accepted', reason }
+        : { rule, action: 'ask', debtOrigin: null, reason };
+}
+function noBudgetReason(i) {
+    return i.unobserved || i.failClass === 'unobserved' ?
+        'verify UNOBSERVED — the spec-required check could not run (tooling absent) and an '
+            + 'unattended re-run cannot provision it'
+        : 'the verification pass itself could not run — re-running the implementation cannot '
+            + 'fix a harness fault';
+}
+/**
+ * The ordered ladder. FIRST MATCH WINS, and this order is the only statement of
+ * the policy:
+ *
+ *  1. `spec-contradiction` — the fix the check demands is the edit the spec
+ *     forbids. First, because every row below would otherwise spend a budget,
+ *     a human's attention or both on a loop that cannot converge (0053 ran three
+ *     rounds past this exact fact).
+ *  2. `judge-accept` — before any budget arithmetic, because that arithmetic is
+ *     precisely what used to override a correct ACCEPT with a rescue attempt.
+ *  3. `no-autofix-budget` — a class worth zero attempts. Its own row, not folded
+ *     into the one below, because a budget that was never offered must not be
+ *     reported as one that was spent.
+ *  4. `budget-spent` — consecutive unattended attempts that all still FAIL. A
+ *     person breaks the loop, or (unattended) it terminates with a debt.
+ *  5. `autofix` — unconditional, so the table is total.
+ */
+export const RESOLUTION_RULES = [
+    {
+        id: 'spec-contradiction',
+        match: i => i.contradiction === null ?
+            null
+            : {
+                rule: 'spec-contradiction',
+                action: 'accept',
+                debtOrigin: 'spec-contradiction',
+                reason: contradictionReason(i.contradiction)
+            }
+    },
+    {
+        id: 'judge-accept',
+        match: i => i.recommend === 'accept' ?
+            terminal(i, 'judge-accept', `judge recommended ACCEPT after investigating the workspace (autofix budget `
+                + `${i.attempts}/${autofixBudget(i)})`)
+            : null
+    },
+    {
+        id: 'no-autofix-budget',
+        match: i => autofixBudget(i) === 0 ? terminal(i, 'no-autofix-budget', noBudgetReason(i)) : null
+    },
+    {
+        id: 'budget-spent',
+        match: i => i.attempts >= autofixBudget(i) ?
+            terminal(i, 'budget-spent', `autofix budget spent (${i.attempts}/${autofixBudget(i)})`)
+            : null
+    },
+    {
+        id: 'autofix',
+        match: i => ({
+            rule: 'autofix',
+            action: 'autofix',
+            debtOrigin: null,
+            reason: `autofix recommended, unattended ${i.attempts + 1}/${autofixBudget(i)}`
+        })
+    }
+];
+export function resolveDisposition(i) {
+    for (const rule of RESOLUTION_RULES) {
+        const d = rule.match(i);
+        if (d !== null)
+            return d;
+    }
+    // Unreachable while the last row is unconditional; a reordering that breaks
+    // that fails loudly here instead of returning undefined into the gate loop.
+    throw new Error('RESOLUTION_RULES must end in an unconditional row');
+}

package/dist/task/git-state-guard.js

@@ -46,8 +46,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { makeGit } from '../shared/git-runner.js';
 import { isRegenerableArtifact } from './regenerable-artifacts.js';
-/** Keep the gate machinery's own artifacts out of the snapshot and the restore. */
-const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
+import { worktreeTreeHash } from './tree-hash.js';
 /**
  * Untracked paths that are regenerable test/build OUTPUT, not graded source. A gate
  * child creating or rewriting one of these has not mutated the work under
@@ -115,28 +114,6 @@ function isAlwaysRegenerable(relPath, ctCacheDirs) {
         return true;
     return ctCacheDirs.some(d => p === d || p.startsWith(d + '/'));
 }
-/**
- * Snapshot the worktree content into a tree object via a THROWAWAY index file, so
- * neither the real index nor the stash is touched. Returns null when git cannot
- * build the tree (odd states — the guard then skips tree reconciliation).
- */
-async function captureWorktreeTree(git) {
-    const tmpIndex = path.join(os.tmpdir(), `pi-task-guard-index-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-    const env = { GIT_INDEX_FILE: tmpIndex };
-    try {
-        const empty = await git(['read-tree', '--empty'], env);
-        if (empty.exitCode !== 0)
-            return null;
-        const add = await git(['add', '-A', '--', '.', EXCLUDE_TASKS_DIR], env);
-        if (add.exitCode !== 0)
-            return null;
-        const tree = await git(['write-tree'], env);
-        return tree.exitCode === 0 ? tree.stdout.trim() : null;
-    }
-    finally {
-        await fsp.rm(tmpIndex, { force: true }).catch(() => { });
-    }
-}
 /** Capture the repo state a gate child must leave untouched. */
 export async function captureGitState(cwd, signal, spawnFn) {
     const git = makeGit(cwd, signal, spawnFn);
@@ -161,7 +138,7 @@ export async function captureGitState(cwd, signal, spawnFn) {
         headSha: head.stdout.trim(),
         branchRef: branch.exitCode === 0 ? branch.stdout.trim() : null,
         stashSha: stash.exitCode === 0 ? stash.stdout.trim() : null,
-        treeSha: await captureWorktreeTree(git)
+        treeSha: await worktreeTreeHash(git)
     };
 }
 /** Paths tracked in the commit `headSha` points at — the "graded" codebase a gate
@@ -309,7 +286,7 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
     }
     // 2. Worktree content.
     if (before.treeSha) {
-        const afterTree = await captureWorktreeTree(git);
+        const afterTree = await worktreeTreeHash(git);
         if (afterTree && afterTree !== before.treeSha) {
             const tracked = await trackedPathsAt(git, before.headSha);
             const ctCacheDirs = readCtCacheDirs(cwd);

package/dist/task/handoff.d.ts

@@ -0,0 +1,35 @@
+import type { FixContext } from './fix-context.js';
+import type { Disposition } from './gate-resolution.js';
+import type { VerifyFailClass } from './verify-work.js';
+/** The part of a {@link FixContext} worth keeping after the run that used it. */
+export interface HandoffFixSummary {
+    /** The rule of the decision table that sent the work back. */
+    rule: Disposition['rule'];
+    failClass?: VerifyFailClass;
+    /** Which re-run the fix context itself was built for, 1-based. */
+    fixAttempt: number;
+    /** Probe names that found something; the findings live in the gate trail. */
+    probes: string[];
+    frozenPath?: string;
+}
+export interface HandoffRecord {
+    /** Which delivery of this task's spec this is, 1-based. */
+    attempt: number;
+    specHash: string;
+    delivered: 'fresh' | 'reattempt';
+    fixContext?: HandoffFixSummary;
+    at?: string;
+}
+/** Short content hash of the spec as delivered. */
+export declare function specHash(spec: string): string;
+export declare function summariseFixContext(ctx: FixContext): HandoffFixSummary;
+export declare function formatHandoff(r: HandoffRecord): string;
+/**
+ * Every record in a `## handoff` body, oldest first. A block without the
+ * `attempt` field is one of the single-timestamp sections this grammar replaced:
+ * it is still a delivery, so it is returned as attempt 1 with an unknown hash
+ * rather than dropped, and the next append counts from it.
+ */
+export declare function parseHandoff(body: string | null): HandoffRecord[];
+/** The section body with `record` appended after everything already in `prev`. */
+export declare function appendHandoff(prev: string | null, record: HandoffRecord): string;

package/dist/task/handoff.js

@@ -0,0 +1,100 @@
+/**
+ * handoff — what was delivered to the implementer, per attempt.
+ *
+ * The `## handoff` section used to be one `handoff_at:` timestamp, overwritten on
+ * every re-entry, which answered neither of the questions asked of it after a run:
+ * how many times was this task's spec delivered, and was the spec that came back
+ * the same one that failed? A record per delivery answers both — the spec hash
+ * makes a re-delivery that silently changed the spec visible, and the fix summary
+ * says which gate decision paid for it.
+ *
+ * Key-value lines because this section is read by humans as often as by code, and
+ * a blank line between records is the only separator the grammar needs.
+ */
+import { createHash } from 'node:crypto';
+/** Short content hash of the spec as delivered. */
+export function specHash(spec) {
+    return createHash('sha256').update(spec).digest('hex').slice(0, 12);
+}
+export function summariseFixContext(ctx) {
+    const probes = Object.entries(ctx.probes)
+        .filter(([, findings]) => Array.isArray(findings) && findings.length > 0)
+        .map(([name]) => name);
+    return {
+        rule: ctx.disposition.rule,
+        ...(ctx.outcome.failClass ? { failClass: ctx.outcome.failClass } : {}),
+        fixAttempt: ctx.attempt,
+        probes,
+        ...(ctx.contradiction ? { frozenPath: ctx.contradiction.frozenPath } : {})
+    };
+}
+const FIELD_RE = /^([a-z_]+):\s*(.*)$/;
+export function formatHandoff(r) {
+    const lines = [
+        `handoff_at: ${r.at ?? new Date().toISOString()}`,
+        `attempt: ${r.attempt}`,
+        `spec_hash: ${r.specHash}`,
+        `delivered: ${r.delivered}`
+    ];
+    const f = r.fixContext;
+    if (f) {
+        lines.push(`fix_rule: ${f.rule}`);
+        if (f.failClass)
+            lines.push(`fix_class: ${f.failClass}`);
+        lines.push(`fix_attempt: ${f.fixAttempt}`);
+        if (f.probes.length > 0)
+            lines.push(`fix_probes: ${f.probes.join(', ')}`);
+        if (f.frozenPath)
+            lines.push(`fix_frozen_path: ${f.frozenPath}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Every record in a `## handoff` body, oldest first. A block without the
+ * `attempt` field is one of the single-timestamp sections this grammar replaced:
+ * it is still a delivery, so it is returned as attempt 1 with an unknown hash
+ * rather than dropped, and the next append counts from it.
+ */
+export function parseHandoff(body) {
+    const out = [];
+    for (const block of (body ?? '').split(/\n\s*\n/)) {
+        const fields = new Map();
+        for (const line of block.split('\n')) {
+            const m = FIELD_RE.exec(line.trim());
+            if (m)
+                fields.set(m[1], m[2].trim());
+        }
+        if (fields.size === 0)
+            continue;
+        const attempt = parseInt(fields.get('attempt') ?? '', 10);
+        const delivered = fields.get('delivered');
+        const rule = fields.get('fix_rule');
+        const probes = fields.get('fix_probes');
+        const failClass = fields.get('fix_class');
+        const frozenPath = fields.get('fix_frozen_path');
+        out.push({
+            attempt: Number.isNaN(attempt) ? out.length + 1 : attempt,
+            specHash: fields.get('spec_hash') ?? '',
+            delivered: delivered === 'reattempt' ? 'reattempt' : 'fresh',
+            ...(fields.has('handoff_at') ? { at: fields.get('handoff_at') } : {}),
+            ...(rule ?
+                {
+                    fixContext: {
+                        rule: rule,
+                        ...(failClass ? { failClass: failClass } : {}),
+                        fixAttempt: parseInt(fields.get('fix_attempt') ?? '1', 10) || 1,
+                        probes: probes ? probes.split(',').map(p => p.trim()) : [],
+                        ...(frozenPath ? { frozenPath } : {})
+                    }
+                }
+                : {})
+        });
+    }
+    return out;
+}
+/** The section body with `record` appended after everything already in `prev`. */
+export function appendHandoff(prev, record) {
+    const before = (prev ?? '').trim();
+    const line = formatHandoff(record);
+    return before.length === 0 ? line : `${before}\n\n${line}`;
+}

package/dist/task/health-baseline.d.ts

@@ -0,0 +1,87 @@
+import type { GitRunner } from '../shared/git-runner.js';
+import type { HealthCommandResult, HealthOutcome } from './repo-health-check.js';
+/**
+ * The permissive read of a health result: everything the differential needs and
+ * nothing else. The gate deps hand around structurally-typed health signals (and
+ * tests fake them), so the differential asks for the two fields it reads rather
+ * than for the full `HealthOutcome`.
+ */
+export interface HealthSignal {
+    ok: boolean;
+    /** Absent → the result predates per-command recording; the differential then
+     *  has only the overall verdict to compare. */
+    commands?: readonly HealthCommandResult[];
+}
+export interface HealthBaseline {
+    /** When the baseline was taken (ISO). */
+    at: string;
+    /** The tree it describes, so a reader can tell whether it still applies. */
+    treeHash: string | null;
+    outcome: HealthOutcome;
+}
+/**
+ * Whose fault the current health result is.
+ *   clean        — nothing is failing now.
+ *   regressed    — a check fails that the baseline did not have failing. THIS task.
+ *   pre-existing — every failing check failed the same way before the task ran.
+ */
+export type HealthDelta = 'clean' | 'regressed' | 'pre-existing';
+/**
+ * Classify the current health result against the baseline.
+ *
+ * A NULL baseline is `regressed`, deliberately. An unestablished baseline is not
+ * evidence that the breakage predates the task — it is the absence of evidence —
+ * and the two errors are not symmetrical: calling it pre-existing SHIPS a real
+ * regression as inherited debt, while calling it a regression routes the failure
+ * through the resolution table, where a judge, a bounded lint fix or a human can
+ * still say otherwise. The same reasoning retires the `healthBefore?.ok ?? true`
+ * default the enforce site used to carry.
+ */
+export declare function classifyHealthDelta(baseline: HealthSignal | null, after: HealthSignal): HealthDelta;
+/** The failing commands, as prompt/trail lines naming the exit code. */
+export declare function inheritedHealthFindings(after: HealthSignal): string[];
+export declare const HEALTH_BASELINE_SECTION = "health baseline";
+/**
+ * Render for `## health baseline`. JSON in a fence rather than a hand-rolled
+ * grammar: this round-trips through a committed file that a later run parses, and
+ * a second grammar is a second thing to drift.
+ *
+ * The captured `output` is dropped — up to 40 lines of a linter's report, in a
+ * file committed with every task, for a field the differential never reads. The
+ * live run's own trail already carries it.
+ */
+export declare function formatHealthBaseline(b: HealthBaseline): string;
+/** Parse a `## health baseline` section back. Null on anything unreadable — an
+ *  unparseable baseline is no baseline, never a fabricated clean one. */
+export declare function parseHealthBaseline(section: string | null): HealthBaseline | null;
+export interface CaptureDeps {
+    runHealth: () => Promise<HealthOutcome>;
+    treeHash: () => Promise<string | null>;
+    /** Undo whatever a `--fix`-style health command wrote. */
+    discardEdits: () => Promise<void>;
+    now?: () => Date;
+}
+/**
+ * Capture the baseline for the tree as it stands. The hash is taken FIRST: a
+ * health command that writes would otherwise be described by the hash of its own
+ * output rather than of the tree the task starts from.
+ */
+export declare function captureHealthBaseline(deps: CaptureDeps): Promise<HealthBaseline>;
+export interface LazyCaptureDeps {
+    git: GitRunner;
+    /** Run the health check in the given directory — the throwaway worktree. */
+    runHealthIn: (dir: string) => Promise<HealthOutcome>;
+    tmpDir?: () => string;
+    now?: () => Date;
+}
+/**
+ * Establish a baseline for a task file that has none, from a DETACHED WORKTREE at
+ * HEAD. HEAD is the last commit before the task's uncommitted work, so it is the
+ * state the task started from — and checking it out elsewhere means the real index,
+ * the real working tree and the stash are all untouched, which no `stash` or
+ * `checkout` of the live tree could promise.
+ *
+ * Null when git cannot produce the worktree; the caller then has no baseline, and
+ * `classifyHealthDelta` says what that means.
+ */
+export declare function lazyHealthBaseline(deps: LazyCaptureDeps): Promise<HealthBaseline | null>;

package/dist/task/health-baseline.js

@@ -0,0 +1,158 @@
+/**
+ * health-baseline — what the repo's own static checks said BEFORE the task ran,
+ * and the differential that decides whose fault a red check is.
+ *
+ * THE FAILURE THIS CLOSES. The verify gate ran `runRepoHealthCheck` and failed on
+ * its absolute exit code. So a task that inherited a repo whose lint was already
+ * red failed its gate for somebody else's defect (AUTO_0002: 0034 absorbed 0033's
+ * lint debt), and — worse — that FAIL short-circuited before the probes, so the
+ * deterministic findings about the task's OWN work were never computed at all.
+ *
+ * THE COMPARISON IS PER COMMAND, not per overall verdict. `ok` is one boolean over
+ * a list of checks that short-circuits on the first failure, so "red before, red
+ * after" is true of a repo whose lint was already broken AND of a task that broke
+ * typecheck on top of it. Only the (cmd, exitCode) pairs can tell those apart.
+ *
+ * WHERE THE BASELINE COMES FROM. `/task-auto` captures it at the pre-task
+ * checkpoint commit, where the tree is clean and therefore describes exactly the
+ * state the task starts from; `/task` captures at its own start. Health commands
+ * may WRITE (`--fix` is a common `lint` script), so the capture discards edits
+ * afterwards — a baseline that silently fixed the repo would make the task's gate
+ * judge a tree nobody authored. A task file that has no baseline (it predates this,
+ * or the capture failed) gets one lazily at verify time from a detached worktree at
+ * HEAD: no stash, and the real index is never touched.
+ */
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { commitTreeHash } from './tree-hash.js';
+function failures(signal) {
+    return (signal.commands ?? []).filter(c => c.outcome === 'fail');
+}
+/**
+ * Classify the current health result against the baseline.
+ *
+ * A NULL baseline is `regressed`, deliberately. An unestablished baseline is not
+ * evidence that the breakage predates the task — it is the absence of evidence —
+ * and the two errors are not symmetrical: calling it pre-existing SHIPS a real
+ * regression as inherited debt, while calling it a regression routes the failure
+ * through the resolution table, where a judge, a bounded lint fix or a human can
+ * still say otherwise. The same reasoning retires the `healthBefore?.ok ?? true`
+ * default the enforce site used to carry.
+ */
+export function classifyHealthDelta(baseline, after) {
+    if (after.ok)
+        return 'clean';
+    if (!baseline)
+        return 'regressed';
+    const before = failures(baseline);
+    const now = failures(after);
+    // A failing result that names no failing command carries no per-command detail
+    // (a legacy record, or an injected signal); the overall verdict is all there is.
+    const detailed = now.length > 0 && (baseline.ok || before.length > 0);
+    if (!detailed)
+        return baseline.ok ? 'regressed' : 'pre-existing';
+    const key = (c) => JSON.stringify([c.cmd, c.exitCode]);
+    const wasFailing = new Set(before.map(key));
+    return now.every(c => wasFailing.has(key(c))) ? 'pre-existing' : 'regressed';
+}
+/** The failing commands, as prompt/trail lines naming the exit code. */
+export function inheritedHealthFindings(after) {
+    return failures(after).map(c => `\`${c.cmd}\` exits ${c.exitCode} (and did before this task)`);
+}
+// ─── The task-file section ───────────────────────────────────────────────────
+export const HEALTH_BASELINE_SECTION = 'health baseline';
+/**
+ * Render for `## health baseline`. JSON in a fence rather than a hand-rolled
+ * grammar: this round-trips through a committed file that a later run parses, and
+ * a second grammar is a second thing to drift.
+ *
+ * The captured `output` is dropped — up to 40 lines of a linter's report, in a
+ * file committed with every task, for a field the differential never reads. The
+ * live run's own trail already carries it.
+ */
+export function formatHealthBaseline(b) {
+    const { output: _output, ...outcome } = b.outcome;
+    return ['```json', JSON.stringify({ ...b, outcome }, null, 2), '```'].join('\n');
+}
+/** Parse a `## health baseline` section back. Null on anything unreadable — an
+ *  unparseable baseline is no baseline, never a fabricated clean one. */
+export function parseHealthBaseline(section) {
+    if (!section)
+        return null;
+    const json = section.replace(/^```(?:json)?\s*/, '').replace(/```\s*$/, '');
+    try {
+        const parsed = JSON.parse(json);
+        const outcome = parsed.outcome;
+        if (!outcome || typeof outcome.ok !== 'boolean')
+            return null;
+        return {
+            at: typeof parsed.at === 'string' ? parsed.at : '',
+            treeHash: typeof parsed.treeHash === 'string' ? parsed.treeHash : null,
+            outcome: {
+                ok: outcome.ok,
+                reason: outcome.reason ?? '',
+                ecosystem: outcome.ecosystem ?? null,
+                commands: outcome.commands ?? [],
+                output: ''
+            }
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Capture the baseline for the tree as it stands. The hash is taken FIRST: a
+ * health command that writes would otherwise be described by the hash of its own
+ * output rather than of the tree the task starts from.
+ */
+export async function captureHealthBaseline(deps) {
+    const treeHash = await deps.treeHash();
+    try {
+        const outcome = await deps.runHealth();
+        return { at: (deps.now?.() ?? new Date()).toISOString(), treeHash, outcome };
+    }
+    finally {
+        await deps.discardEdits();
+    }
+}
+function lazyWorktreePath() {
+    return path.join(os.tmpdir(), `pi-task-health-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+}
+/**
+ * Establish a baseline for a task file that has none, from a DETACHED WORKTREE at
+ * HEAD. HEAD is the last commit before the task's uncommitted work, so it is the
+ * state the task started from — and checking it out elsewhere means the real index,
+ * the real working tree and the stash are all untouched, which no `stash` or
+ * `checkout` of the live tree could promise.
+ *
+ * Null when git cannot produce the worktree; the caller then has no baseline, and
+ * `classifyHealthDelta` says what that means.
+ */
+export async function lazyHealthBaseline(deps) {
+    const dir = (deps.tmpDir ?? lazyWorktreePath)();
+    const added = await deps.git(['worktree', 'add', '--detach', dir, 'HEAD']);
+    if (added.exitCode !== 0)
+        return null;
+    try {
+        const outcome = await deps.runHealthIn(dir);
+        return {
+            at: (deps.now?.() ?? new Date()).toISOString(),
+            treeHash: await commitTreeHash(deps.git, 'HEAD'),
+            outcome
+        };
+    }
+    finally {
+        // `--force` because the health run may have written into it (a `--fix`
+        // script, a build cache), which plain `worktree remove` refuses. If git
+        // still declines, drop the directory and prune the admin record by hand —
+        // a stale worktree entry makes every later `worktree add` in this repo
+        // noisier, and nothing else will clean it up.
+        const removed = await deps.git(['worktree', 'remove', '--force', dir]);
+        if (removed.exitCode !== 0) {
+            await fsp.rm(dir, { recursive: true, force: true }).catch(() => { });
+            await deps.git(['worktree', 'prune']);
+        }
+    }
+}

package/dist/task/health-repair.d.ts

@@ -0,0 +1,68 @@
+/**
+ * health-repair — a red static check at a pre-task checkpoint becomes a repair
+ * entry in the running plan, BEFORE the next planned task builds on it.
+ *
+ * The failure this closes: red enters the tree by three doors — a task whose
+ * regression was accepted, a leftover from an abandoned run swept in by the
+ * checkpoint commit, a repo that was red when the run began — and none of them is
+ * a gate. The health baseline (health-baseline.ts) stops the NEXT task being
+ * blamed, but blaming nobody is not fixing it: every later task inherits the red,
+ * and only the run-end gate re-checks it. All three doors pass the checkpoint,
+ * which already measures health for the baseline, so that one measurement is
+ * where the repair is scheduled.
+ *
+ * The subject of a repair is what the health output NAMES: the tracked files the
+ * failing command reported, or the command itself when it named none. The plan is
+ * the dedup ledger — a title covering the same command, or any of the same files,
+ * means no second entry, checked-off ones included, which is what stops a repair
+ * that failed from being re-spawned.
+ */
+import type { HealthSignal } from './health-baseline.js';
+/** The failing check, and what its output named. */
+export interface HealthRed {
+    command: string;
+    exitCode: number | null;
+    /** Repo-relative tracked paths the output named, in first-seen order. */
+    files: string[];
+}
+export interface HealthRedOwners {
+    /** Task ids whose commits introduced the named files; empty when nothing in
+     *  the run owns them (a leftover, or a red the run started on). */
+    owners: string[];
+}
+/**
+ * What a red health result is about. Null when the result records no failing
+ * command (a legacy baseline, or a signal with no per-command detail) — there is
+ * nothing a repair could be pinned to.
+ */
+export declare function healthRedSubject(health: HealthSignal & {
+    output?: string;
+}, cwd: string, tracked: readonly string[] | null): HealthRed | null;
+/**
+ * The plan title, in one of two fixed shapes the parser below recovers:
+ *   `repair src/a.ts, src/b.ts: \`bun run lint\` exits 1 (introduced by TASK_0033)`
+ *   `repair \`bun run lint\`: exits 1 (no task in this run owns it)`
+ * The subject sits right after the prefix so it is both the dedup key and what
+ * the scope fence pins.
+ */
+export declare function buildHealthRepairTitle(red: HealthRed & HealthRedOwners): string;
+export interface HealthRepairSubject {
+    command: string;
+    files: string[];
+}
+/** The command and files a health-repair title names, or null for any other title. */
+export declare function parseHealthRepairTitle(title: string): HealthRepairSubject | null;
+/**
+ * Does the plan already carry a repair for this red? Same command, or any of the
+ * same files — including a file-scoped root-cause repair (root-cause-repair.ts),
+ * which pins the same file. Checked-off entries count: a repair that ran and
+ * failed lands in the debt ledger, never in the plan a second time.
+ */
+export declare function planCoversHealthRed(titles: readonly string[], red: HealthRed): boolean;
+/**
+ * The extra scope fence a health-repair entry carries into refine. Without it
+ * "repair src/a.ts" refines into "overhaul the client", and a fix child left free
+ * to choose greens a linter fastest by suppressing it — which is how the red in
+ * the run this closes was painted over the first time.
+ */
+export declare function buildHealthRepairFence(subject: HealthRepairSubject): string;