@mjasnikovs/pi-task 0.17.26 → 0.18.0

package/dist/task/final-gate-fix.d.ts

@@ -0,0 +1,91 @@
+/** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
+ *  failing command (and the project's own tooling), not to mutate git state. */
+export declare const FINAL_FIX_TOOLS = "read,edit,bash";
+/**
+ * How many fix passes the user may launch from the picker before the option is
+ * withdrawn (mirrors the per-task MAX_AUTO_AUTOFIX budget). Each attempt is a
+ * full model child plus a full gate re-run — after this many that still FAIL,
+ * only Leave-failed / Accept remain so a person breaks the loop.
+ */
+export declare const MAX_FINAL_GATE_AUTOFIX = 3;
+/** Picker labels/values. Classification accepts the value token, the label, or
+ *  free text (→ autofix guidance), same contract as the per-task resolution. */
+export declare const FINAL_LEAVE_VALUE = "fail";
+export declare const FINAL_ACCEPT_VALUE = "accept";
+export declare const FINAL_AUTOFIX_VALUE = "autofix";
+export declare const FINAL_LEAVE_LABEL = "Leave failed \u2014 I will fix and /task-auto-resume";
+export declare const FINAL_ACCEPT_LABEL = "Accept \u2014 complete the run anyway";
+export declare const FINAL_AUTOFIX_LABEL = "Autofix \u2014 run a bounded fix pass and re-run the gate";
+export interface FinalGateChoice {
+    /** What the user decided. 'leave' = leave the run failed (also the dismissal
+     *  default — identical to the pre-autofix behavior). */
+    action: 'leave' | 'accept' | 'autofix';
+    /** Free-text guidance typed instead of picking a card; folded into the fix
+     *  child's failure seed. Only set with 'autofix'. */
+    guidance?: string;
+}
+/**
+ * Map a final-gate picker answer to an action. Dismissal (undefined/empty) and
+ * an explicit leave stay "leave" — exactly what the two-option picker did.
+ * Free text becomes autofix guidance, mirroring classifyResolutionAnswer; the
+ * caller demotes autofix back to "leave" when the option was not offered.
+ */
+export declare function classifyFinalGateAnswer(answer: string | undefined): FinalGateChoice;
+/**
+ * The gate's fail reason always carries the failing command in backticks
+ * (`` `bun run test` exited 1 — … `` / ``static checks: `make lint` exited 2``).
+ * Extract it for reporting; the shrink guard itself compares the FULL
+ * discovered-command sets, so a reason this cannot parse still guards.
+ */
+export declare function extractFailingCommand(reason: string): string | null;
+/**
+ * Build the fix child's prompt. Generic by construction: the only project facts
+ * in it are the gate's own failure text — the command comes from the project's
+ * discovered manifest, never from a hardcoded ecosystem.
+ */
+export declare function buildFinalFixPrompt(failReason: string): string;
+/**
+ * Parse the child's final marker. Last match wins (the model reasons before
+ * concluding and bash output can echo the words). No marker → treated as DONE:
+ * the gate re-run is the arbiter either way, so a missing marker only skips the
+ * early-out on a self-declared BLOCKED.
+ */
+export declare function parseFinalFixMarker(text: string): {
+    blocked: boolean;
+    note?: string;
+};
+export interface FinalFixResult {
+    /** true → the fix child ran AND the re-run gate passed. */
+    ok: boolean;
+    /** Human-readable outcome (converged gate reason, or why the attempt failed). */
+    reason: string;
+    /** On a did-not-converge outcome: the FRESH gate failure, so the caller's next
+     *  picker (and next fix attempt) works from the current state, not the stale one. */
+    gateReason?: string;
+}
+export interface FinalFixDeps {
+    cwd: string;
+    signal?: AbortSignal;
+    /** The gate's FAIL reason (command + exit code + output tail), plus any
+     *  user-typed guidance the caller folded in. */
+    failReason: string;
+    /** Run the fix child; same closure shape the other gate children use. */
+    runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+    /** Re-run the final integration gate — the only arbiter of convergence. */
+    gate: (cwd: string) => Promise<{
+        ok: boolean;
+        reason: string;
+    }>;
+    /** Labels of every currently-discoverable gate command (static + integration),
+     *  for the shrink guard. Pure discovery — nothing is executed. */
+    discoverLabels: (cwd: string) => string[];
+    /** Discard the fix child's working-tree edits (shrink-guard trip only). Absent
+     *  → the violation is still rejected, edits are left for inspection. */
+    discard?: (cwd: string) => Promise<void>;
+}
+/**
+ * Run one bounded final-gate fix attempt: snapshot discovery → child → shrink
+ * guard → gate re-run. Never throws for an outcome; only a user cancel inside
+ * runChild propagates (the caller's USER_CANCELLED path handles it).
+ */
+export declare function runFinalGateAutofix(deps: FinalFixDeps): Promise<FinalFixResult>;

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

