@mjasnikovs/pi-task 0.18.10 → 0.18.12

package/dist/shared/child-process.d.ts

@@ -14,6 +14,9 @@ export interface ProcLike extends EventEmitter {
     stdout: EventEmitter | null;
     stderr: EventEmitter | null;
     killed: boolean;
+    /** OS pid; used to signal the child's whole process GROUP (orphan reaping). May
+     *  be undefined for a mock spawn or a spawn that failed. */
+    pid?: number;
     kill(signal: string): boolean | void;
 }
 export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
@@ -23,6 +26,11 @@ export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
     /** Set only when the invocation needs env overrides (e.g. GIT_INDEX_FILE);
      *  absent → the child inherits this process's environment as before. */
     env?: NodeJS.ProcessEnv;
+    /** true → give the child its own process group (POSIX `detached`), so any
+     *  server it backgrounds (`bun run dev &`) can be reaped as a group when the
+     *  child exits instead of leaking as an orphan holding a port (mx5 run 9
+     *  item 3). Set only for model children (json-events); plumbing stays put. */
+    detached?: boolean;
 }) => ProcLike;
 export interface ChildResult {
     stdout: string;

package/dist/shared/child-process.js

@@ -1,4 +1,4 @@
-import { spawn as defaultSpawn } from 'node:child_process';
+import { spawn as defaultSpawn, spawnSync as spawnSyncDefault } from 'node:child_process';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export const KILL_GRACE_MS = 5000;
 /** Base flags shared by all child pi invocations. */
@@ -175,10 +175,17 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         // prompt is present we open stdin as a pipe; otherwise keep it 'ignore'
         // (git and other arg-only spawns are unaffected). See GitHub issue #1.
         const usesStdin = invocation.stdin !== undefined;
+        // Model children (json-events) run arbitrary bash — they can `bun run dev &`
+        // a server that outlives the child and holds a port, wrecking the final gate
+        // with a self-inflicted EADDRINUSE (mx5 run 9 item 3). Spawn them in their
+        // OWN process group so every such grandchild can be reaped as a unit on exit.
+        // Plumbing (git, mode:'text') never backgrounds anything and stays in-group.
+        const ownGroup = opts?.mode === 'json-events';
         const proc = spawn(invocation.command, invocation.args, {
             cwd,
             shell: false,
             stdio: [usesStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+            ...(ownGroup ? { detached: true } : {}),
             ...(invocation.env ? { env: invocation.env } : {})
         });
         if (usesStdin) {
@@ -186,14 +193,39 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             proc.stdin?.write(invocation.stdin);
             proc.stdin?.end();
         }
-        // One kill path, shared by user-abort and loop-kill: SIGTERM, then
-        // SIGKILL after a grace period if the child ignored the term.
+        // Reap the child's whole process group — the child itself AND anything it
+        // backgrounded. No-op unless the child owns a group (ownGroup) and we have a
+        // pid; ESRCH (group already gone) is swallowed. POSIX: negative-pid signals
+        // the group; Windows has no groups, so taskkill /T tears down the tree.
+        const reapGroup = (sig) => {
+            if (!ownGroup || !proc.pid)
+                return;
+            try {
+                if (process.platform === 'win32') {
+                    spawnSyncDefault('taskkill', ['/pid', String(proc.pid), '/T', '/F']);
+                }
+                else {
+                    process.kill(-proc.pid, sig);
+                }
+            }
+            catch {
+                // group already gone
+            }
+        };
+        // One kill path, shared by user-abort and loop-kill: SIGTERM, then SIGKILL
+        // after a grace period if the child ignored the term. For a group-owning
+        // (model) child, ALSO sweep the group so anything it backgrounded dies with
+        // it — proc.kill hits only the leader, reapGroup the grandchildren.
         const killProc = () => {
             aborted = true;
             proc.kill('SIGTERM');
+            if (ownGroup)
+                reapGroup('SIGTERM');
             setTimeout(() => {
                 if (!proc.killed)
                     proc.kill('SIGKILL');
+                if (ownGroup)
+                    reapGroup('SIGKILL');
             }, KILL_GRACE_MS);
         };
         const sink = opts?.mode === 'json-events' ? new JsonEventSink(opts, killProc) : null;
@@ -250,6 +282,14 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         proc.on('close', (code) => {
             if (stallTimer)
                 clearInterval(stallTimer);
+            // The child has exited, but anything it backgrounded (a dev server) may
+            // still hold its process group and a port — reap the group so the next
+            // gate's boot check does not collide with our own orphan. Best-effort:
+            // SIGTERM now, SIGKILL shortly after for anything that ignored it.
+            if (ownGroup) {
+                reapGroup('SIGTERM');
+                setTimeout(() => reapGroup('SIGKILL'), 1_000).unref();
+            }
             if (sink)
                 sink.flush();
             const text = sink ? sink.text : undefined;

package/dist/task/auto-commit.d.ts

@@ -1,11 +1,3 @@
-/**
- * Per-task git commit for /task-auto.
- *
- * After each decomposed task passes, runAutoLoop snapshots the working tree into
- * a single commit so the run produces one commit per task. This is best-effort:
- * outside a git repo, with nothing staged, or on any git error we report the
- * reason and let the loop continue (the task already succeeded).
- */
 import { type SpawnFn } from '../shared/child-process.js';
 export interface CommitResult {
     committed: boolean;
@@ -58,11 +50,15 @@ export declare function gitCommitAll(cwd: string, message: string, signal?: Abor
  * `git reset --hard HEAD~1` throws the enforce commit away and brings back the
  * verified task commit underneath it.
  *
- * `reset --hard` is safe here precisely because it runs right after the enforce
- * commit: the working tree is clean (everything was just committed), so there is
- * no unrelated uncommitted work for it to destroy. HEAD~1 is the verified task
- * commit. The enforcement child runs `read,edit` with no `write`, so the dropped
- * commit contains only its in-place source edits — nothing else to preserve.
+ * `reset --hard` targets the enforce pass's in-place SOURCE edits. But it must NOT
+ * rewind the forensic gate trail: `.pi-tasks/` is frequently TRACKED (the per-task
+ * snapshots stage it via `git add -A`), so a bare reset restores TASK_00NN.md to the
+ * snapshot commit and ERASES every trail line written after it — the "commit: task
+ * snapshot committed", "enforce(edit): …", and resolution lines (mx5 run 9:
+ * TASK_0007/0008/0012 each lost their whole post-snapshot trail on this exact path,
+ * so a passing-then-reverted task looked like it had never been committed). So the
+ * trail is snapshotted before the reset and restored after — the revert undoes code,
+ * the audit log survives.
  *
  * Best-effort and never throws: a git failure is swallowed (the caller has
  * already decided to keep the verified work; a failed reset only leaves the

package/dist/task/auto-commit.js

@@ -6,7 +6,12 @@
  * outside a git repo, with nothing staged, or on any git error we report the
  * reason and let the loop continue (the task already succeeded).
  */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
 import { runChildDefault } from '../shared/child-process.js';
+/** The gate machinery's own state/forensic dir — the trail, debug logs, and per-run
+ *  ledgers. Preserved verbatim across a revert (see gitDropLastCommit). */
+const TRAIL_DIR = '.pi-tasks';
 /**
  * Does this git stderr describe a missing author identity? Seen live (mx5 run 4):
  * the headless docker container has no HOME gitconfig, so EVERY per-task commit
@@ -136,16 +141,65 @@ export async function gitCommitAll(cwd, message, signal, spawnFn) {
  * `git reset --hard HEAD~1` throws the enforce commit away and brings back the
  * verified task commit underneath it.
  *
- * `reset --hard` is safe here precisely because it runs right after the enforce
- * commit: the working tree is clean (everything was just committed), so there is
- * no unrelated uncommitted work for it to destroy. HEAD~1 is the verified task
- * commit. The enforcement child runs `read,edit` with no `write`, so the dropped
- * commit contains only its in-place source edits — nothing else to preserve.
+ * `reset --hard` targets the enforce pass's in-place SOURCE edits. But it must NOT
+ * rewind the forensic gate trail: `.pi-tasks/` is frequently TRACKED (the per-task
+ * snapshots stage it via `git add -A`), so a bare reset restores TASK_00NN.md to the
+ * snapshot commit and ERASES every trail line written after it — the "commit: task
+ * snapshot committed", "enforce(edit): …", and resolution lines (mx5 run 9:
+ * TASK_0007/0008/0012 each lost their whole post-snapshot trail on this exact path,
+ * so a passing-then-reverted task looked like it had never been committed). So the
+ * trail is snapshotted before the reset and restored after — the revert undoes code,
+ * the audit log survives.
  *
  * Best-effort and never throws: a git failure is swallowed (the caller has
  * already decided to keep the verified work; a failed reset only leaves the
  * enforce commit in place, which is surfaced as a warning).
  */
 export async function gitDropLastCommit(cwd, signal, spawnFn) {
+    const trail = await snapshotTrail(cwd);
     await git(cwd, ['reset', '--hard', 'HEAD~1'], signal, spawnFn);
+    await restoreTrail(cwd, trail);
+}
+/** Read every file under `.pi-tasks/` into memory (relative path → bytes). Best-effort:
+ *  a missing dir or unreadable file is skipped, so this never blocks the revert. */
+async function snapshotTrail(cwd) {
+    const out = new Map();
+    const root = path.join(cwd, TRAIL_DIR);
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await fsp.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                await walk(full);
+            else if (e.isFile()) {
+                try {
+                    out.set(path.relative(cwd, full), await fsp.readFile(full));
+                }
+                catch {
+                    // unreadable — skip
+                }
+            }
+        }
+    };
+    await walk(root);
+    return out;
+}
+/** Re-materialise the snapshotted trail files, overwriting whatever the reset left. */
+async function restoreTrail(cwd, trail) {
+    for (const [rel, buf] of trail) {
+        const full = path.join(cwd, rel);
+        try {
+            await fsp.mkdir(path.dirname(full), { recursive: true });
+            await fsp.writeFile(full, buf);
+        }
+        catch {
+            // best-effort restore
+        }
+    }
 }

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

@@ -36,7 +36,22 @@ type BootOutcome = {
 } | {
     outcome: 'fail';
     detail: string;
+} | {
+    outcome: 'orphan-port';
+    detail: string;
+    port: number | null;
 };
+/** Injectable environment probes for the boot check's orphan-port recovery, so the
+ *  reap-and-retry path is deterministically testable without a real listener. */
+export interface BootDeps {
+    /** The pid + command line holding `port` in LISTEN, or null if none/unknown. */
+    findPortHolder?: (port: number) => {
+        pid: number;
+        command: string;
+    } | null;
+    /** Terminate a pid we attribute to ourselves; returns whether it was signalled. */
+    reap?: (pid: number) => boolean;
+}
 /**
  * Exercise the start command ONCE, with no port/URL/framework knowledge — the
  * command's own fate within the grace window decides:
@@ -63,5 +78,5 @@ export declare function discoverGateCommandLabels(cwd: string): string[];
  * 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 declare function runFinalIntegrationGate(cwd: string, timeoutMs?: number, bootGraceMs?: number, bootDeps?: BootDeps): Promise<FinalGateOutcome>;
 export {};

package/dist/task/final-gate.js

@@ -167,6 +167,69 @@ export function discoverBootCommand(cwd) {
     }
     return null;
 }
+/** Recognise an "address already in use" bind failure across runtimes (Node
+ *  EADDRINUSE, Bun "Is port N in use?", Go "address already in use", generic). */
+function isAddressInUse(text) {
+    return /EADDRINUSE|address already in use|address in use|port \d+ (?:is |already )?in use/i.test(text);
+}
+/** Best-effort port number from a bind-failure message, for the diagnosis line. The
+ *  digit run ends on any non-digit (a `(?!\d)` lookahead, NOT `\b`): runtimes often
+ *  print ":3000" flush against the next token with no separating space/newline
+ *  ("…:3000error: script exited"), where a trailing `\b` would never match. */
+function extractPort(text) {
+    const m = /(?:port|:)\s*(\d{2,5})(?!\d)/i.exec(text) ?? /\baddress[^0-9]*(\d{2,5})(?!\d)/i.exec(text);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    return n > 0 && n < 65536 ? n : null;
+}
+/** 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) {
+    try {
+        const t = spawnSync('lsof', ['-i', `:${port}`, '-sTCP:LISTEN', '-t', '-P', '-n'], {
+            encoding: 'utf8',
+            timeout: 4000
+        });
+        const pid = Number((t.stdout ?? '').split('\n')[0]?.trim());
+        if (!Number.isInteger(pid) || pid <= 0)
+            return null;
+        const ps = spawnSync('ps', ['-o', 'args=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 4000
+        });
+        return { pid, command: (ps.stdout ?? '').trim() || `pid ${pid}` };
+    }
+    catch {
+        return null;
+    }
+}
+function defaultReap(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+        setTimeout(() => {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }, 1_000).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Does the port holder look like one of OUR gate children (a `dev`/`start` run of
+ *  the discovered boot command)? Only then do we reap it — never a foreign process
+ *  the user happens to be running. */
+function holderIsOurs(command, boot) {
+    const script = boot[1][boot[1].length - 1] ?? ''; // 'start' | 'dev' | 'run'
+    const c = command.toLowerCase();
+    return ((c.includes('bun') || c.includes('node') || c.includes('npm') || c.includes('make'))
+        && (c.includes(` ${script}`) || c.endsWith(script)));
+}
 /**
  * Exercise the start command ONCE, with no port/URL/framework knowledge — the
  * command's own fate within the grace window decides:
@@ -232,6 +295,17 @@ export function runBootCheck(cwd, [bin, args], graceMs = 10_000) {
             }
             const what = status !== null ? `exited ${status}` : `was killed by ${signal}`;
             const tail = outputTail(out, err);
+            // A bind collision is an environment condition, not an app defect — hand
+            // it back distinctly so the gate can reap our own orphan and retry rather
+            // than reporting the app "crashed" (mx5 run 9 item 3).
+            if (isAddressInUse(`${out}\n${err}`)) {
+                settle({
+                    outcome: 'orphan-port',
+                    port: extractPort(`${out}\n${err}`),
+                    detail: `${what}${tail ? ` — ${tail}` : ''}`
+                });
+                return;
+            }
             settle({ outcome: 'fail', detail: `${what}${tail ? ` — ${tail}` : ''}` });
         });
     });
@@ -283,13 +357,33 @@ function runGateCommand(cwd, [bin, args], timeoutMs) {
     }
     return { outcome: 'pass' };
 }
+/**
+ * Boot check hit an address-in-use bind failure. If the port is held by one of OUR
+ * own orphaned gate children (a `dev`/`start` run), reap it and retry the boot once
+ * so the app gets a fair launch; otherwise leave the (foreign) holder alone and let
+ * the caller emit the harness diagnosis. Never reaps a process we cannot attribute
+ * to ourselves.
+ */
+async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps) {
+    if (first.port === null)
+        return first;
+    const holder = (deps.findPortHolder ?? defaultFindPortHolder)(first.port);
+    if (!holder || !holderIsOurs(holder.command, boot))
+        return first;
+    const reaped = (deps.reap ?? defaultReap)(holder.pid);
+    if (!reaped)
+        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);
+}
 /**
  * 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 async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000) {
+export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000, bootDeps = {}) {
     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
@@ -339,10 +433,25 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     }
     if (boot) {
         const label = `${boot[0]} ${boot[1].join(' ')}`;
-        const b = await runBootCheck(cwd, boot, bootGraceMs);
+        let b = await runBootCheck(cwd, boot, bootGraceMs);
+        if (b.outcome === 'orphan-port') {
+            b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDeps);
+        }
         if (b.outcome === 'fail') {
             return withDebts({ ok: false, reason: `boot check: \`${label}\` ${b.detail}` });
         }
+        if (b.outcome === 'orphan-port') {
+            // Could not clear the port. Distinct HARNESS diagnosis, never a bare app
+            // FAIL: name the port and (when known) the process squatting on it.
+            const holder = b.port !== null ? (bootDeps.findPortHolder ?? defaultFindPortHolder)(b.port) : null;
+            const who = holder ? ` — held by an orphaned process (pid ${holder.pid}: ${holder.command})`
+                : b.port !== null ? ` — port ${b.port} is held by another process`
+                    : '';
+            return withDebts({
+                ok: false,
+                reason: `boot check: \`${label}\` could not bind: orphaned process / port already in use${who} (harness condition, not an app fault)`
+            });
+        }
         if (b.outcome === 'pass')
             ran.push(label);
     }

package/dist/task/gate-deps.js

@@ -242,8 +242,17 @@ export function buildGateDeps(params) {
                     const rec = await reconcileGitState(cwd2, guardSnapshot, sig);
                     lastGuardReconcile = rec;
                     if (rec.mutated) {
-                        log(`=== ${kind} GIT-STATE GUARD — child mutated repo state; restored: ${rec.actions.join('; ')} ===`);
-                        gateCtx.ui.notify(`${taskTitle}: ${kind} child mutated repo state — restored (${rec.actions.join('; ').slice(0, 140)}).`, 'warning');
+                        // Distinguish the two outcomes in the trail: a tainting
+                        // mutation (graded work altered → verdict will be
+                        // discarded) vs benign cleanup (test-runner output the
+                        // child left behind → verdict stands).
+                        const label = rec.verdictTainted ?
+                            'child mutated graded state (verdict discarded)'
+                            : 'cleaned child test-runner artifacts (verdict kept)';
+                        log(`=== ${kind} GIT-STATE GUARD — ${label}; restored: ${rec.actions.join('; ')} ===`);
+                        if (rec.verdictTainted) {
+                            gateCtx.ui.notify(`${taskTitle}: ${kind} child mutated repo state — restored (${rec.actions.join('; ').slice(0, 140)}).`, 'warning');
+                        }
                     }
                 }
             }
@@ -419,9 +428,13 @@ export function buildGateDeps(params) {
                     return collectChangedFiles(cwd2, signal).then(files => findProhibitionViolations(banned, files));
                 },
                 // Git-state guard result of the most recent child run: a verdict
-                // computed on a tree the child itself mutated is discarded (the
-                // guard already restored the state — see git-state-guard.ts).
-                mutationCheck: () => lastGuardReconcile?.mutated ?
+                // computed on a tree the child itself mutated is discarded — but ONLY
+                // when the mutation touched graded state (verdictTainted). A child
+                // that merely left test-runner output behind (test-results/,
+                // playwright-report/ …) judged an equivalent tree; its verdict stands
+                // and the artifacts were still cleaned (mx5 run 9 lost 7 verdicts this
+                // way — see git-state-guard.ts).
+                mutationCheck: () => lastGuardReconcile?.verdictTainted ?
                     { mutated: true, detail: lastGuardReconcile.actions.join('; ') }
                     : { mutated: false, detail: '' },
                 // Per-run environment-facts cache under .pi-tasks/ (survives

package/dist/task/git-state-guard.d.ts

@@ -11,8 +11,22 @@ export interface GitStateSnapshot {
     treeSha: string | null;
 }
 export interface ReconcileResult {
-    /** true → the child moved repo state; every detected move was restored. */
+    /** true → the child moved repo state; every detected move was restored. This
+     *  covers benign moves too (test-runner output), so it drives logging/notify —
+     *  NOT the verdict decision. Use `verdictTainted` for that. */
     mutated: boolean;
+    /** true → the child changed *graded* state: a tracked-in-HEAD file was
+     *  modified/deleted, HEAD/branch was moved, a stash was pushed, or an untracked
+     *  non-artifact (source-shaped) file was modified/deleted. This is the real
+     *  mutate-to-pass class; a verdict computed on such a tree is discarded.
+     *
+     *  Deliberately false for child-CREATED files and for modified/deleted untracked
+     *  *test-runner artifacts* (test-results/, playwright-report/, coverage output,
+     *  *.tsbuildinfo, .last-run.json …): a gate child that merely ran the suite and
+     *  left its report behind judged a tree whose only difference from pre-run is
+     *  regenerable output — discarding a 49-min verify over that is the F-class this
+     *  splits off (mx5 run 9: 7 of 9 guard firings were pure test-results churn). */
+    verdictTainted: boolean;
     /** Human-readable restore actions, for the debug log / notify / gate trail. */
     actions: string[];
 }

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

@@ -44,6 +44,24 @@ import * as path from 'node:path';
 import { runChildDefault } from '../shared/child-process.js';
 /** Keep the gate machinery's own artifacts out of the snapshot and the restore. */
 const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
+/**
+ * Untracked paths that are regenerable test/build OUTPUT, not graded source. A gate
+ * child creating or rewriting one of these has not mutated the work under judgement,
+ * so its verdict stands. Gitignored files never reach the snapshot (git add -A skips
+ * them); this list is for the ones a typical project leaves UNIGNORED — Playwright's
+ * `test-results/` and `playwright-report/` above all, the exact churn that discarded
+ * verify verdicts across mx5 run 9. Kept deliberately narrow: anything not matched
+ * here that a child modifies/deletes is treated as graded state (verdict-tainting).
+ */
+const ARTIFACT_PATTERNS = [
+    /^(?:test-results|playwright-report|coverage|\.nyc_output|dist|build|\.next|\.turbo|\.svelte-kit)\//,
+    /(?:^|\/)\.last-run\.json$/,
+    /\.tsbuildinfo$/
+];
+function isBenignArtifact(relPath) {
+    const p = relPath.replace(/\\/g, '/');
+    return ARTIFACT_PATTERNS.some(re => re.test(p));
+}
 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);
