@mjasnikovs/pi-task 0.38.16 → 0.38.18

package/dist/task/boot-probe.js

@@ -486,6 +486,30 @@ function holderIsOurs(command, boot) {
     return ((c.includes('bun') || c.includes('node') || c.includes('npm') || c.includes('make'))
         && (c.includes(` ${script}`) || c.endsWith(script)));
 }
+/** The real spawn. Kept beside the seam so the default is one line to read. */
+function defaultSpawnBoot(bin, args, o) {
+    return spawn(bin, args, o);
+}
+/**
+ * The real group teardown, best-effort. A group already gone is not an error.
+ *
+ * Windows has no process groups / negative-pid kill: `taskkill /T` tears down the
+ * whole tree (the detached child plus any grandchildren it spawned) and `/F`
+ * forces it, so the SIGTERM→SIGKILL escalation collapses to one idempotent call.
+ */
+function defaultKillGroup(pid, sig) {
+    try {
+        if (process.platform === 'win32') {
+            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F']);
+        }
+        else {
+            process.kill(-pid, sig);
+        }
+    }
+    catch {
+        // group already gone
+    }
+}
 /**
  * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
  * command's own fate within the grace window decides:
@@ -547,8 +571,9 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
     // the runner and carry its directory on PATH so the boot script's own chain
     // can re-invoke it.
     const runner = resolveRunner(bin);
+    const spawnBoot = opts.deps?.spawnBoot ?? defaultSpawnBoot;
     return new Promise(resolve => {
-        const child = spawn(runner.bin, args, {
+        const child = spawnBoot(runner.bin, args, {
             cwd,
             detached: true,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -562,13 +587,17 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
         // runner where the group-kill did not take, hanging the whole `bun test
         // --isolate` run on the leaked child's piped stdio). unref() so a child
         // we already tried to kill can never itself keep this process alive.
-        child.unref();
+        child.unref?.();
         let out = '';
         let err = '';
         let listenerSeen = false;
         const cap = (s) => (s.length > 8000 ? s.slice(-8000) : s);
-        child.stdout?.on('data', (d) => (out = cap(out + String(d))));
-        child.stderr?.on('data', (d) => (err = cap(err + String(d))));
+        child.stdout?.on('data', d => {
+            out = cap(out + String(d));
+        });
+        child.stderr?.on('data', d => {
+            err = cap(err + String(d));
+        });
         let settled = false;
         const settle = (r) => {
             if (settled)
@@ -579,24 +608,15 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                 clearInterval(poll);
             resolve(r);
         };
+        const reapGroup = opts.deps?.killGroup ?? defaultKillGroup;
         const killGroup = (sig) => {
-            try {
-                if (!child.pid)
-                    return;
-                if (process.platform === 'win32') {
-                    // Windows has no process groups / negative-pid kill. taskkill
-                    // /T tears down the whole tree (the detached child plus any
-                    // grandchildren it spawned); /F forces it, so the SIGTERM→
-                    // SIGKILL escalation collapses to one idempotent call.
-                    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F']);
-                }
-                else {
-                    process.kill(-child.pid, sig);
-                }
-            }
-            catch {
-                // group already gone
-            }
+            // Truthiness, deliberately: `process.kill(-0, sig)` signals the
+            // CALLER's own process group, so a pid of 0 turns a best-effort
+            // teardown into self-termination. Node's spawn never yields 0, but
+            // `spawnBoot` is a seam now and a fake or future child could.
+            if (!child.pid)
+                return;
+            reapGroup(child.pid, sig);
         };
         const passAndKill = (renderNote) => {
             settle(renderNote ? { outcome: 'pass', renderNote } : { outcome: 'pass' });

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

@@ -139,3 +139,14 @@ export interface ScoredPlan {
      */
     judgeMissing: string[];
 }
+/**
+ * Normalise a missing-area string for cross-round identity — lowercased alnum
+ * words, punctuation and quote-wrapping collapsed. Used only to tell whether an
+ * adopted plan introduced a NEW gap versus re-surfacing the same one (the bonus
+ * round); intentionally coarse, so trivial rewording of the same area does not
+ * read as new and buy an extra round.
+ *
+ * Lives here rather than in `auto-orchestrator.ts` because its only consumer is
+ * `CoverageLedger.consider`, which is the adoption rule this file owns.
+ */
+export declare function normMissingArea(s: string): string;

