@mjasnikovs/pi-task 0.37.2 → 0.37.4

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

@@ -5,6 +5,11 @@ export interface CommitResult {
     reason?: string;
     /** Set when the commit needed a fallback (e.g. self-supplied identity). */
     note?: string;
+    /** UNTRACKED regenerable test-runner output this commit deliberately left out
+     *  of the index (see `stagePathspec`). Empty/absent when nothing was excluded.
+     *  Present so the caller can TRAIL it: a silent exclusion is the same failure
+     *  class as the silent ignored-path write nexttask 4 closed. */
+    excluded?: string[];
 }
 /**
  * Does this git stderr describe a missing author identity? Seen live (mx5 run 4):
@@ -21,6 +26,31 @@ export declare function git(cwd: string, args: string[], signal: AbortSignal | u
     exitCode: number;
     aborted: boolean;
 }>;
+/**
+ * The UNTRACKED files a per-task snapshot must not sweep into the index: Playwright
+ * `test-results/`, `playwright-report/`, `coverage/`, `.nyc_output/`,
+ * `.last-run.json`, `*.tsbuildinfo`.
+ *
+ * This is the other half of mx5 run 20. TASK_0027's snapshot ran a bare
+ * `git add -A` over a tree the test run had just littered with three Playwright
+ * FAILURE screenshots (`*-actual.png` — written only when a screenshot assertion
+ * fails), committed them, and thereby made them tracked deliverables. Two whole
+ * final-gate fix attempts were then rejected for deleting them. The deletion guard
+ * fix (write-guard.ts) stops the rejection; this stops the tracking.
+ *
+ * ONLY UNTRACKED PATHS ARE EXCLUDED, and that is load-bearing rather than tidy.
+ * `git ls-files --others` lists untracked, non-ignored files and nothing else, so a
+ * path git ALREADY tracks can never appear here — meaning a project that
+ * deliberately commits, say, a `coverage/` badge keeps having its edits to it
+ * committed. Excluding by directory pathspec instead (`:(exclude)coverage/`) would
+ * silently stop committing those.
+ *
+ * Best-effort: any git failure yields an empty list, i.e. today's `git add -A`.
+ */
+export declare function untrackedArtifacts(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string[]>;
+/** `:(exclude)` pathspecs for `git add -A`; empty when nothing is excluded, so the
+ *  common case is byte-identical to the previous bare `git add -A`. */
+export declare function stagePathspec(excluded: readonly string[]): string[];
 /**
  * Paths with unmerged index entries (an in-progress merge conflict), deduped.
  * Empty outside a git repo or on any git error — this is a GUARD input, and a

package/dist/task/auto-commit.js

@@ -9,6 +9,7 @@
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { runChildDefault } from '../shared/child-process.js';
+import { isDeletionExemptArtifact } from './regenerable-artifacts.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';
@@ -36,6 +37,44 @@ export async function git(cwd, args, signal, spawnFn) {
     const r = await runChildDefault({ command: 'git', args }, cwd, signal, { mode: 'text' }, spawnFn);
     return { stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode, aborted: r.aborted };
 }
+/**
+ * The UNTRACKED files a per-task snapshot must not sweep into the index: Playwright
+ * `test-results/`, `playwright-report/`, `coverage/`, `.nyc_output/`,
+ * `.last-run.json`, `*.tsbuildinfo`.
+ *
+ * This is the other half of mx5 run 20. TASK_0027's snapshot ran a bare
+ * `git add -A` over a tree the test run had just littered with three Playwright
+ * FAILURE screenshots (`*-actual.png` — written only when a screenshot assertion
+ * fails), committed them, and thereby made them tracked deliverables. Two whole
+ * final-gate fix attempts were then rejected for deleting them. The deletion guard
+ * fix (write-guard.ts) stops the rejection; this stops the tracking.
+ *
+ * ONLY UNTRACKED PATHS ARE EXCLUDED, and that is load-bearing rather than tidy.
+ * `git ls-files --others` lists untracked, non-ignored files and nothing else, so a
+ * path git ALREADY tracks can never appear here — meaning a project that
+ * deliberately commits, say, a `coverage/` badge keeps having its edits to it
+ * committed. Excluding by directory pathspec instead (`:(exclude)coverage/`) would
+ * silently stop committing those.
+ *
+ * Best-effort: any git failure yields an empty list, i.e. today's `git add -A`.
+ */
+export async function untrackedArtifacts(cwd, signal, spawnFn) {
+    const r = await git(cwd, ['ls-files', '--others', '--exclude-standard', '-z'], signal, spawnFn);
+    if (r.aborted || r.exitCode !== 0)
+        return [];
+    return r.stdout
+        .split('\0')
+        .map(p => p.trim())
+        .filter(p => p.length > 0 && isDeletionExemptArtifact(p))
+        .sort();
+}
+/** `:(exclude)` pathspecs for `git add -A`; empty when nothing is excluded, so the
+ *  common case is byte-identical to the previous bare `git add -A`. */
+export function stagePathspec(excluded) {
+    if (excluded.length === 0)
+        return [];
+    return ['--', '.', ...excluded.map(p => `:(exclude)${p}`)];
+}
 /**
  * Paths with unmerged index entries (an in-progress merge conflict), deduped.
  * Empty outside a git repo or on any git error — this is a GUARD input, and a
@@ -93,8 +132,10 @@ export async function gitCommitAll(cwd, message, signal, spawnFn) {
             reason: `git commit blocked: unresolved merge conflict (${unmerged.slice(0, 3).join(', ')}${unmerged.length > 3 ? `, +${unmerged.length - 3} more` : ''})`
         };
     }
-    // 3. Stage all working-tree changes (new, modified, deleted).
-    const add = await git(cwd, ['add', '-A'], signal, spawnFn);
+    // 3. Stage all working-tree changes (new, modified, deleted) EXCEPT untracked
+    //    regenerable test-runner output — see stagePathspec.
+    const excluded = await untrackedArtifacts(cwd, signal, spawnFn);
+    const add = await git(cwd, ['add', '-A', ...stagePathspec(excluded)], signal, spawnFn);
     if (add.aborted)
         return { committed: false, reason: 'cancelled' };
     if (add.exitCode !== 0) {
@@ -119,7 +160,11 @@ export async function gitCommitAll(cwd, message, signal, spawnFn) {
             if (retry.aborted)
                 return { committed: false, reason: 'cancelled' };
             if (retry.exitCode === 0) {
-                return { committed: true, note: 'no git identity configured — used pi-task fallback' };
+                return {
+                    committed: true,
+                    note: 'no git identity configured — used pi-task fallback',
+                    ...(excluded.length > 0 ? { excluded } : {})
+                };
             }
             return {
                 committed: false,
@@ -131,7 +176,7 @@ export async function gitCommitAll(cwd, message, signal, spawnFn) {
             reason: `git commit failed: ${firstLine(commit.stderr || commit.stdout)}`
         };
     }
-    return { committed: true };
+    return { committed: true, ...(excluded.length > 0 ? { excluded } : {}) };
 }
 /**
  * Drop the last commit, restoring the tree to its parent — the differential

package/dist/task/auto-orchestrator.js

@@ -1375,17 +1375,35 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                                 + `so the tree holds REJECTED edits: ${stranded.slice(0, 8).join(', ')}`);
                             return;
                         }
+                        // REPORT WHAT ACTUALLY HAPPENED (mx5 run 20). This bound the
+                        // CommitResult to `sha` and interpolated it, so the trail
+                        // read "committed 5 stranded fix-pass change(s) as
+                        // [object Object]". Worse than cosmetic: `commit` returns
+                        // {committed, reason?, note?} and NEVER a sha, the
+                        // `committed` field was never read, and gitCommitAll
+                        // returns {committed:false} WITHOUT throwing on an unmerged
+                        // index — so on that path the catch below never fires and
+                        // the trail claimed a commit over changes that were still
+                        // sitting in the working tree.
+                        const notCommitted = async (why) => {
+                            await recGate(`final-gate: could NOT commit ${stranded.length} stranded fix-pass `
+                                + `change(s) (${why}) — they remain UNCOMMITTED in the working `
+                                + `tree: ${stranded.slice(0, 8).join(', ')}`);
+                        };
                         try {
-                            const sha = await deps.commit(cwd, STRANDED_FIX_COMMIT(id, outcome));
-                            await recGate(`final-gate: committed ${stranded.length} stranded fix-pass change(s)`
-                                + `${sha ? ` as ${sha}` : ''} — ${stranded.slice(0, 8).join(', ')}`);
+                            const res = await deps.commit(cwd, STRANDED_FIX_COMMIT(id, outcome));
+                            if (res.committed) {
+                                await recGate(`final-gate: committed ${stranded.length} stranded fix-pass change(s)`
+                                    + `${res.note ? ` (${res.note})` : ''} — ${stranded.slice(0, 8).join(', ')}`);
+                            }
+                            else {
+                                await notCommitted(res.reason ?? 'unknown');
+                            }
                         }
                         catch (err) {
                             // Never break the terminal path over this — but say so, so
                             // the changes are not silently lost.
-                            await recGate(`final-gate: could NOT commit ${stranded.length} stranded fix-pass `
-                                + `change(s) (${err instanceof Error ? err.message : String(err)}) — `
-                                + `they remain UNCOMMITTED in the working tree: ${stranded.slice(0, 8).join(', ')}`);
+                            await notCommitted(err instanceof Error ? err.message : String(err));
                         }
                     };
                     while (!fin.ok) {

package/dist/task/final-gate.js

@@ -56,9 +56,10 @@ import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
 import { runRenderCheck } from './render-check.js';
 import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
 import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
+import { findLaunchConfigGap, probeEnv, configGapUnobservedNote } from './launch-config-gap.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { findDanglingArtifacts, danglingGateFailureText } from './artifact-closure.js';
-import { findMissingEnvDeclarations, envGateFailureText } from './env-template-closure.js';
+import { findMissingEnvDeclarations, envGateFailureText, scanEnvTemplateClosure, inertClosure, trackedFiles } from './env-template-closure.js';
 import { findMissingServeEntry, serveEntryGateFailureText } from './serve-entry.js';
 import { makefileRecipe } from './command-shrink.js';
 function packageScripts(cwd) {
@@ -1008,7 +1009,10 @@ export const INFRA_GAP_OUTPUT_RE = /ECONNREFUSED|connection refused|ENOTFOUND|EA
  * passes `extraGapRe` (launch scripts), missing external infrastructure. Only a
  * command that actually ran and exited non-zero for a real reason fails.
  */
-function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
+function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe, 
+/** Replaces the child's environment wholesale (config-gap probe re-run only —
+ *  see launch-config-gap.ts). Absent ⇒ `runnerEnv(runner)`, i.e. unchanged. */
+envOverride) {
     // Runner resolution (mx5 run 16): a login-shell-stripped PATH left `bun`
     // unspawnable, so every dynamic check skipped and the gate went blind. The
     // resolved binary is spawned, and its directory rides on the child's PATH so
@@ -1021,7 +1025,7 @@ function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe) {
         cwd,
         encoding: 'utf8',
         timeout: timeoutMs,
-        env: runnerEnv(runner)
+        env: envOverride ?? runnerEnv(runner)
     });
     if (r.error)
         return { outcome: 'skip', spawnFailed: true };