@@ -99,44 +117,103 @@ export async function captureGitState(cwd, signal, spawnFn) {
         treeSha: await captureWorktreeTree(git)
     };
 }
+/** Paths tracked in the commit `headSha` points at — the "graded" codebase a gate
+ *  child must not rewrite. Empty on any git error (the caller then treats every
+ *  modified/deleted path as tracked, i.e. verdict-tainting — fail safe). */
+async function trackedPathsAt(git, headSha) {
+    const r = await git(['ls-tree', '-r', '--name-only', headSha]);
+    if (r.exitCode !== 0)
+        return new Set();
+    return new Set(r.stdout
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.length > 0));
+}
+/** Cap on itemised path lines per class, so a suite that rewrites hundreds of report
+ *  files cannot flood the gate trail. Beyond it, a single "…and N more" line. */
+const ITEMIZE_CAP = 20;
+function pushCapped(actions, verb, paths) {
+    const shown = paths.slice(0, ITEMIZE_CAP);
+    for (const p of shown)
+        actions.push(`${verb} ${p}`);
+    const extra = paths.length - shown.length;
+    if (extra > 0)
+        actions.push(`${verb} …and ${extra} more`);
+}
 /**
  * Restore every file recorded in `beforeTree` (content + deletions) and remove
  * files that exist in `afterTree` but not in `beforeTree` (files the child
  * created). Uses a throwaway index seeded from the snapshot tree; `checkout-index
  * -a -f` re-materialises the snapshot verbatim.
+ *
+ * Returns whether any restored change was *verdict-tainting* — a modified/deleted
+ * path that is tracked-in-HEAD or an untracked non-artifact (see isBenignArtifact).
+ * 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, actions) {
+async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, 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;
     try {
-        // Files present only in afterTree were created by the child — delete them
-        // BEFORE checkout so a restore failure cannot leave both halves stale.
-        const added = await git([
-            'diff-tree',
-            '-r',
-            '--diff-filter=A',
-            '--name-only',
-            beforeTree,
-            afterTree
-        ]);
-        if (added.exitCode === 0) {
-            for (const rel of added.stdout.split('\n')) {
-                const name = rel.trim();
+        // Classify every path the child changed BEFORE touching the tree, so the
+        // itemised trail and the taint decision are computed from one diff.
+        const created = [];
+        const artifactChanges = [];
+        const gradedModified = [];
+        const gradedDeleted = [];
+        const status = await git(['diff-tree', '-r', '--name-status', beforeTree, afterTree]);
+        if (status.exitCode === 0) {
+            for (const line of status.stdout.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed.length === 0)
+                    continue;
+                // "M\tpath", "A\tpath", "D\tpath", "T\tpath" — no -M, so renames show
+                // as a D + an A pair; both get classified on their own merits.
+                const tab = trimmed.indexOf('\t');
+                if (tab < 0)
+                    continue;
+                const code = trimmed[0];
+                const name = trimmed.slice(tab + 1).trim();
                 if (name.length === 0)
                     continue;
-                await fsp.rm(path.join(cwd, name), { force: true }).catch(() => { });
-                actions.push(`removed child-created file ${name}`);
+                if (code === 'A') {
+                    created.push(name);
+                }
+                else if (isBenignArtifact(name) && !tracked.has(name)) {
+                    // Untracked, regenerable test/build output — not graded work.
+                    artifactChanges.push(name);
+                }
+                else if (code === 'D') {
+                    gradedDeleted.push(name);
+                    tainted = true;
+                }
+                else {
+                    // M, T, and anything else touching a graded (tracked or
+                    // source-shaped untracked) path is the mutate-to-pass class.
+                    gradedModified.push(name);
+                    tainted = true;
+                }
             }
         }
+        // Files the child created — delete them BEFORE checkout so a restore failure
+        // cannot leave both halves stale.
+        for (const name of created) {
+            await fsp.rm(path.join(cwd, name), { force: true }).catch(() => { });
+        }
+        pushCapped(actions, 'removed child-created file', created);
+        pushCapped(actions, 'restored modified file', gradedModified);
+        pushCapped(actions, 'restored deleted file', gradedDeleted);
+        pushCapped(actions, 'restored test-runner artifact', artifactChanges);
         const read = await git(['read-tree', beforeTree], env);
         if (read.exitCode !== 0) {
             actions.push('worktree restore FAILED (read-tree)');
-            return;
+            return { tainted };
         }
         const co = await git(['checkout-index', '-a', '-f'], env);
-        actions.push(co.exitCode === 0 ?
-            'restored worktree files from pre-run snapshot'
-            : 'worktree restore FAILED (checkout-index)');
+        if (co.exitCode !== 0)
+            actions.push('worktree restore FAILED (checkout-index)');
+        return { tainted };
     }
     finally {
         await fsp.rm(tmpIndex, { force: true }).catch(() => { });
@@ -157,9 +234,12 @@ async function restoreWorktree(cwd, git, beforeTree, afterTree, actions) {
  */
 export async function reconcileGitState(cwd, before, signal, spawnFn) {
     if (!before.ok)
-        return { mutated: false, actions: [] };
+        return { mutated: false, verdictTainted: false, actions: [] };
     const git = makeGit(cwd, signal, spawnFn);
     const actions = [];
+    // A child that moved HEAD/branch or pushed a stash swallowed graded work — that
+    // is unambiguously verdict-tainting. Worktree classification adds to this.
+    let tainted = false;
     // 1. HEAD / branch.
     const head = await git(['rev-parse', '-q', '--verify', 'HEAD']);
     const branch = await git(['symbolic-ref', '-q', 'HEAD']);
@@ -171,12 +251,15 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
         actions.push(co.exitCode === 0 ?
             `checked HEAD back out to ${target}`
             : `HEAD restore FAILED (checkout ${target})`);
+        tainted = true;
     }
     // 2. Worktree content.
     if (before.treeSha) {
         const afterTree = await captureWorktreeTree(git);
         if (afterTree && afterTree !== before.treeSha) {
-            await restoreWorktree(cwd, git, before.treeSha, afterTree, actions);
+            const tracked = await trackedPathsAt(git, before.headSha);
+            const { tainted: worktreeTainted } = await restoreWorktree(cwd, git, before.treeSha, afterTree, tracked, actions);
+            tainted = tainted || worktreeTainted;
         }
     }
     // 3. Stash entries the child pushed. Drop stash@{0} until the ref matches the