package/dist/task/coverage-loop.js

@@ -290,3 +290,19 @@ export function decideAdoption(current, retry, hasRequirements) {
     }
     return { adopt: true, reason: 'count floor met, no coverage regression', dropped: [] };
 }
+/**
+ * Normalise a missing-area string for cross-round identity — lowercased alnum
+ * words, punctuation and quote-wrapping collapsed. Used only to tell whether an
+ * adopted plan introduced a NEW gap versus re-surfacing the same one (the bonus
+ * round); intentionally coarse, so trivial rewording of the same area does not
+ * read as new and buy an extra round.
+ *
+ * Lives here rather than in `auto-orchestrator.ts` because its only consumer is
+ * `CoverageLedger.consider`, which is the adoption rule this file owns.
+ */
+export function normMissingArea(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}

package/dist/task/final-gate-fix.js

@@ -43,7 +43,7 @@
  * legitimate whole-repo fix that run needed (migrate.ts — frozen by its own
  * producing task). It activates only when a run-GLOBAL freeze source exists.
  */
-import { USER_CANCELLED } from './child-runner.js';
+import { parseFixMarker, runFixChild } from './fix-child.js';
 import { findForbiddenDeletions, diffIgnoredSnapshots, ignoredWriteTrailLine, ignoredWriteUnobservedNote } from './write-guard.js';
 import { findNarrowedCommands, narrowingRejectionText } from './command-shrink.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
