@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/launch-contract.js

@@ -3,13 +3,10 @@
  * declares the finished project must expose, extracted once at plan time and diffed
  * by the final gate against the shipped manifest.
  *
- * The failure this closes (mx5 run 10 item 4): the design's §9 "Build & run" listed
- * the required scripts verbatim — `dev`, `build`, `migrate`, `seed`, `test` — but the
- * shipped package.json declared only `dev`, `build`, `lint`, `test`, `test:ct`. No
- * task owned `migrate`/`seed` (they fell through decompose), and NOTHING re-checked
- * the finished manifest against the design's own list, so the run completed missing
- * two of its declared entrypoints. A per-slice gate cannot catch this — it is a
- * whole-project launch-surface fact — and the final gate never had the design's list.
+ * The gap it closes is structural. A script the design names but no task owned can
+ * fall through decompose and ship missing, and a per-slice gate cannot see that: it
+ * is a whole-project launch-surface fact, and nothing else re-reads the finished
+ * manifest against the design's own list.
  *
  * Mechanism (mirrors contracts.ts): a plan-time child EMITs `SCRIPT:` lines naming the
  * scripts the design declares; the host GROUNDS each against the design — a name is
@@ -17,9 +14,13 @@
  * form designs use to declare a script. A paraphrase or a script the model invented is
  * not grounded and is dropped, so the diff can never false-flag on a hallucinated
  * requirement. The grounded list is appended HOST-SIDE to `.pi-tasks/launch-contract.md`
- * (children never write it), which survives discardEdits and the git-state guard.
+ * — the extraction child runs `--no-tools` and so has no write tool at all. Both halves
+ * of `discardTreeEdits` skip that directory (`checkout -- . :(exclude).pi-tasks`, then
+ * `clean -fd -e .pi-tasks`), and the git-state guard excludes it from the tree it
+ * hashes, so the file outlives a discarded pass.
  *