@@ -189,6 +272,9 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
     };
     let stash = await stashNow();
     if (stash !== before.stashSha) {
+        // A child that pushed/popped a stash moved graded work in or out of the tree
+        // (mx5 run 6's stash-and-abandon) — always verdict-tainting.
+        tainted = true;
         if (before.stashSha === null || (await stashContains(git, stash, before.stashSha))) {
             let dropped = 0;
             while (stash !== before.stashSha && stash !== null && dropped < 10) {
@@ -206,7 +292,7 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
             actions.push('stash ref changed in a way that cannot be undone (entry popped/dropped)');
         }
     }
-    return { mutated: actions.length > 0, actions };
+    return { mutated: actions.length > 0, verdictTainted: tainted, actions };
 }
 /** Is `ancestorStash` still reachable in the stash reflog chain at `tipSha`? Used to
  *  tell "child pushed on top" (droppable) from "child popped/dropped ours" (not). */

package/dist/task/phases.js

@@ -11,6 +11,7 @@ import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } fr
 import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
 import { isIntegrationUnknown } from './unknown-routing.js';
+import { extractUserDirectives, preserveDirectivesBlock, enforceDirectives } from './user-directives.js';
 import { getFileInventory } from './file-inventory.js';
 import { buildOrientation, orientationTier } from './orientation.js';
 import { getConfig } from '../config/config.js';