@@ -151,16 +151,7 @@ export function buildFinalFixPrompt(failReason) {
  * early-out on a self-declared BLOCKED.
  */
 export function parseFinalFixMarker(text) {
-    const re = /FINAL-GATE-FIX:\s*(DONE|BLOCKED)\b[ \t]*(.*)/gi;
-    let last = null;
-    for (let m = re.exec(text); m !== null; m = re.exec(text))
-        last = m;
-    if (!last)
-        return { blocked: false };
-    if (last[1].toUpperCase() === 'BLOCKED') {
-        return { blocked: true, note: last[2].trim() || 'no reason given' };
-    }
-    return { blocked: false, note: last[2].trim() || undefined };
+    return parseFixMarker('FINAL-GATE-FIX', text);
 }
 /**
  * STRANDED SUB-FIXES (mx5 run 13, PROMPT 4 item 3).
@@ -219,16 +210,16 @@ export async function runFinalGateAutofix(deps) {
     // ignored files are untracked, so git alone cannot tell a file this pass wrote
     // from one that was already sitting in the worktree.
     const ignoredBefore = deps.ignoredSnapshot ? await deps.ignoredSnapshot() : null;
-    let text;
-    try {
-        text = await deps.runChild(FINAL_FIX_TOOLS, buildFinalFixPrompt(deps.failReason), deps.signal);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg === USER_CANCELLED)
-            throw err;
-        return { ok: false, reason: `fix child failed: ${msg}` };
-    }
+    // The four-rung ladder is task/fix-child.ts, shared with the per-task pass.
+    const end = await runFixChild({
+        runChild: deps.runChild,
+        tools: FINAL_FIX_TOOLS,
+        prompt: buildFinalFixPrompt(deps.failReason),
+        signal: deps.signal,
+        marker: 'FINAL-GATE-FIX'
+    });
+    if (end.kind === 'error')
+        return { ok: false, reason: `fix child failed: ${end.msg}` };
     // What the child wrote to gitignored paths. Recorded on the trail IMMEDIATELY —
     // before any guard can reject the attempt — because `discard` reverts tracked
     // edits only: an ignored file the pass wrote survives a rejection, and the trail
@@ -327,10 +318,9 @@ export async function runFinalGateAutofix(deps) {
             return r;
         }
     }
-    const marker = parseFinalFixMarker(text);
-    if (marker.blocked) {
+    if (end.kind === 'blocked') {
         // Self-declared blocked: skip the (expensive) gate re-run; nothing converged.
-        return withIgnored({ ok: false, reason: `fix child blocked: ${marker.note}` });
+        return withIgnored({ ok: false, reason: `fix child blocked: ${end.note}` });
     }
     const fin = await deps.gate(deps.cwd);
     if (!fin.ok) {

package/dist/task/final-gate.js

@@ -62,6 +62,7 @@ import { findMissingEnvDeclarations, envGateFailureText, scanEnvTemplateClosure,
 import { findMissingServeEntry, serveEntryGateFailureText } from './serve-entry.js';
 import { makefileRecipe } from './command-shrink.js';
 import { GateTally, observabilityGapFailure, unobservedVerdict } from './gate-tally.js';
+import { VERIFY_FAIL_PREFIX } from './verify-work.js';
 /**
  * The project's OWN whole-repo integration commands (test, then build — test
  * first because it is the richer signal and the more common script). First
@@ -415,8 +416,12 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
     // dynamic counters, the notes) and the verdict is assembled ONCE at the end —
     // see gate-tally.ts for what each method means.
     const tally = new GateTally();
+    // The prefix comes from VERIFY_FAIL_PREFIX so this run-level mint and the
+    // task-level `repo health:` one stay linked: both are the deterministic
+    // whole-repo static check, and `isStaticClassDebt` must recognise a debt that
+    // entered the ledger through EITHER altitude.
     if (!stat.ok)
-        tally.fail(`static checks: ${stat.reason}`);
+        tally.fail(`${VERIFY_FAIL_PREFIX['static-checks']} ${stat.reason}`);
     // Launch-contract diff (mx5 run 10 item 4): the design declared `migrate`/`seed`
     // scripts that fell through decompose and shipped missing, unchecked. Diff the
     // plan-time-extracted declared scripts against the manifest; a missing one is a

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

@@ -0,0 +1,64 @@
+/**
+ * Running ONE bounded fix child and deciding what its ending MEANS.
+ *
+ * Two graduated-resolution passes drive a fix child through the same four rungs —
+ * cancel propagates, a thrown child is an error, a self-declared BLOCKED ends the
+ * attempt, anything else is DONE — and `final-gate-fix.ts:12` says so out loud:
+ * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is that
+ * ladder, once.
+ *
+ * NOT the rejected sharing. CONTEXT.md's "the two resolution loops stay two" is
+ * about `runGatesForTask` vs `runFinalGateStage` — the LOOPS, at two altitudes.
+ * This is one altitude down: the single child invocation inside each, where the
+ * two had actually drifted.
+ *
+ *  - **The lint-fix marker was a DEAD protocol.** `buildLintFixPrompt` instructs
+ *    the child to end with `LINT-FIX: DONE` or `LINT-FIX: BLOCKED <why>`, and the
+ *    call site was `await deps.runChild(...)` with the return value DISCARDED —
+ *    nothing in `src/` or `scripts/` parsed it. The twin parsed its own marker and
+ *    used it to skip the expensive gate re-run. So a lint-fix child that reported
+ *    BLOCKED still paid the full guard stack plus a whole repo-health run (15–69s
+ *    measured), and the user was told `did not converge: <health.reason>` instead
+ *    of the child's own stated reason. The suite fed `'LINT-FIX: DONE'` as fake
+ *    output, so it stayed green whether the marker was parsed or deleted.
+ *  - **The cancel rung re-typed its constant.** `lint-fix.ts` compared against a
+ *    literal `'__user_cancelled__'`; it was the only production site in `src/` not
+ *    importing `USER_CANCELLED`.
+ *
+ * What stays per-site: the arbiter (a gate re-run vs a repo-health re-run), the
+ * result shape, and the guard sets. Only the child call is shared.
+ */
+/** How one fix child ended. A CANCEL is not a member: it throws, so the caller's
+ *  own `USER_CANCELLED` path runs unchanged. */
+export type FixChildEnd = {
+    kind: 'done';
+    text: string;
+    note?: string;
+} | {
+    kind: 'blocked';
+    text: string;
+    note: string;
+} | {
+    kind: 'error';
+    msg: string;
+};
+export interface FixChildInput {
+    runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+    tools: string;
+    prompt: string;
+    signal?: AbortSignal;
+    /** The marker word this pass's prompt instructs — `LINT-FIX`, `FINAL-GATE-FIX`. */
+    marker: string;
+}
+/**
+ * Parse a fix child's final marker. Last match wins: the model reasons before
+ * concluding, and bash output can echo the words. No marker → DONE, because the
+ * pass's own arbiter re-runs either way; a missing marker only forfeits the
+ * early-out on a self-declared BLOCKED.
+ */
+export declare function parseFixMarker(marker: string, text: string): {
+    blocked: boolean;
+    note?: string;
+};
+/** Run one fix child through the four-rung ladder. Cancel THROWS; nothing else does. */
+export declare function runFixChild(input: FixChildInput): Promise<FixChildEnd>;

package/dist/task/fix-child.js

@@ -0,0 +1,66 @@
+/**
+ * Running ONE bounded fix child and deciding what its ending MEANS.
+ *
+ * Two graduated-resolution passes drive a fix child through the same four rungs —
+ * cancel propagates, a thrown child is an error, a self-declared BLOCKED ends the
+ * attempt, anything else is DONE — and `final-gate-fix.ts:12` says so out loud:
+ * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is that
+ * ladder, once.
+ *
+ * NOT the rejected sharing. CONTEXT.md's "the two resolution loops stay two" is
+ * about `runGatesForTask` vs `runFinalGateStage` — the LOOPS, at two altitudes.
+ * This is one altitude down: the single child invocation inside each, where the
+ * two had actually drifted.
+ *
+ *  - **The lint-fix marker was a DEAD protocol.** `buildLintFixPrompt` instructs
+ *    the child to end with `LINT-FIX: DONE` or `LINT-FIX: BLOCKED <why>`, and the
+ *    call site was `await deps.runChild(...)` with the return value DISCARDED —
+ *    nothing in `src/` or `scripts/` parsed it. The twin parsed its own marker and
+ *    used it to skip the expensive gate re-run. So a lint-fix child that reported
+ *    BLOCKED still paid the full guard stack plus a whole repo-health run (15–69s
+ *    measured), and the user was told `did not converge: <health.reason>` instead
+ *    of the child's own stated reason. The suite fed `'LINT-FIX: DONE'` as fake
+ *    output, so it stayed green whether the marker was parsed or deleted.
+ *  - **The cancel rung re-typed its constant.** `lint-fix.ts` compared against a
+ *    literal `'__user_cancelled__'`; it was the only production site in `src/` not
+ *    importing `USER_CANCELLED`.
+ *
+ * What stays per-site: the arbiter (a gate re-run vs a repo-health re-run), the
+ * result shape, and the guard sets. Only the child call is shared.
+ */
+import { USER_CANCELLED } from './child-runner.js';
+/**
+ * Parse a fix child's final marker. Last match wins: the model reasons before
+ * concluding, and bash output can echo the words. No marker → DONE, because the
+ * pass's own arbiter re-runs either way; a missing marker only forfeits the
+ * early-out on a self-declared BLOCKED.
+ */
+export function parseFixMarker(marker, text) {
+    const re = new RegExp(`${marker}:\\s*(DONE|BLOCKED)\\b[ \\t]*(.*)`, 'gi');
+    let last = null;
+    for (let m = re.exec(text); m !== null; m = re.exec(text))
+        last = m;
+    if (!last)
+        return { blocked: false };
+    if (last[1].toUpperCase() === 'BLOCKED') {
+        return { blocked: true, note: last[2].trim() || 'no reason given' };
+    }
+    return { blocked: false, note: last[2].trim() || undefined };
+}
+/** Run one fix child through the four-rung ladder. Cancel THROWS; nothing else does. */
+export async function runFixChild(input) {
+    let text;
+    try {
+        text = await input.runChild(input.tools, input.prompt, input.signal);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg === USER_CANCELLED)
+            throw err;
+        return { kind: 'error', msg };
+    }
+    const parsed = parseFixMarker(input.marker, text);
+    if (parsed.blocked)
+        return { kind: 'blocked', text, note: parsed.note ?? 'no reason given' };
+    return parsed.note ? { kind: 'done', text, note: parsed.note } : { kind: 'done', text };
+}

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