@@ -0,0 +1,182 @@
+/**
+ * final-gate-fix — the bounded, model-driven fix pass offered when the FINAL
+ * integration gate fails.
+ *
+ * The failure this closes (mx5 run 7, validated): the final gate's first live
+ * firing was a TRUE POSITIVE — the project's own `test` command genuinely failed
+ * whole-repo while every per-slice check was green — but the resolution picker
+ * offered only "Leave failed" / "Accept". There was NO automated path to fix a
+ * defect the run itself shipped; the user had to leave the run failed, fix by
+ * hand, and resume.
+ *
+ * This mirrors the per-task graduated-resolution shape (lint-fix.ts): a bounded
+ * write-enabled child (read, edit, bash) is seeded with the gate's exact failure
+ * (command + exit code + output tail), fixes the defect in place, and the gate
+ * itself is re-run as the only arbiter — the child's self-report is never
+ * trusted. The user always chooses this path from the picker ("Leave failed"
+ * stays the recommended default), and attempts are capped so a non-converging
+ * loop hands control back to a person.
+ *
+ * CHEAT GUARD (deterministic): the cheapest way for a fix child to "converge" is
+ * to remove the failing command itself — delete the `test` script, drop the
+ * Makefile target — so the gate discovers nothing and vacuously passes. Both
+ * live lint-fix validation runs cheated exactly this way (via git checkout)
+ * until a guard existed. So the discovered gate commands are snapshotted before
+ * the child runs; any previously-discovered command that is no longer
+ * discoverable afterwards rejects the attempt and discards its edits. A fix may
+ * change what a command DOES, never make it disappear.
+ */
+import { USER_CANCELLED } from './child-runner.js';
+/** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
+ *  failing command (and the project's own tooling), not to mutate git state. */
+export const FINAL_FIX_TOOLS = 'read,edit,bash';
+/**
+ * How many fix passes the user may launch from the picker before the option is
+ * withdrawn (mirrors the per-task MAX_AUTO_AUTOFIX budget). Each attempt is a
+ * full model child plus a full gate re-run — after this many that still FAIL,
+ * only Leave-failed / Accept remain so a person breaks the loop.
+ */
+export const MAX_FINAL_GATE_AUTOFIX = 3;
+/** Picker labels/values. Classification accepts the value token, the label, or
+ *  free text (→ autofix guidance), same contract as the per-task resolution. */
+export const FINAL_LEAVE_VALUE = 'fail';
+export const FINAL_ACCEPT_VALUE = 'accept';
+export const FINAL_AUTOFIX_VALUE = 'autofix';
+export const FINAL_LEAVE_LABEL = 'Leave failed — I will fix and /task-auto-resume';
+export const FINAL_ACCEPT_LABEL = 'Accept — complete the run anyway';
+export const FINAL_AUTOFIX_LABEL = 'Autofix — run a bounded fix pass and re-run the gate';
+/**
+ * Map a final-gate picker answer to an action. Dismissal (undefined/empty) and
+ * an explicit leave stay "leave" — exactly what the two-option picker did.
+ * Free text becomes autofix guidance, mirroring classifyResolutionAnswer; the
+ * caller demotes autofix back to "leave" when the option was not offered.
+ */
+export function classifyFinalGateAnswer(answer) {
+    if (answer === undefined)
+        return { action: 'leave' };
+    const t = answer.trim();
+    if (t.length === 0)
+        return { action: 'leave' };
+    if (t === FINAL_LEAVE_VALUE || /^leave\b/i.test(t))
+        return { action: 'leave' };
+    if (t === FINAL_ACCEPT_VALUE || /^accept\b/i.test(t))
+        return { action: 'accept' };
+    if (t === FINAL_AUTOFIX_VALUE || /^autofix\b/i.test(t))
+        return { action: 'autofix' };
+    return { action: 'autofix', guidance: t };
+}
+/**
+ * The gate's fail reason always carries the failing command in backticks
+ * (`` `bun run test` exited 1 — … `` / ``static checks: `make lint` exited 2``).
+ * Extract it for reporting; the shrink guard itself compares the FULL
+ * discovered-command sets, so a reason this cannot parse still guards.
+ */
+export function extractFailingCommand(reason) {
+    const m = /`([^`]+)`\s+exited\b/.exec(reason);
+    return m ? m[1] : null;
+}
+/**
+ * Build the fix child's prompt. Generic by construction: the only project facts
+ * in it are the gate's own failure text — the command comes from the project's
+ * discovered manifest, never from a hardcoded ecosystem.
+ */
+export function buildFinalFixPrompt(failReason) {
+    return [
+        'You are a bounded fix pass for a FAILED whole-repo integration gate.',
+        'Every task in this run is complete and committed; then the project’s own',
+        'integration command was run against the assembled repository and failed:',
+        '',
+        failReason.trim(),
+        '',
+        'Your ONLY job is to make that command pass by fixing the DEFECT it reveals.',
+        '',
+        '1. Re-run the exact failing command first and read its full output.',
+        '2. Diagnose the root cause, then fix it with the smallest correct change.',
+        '   The project’s own manifests, configs and conventions define what',
+        '   correct means — follow them, do not invent new structure.',
+        '',
+        '3. HARD CONSTRAINTS:',
+        '   - Do NOT delete, skip, disable, or weaken tests or checks to make the',
+        '     command pass. Relocating or scoping a file the runner was never meant',
+        '     to pick up (per the project’s own config) is a legitimate fix;',
+        '     deleting it or marking it skipped is not.',
+        '   - Do NOT remove or rename the project’s own commands (its test/build/',
+        '     lint scripts or targets). Making the gate unable to find the command',
+        '     is detected and the whole fix is rejected.',
+        '   - Do NOT run git commands that mutate state (checkout, restore, reset,',
+        '     revert, stash, clean). The work in this repository is finished and',
+        '     committed — reverting it is destroying the run, not fixing it.',
+        '',
+        '4. Re-run the failing command after your fix and confirm it exits 0. The',
+        '   gate is re-run mechanically after you finish — your claim is not the',
+        '   verdict, the real exit code is.',
+        '',
+        'End with exactly one line:',
+        '  FINAL-GATE-FIX: DONE',
+        '  FINAL-GATE-FIX: BLOCKED <why you could not fix it>'
+    ].join('\n');
+}
+/**
+ * Parse the child's final marker. Last match wins (the model reasons before
+ * concluding and bash output can echo the words). No marker → treated as DONE:
+ * the gate re-run is the arbiter either way, so a missing marker only skips the
+ * 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 };
+}
+/**
+ * Run one bounded final-gate fix attempt: snapshot discovery → child → shrink
+ * guard → gate re-run. Never throws for an outcome; only a user cancel inside
+ * runChild propagates (the caller's USER_CANCELLED path handles it).
+ */
+export async function runFinalGateAutofix(deps) {
+    const before = deps.discoverLabels(deps.cwd);
+    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}` };
+    }
+    // SHRINK GUARD: every gate command discoverable before the fix must still be
+    // discoverable after it. A vanished command means the child "fixed" the gate
+    // by removing the check — reject and (when possible) discard the edits.
+    const after = new Set(deps.discoverLabels(deps.cwd));
+    const vanished = before.filter(label => !after.has(label));
+    if (vanished.length > 0) {
+        if (deps.discard)
+            await deps.discard(deps.cwd);
+        return {
+            ok: false,
+            reason: `fix pass removed the gate's own command(s) (${vanished.join(', ')}) — `
+                + `edits ${deps.discard ? 'discarded' : 'REJECTED but left in the tree (no discard available)'}`
+        };
+    }
+    const marker = parseFinalFixMarker(text);
+    if (marker.blocked) {
+        // Self-declared blocked: skip the (expensive) gate re-run; nothing converged.
+        return { ok: false, reason: `fix child blocked: ${marker.note}` };
+    }
+    const fin = await deps.gate(deps.cwd);
+    if (!fin.ok) {
+        return {
+            ok: false,
+            reason: `did not converge: ${fin.reason}`,
+            gateReason: fin.reason
+        };
+    }
+    return { ok: true, reason: fin.reason };
+}