@@ -130,7 +131,14 @@ export async function phaseContractsBlock(deps) {
 export const phaseRefine = async (deps, raw, planContext) => {
     const existingFiles = await refineExistingFilesBlock(deps).catch(() => '');
     const contracts = await phaseContractsBlock(deps);
-    return runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext, existingFiles, contracts))), 
+    // Imperative tool directives the user wrote into the RAW prompt ("via web
+    // search", "fetch <url>"). Refine paraphrases the task and a weak model drops
+    // these some of the time (mx5 run 9: "via web search" vanished, the whole run
+    // made 0 search calls). Hand them to refine as a MUST-PRESERVE block (belt) and
+    // re-check the output below (lever). Empty on an ordinary prompt → refine unchanged.
+    const directives = extractUserDirectives(raw);
+    const directivesBlock = preserveDirectivesBlock(directives);
+    const refined = await runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext, existingFiles, contracts, directivesBlock))), 
     // refine's deliverable is a 4-section text rewrite that never strictly
     // needs a successful read — on a test-writing task against a large
     // existing codebase the model over-explores (re-reads source hunting for
@@ -139,6 +147,14 @@ export const phaseRefine = async (deps, raw, planContext) => {
     // refine looped 3×/resume forever; the deliverable was always producible
     // from the title + design doc alone.
     { degradeOnExhaustion: true });