@@ -42,6 +42,13 @@ export interface LintFixDeps {
      * deletion guard is disarmed (prior behavior).
      */
     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.
+     */
+    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";

package/dist/task/lint-fix.js

@@ -58,6 +58,7 @@
  * `currentTaskId` and `introducedBy` are wired.
  */
 import { parseChangedFrozenFiles, pathNamedIn, revertFrozenPaths } from './frozen-path-guard.js';
+import { runFixChild } from './fix-child.js';
 import { parseTreeChanges } from './write-guard.js';
 import { findCrossTaskDeletions } from './task-provenance.js';
 /** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
@@ -204,16 +205,27 @@ 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;
-    try {
-        await deps.runChild(LINT_FIX_TOOLS, buildLintFixPrompt(deps.failReason, frozen), deps.signal);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        // A cancel must propagate so the caller's USER_CANCELLED path runs.
-        if (msg === '__user_cancelled__')
-            throw err;
-        return { ok: false, reason: `fix child failed: ${msg}` };
+    // 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.
+    const end = await runFixChild({
+        runChild: deps.runChild,
+        tools: LINT_FIX_TOOLS,
+        prompt: buildLintFixPrompt(deps.failReason, frozen),
+        signal: deps.signal,
+        marker: 'LINT-FIX'
+    });
+    if (end.kind === 'error') {
+        deps.log?.(`lint-fix child failed — ${end.msg}`);
+        return { ok: false, reason: `fix child failed: ${end.msg}` };
     }
+    // A BLOCKED child is NOT an early return from here: the guards below exist to
+    // catch a child that discarded work, and a child can discard work and then
+    // block. The marker is consulted after them, in place of the re-run — which is
+    // 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
@@ -250,6 +262,7 @@ export async function runBoundedLintFix(deps) {
             await deps.git(['checkout', snapshot, '--', '.', EXCLUDE_TASKS_DIR]);
             await deps.git(['reset']);
         }
+        deps.log?.(`lint-fix REVERT-GUARD — discarded ${violations.length} work file(s)`);
         return {
             ok: false,
             reason: `revert-guard: fix pass discarded work (${violations.slice(0, 3).join(', ')}`
@@ -277,6 +290,7 @@ export async function runBoundedLintFix(deps) {
             if (crossDeletions.length > 0) {
                 await deps.git(['checkout', '-f', 'HEAD', '--', ...crossDeletions.map(d => d.path)]);
                 const named = crossDeletions.map(d => `${d.path} — ${d.owner}'s deliverable`);
+                deps.log?.(`lint-fix CROSS-TASK-DELETION GUARD — ${named[0]}`);
                 return {
                     ok: false,
                     reason: `cross-task-deletion: fix child DELETED sibling task deliverable(s) `
@@ -300,6 +314,7 @@ export async function runBoundedLintFix(deps) {
             const frozenViolations = [...postFrozenDirty].filter(f => !preFrozenDirty.has(f));
             if (frozenViolations.length > 0) {
                 const reverted = await revertFrozenPaths(frozenViolations, deps.git);
+                deps.log?.(`lint-fix FROZEN-PATH GUARD — ${frozenViolations.slice(0, 3).join(', ')}`);
                 return {
                     ok: false,
                     reason: `frozen-path: fix child modified spec-frozen path(s) `
@@ -311,8 +326,28 @@ export async function runBoundedLintFix(deps) {
             }
         }
     }
+    if (end.kind === 'blocked')
+        deps.log?.(`lint-fix BLOCKED — ${end.note}`);
+    // The CHECK is the arbiter, including after a BLOCKED marker.
+    //
+    // The marker is scraped last-match-wins out of arbitrary child output, and
+    // LINT_FIX_TOOLS carries bash — so the child's own command output is in that
+    // text. A child can also genuinely converge and THEN block: `eslint --fix`
+    // silently clears the last finding, and the model still reports
+    // `LINT-FIX: BLOCKED the generated file is frozen`. Returning not-applied on
+    // the marker alone would send the gate to `deps.recommend(...)` with a
+    // failReason that no longer describes the tree, skipping the re-verify and
+    // burning a full implementation re-run on findings that are already gone —
+    // 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.
     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
@@ -324,6 +359,7 @@ export async function runBoundedLintFix(deps) {
         // rounds an impl re-run under the same freeze cannot converge out of.
         const implicated = frozen.filter(p => pathNamedIn(`${health.reason}\n${health.output ?? ''}`, p));
         if (implicated.length > 0) {
+            deps.log?.(`lint-fix FROZEN-PATH TRACE — ${implicated.slice(0, 3).join(', ')}`);
             return {
                 ok: false,
                 reason: `frozen-path: static findings implicate spec-frozen path(s) `

package/dist/task/orchestrator.js

@@ -17,7 +17,7 @@
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import { PHASES, postCommitPhase } from './phases.js';
+import { PHASES, postCommitPhase, replayPhaseCarry, runPhaseRow } from './phases.js';
 import { handleFailure } from './failure-classifier.js';
 import { PHASE_INDEX, PHASE_ORDER, RESUMABLE_STATES } from './task-types.js';
 import { normaliseTaskId, parseFrontMatter, extractSection } from './task-parsers.js';
@@ -246,6 +246,13 @@ export class TaskRunner {
                 const idx = PHASE_INDEX[phase.name];
                 if (idx < resumeIdx) {
                     this._pc[phase.field] = (await readSection(cwd, id, phase.section)) ?? '';
+                    // A row's `section` restores exactly ONE field. A phase that also
+                    // settles another one declares that as its `carry`, and the replay
+                    // is the only thing standing between a resume and losing it — the
+                    // task file deliberately stores the PRE-carry text for the field
+                    // compose rewrites. Trail lines are discarded: the live run that
+                    // wrote this section already recorded them.
+                    await replayPhaseCarry(phase, this._deps, this._pc);
                     continue;
                 }
                 await advance(phase.name);
@@ -255,7 +262,7 @@ export class TaskRunner {
                 const phaseStart = Date.now();
                 let out;
                 try {
-                    out = await phase.run(this._deps, this._pc);
+                    out = await runPhaseRow(phase, this._deps, this._pc);
                 }
                 finally {
                     const phaseMs = Date.now() - phaseStart;

package/dist/task/phases.d.ts

@@ -33,7 +33,34 @@ export interface PhaseConfig {
     name: PhaseName;
     section: string;
     field: OutputField;
+    /**
+     * The pure, idempotent transform this phase performs on `PhaseContext` fields
+     * OTHER than its own `field` — the phase's CARRY. Mutates `pc` and returns the
+     * trail lines the decision produced; it performs no I/O of its own.
+     *
+     * A carry runs on BOTH arms of the orchestrator loop: before `run` on the live
+     * path, and in place of `run` on the resume path. That is the whole point. A
+     * row's `section` is what resume restores from disk, and it restores exactly
+     * ONE field — so a phase that settles a second field and does not declare it
+     * here silently loses that work on every resume past it. Compose is the case
+     * that matters: it drops constraints research REFUTED from `refined`, critique
+     * re-reads `refined` as GROUND TRUTH under a prompt that says CONSTRAINTS "MUST
+     * be preserved", and `## refined prompt` on disk is deliberately left as refine
+     * wrote it. A resume at critique used to hand the refuted constraint straight
+     * back — the mx5 run-19 defect, restored by the very machinery that closed it.
+     *
+     * The trail is returned rather than written so the replay cannot duplicate a
+     * gate line the live run already recorded.
+     */
+    carry?: (deps: PhaseDeps, pc: PhaseContext) => Promise<string[]>;
     run: (deps: PhaseDeps, pc: PhaseContext) => Promise<string>;
+    /**
+     * What this phase must do once its output is PERSISTED — after the section
+     * write, so a fault here cannot lose the output. A row field rather than a
+     * `phase.name !== 'refine'` test inside one function, so the compiler can tell
+     * you which rows have a post-commit effect.
+     */
+    postCommit?: (deps: PhaseDeps, pc: PhaseContext, out: string) => Promise<void>;
 }
 /** Extract the TOOLING section commands from a research output string. */
 export declare function extractToolingCommands(research: string): string[] | null;