package/dist/task/final-gate.d.ts

@@ -15,9 +15,45 @@ export declare function discoverIntegrationCommands(cwd: string): {
     ecosystem: string | null;
     cmds: HealthCommand[];
 };
+/** Every lockfile consistency check that applies to this tree (possibly none). */
+export declare function discoverLockfileChecks(cwd: string): HealthCommand[];
 /**
- * Run the final gate: static analysis first, then the discovered integration
- * commands, whole-repo, verbatim, unaided. Deterministic and synchronous under
- * the hood (callers wrap in Promise.resolve). First real failure wins.
+ * The project's OWN launch command, if it declares one (package.json `start`,
+ * else `dev`; Makefile `run`). null means the project has nothing to boot —
+ * the boot check degrades to nothing-to-run.
  */
-export declare function runFinalIntegrationGate(cwd: string, timeoutMs?: number): FinalGateOutcome;
+export declare function discoverBootCommand(cwd: string): HealthCommand | null;
+type BootOutcome = {
+    outcome: 'skip' | 'pass';
+} | {
+    outcome: 'fail';
+    detail: string;
+};
+/**
+ * Exercise the start command ONCE, with no port/URL/framework knowledge — the
+ * command's own fate within the grace window decides:
+ *
+ *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
+ *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
+ *   - still alive when the window closes → PASS, then the whole process group is
+ *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *
+ * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ */
+export declare function runBootCheck(cwd: string, [bin, args]: HealthCommand, graceMs?: number): Promise<BootOutcome>;
+/**
+ * Labels (`bin args…`) of every command the gate CAN currently discover — the
+ * static half (repo-health) plus the integration half. Pure discovery, nothing
+ * runs. Used by the final-gate autofix shrink guard: a fix pass that makes a
+ * previously-discoverable command undiscoverable (deleted the script/target) is
+ * gaming the gate, not fixing the defect.
+ */
+export declare function discoverGateCommandLabels(cwd: string): string[];
+/**
+ * Run the final gate: static analysis first, then the lockfile consistency
+ * checks, then the discovered integration commands, then one boot exercise of
+ * the start command — whole-repo, verbatim, unaided. Deterministic (no model).
+ * First real failure wins.
+ */
+export declare function runFinalIntegrationGate(cwd: string, timeoutMs?: number, bootGraceMs?: number): Promise<FinalGateOutcome>;
+export {};