+    // Deterministic backstop: if the refined spec still dropped a directive, append
+    // it verbatim rather than trusting the paraphrase. No model in this path.
+    const { text, appended } = enforceDirectives(refined, directives);
+    if (appended.length > 0) {
+        deps.logDebug?.(`refine: re-attached ${appended.length} dropped user directive(s): `
+            + appended.map(d => d.kind).join(', '));
+    }
+    return text;
 };
 export async function phaseVerifyTooling(deps, research) {
     const commands = extractToolingCommands(research);

package/dist/task/prompts.d.ts

@@ -47,7 +47,7 @@ export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) =>
  * "Scaffold …" title re-expands the entire design into one task (validated: a real
  * /task-auto run implemented all 24 steps under step 1).
  */
-declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string, contracts?: string) => string;
+declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string, contracts?: string, directives?: string) => string;
 declare const RESEARCH_READ_ONLY_CONSTRAINT = "IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.";
 declare const RESEARCH_FILES_PROMPT: (refined: string) => string;
 declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap?: string) => string;

package/dist/task/prompts.js

@@ -61,7 +61,7 @@ ${title}`;
  * "Scaffold …" title re-expands the entire design into one task (validated: a real
  * /task-auto run implemented all 24 steps under step 1).
  */
-const REFINE_PROMPT = (raw, planContext, existingFiles, contracts) => `${planContext ? planContext + '\n\n---\n\n' : ''}You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
+const REFINE_PROMPT = (raw, planContext, existingFiles, contracts, directives) => `${planContext ? planContext + '\n\n---\n\n' : ''}You receive a user's task description for an AI coding agent. Rewrite it to be unambiguous and actionable.
 
 Output structure (four sections, exact headings, in this order):
 
@@ -88,7 +88,7 @@ Rules:
 - If the task references a design/spec document (an @-path or a named spec file), READ it and treat it as authoritative. Carry its concrete schema verbatim into GOAL/CONSTRAINTS — table and column names, types, endpoint methods and paths, enum values. The task title is only a pointer into that spec: where the title and the spec disagree, follow the spec, and never introduce a table, column, endpoint, or dependency the spec does not define.
 - CITE interface WIRING, do NOT synthesize it. A wiring specific — how modules/endpoints/files connect (a mount prefix, a route/mount table, a module→path mapping, an exported function/type signature, a file or module layout) — must be citable from the design or the CROSS-SLICE CONTRACTS. The design often pins the interface FACTS (the exact endpoint paths, exported names, layouts) WITHOUT stating the wiring that produces them; when it does, any wiring you write MUST reproduce those pinned facts EXACTLY. Do NOT infer a "uniform" or "tidy" pattern from them — e.g. do not assume one module maps to one mount prefix when the design's pinned facts for that module do not all sit under a single prefix (that exact inference is a seam bug: the consumers follow the pinned facts, the assembly follows your invented pattern, and the seam ships broken). If the design pins neither the fact nor the wiring, leave the detail unspecified rather than inventing a specific.
 - Do not output any preamble, commentary, or markdown headings beyond the four sections above.
-${contracts && contracts.trim() ? `\n${contracts.trim()}\n` : ''}${existingFiles && existingFiles.trim() ? `\n${existingFiles.trim()}\n` : ''}
+${directives && directives.trim() ? `\n${directives.trim()}\n` : ''}${contracts && contracts.trim() ? `\n${contracts.trim()}\n` : ''}${existingFiles && existingFiles.trim() ? `\n${existingFiles.trim()}\n` : ''}
 Task: ${raw}`;
 // ─── Research fan-out prompts ─────────────────────────────────────────────────
 const RESEARCH_READ_ONLY_CONSTRAINT = `IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.`;