- * At run end the final gate reads the list, reads the manifest's `scripts`, and FAILs
+ * At run end the final gate reads the list, reads the shipped manifest's script names
+ * (`readLaunchManifest`: package.json `scripts`, else a Makefile's targets), and FAILs
  * naming any declared script the manifest is missing. FP-safe by construction: an
  * empty/ungrounded list (a design that never backticks a script name) yields no check.
  */
@@ -93,22 +94,20 @@ export function keepGroundedScripts(names, sourceDoc) {
     return kept;
 }
 /**
- * DETERMINISTIC RECALL (mx5 run 11): enumerate every backticked, script-name-shaped
+ * DETERMINISTIC RECALL: enumerate every backticked, script-name-shaped
  * token in a paragraph that mentions the word "script", as extraction CANDIDATES.
  *
- * The run-11 failure this closes: `test:ct` is backticked in the design's §2 tooling
- * paragraph, so the grounding guard would have KEPT it — but the extraction child
- * anchored on §9's one-line summary (`dev`,`build`,`migrate`,`seed`,`test`) and never
- * emitted it. Grounding can only DROP a candidate, never add one, so recall was
- * entirely the model's, over a 20KB doc. This makes recall mechanical: the host
- * enumerates candidates and hands them to the child as an explicit checklist; the
- * model's job flips from recall (weak) to per-candidate classification (strong).
+ * Grounding can only DROP a candidate, never add one, so without this the recall of a
+ * script declared far from the design's summary list is entirely the model's. This
+ * makes recall mechanical: the host enumerates the candidates and hands them to the
+ * child as an explicit checklist, so the model's job flips from recall (weak) to
+ * per-candidate classification (strong).
  *
  * The paragraph gate (`\bscripts?\b`, word-bounded so "TypeScript"/"JavaScript"
  * don't match) is a grounded-context filter, not a tuned knob: a design declares a
- * script by calling it one. It keeps package-name paragraphs (`hono`, `react`) out
- * of the checklist so a weak model isn't invited to keep junk the grounding guard
- * would then bless (every package name is backticked somewhere). A design with no
+ * script by calling it one. It keeps package-name paragraphs out of the checklist so
+ * a weak model isn't invited to keep junk the grounding guard would then bless —
+ * every package name is backticked somewhere. A design with no
  * such paragraph yields no candidates and the prompt is unchanged.
  */
 export function enumerateScriptCandidates(sourceDoc) {
@@ -153,13 +152,12 @@ export async function appendDeclaredScripts(cwd, names) {
  */
 const BOOT_CLASS_RE = /^(?:dev|start|serve|preview|watch)(?:[:_-].*)?$/i;
 /**
- * The declared scripts the final gate must EXECUTE as one-shot commands (mx5 run
- * 11): everything the launch contract declares that is neither boot-class (the
- * boot check exercises those) nor already covered by the gate's integration
- * commands (`covered`, case-insensitive — the test/build-shaped scripts that ran).
- * Run 11 shipped `migrate` and `seed` broken (`.rows` on a Bun sql array —
- * TypeError on first call) while the gate checked only that the scripts EXIST;
- * existence is not launchability.
+ * The declared scripts the final gate must EXECUTE as one-shot commands: everything
+ * the launch contract declares that is neither boot-class (the boot check exercises
+ * those) nor already covered by the gate's integration commands (`covered`,
+ * case-insensitive — the test/build-shaped scripts that ran). Checking only that a
+ * script is DECLARED says nothing about whether running it works; existence is not
+ * launchability.
  */
 export function runnableDeclaredScripts(declared, covered) {
     const have = new Set(covered.map(s => s.toLowerCase()));
@@ -189,9 +187,9 @@ export function missingDeclaredScripts(declared, manifestScripts) {
  * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
  *
  * `candidates` is enumerateScriptCandidates' mechanical checklist. It exists so the
- * model cannot MISS a declared script buried far from the design's summary list (the
- * run-11 `test:ct` hole); the model still classifies each candidate against the
- * design, and the host grounding still applies. Empty ⇒ the prompt is unchanged.
+ * model cannot MISS a declared script buried far from the design's summary list; the
+ * model still classifies each candidate against the design, and the host grounding
+ * still applies. Empty ⇒ the prompt is unchanged.
  */
 export const LAUNCH_EXTRACT_PROMPT = (feature, candidates = []) => [
     'You are recording the PACKAGE/BUILD SCRIPTS the design below says the finished',

package/dist/task/launch-manifest.d.ts

@@ -31,12 +31,16 @@ export declare function makeTargets(src: string): string[];
 export declare function readLaunchManifest(cwd: string): LaunchManifest;
 /**
  * The one line an INERT contract leaves behind. It rides in the gate's UNOBSERVED
- * channel rather than in `warnings` for the reason nexttask 16A gives: a check that
+ * channel rather than in `warnings` for one reason: a check that
  * silently did nothing must not read later as a check that passed.
  */
 export declare function inertLaunchContractNote(declared: string[], manifest: LaunchManifest): string;
 /** The `scripts` map of this tree's package.json, or `{}` when there isn't one.
  *  Shared by the gate and the boot probe — both ask the same manifest question. */
 export declare function packageScripts(cwd: string): Record<string, string>;
-/** Does this tree's Makefile declare `target`? */
+/**
+ * Does this tree's Makefile declare `target`? Reads the literal name `Makefile`
+ * only — unlike {@link readLaunchManifest}, this one does not walk make's lookup
+ * order, so a `GNUmakefile`-only tree answers false.
+ */
 export declare function makeHasTarget(cwd: string, target: string): boolean;

package/dist/task/launch-manifest.js

@@ -1,54 +1,50 @@
 /**
  * launch-manifest — WHICH manifest the launch-contract diff is entitled to diff
- * against, and whether there is one at all (nexttask 16A).
+ * against, and whether there is one at all.
  *
- * The defect this closes (unobserved, proven by construction). The extraction end
- * of the launch contract has no ecosystem test anywhere in it:
- * `enumerateScriptCandidates` scrapes backticked, script-name-shaped tokens out of
- * any design paragraph that says "script", and `keepGroundedScripts` can only DROP
- * a candidate. So a CMake / cargo / poetry / Makefile design saying *"the Makefile
- * must expose `build`, `test`, `migrate`"* records exactly the same artifact an npm
- * design does. The diff end hardcoded the ecosystem anyway:
+ * WHY THE DIFF NEEDS ITS OWN RESOLVER. The extraction end of the launch contract
+ * has no ecosystem test anywhere in it: `enumerateScriptCandidates` scrapes
+ * backticked, script-name-shaped tokens out of any design paragraph that says
+ * "script", and `keepGroundedScripts` can only DROP a candidate. A Makefile design
+ * saying *"the Makefile must expose `build`, `test`, `migrate`"* therefore records
+ * exactly the same artifact an npm design does.
  *
- *     missingDeclaredScripts(declared, Object.keys(packageScripts(cwd)))
- *     …where packageScripts' catch returns {} — so "this project has no
- *     package.json" was indistinguishable from "its package.json declares no
- *     scripts", and every declared script was reported missing, at rank 1, in
- *     wording that NAMES a file the project was never meant to have.
- *
- * That text seeds the autofix child's prompt (final-gate.ts's FinalGateOutcome.reason),
- * so the most likely repair on a CMake project was to write a package.json.
- *
- * IAR1 is how close this got: `plan-debug.log:10` records "launch-contract
- * extraction: 0 grounded script(s) kept from 3 emitted" — a non-npm project that
- * reached extraction and emitted three candidates, saved only by its design not
- * backticking them in a "script" paragraph.
+ * The diff cannot then reach for `packageScripts` alone. Its catch returns `{}`, so
+ * "this project has no package.json" is indistinguishable from "its package.json
+ * declares no scripts", and every declared script reads as missing — in wording that
+ * NAMES a file the project was never meant to have. `tally.fail` text becomes the
+ * gate's `reason`, which `buildFinalFixPrompt` hands to the autofix child, so on a
+ * non-npm tree the repair that text invites is to write a package.json.
  *
  * THE RULE, and it is deliberately two ecosystems wide, not three:
  *   • package.json present and parseable ⇒ diff against its `scripts` keys, exactly
- *     as before (byte-identical failure text on every npm tree — mx5's missing
+ *     as before (byte-identical failure text on every npm tree — a missing
  *     `build`/`seed` is a TRUE positive and must keep failing).
- *   • no package.json but a Makefile ⇒ diff against its TARGETS. The capability was
- *     already in final-gate.ts (`makeHasTarget`); the diff simply never called it.
+ *   • no package.json but a Makefile ⇒ diff against its TARGETS.
  *   • neither ⇒ the check is INERT. No failure, and a note saying the contract was
  *     recorded but is not checkable here, so the silence is not read later as a pass
  *     (the repo-health-check / env-template-closure discipline: ENOENT = pass, and a
  *     check must never invent a file the project chose not to have).
  *
- * cargo/poetry/gradle are NOT here on purpose. The corpus on this box contains one
- * project that ever recorded a launch contract (mx5, npm) and one non-npm project
- * that reached extraction (IAR1, CMake). A third ecosystem would be a guess.
+ * cargo/poetry/gradle are NOT here on purpose: nothing in this repo knows how to
+ * enumerate their entrypoints, and a third resolver written without one would be a
+ * guess that can only produce false FAILs.
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import * as path from 'node:path';
-/** GNU make's own lookup order, and nothing beyond it — this is one ecosystem. */
+/**
+ * GNU make's own lookup order, and nothing beyond it — this is one ecosystem.
+ * Confirmed against `make` itself: with all three files present in one directory it
+ * runs GNUmakefile; with only `makefile` and `Makefile`, it runs `makefile`.
+ */
 const MAKEFILE_NAMES = ['GNUmakefile', 'makefile', 'Makefile'];
 /** A target we are willing to name in a failure: an ordinary word-shaped target. */
 const TARGET_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,39}$/i;
 /**
  * A variable assignment, in every form make accepts (`=`, `:=`, `::=`, `?=`, `+=`,
  * `!=`, with an optional `override`/`export`). Matched BEFORE the target rule
- * because `FLAGS ::= -O2` otherwise reads as a target named `FLAGS`.
+ * because `FLAGS ::= -O2` otherwise reads as a target named `FLAGS` — make itself
+ * reports that line as a variable, not a rule.
  */
 const ASSIGN_RE = /^(?:override\s+|export\s+)?[A-Za-z_][A-Za-z0-9_.]*\s*(?:::|:|\?|\+|!)?=/;
 /**
@@ -87,9 +83,10 @@ export function makeTargets(src) {
 }
 /**
  * The makefiles that really exist in `cwd`, in GNU make's lookup order, named as
- * the DIRECTORY spells them. `existsSync` cannot do this job: on a case-insensitive
- * filesystem (Windows, macOS) `existsSync('makefile')` is true for a `Makefile`, and
- * the failure text would then name a file the project does not have.
+ * the DIRECTORY spells them. The invariant is that `manifest.file` is always a name
+ * `readdirSync(cwd)` contains, so a failure can never name a file the project does
+ * not have. An `existsSync` probe per candidate name cannot promise that, because it
+ * answers about a name we chose rather than a name on disk.
  */
 function makefilesOnDisk(cwd) {
     let entries;
@@ -141,7 +138,7 @@ export function readLaunchManifest(cwd) {
 }
 /**
  * The one line an INERT contract leaves behind. It rides in the gate's UNOBSERVED
- * channel rather than in `warnings` for the reason nexttask 16A gives: a check that
+ * channel rather than in `warnings` for one reason: a check that
  * silently did nothing must not read later as a check that passed.
  */
 export function inertLaunchContractNote(declared, manifest) {
@@ -160,7 +157,11 @@ export function packageScripts(cwd) {
         return {};
     }
 }
-/** Does this tree's Makefile declare `target`? */
+/**
+ * Does this tree's Makefile declare `target`? Reads the literal name `Makefile`
+ * only — unlike {@link readLaunchManifest}, this one does not walk make's lookup
+ * order, so a `GNUmakefile`-only tree answers false.
+ */
 export function makeHasTarget(cwd, target) {
     try {
         const mk = readFileSync(path.join(cwd, 'Makefile'), 'utf8');

package/dist/task/ledger.js

@@ -3,24 +3,26 @@
  * `.pi-tasks/` (contracts, launch-contract, env-notes, accept-debt, repair-queue,
  * requirements, requirements-owned).
  *
- * Six modules each kept their own copy of the same seven steps: read the file
- * (ANY error → ''), parse it into records, key the records, drop an incoming item
- * whose key is already present, cap to the newest MAX (oldest dropped), mkdir the
- * tasks dir, write the whole file back (`lines.join('\n') + '\n'`, plain
- * `writeFile`, NOT atomic), and swallow every fault — a ledger is a sharpener or
- * an auditing aid, never a blocker of the phase or gate that calls it. What
- * genuinely varied per site is the DATA SHAPE (file name, cap, key, line format,
- * parser) and exactly one RULE — what an append does when it adds nothing new
- * (see `onNoop`). Everything else here is the ritual, so a module that keeps a
- * ledger is an ADAPTER: it declares its ledger and calls read/append/write.
+ * The ritual is seven steps: read the file (ANY error → ''), parse it into records,
+ * key the records, drop an incoming item whose key is already present, cap to the
+ * newest MAX (oldest dropped), mkdir the tasks dir, write the whole file back
+ * (`lines.join('\n') + '\n'`, plain `writeFile`, NOT atomic). Every fault is
+ * swallowed — a ledger is a sharpener or an auditing aid, never a blocker of the
+ * phase or gate that calls it.
+ *
+ * What varies per site is the DATA SHAPE (file name, cap, key, line format, parser)
+ * and exactly one RULE — what an append does when it adds nothing new (see
+ * `onNoop`). Everything else here is the ritual, so a module that keeps a ledger is
+ * an ADAPTER: it declares its ledger and calls read/append/write.
  *
  * Contract details a caller can rely on:
  *   • `readRaw` is the trimmed file text ('' when absent or unreadable). Prompt-block
  *     builders take this string.
- *   • `read` is `parse(readRaw)`; every parser skips blank lines and lines it cannot
- *     read, so a corrupt line is dropped, never thrown on.
- *   • `append` with an empty batch is a no-op (no read, no write). Within a batch
- *     the first item with a key wins; a key already stored wins over the batch.
+ *   • `read` is `parse(readRaw)`; every adapter's parser skips blank lines and lines
+ *     it cannot read, so a corrupt line is dropped, never thrown on.
+ *   • `append` with an empty batch is a no-op — it does not even create `.pi-tasks/`.
+ *     Within a batch the first item with a key wins; a key already stored wins over
+ *     the batch.
  *   • `write` overwrites with exactly these records; an empty list writes an empty
  *     file (this is how a drained queue and a fully-resolved debt ledger look).
  *   • Neither `append` nor `write` ever throws.

package/dist/task/lint-fix.d.ts

@@ -43,20 +43,18 @@ export interface LintFixDeps {
      */
     introducedBy?: (rel: string) => Promise<string | null>;
     /**
-     * Debug-log sink. This dep did not exist, so all four of this pass's guard
-     * trips were invisible in the trail while the twin (`FinalFixDeps.log`) logged
-     * three of its own — and a guard whose firing leaves no record cannot be
-     * distinguished from one that never armed.
+     * Debug-log sink. Every guard below logs its own trip through it: a guard whose
+     * firing leaves no record cannot be distinguished from one that never armed.
      */
     log?: (msg: string) => void;
 }
 /** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
 export declare const LINT_FIX_TOOLS = "read,edit,bash";
 /**
- * Build the fix child's prompt. The constraints encode both live findings: smallest
- * edits only (the impl re-run's rewrite habit is the defect this pass replaces), and
- * an explicit ban on discarding work (both validation runs reached green via
- * `git checkout` of the work file until the guard existed).
+ * Build the fix child's prompt. Two constraints carry the design: smallest edits
+ * only — the re-run's rewrite habit is the defect this pass replaces — and an
+ * explicit ban on discarding work, which is the cheapest route to a green check and
+ * exactly what the revert-guard exists to catch.
  */
 export declare function buildLintFixPrompt(failReason: string, frozenPaths?: string[]): string;
 /**

package/dist/task/lint-fix.js

@@ -1,17 +1,16 @@
 /**
  * lint-fix — the bounded, graduated resolution for a repo-health verify FAIL.
  *
- * The failure this closes (mx5 run 3, TASK_0017): AUTOFIX's only hammer is a FULL
- * implementation re-run. For a repo-health FAIL of 10 trivial lint findings the live
- * run burned two 36–56-minute impl turns, each REGENERATING a fresh 900-line rewrite
- * that failed lint differently — the loop cannot converge because the tool is bigger
- * than the defect. Validated live on the real TASK_0017 tree: a bounded fix child
- * (read,edit,bash) reached lint-clean in 64s and 106s, 2/2.
+ * WHY A SEPARATE PASS. AUTOFIX's only hammer is a FULL implementation re-run. For a
+ * repo-health FAIL of a few trivial lint findings the re-run REGENERATES the work
+ * rather than editing it, and fresh output fails lint differently — the loop cannot
+ * converge because the tool is bigger than the defect. A bounded fix child
+ * (read,edit,bash) edits only the findings.
  *
- * The same validation caught the design's failure mode: BOTH runs cheated, running
- * `git checkout -- src/test/request.ts` — REVERTING the task's uncommitted work to
- * make the findings vanish. So this pass ships with a deterministic REVERT-GUARD,
- * outcome-based (command filtering can't catch every path to the same effect):
+ * REVERT-GUARD. A fix child can reach lint-clean by DISCARDING the task's
+ * uncommitted work: `git checkout -- <the work file>` makes every finding vanish.
+ * The prompt forbids it, but the guard is outcome-based, because command filtering
+ * cannot catch every path to the same effect:
  *
  *   - Before the child runs: snapshot the full working state (`git add -A` +
  *     `git write-tree`, then unstage) and record which files differ from HEAD.
@@ -28,34 +27,38 @@
  * recommend → AUTOFIX/ACCEPT/dismiss picker, so this pass can only make the loop
  * faster, never change what it can decide.
  *
- * FROZEN-PATH GUARD (mx5 run 12, TASK_0021/0022): the checker's own error text
- * can INSTRUCT an edit to a spec-frozen file (typed ESLint: "playwright/index.ts
- * was not found by the project … Consider either including it in the
- * tsconfig.json") and this child complies — while the task's spec froze
- * `tsconfig.json` and verify's rule-4b prohibition probe then fails the TASK for
- * the gate child's edit. Two gates, contradictory rules, same file; the loop
- * never converges (live: TASK_0021 burned all three unattended AUTOFIX rounds).
- * Prompt framing alone is A/B-proven ~0–1/5 on the weak model (see
- * frozen-path-guard.ts), so the deny is mechanical: the spec's frozen paths are
+ * FROZEN-PATH GUARD. The checker's own error text can INSTRUCT an edit to a
+ * spec-frozen file. Typed ESLint, asked to lint a file outside the tsconfig
+ * `include`, prints:
+ *
+ *     Parsing error: <file> was not found by the project service. Consider either
+ *     including it in the tsconfig.json or including it in allowDefaultProject.
+ *
+ * A child that complies edits `tsconfig.json`. If the task's spec froze that file,
+ * verify's prohibition probe raises rule 4b — "SPEC PROHIBITIONS ARE PART OF THE
+ * BAR — YOU HAVE NO WAIVER AUTHORITY" — and FAILs the TASK for the gate child's
+ * edit. Two gates, contradictory rules, same file; the loop never converges.
+ *
+ * So the deny is mechanical rather than framing: the spec's frozen paths are
  * threaded in via `frozenPaths`, injected into the prompt as a do-not-touch list
- * (belt), and any frozen path the child still changed is deterministically
- * reverted post-child and the fix reported not-applied (suspenders). Only paths
- * that were CLEAN before the child ran are reverted — a frozen path already
- * dirty with (possibly task) work is left alone, in the guard's safe direction:
- * cost time, never work.
+ * (belt), and any frozen path the child still changed is deterministically reverted
+ * post-child and the fix reported not-applied (suspenders). Only paths that were
+ * CLEAN before the child ran are reverted — a frozen path already dirty with
+ * (possibly task) work is left alone, in the guard's safe direction: cost time,
+ * never work.
  *
- * CROSS-TASK DELETION GUARD (mx5 run 12 PROMPT 2, verify-debug.log 17:53:44): the
- * revert-guard above is outcome-based but blind to a CLEAN tracked file — a
- * sibling task's committed deliverable is neither pre-dirty nor pre-untracked, so
- * DELETING it slips both checks, and if the lint converges the pass returns ok
- * (confirmed live: the child deleted TASK_0020's playwright ct files to green a
- * typed-lint it was frozen out of fixing properly). The discriminator is
- * PROVENANCE, not deletion per se: a tracked file the CHILD deleted whose
- * introducing task (per `introducedBy`, git history) differs from the CURRENT
+ * CROSS-TASK DELETION GUARD. The revert-guard above is outcome-based but blind to a
+ * CLEAN tracked file. Delete one and `git status --porcelain` reports ` D <path>`
+ * while it appears in NEITHER of the guard's two lists: it was not pre-dirty (it
+ * matched HEAD) and not pre-untracked (it is tracked). If the lint then converges,
+ * the pass returns ok having destroyed a sibling task's committed deliverable. The
+ * discriminator is PROVENANCE, not deletion per se: a tracked file the CHILD deleted
+ * whose introducing task (per `introducedBy`, git history) differs from the CURRENT
  * task is restored from HEAD and the fix reported not-applied naming the owner.
- * Same-task deletions, unknown provenance, relocations, and any git error all
- * step aside — the guard may only cost time, never work. Armed only when both
- * `currentTaskId` and `introducedBy` are wired.
+ * Same-task deletions, unknown provenance, relocations (a deletion whose basename
+ * reappears among the added paths) and any git error all step aside — the guard may
+ * only cost time, never work. Armed only when both `currentTaskId` and
+ * `introducedBy` are wired.
  */
 import { parseChangedFrozenFiles, pathNamedIn, revertFrozenPaths } from './frozen-path-guard.js';
 import { runFixChild } from './fix-child.js';
@@ -64,10 +67,10 @@ import { findCrossTaskDeletions } from './task-provenance.js';
 /** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
 export const LINT_FIX_TOOLS = 'read,edit,bash';
 /**
- * Build the fix child's prompt. The constraints encode both live findings: smallest
- * edits only (the impl re-run's rewrite habit is the defect this pass replaces), and
- * an explicit ban on discarding work (both validation runs reached green via
- * `git checkout` of the work file until the guard existed).
+ * Build the fix child's prompt. Two constraints carry the design: smallest edits
+ * only — the re-run's rewrite habit is the defect this pass replaces — and an
+ * explicit ban on discarding work, which is the cheapest route to a green check and
+ * exactly what the revert-guard exists to catch.
  */
 export function buildLintFixPrompt(failReason, frozenPaths = []) {
     const frozenBlock = frozenPaths.length === 0 ?
@@ -123,7 +126,7 @@ export function revertGuardViolations(preDirty, stillDirty) {
 const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
 /**
  * Files differing from HEAD, or null when git itself failed. The distinction is
- * load-bearing: mx5 run 4 rolled back two GOOD converged fixes because a git
+ * load-bearing: without it a run rolls back GOOD converged fixes because a git
  * failure after the child read as "[] files still dirty" → every pre-existing work
  * file looked reverted → false "discarded work". A git error is INCONCLUSIVE, not
  * evidence of destruction.
@@ -205,12 +208,10 @@ export async function runBoundedLintFix(deps) {
     // guard for this run (inconclusive ≠ evidence).
     const deletionGuardArmed = Boolean(deps.currentTaskId && deps.introducedBy);
     const preChanges = deletionGuardArmed ? await treeChanges(deps) : null;
-    // The four-rung ladder lives in task/fix-child.ts. A cancel still propagates
-    // (it THROWS, so the caller's USER_CANCELLED path is unchanged); what is new
-    // here is the BLOCKED rung, which this pass instructed in its prompt and then
-    // discarded the reply of — so a child that reported BLOCKED still paid the
-    // whole guard stack and a repo-health re-run (15–69s measured) to be told
-    // `did not converge`, instead of its own stated reason.
+    // The four-rung ladder lives in task/fix-child.ts: a cancel propagates as a
+    // THROW (so the caller's USER_CANCELLED path is unchanged), a child that threw
+    // for any other reason is `error`, a self-declared BLOCKED is `blocked`, and
+    // anything else is `done`.
     const end = await runFixChild({
         runChild: deps.runChild,
         tools: LINT_FIX_TOOLS,
@@ -228,10 +229,10 @@ export async function runBoundedLintFix(deps) {
     // where the twin consults its own.
     // REVERT-GUARD: every pre-existing work file must still differ from HEAD, and
     // every pre-existing untracked file must still exist. Trip → restore snapshot.
-    // Every comparison requires git to have actually SUCCEEDED: a git error after
-    // the child is inconclusive (proven live: it flagged the whole untracked file
-    // list as "discarded" while the child had verifiably edited only lint findings)
-    // — then the guard steps aside and the converge check below still decides.
+    // Every comparison requires git to have actually SUCCEEDED. A git error after
+    // the child reads as "nothing is dirty", which would flag every pre-existing
+    // work file as discarded — inconclusive, not evidence. The guard then steps
+    // aside and the converge check below still decides.
     const stillDirtyList = await dirtyFiles(deps);
     let guardNote;
     const violations = [];
@@ -271,10 +272,9 @@ export async function runBoundedLintFix(deps) {
     }
     // CROSS-TASK DELETION GUARD: a tracked file the CHILD deleted whose
     // introducing task differs from the current task is a sibling's committed
-    // deliverable destroyed to go green (mx5 run 12: the child deleted TASK_0020's
-    // playwright ct files and the pass returned ok — the revert-guard above only
-    // watches pre-dirty and pre-untracked files, and a clean tracked sibling file
-    // is neither). Restore JUST those paths from HEAD (they were clean pre-child,
+    // deliverable destroyed to go green. The revert-guard above only watches
+    // pre-dirty and pre-untracked files, and a clean tracked sibling file is
+    // neither. Restore JUST those paths from HEAD (they were clean pre-child,
     // so nothing of the task's work can be lost) and report not-applied naming the
     // owner. Inconclusive on any side — git error, unknown provenance, same-task
     // deletion, relocation — steps aside.
@@ -300,14 +300,13 @@ export async function runBoundedLintFix(deps) {
             }
         }
     }
-    // FROZEN-PATH GUARD: a frozen path that was clean pre-child and is changed
-    // now is the child's edit — the exact write verify's rule-4b prohibition
-    // probe is guaranteed to fail the TASK for (mx5 run 12: ESLint's own error
-    // text instructed the tsconfig.json edit and the child complied, 5/5 in the
-    // live A/B). Revert JUST those paths (they were clean, so HEAD == pre-state:
-    // no work can be lost) and report not-applied so the caller falls through to
-    // the ordinary recommend → AUTOFIX/ACCEPT picker. Inconclusive git (either
-    // side) → guard steps aside; the verify probe still catches what survives.
+    // FROZEN-PATH GUARD: a frozen path that was clean pre-child and is changed now
+    // is the child's edit — the exact write verify's rule-4b prohibition probe
+    // fails the TASK for. Revert JUST those paths (they were clean, so HEAD ==
+    // pre-state: no work can be lost) and report not-applied so the caller falls
+    // through to the ordinary recommend → AUTOFIX/ACCEPT picker. Inconclusive git
+    // (either side) → guard steps aside; the verify probe still catches what
+    // survives.
     if (preFrozenDirty !== null) {
         const postFrozenDirty = await frozenDirtySet(deps, frozen);
         if (postFrozenDirty !== null) {
@@ -341,18 +340,17 @@ export async function runBoundedLintFix(deps) {
     // while the child's edits sit in the working tree.
     //
     // So BLOCKED does not decide; it only supplies a better REASON when the check
-    // agrees nothing converged. That was the durable half of the win. Skipping the
-    // re-run was the other half, and it is not worth this.
+    // agrees nothing converged. Skipping the re-run on the marker alone is not
+    // worth that risk.
     const health = await deps.repoHealth();
     if (!health.ok) {
         if (end.kind === 'blocked') {
             return { ok: false, reason: `fix child blocked: ${end.note}` };
         }
-        // FROZEN-PATH TRACE on non-convergence (PROMPT 1 layer B): when the child
-        // was honest — it did NOT touch the frozen path, so the guard above never
-        // tripped — but the check is still red and its own output NAMES a frozen
-        // path (typed ESLint: "playwright/index.ts was not found by the project …
-        // consider including it in the tsconfig.json"), the findings can only be
+        // FROZEN-PATH TRACE on non-convergence: when the child was honest — it did
+        // NOT touch the frozen path, so the guard above never tripped — but the
+        // check is still red and its own output NAMES a frozen path (the typed
+        // ESLint message quoted in this file's header), the findings can only be
         // fixed by an edit this task's spec forbids. Report it under the same
         // `frozen-path:` prefix as the guard trip, so the gate loop can route
         // straight to the human picker instead of burning unattended AUTOFIX

package/dist/task/loop-detector.d.ts

@@ -12,7 +12,19 @@
  *
  * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
  * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
+ *
+ * The three tuning constants live here rather than in child-runner.ts because
+ * worker-profiles.ts reads them at module top level to build DEFAULT_LOOP_DETECTOR.
+ * From child-runner.ts that is a cycle — child-runner → worker-profiles →
+ * child-runner — and the failure is a TDZ ReferenceError on import order, which
+ * no compile step catches. This module imports nothing, so it cannot close one.
  */
+/** Recent tool calls the exact-repeat rule looks back over. */
+export declare const LOOP_WINDOW = 20;
+/** Repeats of one key within the window that trip the detector. */
+export declare const LOOP_THRESHOLD = 5;
+/** Re-spawns allowed after a loop kill — 3 attempts total with the initial one. */
+export declare const MAX_LOOP_RESTARTS = 2;
 export interface ToolCall {
     name: string;
     args: unknown;
@@ -27,6 +39,12 @@ export interface LoopHit {
  * Arrays preserve their order (positional). undefined / primitives passthrough.
  */
 export declare function stableStringify(value: unknown): string;
+/**
+ * The exact-match identity of a tool call. Exported because implementation-guards.ts
+ * keys its own per-call strike count on it, and a second hand-written copy of this
+ * expression is free to drift away from the one `record` uses.
+ */
+export declare function loopKey(call: ToolCall): string;
 /**
  * The primary file path a tool call targets, mirroring summarizeToolArgs' field
  * precedence. Returns null when the call names no path (e.g. bash, or a grep
@@ -47,15 +65,16 @@ export declare class LoopDetector {
     /**
      * Count same-path calls in the window that are "revisits" — accesses that end
      * no further into the file than the furthest line already covered for that
-     * path. Paging yields zero revisits and never trips; repeated whole-file
-     * re-reads, backward jumps and path-targeting greps accumulate.
+     * path. The FIRST call on a path is therefore never a revisit: it sets the
+     * high-water mark. Paging yields zero revisits and never trips; repeated
+     * whole-file re-reads, backward jumps, narrower re-reads and repeated
+     * path-targeting greps all accumulate.
      *
-     * The comparison is on the RANGE, not the offset. Offset alone scored a page
-     * that re-asks from the same start with a bigger limit — `{offset:80,
-     * limit:400}` after `{offset:80, limit:300}`, real reads from a measured
-     * decompose run — as a revisit, even though it covers 100 lines the child had
-     * never seen. That is the same mistake SingleReadGuard made by keying on the
-     * path alone, and it is corrected the same way.
+     * The comparison is on the RANGE, not the offset. Keying on offset alone scores
+     * `{offset:80, limit:400}` after `{offset:80, limit:300}` as a revisit, even
+     * though it covers 100 lines the child has never seen. That is the same mistake
+     * SingleReadGuard made by keying on the path alone, and it is corrected the same
+     * way.
      */
     private countRevisits;
 }