@@ -1457,6 +1461,10 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     // real defect the gate could not reach here (run 11's "pre-existing .rows
     // bug" note excused the exact scripts that shipped broken).
     const warnings = [];
+    /** UNOBSERVED notes for launch scripts reclassified as CONFIG GAPS (run 20).
+     *  They ride in `unobserved`, not `warnings`, so the caller's existing
+     *  recordFinalGateUnobservedDebt writes the debt — never a PASS. */
+    const configGapNotes = [];
     if (declared.length > 0) {
         const covered = cmds.flatMap(([bin, args]) => (bin === 'bun' || bin === 'npm') && args[0] === 'run' && args[1] ? [args[1]] : []);
         const skippedLaunch = [];
@@ -1464,6 +1472,21 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
         // failure above; executing it too would double-report (pre-aggregation the
         // contract diff early-returned, so this loop could assume presence).
         const present = new Set(Object.keys(packageScripts(cwd)).map(s => s.toLowerCase()));
+        const scripts = packageScripts(cwd);
+        // CONFIG-GAP INPUTS (mx5 run 20), read once: the tracked file list and the
+        // union of every tracked env template's declared variables. Both empty on a
+        // non-git tree or a tree with no template, which makes the whole check inert
+        // — a project with no template gains no excuse. See launch-config-gap.ts.
+        const closure = (() => {
+            try {
+                return scanEnvTemplateClosure(cwd);
+            }
+            catch {
+                return inertClosure();
+            }
+        })();
+        const trackedForGap = closure.templates.length > 0 ? (trackedFiles(cwd) ?? []) : [];
+        const launchTimeout = Math.min(timeoutMs, 180_000);
         for (const name of runnableDeclaredScripts(declared, covered)) {
             if (!present.has(name.toLowerCase()))
                 continue;
@@ -1471,7 +1494,7 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
             const label = `${cmd[0]} ${cmd[1].join(' ')}`;
             dynAttempted += 1;
             dynBins.add(cmd[0]);
-            const r = runGateCommand(cwd, cmd, Math.min(timeoutMs, 180_000), INFRA_GAP_OUTPUT_RE);
+            const r = runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE);
             if (r.outcome === 'skip') {
                 if (r.spawnFailed)
                     dynSpawnFailures += 1;
@@ -1480,6 +1503,37 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
             }
             dynObserved += 1;
             if (r.outcome === 'fail') {
+                // A CONFIG GAP IS NOT A CODE FAULT (mx5 run 20). The run died on
+                // `bun run seed` exiting 1 because ADMIN_PHONE — which the project's
+                // own `.env.example` DECLARES — is absent from this box, and the only
+                // way to supply it is a gitignored `.env` the commit cannot contain.
+                // Four static conditions (findLaunchConfigGap) plus one dynamic one:
+                // re-run with the variables supplied as synthetic placeholders, and
+                // reclassify ONLY if that exits 0. A script that fails for its own
+                // reasons fails again with the values present and stays a FAIL — an
+                // absent variable is not a licence to ignore an exit code the code
+                // caused. Nothing is parsed from the child's stderr: the wording is
+                // the project's, not the harness's.
+                const gap = findLaunchConfigGap({
+                    cwd,
+                    script: name,
+                    body: scripts[name] ?? null,
+                    tracked: trackedForGap,
+                    declared: closure.declared,
+                    env: process.env
+                });
+                if (gap) {
+                    const probe = runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, probeEnv(runnerEnv(resolveRunner(cmd[0])), gap));
+                    if (probe.outcome === 'pass') {
+                        // Nothing about this script was OBSERVED: the real run could
+                        // not reach it and the probe run is a diagnostic, never an
+                        // observation. So it un-counts, exactly like a skip.
+                        dynObserved -= 1;
+                        skippedLaunch.push(name);
+                        configGapNotes.push(configGapUnobservedNote(gap));
+                        continue;
+                    }
+                }
                 fail(`launch script: \`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`);
                 continue;
             }