package/dist/task/user-directives.d.ts

@@ -0,0 +1,52 @@
+/**
+ * user-directives — deterministic extraction of the imperative tool/method
+ * directives a user writes into a raw task prompt, so a downstream rewrite (refine)
+ * cannot silently drop them.
+ *
+ * The failure this closes (mx5 run 9, validated): the raw prompt was
+ *   "Research Playwright best practices VIA WEB SEARCH — focus on E2E testing…"
+ * Refine rewrote the task well in every other respect (it correctly killed a wrong
+ * "Next.js" framing) but the "via web search" instruction vanished from the refined
+ * spec entirely — and the whole 2-run session then made ZERO pi-worker-search and
+ * ZERO pi-worker-fetch calls. A user who explicitly asks for web search must get
+ * web search; the model's paraphrase is not allowed to quietly demote it to
+ * "research from local files".
+ *
+ * The mechanism is the lever, the prompt is the belt: refine is HANDED the
+ * directives as a MUST-PRESERVE block (prompt), and — because a weak model still
+ * drops them some fraction of the time — the refined text is deterministically
+ * re-checked afterwards and the directive is APPENDED verbatim if it went missing
+ * (mechanism). Extraction is conservative: only concrete tool/method directives
+ * (web search, fetch <url>) are recognised, and a negated mention ("do NOT use web
+ * search") is ignored, so a prompt that never asked for a tool gets nothing added.
+ */
+export type UserDirectiveKind = 'web-search' | 'fetch-url';
+export interface UserDirective {
+    kind: UserDirectiveKind;
+    /** The canonical MUST line threaded into refine and appended as a backstop. */
+    must: string;
+    /** Regexes that, if ANY matches the refined text, prove the directive survived. */
+    survives: RegExp[];
+}
+/**
+ * The imperative tool/method directives present in a raw user prompt. Deterministic
+ * and side-effect free. Deduped by kind (a prompt that says "web search" twice yields
+ * one directive). Empty when the prompt names no concrete tool directive.
+ */
+export declare function extractUserDirectives(raw: string): UserDirective[];
+/** Does the refined text still carry `directive`? True when ANY survives-regex hits. */
+export declare function directiveSurvives(refined: string, directive: UserDirective): boolean;
+/**
+ * The MUST-PRESERVE block threaded into the refine prompt (the belt). Empty string
+ * when there are no directives, so refine is unchanged on an ordinary prompt.
+ */
+export declare function preserveDirectivesBlock(directives: UserDirective[]): string;
+/**
+ * Backstop (the lever): if the refined spec dropped a directive, append it under a
+ * CONSTRAINTS-adjacent header so downstream phases still see it. Returns the possibly
+ * amended text and the list of directives that had to be force-appended (for logging).
+ */
+export declare function enforceDirectives(refined: string, directives: UserDirective[]): {
+    text: string;
+    appended: UserDirective[];
+};