@@ -176,6 +203,17 @@ export declare function phaseGrill(deps: PhaseDeps, ctx: ExtensionCommandContext
  * STEP 0 `scripts/refuted-constraint-baserate.ts`; A/B-1 `…-ab.ts` (PASS).
  */
 export declare function dropRefutedConstraints(deps: PhaseDeps, refined: string, research: string): Promise<string>;
+/**
+ * COMPOSE's carry: the refutation drop, as a `PhaseConfig.carry`.
+ *
+ * Same transform as `dropRefutedConstraints` over the same pure core, minus the
+ * recording — the caller decides whether this application is the live one or a
+ * resume replay. `dropRefutedConstraints` stays exported and unchanged for the
+ * harnesses under `scripts/` that drive the drop directly.
+ */
+export declare function composeCarry(_deps: PhaseDeps, pc: PhaseContext): Promise<string[]>;
+/** Write a carry's trail to the debug log and the task file's `## gates` section. */
+export declare function recordPhaseTrail(deps: PhaseDeps, phaseName: string, trail: string[]): Promise<void>;
 export declare function phaseCompose(deps: PhaseDeps, refined: string, research: string, qa: string): Promise<string>;
 export declare function phaseCritique(deps: PhaseDeps, spec: string, refined: string, qa: string, planContext?: string, research?: string, 
 /**
@@ -212,11 +250,12 @@ export declare function researchPhase(d: PhaseDeps, p: PhaseContext): Promise<st
 /** GRILL — the adaptive question loop, and the only phase that talks to the user. */
 export declare function grillPhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
 /**
- * COMPOSE — drop constraints research REFUTED before composing, then compose.
+ * COMPOSE — compose the spec from the refined task, the research and the Q&A.
  *
- * The drop mutates `p.refined` in place on purpose: the refuted constraint must be
- * gone from every later reader of the refined spec, not just from this call's
- * argument. Critique re-reads it.
+ * The refutation drop that must happen first is compose's declared `carry`
+ * (`composeCarry`), not a line at the top of this function. It settles `p.refined`,
+ * which is not compose's own `field`, so the orchestrator has to replay it on the
+ * resume path too — and a `run` body cannot be replayed.
  */
 export declare function composePhase(d: PhaseDeps, p: PhaseContext): Promise<string>;
 /**
@@ -245,4 +284,27 @@ export declare function critiquePhase(d: PhaseDeps, p: PhaseContext): Promise<st
  * they run in is now asserted by driving the row rather than retyped in a test.
  */
 export declare const PHASES: PhaseConfig[];
+/**
+ * Run one phase row the way the orchestrator does: carry, then run.
+ *
+ * The row is the interface, so this is the surface a row-driving test crosses —
+ * calling `row.run` alone tests past it and would not have caught a carry that the
+ * resume path drops. The orchestrator adds only persistence, timings and the
+ * checkpoint around this.
+ */
+export declare function runPhaseRow(row: PhaseConfig, deps: PhaseDeps, pc: PhaseContext): Promise<string>;
+/**
+ * Re-apply one phase row's carry on the RESUME path, where `run` is skipped.
+ *
+ * The trail is discarded: the live run that produced this phase's output already
+ * recorded it on `## gates`, and a replay must not append a second copy.
+ */
+export declare function replayPhaseCarry(row: PhaseConfig, deps: PhaseDeps, pc: PhaseContext): Promise<void>;
+/** Dispatch a row's declared post-commit effect. Rows with none do nothing. */
 export declare function postCommitPhase(phase: PhaseConfig, deps: PhaseDeps, pc: PhaseContext, out: string): Promise<void>;
+/**
+ * REFINE's post-commit: derive the task title from the refined prompt, then a short
+ * display label. Runs after the section write, so a fault here cannot lose the
+ * output it reads.
+ */
+export declare function refinePostCommit(deps: PhaseDeps, pc: PhaseContext, out: string): Promise<void>;