@@ -1649,7 +1703,8 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     // because it names a concrete command and the trail line is sliced at 300 chars.
     const unobserved = [
         bootUnobserved,
-        unobservedVerdict({ discovered: dynAttempted, observed: dynObserved })
+        unobservedVerdict({ discovered: dynAttempted, observed: dynObserved }),
+        ...configGapNotes
     ]
         .filter(n => n !== null)
         .join(' ');

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

@@ -43,6 +43,7 @@ import * as fsp from 'node:fs/promises';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { runChildDefault } from '../shared/child-process.js';
+import { isRegenerableArtifact } from './regenerable-artifacts.js';
 /** Keep the gate machinery's own artifacts out of the snapshot and the restore. */
 const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
 /**
@@ -53,16 +54,12 @@ const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
  * `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).
+ *
+ * The list itself now lives in `regenerable-artifacts.ts` — the deletion guard and
+ * the per-task commit need the same knowledge, and three private copies of it is
+ * how mx5 run 20 spent two thirds of its repair budget on three screenshots.
  */
-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));
-}
+const isBenignArtifact = isRegenerableArtifact;
 /**
  * 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

package/dist/task/launch-config-gap.d.ts

@@ -0,0 +1,53 @@
+import { type EnvRead } from './env-template-closure.js';
+/** What a launch script needs that this box does not have. */
+export interface LaunchConfigGap {
+    /** Declared script name, e.g. `seed`. */
+    script: string;
+    /** The tracked source file the script body runs. */
+    file: string;
+    /** Variables it REQUIRES that the template declares and the env lacks. */
+    variables: string[];
+    /** First read site per variable, for the debt line. */
+    reads: EnvRead[];
+}
+/**
+ * The value the probe run supplies. Obviously synthetic and obviously ours, so a
+ * seeded row or a log line carrying it is recognisable as harness residue rather
+ * than mistaken for real configuration.
+ */
+export declare const CONFIG_GAP_PROBE_VALUE = "pi-task-config-gap-probe";
+/**
+ * The tracked source files a script body runs. Purely lexical and deliberately
+ * so: every whitespace/operator-separated token, normalised, that the tracked set
+ * contains. A token that is not a tracked file (a flag, the runner, a bare word)
+ * cannot match, and a body that names no tracked file yields nothing — which
+ * fails condition 1 and ends the check.
+ */
+export declare function bodySourceFiles(body: string, tracked: ReadonlySet<string>): string[];
+/**
+ * The static half: conditions 1–4. Returns null when ANY of them fails, which is
+ * the common case and means "behave exactly as before".
+ *
+ * `declared` is the union of every tracked template's variables. When it is empty
+ * the tree has no template, condition 3 can never hold, and this always returns
+ * null — a project with no template gains no excuse.
+ */
+export declare function findLaunchConfigGap(args: {
+    cwd: string;
+    script: string;
+    /** Resolved script body (`packageScripts(cwd)[name]`), or null. */
+    body: string | null;
+    /** Tracked files, repo-relative (`trackedFiles(cwd)`). */
+    tracked: readonly string[];
+    /** Variables the tracked env template(s) declare. */
+    declared: ReadonlySet<string>;
+    /** The env the gate spawned (or would spawn) the child with. */
+    env: Record<string, string | undefined>;
+}): LaunchConfigGap | null;
+/** The env for the probe re-run: the gate's own env plus a synthetic value per
+ *  gap variable. Nothing else changes, so a second non-zero exit is the script's
+ *  own fault and not the harness's. */
+export declare function probeEnv(base: Record<string, string | undefined>, gap: LaunchConfigGap): Record<string, string | undefined>;
+/** The UNOBSERVED warning: names the script and every variable, so a human can
+ *  supply them and re-run by hand. */
+export declare function configGapUnobservedNote(gap: LaunchConfigGap): string;

package/dist/task/launch-config-gap.js