package/dist/task/user-directives.js

@@ -0,0 +1,98 @@
+/**
+ * user-directives — deterministic extraction of the imperative tool/method
+ * directives a user writes into a raw task prompt, so a downstream rewrite (refine)
+ * cannot silently drop them.
+ *
+ * The failure this closes (mx5 run 9, validated): the raw prompt was
+ *   "Research Playwright best practices VIA WEB SEARCH — focus on E2E testing…"
+ * Refine rewrote the task well in every other respect (it correctly killed a wrong
+ * "Next.js" framing) but the "via web search" instruction vanished from the refined
+ * spec entirely — and the whole 2-run session then made ZERO pi-worker-search and
+ * ZERO pi-worker-fetch calls. A user who explicitly asks for web search must get
+ * web search; the model's paraphrase is not allowed to quietly demote it to
+ * "research from local files".
+ *
+ * The mechanism is the lever, the prompt is the belt: refine is HANDED the
+ * directives as a MUST-PRESERVE block (prompt), and — because a weak model still
+ * drops them some fraction of the time — the refined text is deterministically
+ * re-checked afterwards and the directive is APPENDED verbatim if it went missing
+ * (mechanism). Extraction is conservative: only concrete tool/method directives
+ * (web search, fetch <url>) are recognised, and a negated mention ("do NOT use web
+ * search") is ignored, so a prompt that never asked for a tool gets nothing added.
+ */
+/** ~24 chars of lead-in before a match, scanned for a negation that flips intent. */
+const NEGATION = /\b(?:no|not|never|without|don'?t|do not|avoid|skip)\b[^.?!]{0,24}$/i;
+function isNegated(text, matchIndex) {
+    return NEGATION.test(text.slice(Math.max(0, matchIndex - 40), matchIndex));
+}
+// "web search", "search the web/internet", "search online" — the concrete
+// external-research directive. Kept tight so ordinary prose ("search the codebase",
+// "search for the function") never trips it: the object must be web/internet/online.
+const WEB_SEARCH_RE = /\bweb[-\s]*search(?:es|ing)?\b|\bsearch(?:es|ing)?\s+(?:the\s+|on\s+the\s+|across\s+the\s+)?(?:web|internet|online)\b|\bsearch\s+online\b/i;
+// "fetch https://…" / "fetch the page at https://…" — an explicit fetch directive
+// naming a URL. The URL is captured so it can be preserved verbatim.
+const FETCH_URL_RE = /\bfetch(?:es|ing)?\b[^.\n]{0,40}?(https?:\/\/[^\s)>"']+)/i;
+const WEB_SEARCH_SURVIVES = [
+    /\bweb[-\s]*search/i,
+    /\bsearch(?:es|ing)?\s+(?:the\s+|on\s+the\s+|across\s+the\s+)?(?:web|internet|online)\b/i,
+    /\bsearch\s+online\b/i,
+    /pi-worker-search/i
+];
+/**
+ * The imperative tool/method directives present in a raw user prompt. Deterministic
+ * and side-effect free. Deduped by kind (a prompt that says "web search" twice yields
+ * one directive). Empty when the prompt names no concrete tool directive.
+ */
+export function extractUserDirectives(raw) {
+    const out = [];
+    const ws = WEB_SEARCH_RE.exec(raw);
+    if (ws && !isNegated(raw, ws.index)) {
+        out.push({
+            kind: 'web-search',
+            must: 'MUST use live web search (via pi-worker-search) — the user explicitly asked to search the web. Do NOT restrict this task to local files or pi-worker-docs only; external web research is a required part of the deliverable.',
+            survives: WEB_SEARCH_SURVIVES
+        });
+    }
+    const fu = FETCH_URL_RE.exec(raw);
+    if (fu && !isNegated(raw, fu.index)) {
+        const url = fu[1];
+        out.push({
+            kind: 'fetch-url',
+            must: `MUST fetch ${url} (via pi-worker-fetch) — the user explicitly asked to fetch this URL; keep it named in the spec.`,
+            survives: [/pi-worker-fetch/i, new RegExp(escapeRegExp(url), 'i'), /\bfetch\b/i]
+        });
+    }
+    return out;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Does the refined text still carry `directive`? True when ANY survives-regex hits. */
+export function directiveSurvives(refined, directive) {
+    return directive.survives.some(re => re.test(refined));
+}
+/**
+ * The MUST-PRESERVE block threaded into the refine prompt (the belt). Empty string
+ * when there are no directives, so refine is unchanged on an ordinary prompt.
+ */
+export function preserveDirectivesBlock(directives) {
+    if (directives.length === 0)
+        return '';
+    const lines = directives.map(d => `- ${d.must}`).join('\n');
+    return ('USER TOOL DIRECTIVES — MUST PRESERVE (the raw task explicitly names how to do the '
+        + 'work; carry each into GOAL/CONSTRAINTS verbatim in intent — never drop or soften '
+        + `it to a local-only paraphrase):\n${lines}`);
+}
+/**
+ * Backstop (the lever): if the refined spec dropped a directive, append it under a
+ * CONSTRAINTS-adjacent header so downstream phases still see it. Returns the possibly
+ * amended text and the list of directives that had to be force-appended (for logging).
+ */
+export function enforceDirectives(refined, directives) {
+    const appended = directives.filter(d => !directiveSurvives(refined, d));
+    if (appended.length === 0)
+        return { text: refined, appended };
+    const block = appended.map(d => `- ${d.must}`).join('\n');
+    const text = `${refined.trimEnd()}\n\nUSER TOOL DIRECTIVES (preserved from the raw prompt):\n${block}\n`;
+    return { text, appended };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.10",
+    "version": "0.18.12",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",