package/dist/task/final-gate.js

@@ -15,7 +15,18 @@
  * and lets their REAL exit codes decide:
  *
  *   - static analysis first (runRepoHealthCheck — cheap, precise), then
- *   - the project's own `test` and `build` commands, run verbatim and unaided.
+ *   - lockfile↔manifest consistency (mx5 run 7, validated: the lockfile carried a
+ *     dependency no committed manifest declared, so the tree tested green here
+ *     but a FRESH CHECKOUT could not even install — each ecosystem's own offline
+ *     "is the lock in sync" command decides), then
+ *   - the project's own `test` and `build` commands, run verbatim and unaided, then
+ *   - one boot exercise of the project's own start command (mx5 run 7, validated:
+ *     every static and test gate green, yet `bun run start` died in ~1s on a
+ *     self-inflicted EADDRINUSE — nothing had ever LAUNCHED the finished project).
+ *     No ports, URLs, or framework knowledge: fast non-zero exit → FAIL, quick
+ *     exit 0 → PASS (CLI-style), still alive after the grace window → PASS and
+ *     the whole process group is killed (scripts spawn children; a leaked child
+ *     server would mask every later boot check with a port collision).
  *
  * Environment-gap safety, same contract as repo-health-check: a command that
  * CANNOT run (ENOENT, exit 127 = command-not-found inside the script chain, or a
@@ -27,10 +38,10 @@
  * per-task gates kept excusing — and the caller puts a human on the decision
  * (accept / leave failed), so a genuine external gap can still be overridden.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
-import { runRepoHealthCheck } from './repo-health-check.js';
+import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -96,6 +107,141 @@ export function discoverIntegrationCommands(cwd) {
     }
     return { ecosystem: null, cmds: [] };
 }
