@mjasnikovs/pi-task 0.18.12 → 0.18.14

package/dist/task/final-gate.js

@@ -43,6 +43,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.js';
 import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtNote } from './accept-debt.js';
+import { readDeclaredScripts, missingDeclaredScripts } from './launch-contract.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -71,10 +72,18 @@ export function discoverIntegrationCommands(cwd) {
     if (existsSync(path.join(cwd, 'package.json'))) {
         const s = packageScripts(cwd);
         const cmds = [];
-        for (const name of ['test', 'build']) {
-            if (s[name])
-                cmds.push(['bun', ['run', name]]);
-        }
+        // Every test-shaped script, not just the one literally named `test` (mx5 run
+        // 10: `test:ct` — 89 Playwright component tests, the ONLY client-executing
+        // suite — never ran because the gate looked only for `test`/`build`). Plain
+        // `test` leads (richer, most common), then `test:*`/`test-*` in declaration
+        // order, then `build`. Env-gap SKIP still applies per command (a suite whose
+        // browser/runtime is absent skips, it does not fail — see runGateCommand).
+        const testNames = Object.keys(s).filter(n => n === 'test' || /^test[:_-]/.test(n));
+        testNames.sort((a, b) => (a === 'test' ? -1 : b === 'test' ? 1 : 0));
+        for (const name of testNames)
+            cmds.push(['bun', ['run', name]]);
+        if (s.build)
+            cmds.push(['bun', ['run', 'build']]);
         return { ecosystem: 'package.json', cmds };
     }
     if (existsSync(path.join(cwd, 'Makefile'))) {
@@ -183,6 +192,90 @@ function extractPort(text) {
     const n = Number(m[1]);
     return n > 0 && n < 65536 ? n : null;
 }
+/** Package deps that mean "this project stands up an HTTP server" — the deterministic
+ *  proxy for "the plan/spec promised a served app". Bare framework names plus the
+ *  scoped families whose presence implies a listener at runtime. */
+function isServerFrameworkDep(name) {
+    return (/^(?:hono|express|fastify|koa|polka|restify|next|nuxt|http-server|serve|ws|socket\.io)$/.test(name) || /^@(?:hono|fastify|koa|nestjs|sveltejs|remix-run)\//.test(name));
+}
+/** Spec/plan phrasings that promise a listening server, for the text signal. */
+const SERVE_TEXT_RE = /\b(?:https?\s+server|web\s+server|serves?\b|listen(?:s|ing)?\b|Bun\.serve|app\.listen|createServer|serve\s+(?:static|the)|\/api\/|endpoints?\b)/i;
+/**
+ * Does the finished run stand up a listening HTTP server? Deterministic, from the
+ * built manifest (a server-framework dependency is the plan's own artifact) OR, when
+ * available, the plan/spec text. Used to decide whether the boot check must observe a
+ * LISTENER (served app) or may pass on mere survival / quick exit (CLI project).
+ */
+export function detectsServedApp(cwd, planText) {
+    try {
+        const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        const all = { ...(j.dependencies ?? {}), ...(j.devDependencies ?? {}) };
+        if (Object.keys(all).some(isServerFrameworkDep))
+            return true;
+    }
+    catch {
+        // no/unreadable manifest → fall through to the text signal
+    }
+    return planText !== undefined && SERVE_TEXT_RE.test(planText);
+}
+/** Pids currently owning a LISTENing TCP socket (best-effort; ss first, then lsof).
+ *  Empty on any failure — the caller then cannot attribute a listener to our group
+ *  and the served-app check degrades to survival (never a false FAIL). */
+function listeningSocketPids() {
+    const pids = new Set();
+    try {
+        const t = spawnSync('ss', ['-tlnpH'], { encoding: 'utf8', timeout: 4000 });
+        if (!t.error && t.stdout) {
+            for (const m of t.stdout.matchAll(/pid=(\d+)/g))
+                pids.add(Number(m[1]));
+        }
+    }
+    catch {
+        // ss missing — try lsof
+    }
+    if (pids.size === 0) {
+        try {
+            const t = spawnSync('lsof', ['-iTCP', '-sTCP:LISTEN', '-t', '-n', '-P'], {
+                encoding: 'utf8',
+                timeout: 4000
+            });
+            if (!t.error && t.stdout) {
+                for (const line of t.stdout.split('\n')) {
+                    const n = Number(line.trim());
+                    if (Number.isInteger(n) && n > 0)
+                        pids.add(n);
+                }
+            }
+        }
+        catch {
+            // neither tool available
+        }
+    }
+    return [...pids];
+}
+/** Process-group id of `pid`, or null if it cannot be read. */
+function pgidOf(pid) {
+    try {
+        const r = spawnSync('ps', ['-o', 'pgid=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 4000
+        });
+        const n = Number((r.stdout ?? '').trim());
+        return Number.isInteger(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default listener probe: any LISTENing socket owned by a pid in process group
+ *  `pgid` (the detached boot child IS its own group leader, so pgid === child.pid). */
+function defaultGroupHasListener(pgid) {
+    for (const pid of listeningSocketPids()) {
+        if (pgidOf(pid) === pgid)
+            return true;
+    }
+    return false;
+}
 /** Default port-holder lookup: `lsof` first, then `ss`/`fuser`. Returns null on any
  *  failure (the diagnosis then omits the pid — never blocks). */
 function defaultFindPortHolder(port) {
@@ -231,7 +324,7 @@ function holderIsOurs(command, boot) {
         && (c.includes(` ${script}`) || c.endsWith(script)));
 }
 /**
- * Exercise the start command ONCE, with no port/URL/framework knowledge — the
+ * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
  * command's own fate within the grace window decides:
  *
  *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
@@ -239,9 +332,21 @@ function holderIsOurs(command, boot) {
  *   - still alive when the window closes → PASS, then the whole process group is
  *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
  *
+ * For a SERVED app (`expectServer` true — the spec/plan promised an HTTP server) mere
+ * survival is not enough: a watcher (`dev` = tailwind/bundler --watch) stays alive
+ * forever without ever listening, and a type-only entrypoint exits 0 in <1s having
+ * served nothing (mx5 run 10 — both were blessed by the survival rule). The boot then
+ * PASSes only once a LISTENing socket owned by our process group is observed; if the
+ * command exits, or the grace window closes, with no listener ever seen → FAIL naming
+ * that a listening server was expected. (The listener requirement needs pgid probing,
+ * absent on win32, where `expectServer` collapses to the survival rule — best-effort,
+ * never a false FAIL on a platform we cannot probe.)
+ *
  * Env-gap contract as everywhere: spawn error (ENOENT) or exit 127 → skip.
  */
-export function runBootCheck(cwd, [bin, args], graceMs = 10_000) {
+export function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}) {
+    const expectServer = (opts.expectServer ?? false) && process.platform !== 'win32';
+    const groupHasListener = opts.deps?.groupHasListener ?? defaultGroupHasListener;
     return new Promise(resolve => {
         const child = spawn(bin, args, {
             cwd,
@@ -251,6 +356,7 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000) {
         });
         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))));
@@ -260,6 +366,8 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000) {
                 return;
             settled = true;
             clearTimeout(timer);
+            if (poll)
+                clearInterval(poll);
             resolve(r);
         };
         const killGroup = (sig) => {
@@ -281,15 +389,47 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000) {
                 // group already gone
             }
         };
-        const timer = setTimeout(() => {
+        const passAndKill = () => {
             settle({ outcome: 'pass' });
             killGroup('SIGTERM');
             setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+        };
+        // Served apps only: poll for a listening socket owned by our process group.
+        // As soon as one appears the boot has demonstrably served → PASS early.
+        const poll = expectServer ?
+            setInterval(() => {
+                if (settled || !child.pid)
+                    return;
+                if (groupHasListener(child.pid)) {
+                    listenerSeen = true;
+                    passAndKill();
+                }
+            }, 500)
+            : null;
+        const timer = setTimeout(() => {
+            if (expectServer && !listenerSeen) {
+                settle({
+                    outcome: 'fail',
+                    detail: `still running after ${graceMs}ms but never opened a listening socket — the spec/dependencies promise an HTTP server`
+                });
+                killGroup('SIGTERM');
+                setTimeout(() => killGroup('SIGKILL'), 2_000).unref();
+                return;
+            }
+            passAndKill();
         }, graceMs);
         child.on('error', () => settle({ outcome: 'skip' }));
         child.on('exit', (status, signal) => {
-            if (status === 0)
+            if (status === 0) {
+                if (expectServer && !listenerSeen) {
+                    return settle({
+                        outcome: 'fail',
+                        detail: 'exited 0 without ever opening a listening socket — the spec/dependencies '
+                            + 'promise an HTTP server, so a boot that serves nothing is not a launch'
+                    });
+                }
                 return settle({ outcome: 'pass' });
+            }
             if (status === 127 || (status === null && signal === null)) {
                 return settle({ outcome: 'skip' });
             }
@@ -335,11 +475,20 @@ function outputTail(stdout, stderr, limit = 400) {
     const tail = combined.slice(-limit).replace(/\s+/g, ' ').trim();
     return combined.length > limit ? `…${tail}` : tail;
 }
+/**
+ * A non-zero exit whose output shows an EXTERNAL runtime dependency is missing, not
+ * a code fault: a browser suite (Playwright/Cypress) whose browser binaries or system
+ * libraries were never installed here (mx5 run 10 item 2: `test:ct` must run in the
+ * gate, but on a box with no Playwright browsers it is an environment gap, not a FAIL).
+ * These exit non-zero (not 127), so they need output-shape recognition to skip.
+ */
+const ENV_GAP_OUTPUT_RE = /Executable doesn't exist|playwright install|browserType\.\w+: Executable|(?:wasn't|weren't) installed|Host system is missing dependencies|No usable sandbox|Cypress verification|Cypress executable (?:not found|was not found)|browser(?:s)? (?:is|are)? ?not installed/i;
 /**
  * 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.
+ * fault → skipped (same contract as repo-health). Also skips a non-zero exit whose
+ * output shows a missing browser/runtime (ENV_GAP_OUTPUT_RE). Only a command that
+ * actually ran and exited non-zero for a real reason fails.
  */
 function runGateCommand(cwd, [bin, args], timeoutMs) {
     // env passed explicitly: bun's spawnSync resolves the binary against a
@@ -353,6 +502,8 @@ function runGateCommand(cwd, [bin, args], timeoutMs) {
     if (r.error || r.status === null || r.status === 127)
         return { outcome: 'skip' };
     if (r.status !== 0) {
+        if (ENV_GAP_OUTPUT_RE.test(`${r.stdout ?? ''}\n${r.stderr ?? ''}`))
+            return { outcome: 'skip' };
         return { outcome: 'fail', status: r.status, tail: outputTail(r.stdout ?? '', r.stderr ?? '') };
     }
     return { outcome: 'pass' };
@@ -364,7 +515,7 @@ function runGateCommand(cwd, [bin, args], timeoutMs) {
  * the caller emit the harness diagnosis. Never reaps a process we cannot attribute
  * to ourselves.
  */
-async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps) {
+async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps, expectServer) {
     if (first.port === null)
         return first;
     const holder = (deps.findPortHolder ?? defaultFindPortHolder)(first.port);
@@ -375,7 +526,7 @@ async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps) {
         return first;
     // Give the OS a moment to release the socket, then re-run the boot once.
     await new Promise(r => setTimeout(r, 1_500));
-    return runBootCheck(cwd, boot, bootGraceMs);
+    return runBootCheck(cwd, boot, bootGraceMs, { expectServer, deps });
 }
 /**
  * Run the final gate: static analysis first, then the lockfile consistency
@@ -383,7 +534,7 @@ async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps) {
  * the start command — whole-repo, verbatim, unaided. Deterministic (no model).
  * First real failure wins.
  */
-export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000, bootDeps = {}) {
+export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000, bootDeps = {}, planText) {
     const stat = runRepoHealthCheck(cwd);
     // ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
     // the user accepted despite a verify-FAIL and re-check each against the current
@@ -406,6 +557,20 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     });
     if (!stat.ok)
         return withDebts({ ok: false, reason: `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
+    // launch-surface defect. FP-safe: empty declared list (nothing grounded) → no check.
+    const declared = await readDeclaredScripts(cwd);
+    if (declared.length > 0) {
+        const missing = missingDeclaredScripts(declared, Object.keys(packageScripts(cwd)));
+        if (missing.length > 0) {
+            return withDebts({
+                ok: false,
+                reason: `launch contract: the design declares script(s) the shipped package.json does not expose: ${missing.join(', ')} (declared: ${declared.join(', ')})`
+            });
+        }
+    }
     const lockCmds = discoverLockfileChecks(cwd);
     const { cmds } = discoverIntegrationCommands(cwd);
     const boot = discoverBootCommand(cwd);
@@ -433,9 +598,10 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     }
     if (boot) {
         const label = `${boot[0]} ${boot[1].join(' ')}`;
-        let b = await runBootCheck(cwd, boot, bootGraceMs);
+        const expectServer = detectsServedApp(cwd, planText);
+        let b = await runBootCheck(cwd, boot, bootGraceMs, { expectServer, deps: bootDeps });
         if (b.outcome === 'orphan-port') {
-            b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDeps);
+            b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDeps, expectServer);
         }
         if (b.outcome === 'fail') {
             return withDebts({ ok: false, reason: `boot check: \`${label}\` ${b.detail}` });

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

@@ -6,6 +6,12 @@ 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-line, tail-kept, whitespace-flattened summary of a tool's output for the gate
+ * debug log. The TAIL is kept (a bind failure / final status / assertion lands at the
+ * end of the output) with a leading ellipsis when truncated; empty output → "(no output)".
+ */
+export declare function truncateToolResult(text: string, limit?: number): string;
 /** 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>;

package/dist/task/gate-deps.js

@@ -21,7 +21,7 @@ import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { readContracts } from './contracts.js';
-import { recordAcceptDebt } from './accept-debt.js';
+import { recordAcceptDebt, recordEnforceRevertDebt } from './accept-debt.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels } from './final-gate.js';
 import { runFinalGateAutofix } from './final-gate-fix.js';
@@ -38,6 +38,19 @@ import { formatLoopHint } from './child-runner.js';
 import { getConfig } from '../config/config.js';
 import { startAutoLoader } from './widget.js';
 import { resolveContextUsage } from './context-usage.js';
+/** Max chars of a tool result kept in the gate debug log (mx5 run 10 item 6). */
+const TOOL_RESULT_LOG_LIMIT = 300;
+/**
+ * One-line, tail-kept, whitespace-flattened summary of a tool's output for the gate
+ * debug log. The TAIL is kept (a bind failure / final status / assertion lands at the
+ * end of the output) with a leading ellipsis when truncated; empty output → "(no output)".
+ */
+export function truncateToolResult(text, limit = TOOL_RESULT_LOG_LIMIT) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    if (flat.length === 0)
+        return '(no output)';
+    return flat.length > limit ? `…${flat.slice(-limit)}` : flat;
+}
 /** Keep the gate machinery's own artifacts out of every git pathspec below. */
 const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
 const splitLines = (s) => s
@@ -230,6 +243,11 @@ export function buildGateDeps(params) {
                         lastLine = line;
                         log(line);
                     },
+                    // Log tool OUTPUTS, not just the command (mx5 run 10 item 6):
+                    // without the result "verify claimed curl PASS on a server that
+                    // cannot serve" is undecidable from the log. Truncated, tail-kept
+                    // (a bind failure / status usually lands at the end), error-flagged.
+                    onToolResult: ({ name, isError, text }) => log(`↳ ${name} [${isError ? 'ERR' : 'ok'}]: ${truncateToolResult(text)}`),
                     onContextUsage: snapshot => {
                         contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
                     }
@@ -278,6 +296,7 @@ export function buildGateDeps(params) {
         // Durable ACCEPT-despite-verify-FAIL ledger under .pi-tasks/ (survives
         // discardEdits): the final integration gate re-checks each debt at run end.
         recordAcceptDebt: (cwd2, taskId, reason) => recordAcceptDebt(cwd2, taskId, reason),
+        recordEnforceRevertDebt: (cwd2, taskId, reason) => recordEnforceRevertDebt(cwd2, taskId, reason),
         // Frozen-path write-deny (see frozen-path-guard.ts): the concrete paths this
         // task's spec forbids modifying, so the gate sequence can UNDO any edit the
         // enforce EDIT pass makes to them before those edits are committed. Reads the

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

@@ -38,6 +38,7 @@
  * missing) disables the guard (capture returns ok:false and reconcile no-ops) —
  * the gate must keep working in non-git projects exactly as before.
  */
+import { readFileSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -62,6 +63,55 @@ function isBenignArtifact(relPath) {
     const p = relPath.replace(/\\/g, '/');
     return ARTIFACT_PATTERNS.some(re => re.test(p));
 }
+/**
+ * Regenerable machine state that is benign EVEN WHEN TRACKED — a project that
+ * mistakenly commits it (mx5 run 10 does exactly this) must not have a gate child's
+ * incidental rewrite of it discard the verdict. Two classes:
+ *   - Playwright component-test build cache (`ctCacheDir` — run 10 committed 60+
+ *     `.playwright-cache/assets/*.js` bundles; a `test:ct` run rewrites them every
+ *     time), and
+ *   - the test runner's `.last-run.json` run-state file.
+ * DELIBERATELY narrow: snapshot BASELINE images (`*-snapshots/*.png`) are NOT here —
+ * a child that rewrites a baseline to make a screenshot test pass is the real
+ * mutate-to-pass catch (run 10's other half), so those stay verdict-tainting.
+ */
+const ALWAYS_REGENERABLE_PATTERNS = [/(?:^|\/)\.last-run\.json$/];
+/** Playwright config files that may declare a custom `ctCacheDir`. */
+const CT_CONFIG_FILES = [
+    'playwright-ct.config.ts',
+    'playwright-ct.config.js',
+    'playwright.config.ts',
+    'playwright.config.js'
+];
+/** ctCacheDir defaults Playwright uses when a config does not override it. */
+const DEFAULT_CT_CACHE_DIRS = ['.playwright-cache', 'playwright/.cache'];
+/**
+ * The component-test cache dir(s) for this project: the `ctCacheDir` any Playwright
+ * config declares, plus the known defaults. Read once per reconcile (best-effort — a
+ * missing/odd config just leaves the defaults). Normalised to a repo-relative prefix.
+ */
+function readCtCacheDirs(cwd) {
+    const dirs = new Set(DEFAULT_CT_CACHE_DIRS);
+    for (const f of CT_CONFIG_FILES) {
+        try {
+            const text = readFileSync(path.join(cwd, f), 'utf8');
+            const m = /ctCacheDir\s*:\s*['"`]([^'"`]+)['"`]/.exec(text);
+            if (m)
+                dirs.add(m[1].replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, ''));
+        }
+        catch {
+            // no such config, or unreadable — defaults stand
+        }
+    }
+    return [...dirs].filter(d => d.length > 0);
+}
+/** Is this path regenerable machine state that is benign even when tracked-in-HEAD? */
+function isAlwaysRegenerable(relPath, ctCacheDirs) {
+    const p = relPath.replace(/\\/g, '/');
+    if (ALWAYS_REGENERABLE_PATTERNS.some(re => re.test(p)))
+        return true;
+    return ctCacheDirs.some(d => p === d || p.startsWith(d + '/'));
+}
 function makeGit(cwd, signal, spawnFn) {
     return async (args, env) => {
         const r = await runChildDefault({ command: 'git', args, ...(env ? { env: { ...process.env, ...env } } : {}) }, cwd, signal, { mode: 'text' }, spawnFn);
@@ -151,7 +201,7 @@ function pushCapped(actions, verb, paths) {
  * Creations and test-runner-artifact churn restore identically but do NOT taint.
  * Each changed path is itemised (capped) so the gate trail says WHICH files moved.
  */
-async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, actions) {
+async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, ctCacheDirs, actions) {
     const tmpIndex = path.join(os.tmpdir(), `pi-task-guard-restore-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
     const env = { GIT_INDEX_FILE: tmpIndex };
     let tainted = false;
@@ -180,8 +230,11 @@ async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, actions
                 if (code === 'A') {
                     created.push(name);
                 }
-                else if (isBenignArtifact(name) && !tracked.has(name)) {
-                    // Untracked, regenerable test/build output — not graded work.
+                else if (isAlwaysRegenerable(name, ctCacheDirs)
+                    || (isBenignArtifact(name) && !tracked.has(name))) {
+                    // Regenerable test/build output — not graded work. Either an
+                    // always-regenerable class (ct cache / run-state, benign even when
+                    // tracked — mx5 run 10) or untracked test-runner output.
                     artifactChanges.push(name);
                 }
                 else if (code === 'D') {
@@ -258,7 +311,8 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
         const afterTree = await captureWorktreeTree(git);
         if (afterTree && afterTree !== before.treeSha) {
             const tracked = await trackedPathsAt(git, before.headSha);
-            const { tainted: worktreeTainted } = await restoreWorktree(cwd, git, before.treeSha, afterTree, tracked, actions);
+            const ctCacheDirs = readCtCacheDirs(cwd);
+            const { tainted: worktreeTainted } = await restoreWorktree(cwd, git, before.treeSha, afterTree, tracked, ctCacheDirs, actions);
             tainted = tainted || worktreeTainted;
         }
     }

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

@@ -0,0 +1,31 @@
+export declare function launchContractFile(cwd: string): string;
+/**
+ * Parse `SCRIPT: <name>` lines out of a child's answer into bare script names. A line
+ * whose token is not script-name-shaped is skipped (an accidental sentence, a path).
+ */
+export declare function parseScriptLines(text: string): string[];
+/**
+ * THE GROUNDING GUARD: keep only names the design declares as an inline-code token
+ * (`` `name` ``) — the form a design uses to name a script. A name the model
+ * paraphrased or invented has no such token, so it is dropped and the diff cannot
+ * false-flag on it. Deduplicated, case-insensitive.
+ */
+export declare function keepGroundedScripts(names: string[], sourceDoc: string): string[];
+/** The stored declared-script list ('' when none recorded). */
+export declare function readLaunchContractRaw(cwd: string): Promise<string>;
+/** The declared script names recorded for this run (deduped, order preserved). */
+export declare function readDeclaredScripts(cwd: string): Promise<string[]>;
+/** Append grounded script names, deduped against what is stored, keeping newest MAX. */
+export declare function appendDeclaredScripts(cwd: string, names: string[]): Promise<void>;
+/**
+ * Declared scripts the manifest does NOT expose (case-insensitive). Empty when every
+ * declared script is present, or when nothing was declared (no check). This is the
+ * deterministic lever the final gate FAILs on.
+ */
+export declare function missingDeclaredScripts(declared: string[], manifestScripts: string[]): string[];
+/**
+ * The plan-time extraction prompt: the design in hand, emit the scripts it declares.
+ * Runs with --no-tools (pure extraction). Every emitted name is re-grounded HOST-SIDE
+ * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
+ */
+export declare const LAUNCH_EXTRACT_PROMPT: (feature: string) => string;

package/dist/task/launch-contract.js

@@ -0,0 +1,162 @@
+/**
+ * launch-contract — a per-run record of the package/build SCRIPTS the SOURCE design
+ * 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.
+ *
+ * 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
+ * kept only if the design mentions it as an inline-code token (`` `migrate` ``), the
+ * 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.
+ *
+ * At run end the final gate reads the list, reads the manifest's `scripts`, 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.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir } from './task-io.js';
+const LAUNCH_CONTRACT_FILE = 'launch-contract.md';
+/** Cap kept entries so a noisy extraction cannot grow the artifact unboundedly. */
+const MAX_SCRIPTS = 40;
+/** npm/package script names are short kebab/colon tokens; reject anything unscript-like. */
+const SCRIPT_NAME_RE = /^[a-z0-9][a-z0-9:_-]{0,39}$/i;
+export function launchContractFile(cwd) {
+    return path.join(tasksDir(cwd), LAUNCH_CONTRACT_FILE);
+}
+/**
+ * Parse `SCRIPT: <name>` lines out of a child's answer into bare script names. A line
+ * whose token is not script-name-shaped is skipped (an accidental sentence, a path).
+ */
+export function parseScriptLines(text) {
+    const out = [];
+    for (const m of text.matchAll(/^[ \t]*SCRIPT:[ \t]*(.+)$/gim)) {
+        // Take the first whitespace/comma-delimited token, stripping backticks/quotes.
+        const raw = m[1].trim().split(/[\s,]+/)[0]?.replace(/[`'"]/g, '') ?? '';
+        if (SCRIPT_NAME_RE.test(raw))
+            out.push(raw);
+    }
+    return out;
+}
+/**
+ * THE GROUNDING GUARD: keep only names the design declares as an inline-code token
+ * (`` `name` ``) — the form a design uses to name a script. A name the model
+ * paraphrased or invented has no such token, so it is dropped and the diff cannot
+ * false-flag on it. Deduplicated, case-insensitive.
+ */
+export function keepGroundedScripts(names, sourceDoc) {
+    const haystack = sourceDoc.toLowerCase();
+    const seen = new Set();
+    const kept = [];
+    for (const n of names) {
+        const key = n.toLowerCase();
+        if (seen.has(key))
+            continue;
+        if (!haystack.includes('`' + key + '`'))
+            continue;
+        seen.add(key);
+        kept.push(n);
+    }
+    return kept;
+}
+/** The stored declared-script list ('' when none recorded). */
+export async function readLaunchContractRaw(cwd) {
+    try {
+        return (await fsp.readFile(launchContractFile(cwd), 'utf8')).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** The declared script names recorded for this run (deduped, order preserved). */
+export async function readDeclaredScripts(cwd) {
+    const raw = await readLaunchContractRaw(cwd);
+    const seen = new Set();
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const n = line.trim();
+        if (n.length === 0 || !SCRIPT_NAME_RE.test(n))
+            continue;
+        const key = n.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(n);
+    }
+    return out;
+}
+/** Append grounded script names, deduped against what is stored, keeping newest MAX. */
+export async function appendDeclaredScripts(cwd, names) {
+    if (names.length === 0)
+        return;
+    try {
+        const existing = await readDeclaredScripts(cwd);
+        const seen = new Set(existing.map(n => n.toLowerCase()));
+        const merged = [...existing];
+        for (const n of names) {
+            if (seen.has(n.toLowerCase()))
+                continue;
+            seen.add(n.toLowerCase());
+            merged.push(n);
+        }
+        const kept = merged.slice(-MAX_SCRIPTS);
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        await fsp.writeFile(launchContractFile(cwd), kept.join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // best-effort artifact
+    }
+}
+/**
+ * Declared scripts the manifest does NOT expose (case-insensitive). Empty when every
+ * declared script is present, or when nothing was declared (no check). This is the
+ * deterministic lever the final gate FAILs on.
+ */
+export function missingDeclaredScripts(declared, manifestScripts) {
+    const have = new Set(manifestScripts.map(s => s.toLowerCase()));
+    const seen = new Set();
+    const missing = [];
+    for (const d of declared) {
+        const key = d.toLowerCase();
+        if (have.has(key) || seen.has(key))
+            continue;
+        seen.add(key);
+        missing.push(d);
+    }
+    return missing;
+}
+/**
+ * The plan-time extraction prompt: the design in hand, emit the scripts it declares.
+ * Runs with --no-tools (pure extraction). Every emitted name is re-grounded HOST-SIDE
+ * (keepGroundedScripts), so a hallucinated script cannot reach the diff.
+ */
+export const LAUNCH_EXTRACT_PROMPT = (feature) => [
+    'You are recording the PACKAGE/BUILD SCRIPTS the design below says the finished',
+    'project MUST expose (the `scripts` a package.json / Makefile / task runner must',
+    'declare — e.g. build, test, a migration runner, a seed step, a start/serve command).',
+    'These are launch-surface entrypoints the whole project shares; if one the design',
+    'names is missing from the shipped manifest, the project cannot be run as specified.',
+    '',
+    'DESIGN (the ONLY source — name only scripts the design itself declares):',
+    feature.trim(),
+    '',
+    'For each script the design declares by name, emit exactly:',
+    '  SCRIPT: <name>',
+    'one per line, the bare script name only (e.g. `SCRIPT: migrate`). RULES: (1) name',
+    'ONLY scripts the design explicitly lists — do NOT invent conventional ones it does',
+    'not mention. (2) Use the exact name the design uses. (3) A name that is not literally',
+    'in the design is DISCARDED host-side, so guessing wastes effort. If the design',
+    'declares no scripts, output nothing.',
+    '',
+    'Output the SCRIPT: lines and nothing else.'
+].join('\n');