@@ -0,0 +1,159 @@
+/**
+ * launch-config-gap — a launch script that cannot run because a variable the
+ * project's own tracked template DECLARES is absent from this box is an
+ * ENVIRONMENT GAP, not a code fault (mx5 run 20).
+ *
+ * THE EPISODE. Attempt 3 of the final-gate autofix passed every guard, fixed the
+ * failing test, and still lost the run:
+ *
+ *     autofix attempt 3 failed — did not converge: launch script: `bun run seed`
+ *     exited 1 — $ bun run src/server/seed.ts  Missing required environment
+ *     variable: ADMIN_PHONE  error: script "seed" exited with code 1
+ *
+ * Single-failure phrasing (final-gate.ts uses a numbered list for ≥2), so the
+ * suite was green and this was the only remaining failure. The run failed on
+ * exactly this, and it is self-inflicted at the last moment: pre-gate
+ * `package.json` had no `seed` script at all, so `if (!present.has(name)) continue`
+ * skipped it. Attempt 3 added the script to clear the launch-contract diff — and
+ * thereby armed the check that killed the run.
+ *
+ * The loop was closed by construction. The gate runs every declared non-boot
+ * script with `runnerEnv(runner)` = `process.env` plus a PATH prefix and nothing
+ * else; "Missing required environment variable" matches neither ENV_GAP_OUTPUT_RE
+ * nor INFRA_GAP_OUTPUT_RE, so it is a hard FAIL; and the only way to supply the
+ * value is a gitignored `.env`, whose writes nexttask 4 correctly refuses to
+ * credit. The static half of this already shipped and WORKED — `.env.example`
+ * declares ADMIN_PHONE/ADMIN_PASSWORD, so `findMissingEnvDeclarations` was
+ * correctly silent. This is the execution half.
+ *
+ * FOUR STATIC CONDITIONS, ALL REQUIRED. Deliberately over-constrained: the
+ * failure mode of getting this wrong is a gate that excuses real breakage.
+ *
+ *   1. the script's resolved body names a TRACKED SOURCE FILE
+ *      (`bun run src/server/seed.ts` → `src/server/seed.ts`);
+ *   2. that file REQUIRES an env var `X` under `scanSource` — i.e. none of its
+ *      step-asides (default / compared / assigned / ambient / …) applies;
+ *   3. `X` is DECLARED in the tracked template. If it is NOT,
+ *      `findMissingEnvDeclarations` has already failed the gate statically and
+ *      this path must not fire — otherwise the two checks would cancel out and a
+ *      project with no template at all would gain a blanket excuse;
+ *   4. `X` is ABSENT from the env the gate spawned the child with.
+ *
+ * NOTHING IS PARSED FROM THE CHILD'S STDERR. `Missing required environment
+ * variable: ADMIN_PHONE` is a string the PROJECT authored; matching on it would
+ * be a rule about one project's phrasing, and every other project would phrase it
+ * differently or not at all.
+ *
+ * THE FIFTH CONDITION IS DYNAMIC, AND IT IS WHAT MAKES THE RULE HONEST. The four
+ * above cannot tell "exited BECAUSE the variable is absent" from "exited for its
+ * own reasons, and also happens to read an absent variable". A script that throws
+ * a TypeError on line 1 and also reads ADMIN_PHONE on line 3 satisfies all four.
+ * So the script is re-run once with the gap variables supplied as OBVIOUSLY
+ * SYNTHETIC placeholders, and the exit code decides:
+ *
+ *     still non-zero → the absence did not cause it → FAIL, as today
+ *     now zero       → the absence did cause it     → skip + UNOBSERVED + debt
+ *
+ * The probe run is a DIAGNOSTIC, never an observation. Its success is not
+ * reported, and the verdict it produces is UNOBSERVED with debt — never a PASS
+ * (memory/unobserved-gate-verdict-shipped.md). The placeholder is a fixed
+ * harness-authored string; `.env.example`'s own values are never injected,
+ * because they are placeholders too (`change-me`) and a green seed run against
+ * them would be a fabricated observation.
+ */
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { scanSource } from './env-template-closure.js';
+/**
+ * The value the probe run supplies. Obviously synthetic and obviously ours, so a
+ * seeded row or a log line carrying it is recognisable as harness residue rather
+ * than mistaken for real configuration.
+ */
+export const CONFIG_GAP_PROBE_VALUE = 'pi-task-config-gap-probe';
+/** Shell operators that separate commands inside a script body. */
+const SEPARATORS = /[\s;|&()<>]+/;
+/**
+ * The tracked source files a script body runs. Purely lexical and deliberately
+ * so: every whitespace/operator-separated token, normalised, that the tracked set
+ * contains. A token that is not a tracked file (a flag, the runner, a bare word)
+ * cannot match, and a body that names no tracked file yields nothing — which
+ * fails condition 1 and ends the check.
+ */
+export function bodySourceFiles(body, tracked) {
+    const out = [];
+    for (const raw of body.split(SEPARATORS)) {
+        const tok = raw
+            .trim()
+            .replace(/^["']|["']$/g, '')
+            .replace(/^\.\//, '');
+        if (tok.length === 0)
+            continue;
+        if (tracked.has(tok) && !out.includes(tok))
+            out.push(tok);
+    }
+    return out;
+}
+/**
+ * The static half: conditions 1–4. Returns null when ANY of them fails, which is
+ * the common case and means "behave exactly as before".
+ *
+ * `declared` is the union of every tracked template's variables. When it is empty
+ * the tree has no template, condition 3 can never hold, and this always returns
+ * null — a project with no template gains no excuse.
+ */
+export function findLaunchConfigGap(args) {
+    if (!args.body || args.declared.size === 0)
+        return null;
+    const trackedSet = new Set(args.tracked);
+    const files = bodySourceFiles(args.body, trackedSet);
+    if (files.length === 0)
+        return null; // condition 1
+    const variables = [];
+    const reads = [];
+    let file = null;
+    for (const f of files) {
+        let text;
+        try {
+            text = readFileSync(path.join(args.cwd, f), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const r of scanSource(f, text)) {
+            if (r.stepAside !== null)
+                continue; // condition 2: REQUIRED only
+            if (!args.declared.has(r.name))
+                continue; // condition 3: template declares it
+            if (args.env[r.name] !== undefined)
+                continue; // condition 4: absent here
+            if (variables.includes(r.name))
+                continue;
+            variables.push(r.name);
+            reads.push(r);
+            file ??= f;
+        }
+    }
+    if (variables.length === 0 || file === null)
+        return null;
+    return { script: args.script, file, variables, reads };
+}
+/** The env for the probe re-run: the gate's own env plus a synthetic value per
+ *  gap variable. Nothing else changes, so a second non-zero exit is the script's
+ *  own fault and not the harness's. */
+export function probeEnv(base, gap) {
+    const out = { ...base };
+    for (const v of gap.variables)
+        out[v] = CONFIG_GAP_PROBE_VALUE;
+    return out;
+}
+/** The UNOBSERVED warning: names the script and every variable, so a human can
+ *  supply them and re-run by hand. */
+export function configGapUnobservedNote(gap) {
+    const site = gap.reads[0];
+    return (`launch script \`${gap.script}\` could not run here — ${gap.file}`
+        + `${site ? `:${site.line}` : ''} requires ${gap.variables.map(v => `\`${v}\``).join(', ')}, `
+        + `which the tracked env template DECLARES but this environment does not supply. `
+        + `Re-running it with the value(s) present exits 0, so the failure is a CONFIG GAP, not a `
+        + `code fault — UNOBSERVED: the launch surface was not exercised here. Supply `
+        + `${gap.variables.join(', ')} and run \`bun run ${gap.script}\` to observe it.`);
+}

package/dist/task/regenerable-artifacts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The one place that knows which repo paths are regenerable machine OUTPUT.
+ *
+ * This module exists because the knowledge was in exactly one module and two
+ * others needed it (mx5 run 20). `git-state-guard.ts` knew `test-results/` was
+ * regenerable and used it for VERDICT decisions only; `write-guard.ts`'s deletion
+ * guard did not, so it rejected two whole fix attempts over three Playwright
+ * failure screenshots — taking each attempt's real `src/client/api.test.tsx`
+ * repair with them — and `auto-commit.ts` did not, so its blind `git add -A` is
+ * how the screenshots became tracked in the first place. Three modules, one fact,
+ * shared with neither of the two that needed it. Import from here; do not copy.
+ *
+ * TWO LISTS, and the split between them is the whole point.
+ *
+ * `REGENERABLE_ARTIFACT_PATTERNS` is the VERDICT list: a gate child that rewrote
+ * one of these did not mutate the work under judgement, so its verdict stands.
+ * Being wrong here costs a discarded verify.
+ *
+ * `DELETION_EXEMPT_ARTIFACT_PATTERNS` is the strict SUBSET a fix pass may DELETE
+ * without its whole attempt being rejected. Being wrong here destroys a
+ * deliverable, so it is narrower, and `dist/`, `build/`, `.next/`, `.turbo/` and
+ * `.svelte-kit/` are deliberately NOT in it.
+ *
+ * MEASURED over 269 git work trees under ~/hub, ~/tmp, ~/.cache
+ * (`scripts/tracked-artifact-baserate.ts`, 2026-08-07):
+ *
+ *     trees tracking any artifact path      33   (33 of 33 have .pi-tasks)
+ *     test-results/                         33 trees / 33 files
+ *     .last-run.json                        33 trees / 33 files  ← the SAME 33 files
+ *     dist/, build/, .next/, .turbo/, .svelte-kit/, playwright-report/,
+ *     coverage/, .nyc_output/, *.tsbuildinfo      0 trees
+ *
+ * So `test-results/` and `.last-run.json` are exempt on MEASUREMENT — they are the
+ * only artifact paths this corpus tracks at all, and the one real episode is
+ * exactly a tracked `test-results/` deletion. `playwright-report/`, `coverage/`,
+ * `.nyc_output/` and `*.tsbuildinfo` are exempt BY CONSTRUCTION with zero corpus
+ * evidence either way: none of the four has a hand-authored form, so there is no
+ * version of them that is a deliverable. `dist/` and its family have exactly the
+ * hand-authored form the other six lack — a published package's `dist/` IS the
+ * shipped artifact — and with 0 tracked instances here the exemption would never
+ * fire anyway, so it would buy nothing while carrying that risk.
+ *
+ * 32 of the 33 trees are one A/B harness's delivery trees built from a single mx5
+ * DESIGN/PROJECT.md: 32 independent RUNS of one project shape, which is evidence
+ * of reproducibility and not of breadth. The 33rd is mx5 itself.
+ */
+/** Directory prefixes and file names that are regenerable test/build output. */
+export declare const REGENERABLE_ARTIFACT_PATTERNS: readonly RegExp[];
+/**
+ * The strict subset a fix pass may delete, and the pipeline must not newly track.
+ *
+ * Every entry here is output a test runner rewrites on its next run. Absent from
+ * this list, and staying absent: `dist/`, `build/`, `.next/`, `.turbo/`,
+ * `.svelte-kit/` — see the header.
+ */
+export declare const DELETION_EXEMPT_ARTIFACT_PATTERNS: readonly RegExp[];
+/** Human-readable form of the exempt list, for trail lines and pathspecs. */
+export declare const DELETION_EXEMPT_ARTIFACT_GLOBS: readonly string[];
+/** Is this path regenerable machine output, for VERDICT purposes? */
+export declare function isRegenerableArtifact(relPath: string): boolean;
+/**
+ * May a fix pass DELETE this path without its whole attempt being rejected, and
+ * may the pipeline leave it untracked? Narrower than `isRegenerableArtifact` on
+ * purpose: build output is excluded because a committed one can be the product.
+ */
+export declare function isDeletionExemptArtifact(relPath: string): boolean;

package/dist/task/regenerable-artifacts.js

@@ -0,0 +1,88 @@
+/**
+ * The one place that knows which repo paths are regenerable machine OUTPUT.
+ *
+ * This module exists because the knowledge was in exactly one module and two
+ * others needed it (mx5 run 20). `git-state-guard.ts` knew `test-results/` was
+ * regenerable and used it for VERDICT decisions only; `write-guard.ts`'s deletion
+ * guard did not, so it rejected two whole fix attempts over three Playwright
+ * failure screenshots — taking each attempt's real `src/client/api.test.tsx`
+ * repair with them — and `auto-commit.ts` did not, so its blind `git add -A` is
+ * how the screenshots became tracked in the first place. Three modules, one fact,
+ * shared with neither of the two that needed it. Import from here; do not copy.
+ *
+ * TWO LISTS, and the split between them is the whole point.
+ *
+ * `REGENERABLE_ARTIFACT_PATTERNS` is the VERDICT list: a gate child that rewrote
+ * one of these did not mutate the work under judgement, so its verdict stands.
+ * Being wrong here costs a discarded verify.
+ *
+ * `DELETION_EXEMPT_ARTIFACT_PATTERNS` is the strict SUBSET a fix pass may DELETE
+ * without its whole attempt being rejected. Being wrong here destroys a
+ * deliverable, so it is narrower, and `dist/`, `build/`, `.next/`, `.turbo/` and
+ * `.svelte-kit/` are deliberately NOT in it.
+ *
+ * MEASURED over 269 git work trees under ~/hub, ~/tmp, ~/.cache
+ * (`scripts/tracked-artifact-baserate.ts`, 2026-08-07):
+ *
+ *     trees tracking any artifact path      33   (33 of 33 have .pi-tasks)
+ *     test-results/                         33 trees / 33 files
+ *     .last-run.json                        33 trees / 33 files  ← the SAME 33 files
+ *     dist/, build/, .next/, .turbo/, .svelte-kit/, playwright-report/,
+ *     coverage/, .nyc_output/, *.tsbuildinfo      0 trees
+ *
+ * So `test-results/` and `.last-run.json` are exempt on MEASUREMENT — they are the
+ * only artifact paths this corpus tracks at all, and the one real episode is
+ * exactly a tracked `test-results/` deletion. `playwright-report/`, `coverage/`,
+ * `.nyc_output/` and `*.tsbuildinfo` are exempt BY CONSTRUCTION with zero corpus
+ * evidence either way: none of the four has a hand-authored form, so there is no
+ * version of them that is a deliverable. `dist/` and its family have exactly the
+ * hand-authored form the other six lack — a published package's `dist/` IS the
+ * shipped artifact — and with 0 tracked instances here the exemption would never
+ * fire anyway, so it would buy nothing while carrying that risk.
+ *
+ * 32 of the 33 trees are one A/B harness's delivery trees built from a single mx5
+ * DESIGN/PROJECT.md: 32 independent RUNS of one project shape, which is evidence
+ * of reproducibility and not of breadth. The 33rd is mx5 itself.
+ */
+/** Directory prefixes and file names that are regenerable test/build output. */
+export const REGENERABLE_ARTIFACT_PATTERNS = [
+    /^(?:test-results|playwright-report|coverage|\.nyc_output|dist|build|\.next|\.turbo|\.svelte-kit)\//,
+    /(?:^|\/)\.last-run\.json$/,
+    /\.tsbuildinfo$/
+];
+/**
+ * The strict subset a fix pass may delete, and the pipeline must not newly track.
+ *
+ * Every entry here is output a test runner rewrites on its next run. Absent from
+ * this list, and staying absent: `dist/`, `build/`, `.next/`, `.turbo/`,
+ * `.svelte-kit/` — see the header.
+ */
+export const DELETION_EXEMPT_ARTIFACT_PATTERNS = [
+    /^(?:test-results|playwright-report|coverage|\.nyc_output)\//,
+    /(?:^|\/)\.last-run\.json$/,
+    /\.tsbuildinfo$/
+];
+/** Human-readable form of the exempt list, for trail lines and pathspecs. */
+export const DELETION_EXEMPT_ARTIFACT_GLOBS = [
+    'test-results/',
+    'playwright-report/',
+    'coverage/',
+    '.nyc_output/',
+    '.last-run.json',
+    '*.tsbuildinfo'
+];
+const normalize = (relPath) => relPath.replace(/\\/g, '/');
+/** Is this path regenerable machine output, for VERDICT purposes? */
+export function isRegenerableArtifact(relPath) {
+    const p = normalize(relPath);
+    return REGENERABLE_ARTIFACT_PATTERNS.some(re => re.test(p));
+}
+/**
+ * May a fix pass DELETE this path without its whole attempt being rejected, and
+ * may the pipeline leave it untracked? Narrower than `isRegenerableArtifact` on
+ * purpose: build output is excluded because a committed one can be the product.
+ */
+export function isDeletionExemptArtifact(relPath) {
+    const p = normalize(relPath);
+    return DELETION_EXEMPT_ARTIFACT_PATTERNS.some(re => re.test(p));
+}

package/dist/task/task-gates.js

@@ -391,6 +391,17 @@ export async function runGatesForTask(ctxIn, deps, p) {
     const commit = await deps.commit(p.cwd, `task: ${p.title} (${p.taskId})`);
     if (commit.committed) {
         await rec(`commit: task snapshot committed${commit.note ? ` (${commit.note})` : ''}`);
+        // SAY WHAT WAS LEFT OUT. The stage skips untracked regenerable test-runner
+        // output (mx5 run 20: TASK_0027's `git add -A` swept in three Playwright
+        // failure screenshots and two later fix attempts were rejected for deleting
+        // them). A SILENT exclusion is the same failure class as the silent
+        // ignored-path write nexttask 4 closed, so it gets its own trail line.
+        if (commit.excluded && commit.excluded.length > 0) {
+            await rec(`commit: left ${commit.excluded.length} untracked test-runner artifact(s) out of the `
+                + `snapshot — regenerable output, not deliverables: `
+                + `${commit.excluded.slice(0, 8).join(', ')}`
+                + `${commit.excluded.length > 8 ? `, +${commit.excluded.length - 8} more` : ''}`);
+        }
         active.ui.notify(`${p.tag}: committed "${p.title}".`, 'info');
     }
     else {

package/dist/task/write-guard.d.ts

@@ -1,24 +1,3 @@
-/**
- * write-guard — deterministic tree-change accounting for WRITE-CAPABLE gate
- * children (mx5 run 11).
- *
- * The failure class: the final-gate autofix child (read,edit,bash) was added after
- * the run-8 guard generation and inherited NONE of the guards the other
- * write-capable passes carry — no diff capture, no frozen-path deny, no probe
- * scans, free `rm`. Run 11 it deleted `src/client/pages/admin.tsx` (TASK_0008's
- * verified deliverable) to satisfy a recorded debt claim, and the deletion was
- * invisible: nothing even logged what the pass changed.
- *
- * This module is the pure half of the guard stack: parse `git status --porcelain`
- * into a change summary (the diff-capture log line every write-capable child now
- * gets at the gate-deps seam), and classify tracked-file DELETIONS. A fix pass
- * exists to repair the assembled repository, not to shrink it: every tracked file
- * is a committed task's deliverable, so deleting one is rejected outright — with
- * one allowance, a RELOCATION (the same file name reappears as an added file
- * elsewhere, e.g. moving a test the runner was never meant to pick up out of its
- * glob — the legitimate fix shape from run 7). Pure text/path analysis; no git
- * execution, no stack assumptions.
- */
 /** What a write-capable pass changed, from `git status --porcelain`. */
 export interface TreeChangeSummary {
     /** Tracked files modified in place (includes rename targets). */
@@ -52,6 +31,21 @@ export declare function parseNameStatusChanges(nameStatus: string): TreeChangeSu
  * name, somewhere in the tree). Anything returned here rejects the whole fix
  * attempt — run 11's `rm src/client/pages/admin.tsx` had no corresponding add and
  * destroyed a sibling task's verified deliverable.
+ *
+ * REGENERABLE TEST-RUNNER OUTPUT IS EXEMPT (mx5 run 20). The guard is pure git: no
+ * ecosystem, no exemption list, so three Playwright FAILURE screenshots that
+ * TASK_0027's own `git add -A` had swept into a commit read as deliverables. Two
+ * consecutive attempts were discarded whole over them — each taking a real
+ * `src/client/api.test.tsx` repair with it, which attempt 3 then re-did and kept.
+ * 6m14s of an 8m16s gate. And the pipeline committed those same three deletions at
+ * the end anyway, in the stranded-fix commit (mx5 5d4147e), so the guard did not
+ * even preserve what it rejected two attempts to protect.
+ *
+ * The exempt list is a strict SUBSET of the verdict-level artifact list and lives
+ * in `regenerable-artifacts.ts`. `dist/`, `build/`, `.next/`, `.turbo/` and
+ * `.svelte-kit/` are NOT in it: a committed build output can be the shipped
+ * artifact, so deleting one is destructive in a way deleting a failure screenshot
+ * is not.
  */
 export declare function findForbiddenDeletions(changes: TreeChangeSummary): string[];
 /** Why an ignored path is (or is not) something the gate may rule on. */

package/dist/task/write-guard.js

@@ -19,6 +19,7 @@
  * glob — the legitimate fix shape from run 7). Pure text/path analysis; no git
  * execution, no stack assumptions.
  */
+import { isDeletionExemptArtifact } from './regenerable-artifacts.js';
 /** Porcelain v1 line: `XY <path>` or `XY <orig> -> <new>` (rename/copy). */
 function splitEntry(raw) {
     if (raw.length < 4)
@@ -125,12 +126,27 @@ const basename = (p) => {
  * name, somewhere in the tree). Anything returned here rejects the whole fix
  * attempt — run 11's `rm src/client/pages/admin.tsx` had no corresponding add and
  * destroyed a sibling task's verified deliverable.
+ *
+ * REGENERABLE TEST-RUNNER OUTPUT IS EXEMPT (mx5 run 20). The guard is pure git: no
+ * ecosystem, no exemption list, so three Playwright FAILURE screenshots that
+ * TASK_0027's own `git add -A` had swept into a commit read as deliverables. Two
+ * consecutive attempts were discarded whole over them — each taking a real
+ * `src/client/api.test.tsx` repair with it, which attempt 3 then re-did and kept.
+ * 6m14s of an 8m16s gate. And the pipeline committed those same three deletions at
+ * the end anyway, in the stranded-fix commit (mx5 5d4147e), so the guard did not
+ * even preserve what it rejected two attempts to protect.
+ *
+ * The exempt list is a strict SUBSET of the verdict-level artifact list and lives
+ * in `regenerable-artifacts.ts`. `dist/`, `build/`, `.next/`, `.turbo/` and
+ * `.svelte-kit/` are NOT in it: a committed build output can be the shipped
+ * artifact, so deleting one is destructive in a way deleting a failure screenshot
+ * is not.
  */
 export function findForbiddenDeletions(changes) {
     if (changes.deleted.length === 0)
         return [];
     const addedNames = new Set(changes.added.map(basename));
-    return changes.deleted.filter(p => !addedNames.has(basename(p)));
+    return changes.deleted.filter(p => !addedNames.has(basename(p)) && !isDeletionExemptArtifact(p));
 }
 /**
  * Directory names that are build output or a dependency tree by convention. The

package/dist/workers/fetch-core.d.ts

@@ -4,6 +4,7 @@ import { type ExcerptVerification } from '../shared/child-output.js';
 /** The exact non-answers the child is instructed to emit, matched at the tool layer. */
 export declare const UNCLEAR_ANSWER = "unclear from this page";
 export declare const NOT_COVERED_ANSWER = "not covered by this page";
+export declare function normaliseSourceUrl(url: string): string;
 export interface FetchRawInput {
     url: string;
     signal?: AbortSignal;
@@ -51,6 +52,15 @@ export interface FetchFocusedResult {
      * "page has no answer" and "answer is ambiguous" as the same thing (PROMPT-3 item 3).
      */
     coverageMiss: boolean;
+    /**
+     * What to do INSTEAD, present only on a coverage miss. `coverageMiss` was computed and
+     * stored and read nowhere, so the distinct channel it exists to provide never reached the
+     * worker: all it ever saw was the bare sentence "not covered by this page", which reads
+     * as "ask again, differently". It did — 9 of the 84 corpus fetches re-read a URL that had
+     * already returned a non-answer, one release-notes page three times with near-identical
+     * questions.
+     */
+    nextStep?: string;
     /** The #fragment slug that was anchored, when the URL carried one and it was located. */
     anchoredSection?: string;
     /** Retained evidence for a false `excerptVerified`, so it is diagnosable without re-fetch. */
@@ -63,6 +73,16 @@ export interface FetchFocusedResult {
     stdout: string;
 }
 export declare function fetchFocused(input: FetchFocusedInput): Promise<FetchFocusedResult>;
+/**
+ * The instruction that goes with a coverage miss. It says two things the bare sentinel does
+ * not: WHICH page was actually read (after the blob rewrite these differ, and a worker that
+ * cannot see that would "retry" the raw URL it already got), and that re-reading this page
+ * with a reworded question returns the same answer — so the next move is a different URL.
+ *
+ * Deliberately not a suggestion of WHICH other URL. Nothing at this layer knows one, and
+ * naming a guess is how a dead end becomes two dead ends.
+ */
+export declare function coverageMissNextStep(requestedUrl: string, fetchedUrl: string): string;
 export interface SelectedContent {
     content: string;
     /** The #fragment slug that was anchored, if the URL carried one AND it was located. */

package/dist/workers/fetch-core.js

@@ -11,18 +11,58 @@ const TRUNCATION_MARKER = '\n\n[...page continues, truncated...]\n\n';
 /** The exact non-answers the child is instructed to emit, matched at the tool layer. */
 export const UNCLEAR_ANSWER = 'unclear from this page';
 export const NOT_COVERED_ANSWER = 'not covered by this page';
-const NOT_COVERED_RE = /not covered by this page/i;
+/**
+ * Rule 6 asks the child to write the sentinel and NOTHING else, so the sentinel is the whole
+ * answer — anchored, not a substring search. A substring search misreads the opposite case:
+ * rule 5 tells the child to answer partially and say what is missing, and it says it in the
+ * prompt's own words ("… `obs_add_raw_audio_callback` and `obs_remove_raw_audio_callback`
+ * are not covered by this page"). That is a sourced answer, and the loose match filed it as
+ * a coverage miss. Observed twice in 5 reps of scripts/fetch-url-normalise-ab.ts once the
+ * rewrite started delivering pages that could half-answer; never in the 84 recorded corpus
+ * fetches, where 11 of 11 sentinel answers are the bare sentinel — so tightening it changes
+ * no recorded verdict.
+ */
+const NOT_COVERED_RE = /^not covered by this page[.\s]*$/i;
 const childArgs = () => [...childBaseArgs(), '--no-tools'];
+/**
+ * `github.com/{owner}/{repo}/blob/{ref}/{path}` renders the file through a client-side
+ * viewer, so the HTML we clean carries GitHub chrome ("Sign in", "Appearance settings")
+ * and none of the file. Every one of the 8 blob URLs in the three-project research-cache
+ * corpus came back a non-answer for that reason. `raw.githubusercontent.com` serves the
+ * same bytes as text/plain.
+ *
+ * Only the URL handed to the fetcher is rewritten — the caller's URL still keys the cache
+ * and still supplies the #fragment — so a worker that retries the raw URL by hand hits the
+ * cache, and a run's own recorded URLs stay what the run asked for.
+ *
+ * The query string is dropped: every blob query param (`?plain=1`, `?w=1`, …) is a viewer
+ * setting with no meaning on raw. The #fragment is dropped from the request too (it never
+ * reaches a server) but is preserved for {@link selectContent} via the original URL.
+ */
+const GH_BLOB_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/?#]+)\/([^/?#]+)\/blob\/([^?#]+?)\/*(?:[?#].*)?$/i;
+export function normaliseSourceUrl(url) {
+    const m = GH_BLOB_RE.exec(url.trim());
+    if (!m)
+        return url;
+    const [, owner, repo, refAndPath] = m;
+    // `/blob/{ref}/{path}` — a bare `/blob/{ref}` with no path names no file.
+    if (!refAndPath.includes('/'))
+        return url;
+    return `https://raw.githubusercontent.com/${owner}/${repo}/${refAndPath}`;
+}
 export async function fetchRaw(input) {
     const fetchAndCleanFn = input.fetchAndClean ?? defaultFetchAndClean;
-    const cleaned = await fetchAndCleanFn(input.url, { signal: input.signal });
+    const cleaned = await fetchAndCleanFn(normaliseSourceUrl(input.url), {
+        signal: input.signal
+    });
     return { markdown: cleaned.markdown, finalUrl: cleaned.finalUrl, title: cleaned.title };
 }
 export async function fetchFocused(input) {
     const fetchAndCleanFn = input.fetchAndClean ?? defaultFetchAndClean;
     const spawnFn = input.spawn ?? defaultSpawn;
     const strategy = input.strategy ?? shippedStrategy;
-    const cleaned = await fetchAndCleanFn(input.url, { signal: input.signal });
+    const fetchedUrl = normaliseSourceUrl(input.url);
+    const cleaned = await fetchAndCleanFn(fetchedUrl, { signal: input.signal });
     // The #fragment is a client-side concern the server never sees, so anchor from the
     // ORIGINALLY REQUESTED url, not the post-redirect finalUrl (which will have dropped it).
     const selected = strategy.selectContent(cleaned.markdown, input.url);
@@ -60,6 +100,7 @@ export async function fetchFocused(input) {
         };
     }
     const parsed = parseChildOutput(childResult.stdout);
+    const coverageMiss = NOT_COVERED_RE.test(parsed.answer.trim());
     // Verify against the FULL page, not the anchored slice: the slice is a substring of it,
     // so a genuine excerpt still verifies, and an excerpt the child pulled from memory still
     // fails — the detector's discrimination is unchanged by fragment anchoring.
@@ -69,12 +110,32 @@ export async function fetchFocused(input) {
         excerpt: parsed.excerpt,
         excerptVerified: check?.verified,
         excerptCheck: check,
-        coverageMiss: NOT_COVERED_RE.test(parsed.answer),
+        coverageMiss,
+        nextStep: coverageMiss ? coverageMissNextStep(input.url, fetchedUrl) : undefined,
         childExitCode: 0,
         aborted: false,
         ...base
     };
 }
+/**
+ * The instruction that goes with a coverage miss. It says two things the bare sentinel does
+ * not: WHICH page was actually read (after the blob rewrite these differ, and a worker that
+ * cannot see that would "retry" the raw URL it already got), and that re-reading this page
+ * with a reworded question returns the same answer — so the next move is a different URL.
+ *
+ * Deliberately not a suggestion of WHICH other URL. Nothing at this layer knows one, and
+ * naming a guess is how a dead end becomes two dead ends.
+ */
+export function coverageMissNextStep(requestedUrl, fetchedUrl) {
+    const rewritten = fetchedUrl !== requestedUrl ?
+        ` ${requestedUrl} is a GitHub file viewer whose HTML does not carry the file, so the`
+            + ` file itself was already read from ${fetchedUrl} — fetching that raw URL by hand`
+            + ` returns exactly this.`
+        : '';
+    return (`NEXT STEP: this page does not contain the answer.${rewritten}`
+        + ` Asking ${fetchedUrl} the same question a different way returns this same result —`
+        + ` do not re-read it. Try a different URL, or search for one.`);
+}
 /** Read the #fragment from a URL. Empty string when there is none. */
 function fragmentOf(url) {
     const h = url.indexOf('#');

package/dist/workers/pi-worker-fetch.js

@@ -52,7 +52,11 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                 if (failure !== null) {
                     return { text: failure, details: { childExitCode: result.childExitCode } };
                 }
-                const text = formatResultText({ answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
+                const body = formatResultText({ answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
+                // The coverage miss is the one outcome that carries an instruction. It goes
+                // in the TEXT, not only in details: details are for the harness, and the
+                // worker acts on what it reads.
+                const text = result.nextStep ? `${body}\n\n${result.nextStep}` : body;
                 return {
                     text,
                     details: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.37.2",
+    "version": "0.37.4",
     "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",