+/**
+ * Per-ecosystem lockfile↔manifest consistency checks. A check applies only when
+ * BOTH the manifest and its lockfile exist (no lockfile → nothing to verify),
+ * and every command is the ecosystem's own non-mutating "is the lock in sync
+ * with the manifest" form — validated to exit 0 fast on an in-sync tree and
+ * non-zero on a genuine desync, without touching the tree or (when in sync)
+ * the network.
+ */
+const LOCKFILE_CHECKS = [
+    {
+        manifest: 'package.json',
+        lockfiles: ['bun.lock', 'bun.lockb'],
+        cmd: ['bun', ['install', '--frozen-lockfile', '--dry-run']]
+    },
+    {
+        manifest: 'package.json',
+        lockfiles: ['package-lock.json'],
+        cmd: ['npm', ['ci', '--dry-run']]
+    },
+    {
+        manifest: 'Cargo.toml',
+        lockfiles: ['Cargo.lock'],
+        cmd: ['cargo', ['metadata', '--locked', '--format-version', '1']]
+    },
+    { manifest: 'go.mod', lockfiles: ['go.sum'], cmd: ['go', ['mod', 'verify']] },
+    { manifest: 'pyproject.toml', lockfiles: ['uv.lock'], cmd: ['uv', ['lock', '--check']] },
+    { manifest: 'pyproject.toml', lockfiles: ['poetry.lock'], cmd: ['poetry', ['check', '--lock']] }
+];
+/** Every lockfile consistency check that applies to this tree (possibly none). */
+export function discoverLockfileChecks(cwd) {
+    const cmds = [];
+    for (const { manifest, lockfiles, cmd } of LOCKFILE_CHECKS) {
+        if (!existsSync(path.join(cwd, manifest)))
+            continue;
+        if (!lockfiles.some(f => existsSync(path.join(cwd, f))))
+            continue;
+        cmds.push(cmd);
+    }
+    return cmds;
+}
+/**
+ * The project's OWN launch command, if it declares one (package.json `start`,
+ * else `dev`; Makefile `run`). null means the project has nothing to boot —
+ * the boot check degrades to nothing-to-run.
+ */
+export function discoverBootCommand(cwd) {
+    if (existsSync(path.join(cwd, 'package.json'))) {
+        const s = packageScripts(cwd);
+        for (const name of ['start', 'dev']) {
+            if (s[name])
+                return ['bun', ['run', name]];
+        }
+        return null;
+    }
+    if (existsSync(path.join(cwd, 'Makefile')) && makeHasTarget(cwd, 'run')) {
+        return ['make', ['run']];
+    }
+    return null;
+}
+/**
+ * Exercise the start command ONCE, with no port/URL/framework knowledge — the
+ * command's own fate within the grace window decides:
+ *
+ *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
+ *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
+ *   - still alive when the window closes → PASS, then the whole process group is
+ *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
+ *
+ * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
+ */
+export function runBootCheck(cwd, [bin, args], graceMs = 10_000) {
+    return new Promise(resolve => {
+        const child = spawn(bin, args, {
+            cwd,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env }
+        });
+        let out = '';
+        let err = '';
+        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))));
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        const killGroup = (sig) => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, sig);
+            }
+            catch {
+                // group already gone
+            }
+        };
+        const timer = setTimeout(() => {
+            settle({ outcome: 'pass' });
+            killGroup('SIGTERM');
+            setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+        }, graceMs);
+        child.on('error', () => settle({ outcome: 'skip' }));
+        child.on('exit', (status, signal) => {
+            if (status === 0)
+                return settle({ outcome: 'pass' });
+            if (status === 127 || (status === null && signal === null)) {
+                return settle({ outcome: 'skip' });
+            }
+            const what = status !== null ? `exited ${status}` : `was killed by ${signal}`;
+            const tail = outputTail(out, err);
+            settle({ outcome: 'fail', detail: `${what}${tail ? ` — ${tail}` : ''}` });
+        });
+    });
+}
+/**
+ * Labels (`bin args…`) of every command the gate CAN currently discover — the
+ * static half (repo-health) plus the integration half. Pure discovery, nothing
+ * runs. Used by the final-gate autofix shrink guard: a fix pass that makes a
+ * previously-discoverable command undiscoverable (deleted the script/target) is
+ * gaming the gate, not fixing the defect.
+ */
+export function discoverGateCommandLabels(cwd) {
+    const boot = discoverBootCommand(cwd);
+    const labels = [
+        ...discoverHealthCommands(cwd).cmds,
+        ...discoverLockfileChecks(cwd),
+        ...discoverIntegrationCommands(cwd).cmds,
+        ...(boot ? [boot] : [])
+    ].map(([bin, args]) => `${bin} ${args.join(' ')}`);
+    return [...new Set(labels)];
+}
 /** Last ~`limit` chars of the command's combined output, one line, for the reason. */
 function outputTail(stdout, stderr, limit = 400) {
     const combined = `${stdout}\n${stderr}`.trim();
@@ -105,34 +251,70 @@ function outputTail(stdout, stderr, limit = 400) {
     return combined.length > limit ? `…${tail}` : tail;
 }
 /**
- * Run the final gate: static analysis first, then the discovered integration
- * commands, whole-repo, verbatim, unaided. Deterministic and synchronous under
- * the hood (callers wrap in Promise.resolve). First real failure wins.
+ * Run one gate command with the env-gap contract: tool missing, timeout, or
+ * command-not-found inside the script chain (127) → environment gap, not a code
+ * fault → skipped (same contract as repo-health). Only a command that actually
+ * ran and exited non-zero fails.
+ */
+function runGateCommand(cwd, [bin, args], timeoutMs) {
+    // env passed explicitly: bun's spawnSync resolves the binary against a
+    // startup snapshot of the environment, not the live process.env.
+    const r = spawnSync(bin, args, {
+        cwd,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        env: { ...process.env }
+    });
+    if (r.error || r.status === null || r.status === 127)
+        return { outcome: 'skip' };
+    if (r.status !== 0) {
+        return { outcome: 'fail', status: r.status, tail: outputTail(r.stdout ?? '', r.stderr ?? '') };
+    }
+    return { outcome: 'pass' };
+}
+/**
+ * Run the final gate: static analysis first, then the lockfile consistency
+ * checks, then the discovered integration commands, then one boot exercise of
+ * the start command — whole-repo, verbatim, unaided. Deterministic (no model).
+ * First real failure wins.
  */
-export function runFinalIntegrationGate(cwd, timeoutMs = 900_000) {
+export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000) {
     const stat = runRepoHealthCheck(cwd);
     if (!stat.ok)
         return { ok: false, reason: `static checks: ${stat.reason}` };
-    const { ecosystem, cmds } = discoverIntegrationCommands(cwd);
-    if (!ecosystem || cmds.length === 0) {
+    const lockCmds = discoverLockfileChecks(cwd);
+    const { cmds } = discoverIntegrationCommands(cwd);
+    const boot = discoverBootCommand(cwd);
+    if (lockCmds.length === 0 && cmds.length === 0 && !boot) {
         return { ok: true, reason: 'no integration command found (statics passed)' };
     }
     const ran = [];
-    for (const [bin, args] of cmds) {
-        const label = `${bin} ${args.join(' ')}`;
-        const r = spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: timeoutMs });
-        // Tool missing, timeout, or command-not-found inside the script chain →
-        // environment gap, not a code fault; skip (same contract as repo-health).
-        if (r.error || r.status === null || r.status === 127)
-            continue;
-        if (r.status !== 0) {
-            const tail = outputTail(r.stdout ?? '', r.stderr ?? '');
-            return {
-                ok: false,
-                reason: `\`${label}\` exited ${r.status}${tail ? ` — ${tail}` : ''}`
-            };
+    for (const { prefix, list } of [
+        { prefix: 'lockfile check: ', list: lockCmds },
+        { prefix: '', list: cmds }
+    ]) {
+        for (const cmd of list) {
+            const label = `${cmd[0]} ${cmd[1].join(' ')}`;
+            const r = runGateCommand(cwd, cmd, timeoutMs);
+            if (r.outcome === 'skip')
+                continue;
+            if (r.outcome === 'fail') {
+                return {
+                    ok: false,
+                    reason: `${prefix}\`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`
+                };
+            }
+            ran.push(label);
+        }
+    }
+    if (boot) {
+        const label = `${boot[0]} ${boot[1].join(' ')}`;
+        const b = await runBootCheck(cwd, boot, bootGraceMs);
+        if (b.outcome === 'fail') {
+            return { ok: false, reason: `boot check: \`${label}\` ${b.detail}` };
         }
-        ran.push(label);
+        if (b.outcome === 'pass')
+            ran.push(label);
     }
     return {
         ok: true,

package/dist/task/gate-deps.d.ts

@@ -1,8 +1,13 @@
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { GateDeps } from './task-gates.js';
+import { type FinalFixResult } from './final-gate-fix.js';
 import { type ChangedFile } from './substitution-probe.js';
 /** A function that re-runs a task's implementation turn (AUTOFIX). Injected by the
  *  command so this module stays free of the orchestrators (avoids an import cycle). */
 export type RunTaskFn = GateDeps['runTask'];
+/** One bounded final-gate fix attempt (see final-gate-fix.ts): fix child →
+ *  shrink guard → gate re-run. Consumed by /task-auto's run-end gate branch. */
+export type FinalGateFixFn = (ctx: ExtensionCommandContext, cwd: string, failReason: string) => Promise<FinalFixResult>;
 /**
  * Collect the task's changed files as pure GIT SHAPE — path + added-line count,
  * no content, no language parsing — for the self-verification probe. Before the
@@ -23,4 +28,6 @@ export declare function buildGateDeps(params: {
     signal: AbortSignal;
     parentContextWindow: number;
     runTask: RunTaskFn;
-}): GateDeps;
+}): GateDeps & {
+    finalGateFix: FinalGateFixFn;
+};