@mjasnikovs/pi-task 0.17.27 → 0.18.1

package/dist/task/phases.js

@@ -318,10 +318,10 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         }
     };
     // Per-worker timing split into wait (spawn → first byte) and work (first
-    // byte → exit). The workers run sequentially below, so each split is a clean
+    // byte → exit). With the default serial execution each split is a clean
     // per-worker measurement — waitMs the worker's own cold-start, workMs its
-    // generation+tool-call cost — not a Promise.all-relative wall-clock that
-    // conflates the two.
+    // generation+tool-call cost. Under the opt-in parallel mode the numbers are
+    // wall-clock-relative (queueing shows up in waitMs).
     const recordWorker = (label, p) => p.then(r => {
         deps.recordSubStep?.(`${label} wait`, r.waitMs);
         deps.recordSubStep?.(`${label} work`, r.workMs);
@@ -337,7 +337,9 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     //     each other ~4x (context worker measured 27s solo vs 128s under load),
     //     so summed-but-fast (~100s) beats max-of-slowed (~130s).
     // Every worker runs /no_think (below), so sequential is the faster regime.
-    // Do NOT switch this back to Promise.all without re-running that A/B.
+    // Do NOT switch the DEFAULT back to concurrent without re-running that A/B;
+    // the opt-in `parallelResearchWorkers` config flag exists for backends that
+    // genuinely serve parallel streams.
     //
     // `/no_think` is the big win: these are agentic exploration loops, and on a
     // reasoning model the child would otherwise emit a full <think> trace at
@@ -358,9 +360,13 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             label: 'worker:apis',
             // Read-heavy: gets the orientation core (see note above). Search/fetch
             // ride along only when a Brave key exists — see SEARCH_EXTENSION_PATH.
-            prompt: appendNoThink(orientation.block
+            // FILES' finished map rides along when available (serial default), so
+            // the worker doesn't re-derive where-things-live via docs-"."
+            // queries the FILES worker just answered (run-7 F7: up to 10
+            // duplicate `.`-decodes per task through the serial bottleneck).
+            prompt: prior => appendNoThink(orientation.block
                 + promptHeader
-                + RESEARCH_APIS_PROMPT(refined)
+                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
                 + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')),
             tools: 'read,grep,find,ls,pi-worker-docs'
                 + (searchConfigured() ? ',pi-worker-search,pi-worker-fetch' : ''),
@@ -390,25 +396,36 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             extensions: [SINGLE_READ_EXTENSION_PATH]
         }
     ];
-    // Run workers one at a time, persisting each worker's validated output the
-    // moment it succeeds. On a resume, a worker whose cached output is already on
-    // disk is skipped — so when one worker fails and the phase is re-run, the
-    // others don't burn minutes regenerating work that was already good. Each
-    // worker is validated inline (not in a second pass) so a failure throws
-    // before later workers run, and only trustworthy text is ever cached.
-    const sections = [];
-    for (const spec of workerSpecs) {
+    // Persisting a worker's section is a read-modify-write of the shared task
+    // file, so writes are chained through one lock — a no-op in serial mode,
+    // load-bearing in parallel mode where two workers can settle together.
+    let persistChain = Promise.resolve();
+    const persistSection = (heading, text) => {
+        const next = persistChain.then(() => setTaskSection(deps.cwd, deps.taskId, heading, text));
+        persistChain = next.catch(() => { });
+        return next;
+    };
+    // One worker, cache-skip to persist: on a resume, a worker whose cached
+    // output is already on disk is skipped — so when one worker fails and the
+    // phase is re-run, the others don't burn minutes regenerating work that was
+    // already good. Each worker is validated inline (not in a second pass), so
+    // only trustworthy text is ever cached.
+    //
+    // A fatal failure (crash/empty/leak) still throws — the already-cached
+    // workers survive for the resume. A runaway (loop/timeout) degrades to its
+    // partial output instead, so one weak worker can't abort a whole auto-run;
+    // the degraded section is cached too, so a resume doesn't re-loop it.
+    const runSpec = async (spec, prior) => {
         const cacheHeading = researchWorkerCacheHeading(spec.section);
         const cached = (await readSection(deps.cwd, deps.taskId, cacheHeading)) ?? '';
         if (cached.trim().length > 0) {
             deps.logDebug?.(`${spec.label}: cached — skipping re-run`);
             updateProgress();
-            sections.push({ name: spec.section, text: cached.trim() });
-            continue;
+            return { name: spec.section, text: cached.trim() };
         }
         deps.logDebug?.(`${spec.label}: start`);
         const r = await recordWorker(spec.label, runWorker({
-            prompt: spec.prompt,
+            prompt: typeof spec.prompt === 'function' ? spec.prompt(prior) : spec.prompt,
             cwd: deps.cwd,
             signal: deps.signal,
             spawn: deps.spawn,
@@ -423,10 +440,6 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
             + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));
         updateProgress();
-        // A fatal failure (crash/empty/leak) still throws — the already-cached
-        // workers survive for the resume. A runaway (loop/timeout) degrades to its
-        // partial output instead, so one weak worker can't abort a whole auto-run;
-        // the degraded section is cached too, so a resume doesn't re-loop it.
         const failure = classifyResearchWorker(spec.section, r);
         if (failure?.kind === 'fatal')
             throw failure.error;
@@ -436,8 +449,34 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         if (failure?.kind === 'runaway') {
             deps.logDebug?.(`${spec.label}: degraded — ${failure.reason}`);
         }
-        await setTaskSection(deps.cwd, deps.taskId, cacheHeading, sectionText);
-        sections.push({ name: spec.section, text: sectionText });
+        await persistSection(cacheHeading, sectionText);
+        return { name: spec.section, text: sectionText };
+    };
+    const sections = [];
+    if (!getConfig().parallelResearchWorkers) {
+        // Default: ONE AT A TIME (see the A/B note above the specs) — a fatal
+        // failure throws before later workers run, and each worker can see the
+        // finished sections before it (APIS builds on the FILES map).
+        for (const spec of workerSpecs) {
+            sections.push(await runSpec(spec, sections));
+        }
+    }
+    else {
+        // Opt-in for parallel-capable backends. allSettled (not all): every
+        // worker runs to its own outcome first, so one fatal failure cannot
+        // orphan the others' output — their sections persist for the resume
+        // before the failure is thrown. Assembly order stays the spec order
+        // regardless of completion order. No prior sections exist here, so
+        // prompt builders get none (APIS runs map-less, as before this option).
+        const settled = await Promise.allSettled(workerSpecs.map(spec => runSpec(spec, [])));
+        for (const s of settled) {
+            if (s.status === 'rejected')
+                throw s.reason;
+        }
+        for (const s of settled) {
+            if (s.status === 'fulfilled')
+                sections.push(s.value);
+        }
     }
     // All workers succeeded — the assembled output below becomes the canonical
     // 'research' section (written by the orchestrator). The per-worker caches

package/dist/task/prohibition-probe.d.ts

@@ -0,0 +1,53 @@
+/**
+ * prohibition-probe — deterministic detection of VIOLATED SPEC PROHIBITIONS,
+ * feeding the verify gate's prompt.
+ *
+ * The failure class (mx5 run 7, "New Listing page" task): the spec's CONSTRAINTS
+ * said "**Do NOT modify** any server-side code: `src/server/index.ts`, …"; the
+ * implementation modified `src/server/index.ts` anyway; the verify child SAW it
+ * ("VIOLATES 'Do NOT modify server-side code'"), waived it ("BUT: this is
+ * additive, tests pass with it"), and PASSed. Worse, the reproduction fixture
+ * showed the baseline child usually never LOOKS: 5/5 baseline runs consulted no
+ * diff at all and several affirmatively claimed the forbidden file was untouched.
+ *
+ * So — like the substitution probe (see substitution-probe.ts, whose A/B proved
+ * prompt language alone gets ~40% attention while a concrete deterministic
+ * finding gets 100%) — the fix is a deterministic pre-check whose finding is
+ * injected into the prompt: extract the concrete paths the spec forbids
+ * modifying, intersect with the task's changed files (pure git shape, already
+ * collected for the substitution probe), and hand the child each hit with the
+ * exact constraint wording.
+ *
+ * The finding is advisory, not an auto-FAIL, for one reason: prohibitions in
+ * real specs are prose and can be CONDITIONAL ("Do NOT modify `api.ts` beyond
+ * what is needed for the new endpoint") — a hard gate on prose extraction would
+ * false-FAIL legitimate work. The finding therefore carries the constraint line
+ * verbatim and the prompt's no-waiver rule (4b in verify-work.ts) forbids
+ * excusing an ABSOLUTE prohibition while directing conditional ones to be judged
+ * against their own stated exception. A violation that was fully reverted before
+ * verify produces no diff entry, so it never fires — reverted = not violated.
+ */
+import type { ChangedFile } from './substitution-probe.js';
+/** One "do not modify X" constraint extracted from the spec text. */
+export interface Prohibition {
+    /** The forbidden path exactly as the spec spells it (file or directory). */
+    path: string;
+    /** The full spec line carrying the prohibition, so the verify child judges
+     *  against the EXACT wording — including any exception clause it states. */
+    constraint: string;
+}
+/**
+ * Extract the concrete paths the spec explicitly forbids modifying: every
+ * backtick-quoted path-like token on a line that expresses a modification ban.
+ * Prose-only prohibitions ("do not modify server-side code" with no path named)
+ * extract nothing — the prompt-level rule still covers them.
+ */
+export declare function extractProhibitions(spec: string): Prohibition[];
+/**
+ * Intersect the spec's prohibitions with the task's changed files (git shape —
+ * the same collector the substitution probe uses). A prohibition matches a
+ * changed file exactly, or as a directory prefix (`src/server` covers
+ * `src/server/index.ts`). One finding line per violated file, carrying the
+ * constraint verbatim; empty array → no block in the prompt.
+ */
+export declare function findProhibitionViolations(prohibitions: Prohibition[], files: ChangedFile[]): string[];

package/dist/task/prohibition-probe.js

@@ -0,0 +1,64 @@
+/**
+ * Does this line express a modification ban? Matches the active forms ("do not
+ * modify", "must not touch", "never edit", "don't change") and the passive form
+ * ("must not be modified"). Deliberately verb-scoped to modification — a "do not
+ * add a dependency" style rule names no path and is the prompt rule's job.
+ */
+const PROHIBITION_RE = /\b(?:do\s+not|don'?t|must\s+not|never)\s+(?:be\s+)?(?:modify|modified|touch|touched|edit|edited|change|changed|alter|altered|rewrite|rewritten|overwrite|overwritten|delete|deleted|remove|removed)\b/i;
+/**
+ * A backtick token counts as a path only when it is whitespace-free, uses path
+ * characters, and either contains a directory separator, has a file extension,
+ * or is a dotfile. Bare identifiers (`getOrder`), API routes with spaces
+ * (`POST /api/listings`), and code snippets are rejected — the probe would
+ * rather miss a `Makefile` than fire on prose.
+ */
+function looksLikePath(token) {
+    if (!/^[\w.@~/-]+$/.test(token))
+        return false;
+    return token.includes('/') || /\.[A-Za-z0-9]+$/.test(token) || token.startsWith('.');
+}
+/**
+ * Extract the concrete paths the spec explicitly forbids modifying: every
+ * backtick-quoted path-like token on a line that expresses a modification ban.
+ * Prose-only prohibitions ("do not modify server-side code" with no path named)
+ * extract nothing — the prompt-level rule still covers them.
+ */
+export function extractProhibitions(spec) {
+    const out = [];
+    const seen = new Set();
+    for (const line of spec.split('\n')) {
+        if (!PROHIBITION_RE.test(line))
+            continue;
+        for (const m of line.matchAll(/`([^`]+)`/g)) {
+            const token = m[1].trim();
+            if (!looksLikePath(token) || seen.has(token))
+                continue;
+            seen.add(token);
+            out.push({ path: token, constraint: line.trim() });
+        }
+    }
+    return out;
+}
+/** Normalise a path for comparison: strip leading ./ and trailing /. */
+const norm = (p) => p.replace(/^\.\//, '').replace(/\/+$/, '');
+/**
+ * Intersect the spec's prohibitions with the task's changed files (git shape —
+ * the same collector the substitution probe uses). A prohibition matches a
+ * changed file exactly, or as a directory prefix (`src/server` covers
+ * `src/server/index.ts`). One finding line per violated file, carrying the
+ * constraint verbatim; empty array → no block in the prompt.
+ */
+export function findProhibitionViolations(prohibitions, files) {
+    const findings = [];
+    for (const f of files) {
+        const fp = norm(f.path);
+        const hit = prohibitions.find(p => {
+            const pp = norm(p.path);
+            return fp === pp || fp.startsWith(`${pp}/`);
+        });
+        if (!hit)
+            continue;
+        findings.push(`${f.path} — modified by this task, but the spec forbids it: "${hit.constraint}"`);
+    }
+    return findings;
+}

package/dist/task/prompts.d.ts

@@ -50,7 +50,7 @@ export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) =>
 declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: 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) => string;
+declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap?: string) => string;
 declare const RESEARCH_CONTEXT_PROMPT: (refined: string) => string;
 declare const RESEARCH_TOOLING_PROMPT: (refined: string) => string;
 declare const GRILL_GEN_PROMPT: (refined: string, research: string, priorQA: string) => string;

package/dist/task/prompts.js

@@ -122,7 +122,7 @@ No section header. No other sections. No preamble.
 
 Task:
 ${refined}`;
-const RESEARCH_APIS_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools — and \`pi-worker-docs\` for installed npm packages — to identify the commands, functions, types, and interfaces the agent will use for the following task.
+const RESEARCH_APIS_PROMPT = (refined, filesMap) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools — and \`pi-worker-docs\` for installed npm packages — to identify the commands, functions, types, and interfaces the agent will use for the following task.
 
 NPM PACKAGES — use pi-worker-docs, NOT file reads: for any third-party npm package (e.g. "zod", "hono", "drizzle-orm"), call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open node_modules source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost.
 
@@ -133,7 +133,14 @@ RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references)
 APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
 
 RELEVANCE — read carefully: list ONLY the symbols the agent will call, implement, modify, or directly depend on for THIS task. Do NOT enumerate the project's entire public surface or dump every exported function in a touched file. A symbol unrelated to the task does not belong here just because it sits in the same module. Keep the smallest sufficient set: include every symbol the task actually exercises and nothing more. There is no fixed limit — list as many as the task truly needs and no padding beyond that.
+${filesMap ?
+    `
+PROJECT FILE MAP — already surveyed for this task by a prior worker (authoritative):
+${filesMap}
 
+USE THE MAP: where things live is ALREADY ANSWERED above. Do NOT re-derive it — never call \`pi-worker-docs(".", …)\` (or grep/find) for a question the map already answers: which file holds X, whether a path exists, what a file is for. Reserve \`.\`-queries for symbol-level facts the map cannot carry — signatures, parameter and return types, what a module exports. Go straight to the mapped files' symbols.
+`
+    : ''}
 ${RESEARCH_INPUTS_NOT_DELIVERABLE}
 
 ${RESEARCH_READ_ONLY_CONSTRAINT}

package/dist/task/verify-work.d.ts

@@ -38,11 +38,24 @@ export declare function extractSpecForVerification(taskBody: string): string | n
  * `probeFindings` are the deterministic self-verification probe results (see
  * substitution-probe.ts): the TEST-THE-COPY class is caught 5/5 only when the
  * prompt carries both the rule (3b) AND a concrete finding naming the suspect
- * file — the rule alone got 2/5 attention on the live model. The findings are
+ * file — the rule alone got 2/5 attention on the local model. The findings are
  * pure git shape (test files the task itself changed), so the mandate is
  * language- and framework-agnostic.
+ *
+ * `prohibitionFindings` are the deterministic prohibition probe results (see
+ * prohibition-probe.ts): spec-forbidden paths the task's diff modified anyway.
+ * Same probe+rule design, same reason: the VIOLATION-EXCUSAL class (mx5 run 7:
+ * child saw "Do NOT modify server-side code" violated, waived it as "additive,
+ * tests pass", PASSed) needs both the no-waiver rule (4b) AND the concrete diff
+ * fact — the baseline child usually never runs `git diff` at all, so without the
+ * finding it cannot even SEE the violation. A/B on the live local model
+ * (violated-but-working fixture, everything green, forbidden file modified
+ * additively): old prompt 5/5 false-PASS (several runs affirmatively claimed the
+ * forbidden file was untouched); rule+finding 5/5 FAIL naming the constraint.
+ * Guard: honest-clean fixture (prohibition in spec, probe silent) 5/5 PASS — no
+ * paranoia. Reverted-violation ≡ clean at the diff level (no entry → no finding).
  */
-export declare function buildVerifyPrompt(spec: string, probeFindings?: string[]): string;
+export declare function buildVerifyPrompt(spec: string, probeFindings?: string[], envNotes?: string, prohibitionFindings?: string[]): string;
 /**
  * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL` marker
  * (the model discusses before concluding, and bash output may echo the word
@@ -82,6 +95,12 @@ export interface VerificationDeps {
      * into the child's prompt. A/B-proven load-bearing: the prompt rule alone caught
      * the class 2/5, rule + probe finding 5/5. ABSENT or empty → no probe block. */
     probe?: () => Promise<string[]>;
+    /**
+     * DETERMINISTIC prohibition probe (see prohibition-probe.ts): spec-forbidden
+     * paths the task's diff modified anyway, injected as prompt findings under the
+     * no-waiver rule (4b). Advisory, never auto-FAIL — real prohibitions can be
+     * conditional prose. ABSENT or empty → no prohibition block. */
+    prohibitionProbe?: () => Promise<string[]>;
     /**
      * Result of the git-state guard for the MOST RECENT runChild call (see
      * git-state-guard.ts): did the child mutate repo state (stash/checkout/file
@@ -94,6 +113,17 @@ export interface VerificationDeps {
         mutated: boolean;
         detail: string;
     };
+    /**
+     * Per-run environment-facts cache (see env-notes.ts): `read` supplies the
+     * facts earlier gate children discovered (inlined into the prompt with the
+     * no-waiver caveat); `append` stores the `ENV-NOTE:` lines this child
+     * emitted, host-side. ABSENT → no block, no capture (tests unchanged).
+     * Facts only cut re-discovery time; verdict rules are unaffected.
+     */
+    envNotes?: {
+        read: () => Promise<string>;
+        append: (notes: string[]) => Promise<void>;
+    };
 }
 /**
  * Run the verification pass for one task. A missing spec is a pass. Otherwise run

package/dist/task/verify-work.js

@@ -68,6 +68,7 @@
  * verify, this is a pass (ok: true).
  */
 import { USER_CANCELLED } from './child-runner.js';
+import { buildEnvNotesBlock, ENV_NOTE_EMIT_INSTRUCTION, extractEnvNotes } from './env-notes.js';
 /**
  * The verification child gets exactly two tools: `read` and `bash`.
  *
@@ -119,11 +120,24 @@ export function extractSpecForVerification(taskBody) {
  * `probeFindings` are the deterministic self-verification probe results (see
  * substitution-probe.ts): the TEST-THE-COPY class is caught 5/5 only when the
  * prompt carries both the rule (3b) AND a concrete finding naming the suspect
- * file — the rule alone got 2/5 attention on the live model. The findings are
+ * file — the rule alone got 2/5 attention on the local model. The findings are
  * pure git shape (test files the task itself changed), so the mandate is
  * language- and framework-agnostic.
+ *
+ * `prohibitionFindings` are the deterministic prohibition probe results (see
+ * prohibition-probe.ts): spec-forbidden paths the task's diff modified anyway.
+ * Same probe+rule design, same reason: the VIOLATION-EXCUSAL class (mx5 run 7:
+ * child saw "Do NOT modify server-side code" violated, waived it as "additive,
+ * tests pass", PASSed) needs both the no-waiver rule (4b) AND the concrete diff
+ * fact — the baseline child usually never runs `git diff` at all, so without the
+ * finding it cannot even SEE the violation. A/B on the live local model
+ * (violated-but-working fixture, everything green, forbidden file modified
+ * additively): old prompt 5/5 false-PASS (several runs affirmatively claimed the
+ * forbidden file was untouched); rule+finding 5/5 FAIL naming the constraint.
+ * Guard: honest-clean fixture (prohibition in spec, probe silent) 5/5 PASS — no
+ * paranoia. Reverted-violation ≡ clean at the diff level (no entry → no finding).
  */
-export function buildVerifyPrompt(spec, probeFindings) {
+export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFindings) {
     const probeBlock = probeFindings && probeFindings.length > 0 ?
         [
             'SELF-VERIFICATION NOTICE (deterministic, computed by the orchestrator from the diff):',
@@ -137,6 +151,20 @@ export function buildVerifyPrompt(spec, probeFindings) {
             ''
         ]
         : [];
+    const prohibitionBlock = prohibitionFindings && prohibitionFindings.length > 0 ?
+        [
+            'PROHIBITION NOTICE (deterministic, computed by the orchestrator from the',
+            "spec's own constraint lines and the task's diff): this task MODIFIED paths",
+            'the spec explicitly forbids modifying:',
+            ...prohibitionFindings.map(f => `- ${f}`),
+            'Read the exact constraint wording in the spec. Unless that wording itself',
+            'states an exception that covers this change, this is a violated prohibition:',
+            'rule 4b applies and the verdict is FAIL naming the forbidden path — even if',
+            'every test passes and the change looks harmless.',
+            ''
+        ]
+        : [];
+    const envBlock = envNotes && envNotes.trim().length > 0 ? [buildEnvNotesBlock(envNotes)] : [];
     return [
         'You are a strict verification pass running right after an AI coding agent',
         'finished a task and committed it. The agent is known to mark work "done"',
@@ -150,7 +178,9 @@ export function buildVerifyPrompt(spec, probeFindings) {
         'THE TASK SPEC (its ACCEPTANCE criteria and VERIFY block are the contract):',
         spec.trim(),
         '',
+        ...envBlock,
         ...probeBlock,
+        ...prohibitionBlock,
         'How to verify — verify the REAL, shipped deliverable exactly as an unaided fresh',
         'checkout (or CI run) would experience it:',
         '',
@@ -215,6 +245,19 @@ export function buildVerifyPrompt(spec, probeFindings) {
         '4. Treat the ACCEPTANCE criteria as the bar. If a command fails, or its real output',
         '   contradicts an ACCEPTANCE criterion, the work has NOT verified.',
         '',
+        '4b. SPEC PROHIBITIONS ARE PART OF THE BAR — YOU HAVE NO WAIVER AUTHORITY: when the',
+        '   spec explicitly forbids something ("Do NOT modify X", "MUST NOT touch Y") and the',
+        '   shipped work does it anyway, that is a FAIL naming the violated constraint. You',
+        '   may not excuse a violation because it is additive, small, harmless, an improvement,',
+        '   or because every test still passes — "it works anyway" is exactly the waiver you do',
+        "   not have; relaxing a constraint is the spec owner's call, not yours. Check the",
+        "   task's own diff (git) against the spec's prohibitions — a forbidden file can be",
+        '   modified without any test noticing. Only two outcomes are not a FAIL: the',
+        '   violation was fully REVERTED (the shipped tree no longer violates), or the',
+        '   prohibition\'s own wording states an exception ("except…", "beyond what is needed',
+        '   for…") that covers the change — judged against that stated exception, not against',
+        '   your view of harmlessness.',
+        '',
         '5. The ONLY thing you may assume is already provided is a genuinely EXTERNAL running',
         '   service or network resource (a database server, an API host) that the project',
         '   documents as a prerequisite. Before you rely on that assumption, PROBE for the',
@@ -249,6 +292,8 @@ export function buildVerifyPrompt(spec, probeFindings) {
         'a required behavior missing — the verdict is FAIL, even if typecheck and lint are green',
         'and even if the gap seems minor. Never downgrade an unmet criterion to a warning note.',
         '',
+        ENV_NOTE_EMIT_INSTRUCTION,
+        '',
         'When you are done, output EXACTLY ONE of these as the final line:',
         "  WORK-VERIFIED: PASS              (the project's own command, run unaided, met the spec)",
         '  WORK-VERIFIED: FAIL <text>      (the shipped command failed or did not meet the spec; say what failed)',
@@ -305,6 +350,26 @@ export async function runWorkVerification(deps) {
             findings = [];
         }
     }
+    let prohibitions = [];
+    if (deps.prohibitionProbe) {
+        try {
+            prohibitions = await deps.prohibitionProbe();
+        }
+        catch {
+            prohibitions = [];
+        }
+    }
+    // Environment facts from earlier gate children (best-effort; a cache failure
+    // must never block verification).
+    let envNotes = '';
+    if (deps.envNotes) {
+        try {
+            envNotes = await deps.envNotes.read();
+        }
+        catch {
+            envNotes = '';
+        }
+    }
     // A child that emits NO verdict never judged the work (budget/context death mid-
     // investigation — seen live: an 11-minute verify wandered, died verdict-less, and
     // the resulting FAIL burned a full implementation re-run on an unjudged artifact).
@@ -312,7 +377,7 @@ export async function runWorkVerification(deps) {
     for (let attempt = 1;; attempt++) {
         let text;
         try {
-            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings), deps.signal);
+            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings, envNotes, prohibitions), deps.signal);
         }
         catch (err) {
             if (err instanceof Error && err.message === USER_CANCELLED)
@@ -320,6 +385,16 @@ export async function runWorkVerification(deps) {
             const msg = err instanceof Error ? err.message : String(err);
             return { ok: false, reason: `verification pass could not run: ${msg}` };
         }
+        // Capture the environment facts the child shared — regardless of verdict
+        // (a FAIL run's discoveries are just as reusable).
+        if (deps.envNotes) {
+            try {
+                await deps.envNotes.append(extractEnvNotes(text));
+            }
+            catch {
+                // best-effort cache
+            }
+        }
         // A child that mutated the repo (git-state guard fired) judged a tree it had
         // itself changed — its verdict is meaningless in both directions, so discard
         // it BEFORE parsing. The guard already restored the state, so one retry runs

package/dist/task/widget.d.ts

@@ -57,8 +57,9 @@ export interface AutoLoaderState {
      *  pass and 'verify' is the per-task work-verification pass, neither of which
      *  has step numbering. 'recommend' is the read-only research that picks the
      *  recommended action after a verify FAIL. 'lint-fix' is the bounded fix pass
-     *  for a repo-health verify FAIL. */
-    kind?: 'planning' | 'enforce' | 'verify' | 'recommend' | 'lint-fix';
+     *  for a repo-health verify FAIL; 'final-fix' the bounded fix pass for a
+     *  final-integration-gate FAIL. */
+    kind?: 'planning' | 'enforce' | 'verify' | 'recommend' | 'lint-fix' | 'final-fix';
 }
 export declare function buildAutoLoaderLines(s: AutoLoaderState, theme?: WidgetTheme): string[];
 /** Structured mirror of buildAutoLoaderLines. Only the numbered planning stage

package/dist/task/widget.js

@@ -148,7 +148,8 @@ export function buildAutoLoaderLines(s, theme) {
         : s.kind === 'verify' ? `verifying work · ${elapsed}`
             : s.kind === 'recommend' ? `assessing the failure · ${elapsed}`
                 : s.kind === 'lint-fix' ? `fixing static findings · ${elapsed}`
-                    : `planning ${s.stepNum}/${s.stepTotal} ${s.step} · ${elapsed}`;
+                    : s.kind === 'final-fix' ? `fixing the final gate · ${elapsed}`
+                        : `planning ${s.stepNum}/${s.stepTotal} ${s.step} · ${elapsed}`;
     if (s.contextUsage) {
         const ctxDetail = formatContextDetail(s.contextUsage, theme);
         if (ctxDetail)
@@ -167,7 +168,8 @@ export function buildAutoLoaderData(s) {
         : s.kind === 'verify' ? 'verifying work'
             : s.kind === 'recommend' ? 'assessing the failure'
                 : s.kind === 'lint-fix' ? 'fixing static findings'
-                    : s.step;
+                    : s.kind === 'final-fix' ? 'fixing the final gate'
+                        : s.step;
     const d = {
         title: `/task-auto · ${s.title}`,
         phase,

package/dist/workers/pi-worker-core.d.ts

@@ -36,6 +36,16 @@ export interface RunWorkerInput {
         threshold?: number;
         pathThreshold?: number;
     } | false;
+    /**
+     * Dead-backend stall guard override. Default ON: no output for
+     * STALL_AFTER_MS → probe the model endpoints pi is configured with →
+     * unreachable → kill + `stalled: true`. Pass `false` to disable, or
+     * override the window/probe (tests, harnesses).
+     */
+    stall?: {
+        afterMs?: number;
+        probe?: () => Promise<boolean>;
+    } | false;
 }
 export interface RunWorkerResult {
     text: string;
@@ -73,5 +83,11 @@ export interface RunWorkerResult {
      * the caller must treat it as a failure.
      */
     timedOut?: boolean;
+    /**
+     * Set when the stall guard killed the worker: no output progress AND the
+     * model endpoint unreachable. Check BEFORE `aborted` — the kill sets
+     * aborted too, and mislabeling this as a user cancel hides a dead backend.
+     */
+    stalled?: boolean;
 }
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;

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

@@ -3,6 +3,7 @@ import { CHILD_BASE_ARGS, runChildDefault } from '../shared/child-process.js';
 import { LoopDetector } from '../task/loop-detector.js';
 import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint } from '../task/child-runner.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
+import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
 // `--mode json` makes pi emit structured events as they happen instead of
 // buffering the assistant text and flushing on exit. That matters for the
 // wait/work timing split: in text mode the first stdout chunk only arrives at
@@ -21,6 +22,15 @@ const DEFAULT_TOOLS = 'read,grep,find,ls';
  * so it never trips a legitimately slow run.
  */
 const RESEARCH_WORKER_TIMEOUT_MS = 240_000;
+/**
+ * Output-stall window before the dead-backend probe fires (mx5 run 7: model
+ * server died mid-gate-child, the child hung MUTE for 64 minutes). This is NOT
+ * a wall-clock cap — output progress resets it, and even a fully stalled child
+ * is only killed when the model endpoint is actually unreachable. Sized so a
+ * long local prompt-processing pass (minutes of legitimate silence, server
+ * alive) just gets probed and waits on.
+ */
+const STALL_AFTER_MS = 180_000;
 /** Restart hint after a wall-clock timeout — distinct from the loop hint. */
 const WORKER_TIMEOUT_HINT = '[SYSTEM NOTE: Your previous attempt ran out of time before answering — you '
     + 'were exploring too long. Be decisive: do the minimum reads/greps needed, '
@@ -95,6 +105,15 @@ export async function runWorker(input) {
         try {
             result = await runChildDefault(invocation, input.cwd, timeout.signal, {
                 mode: 'json-events',
+                ...(input.stall === false ?
+                    {}
+                    : {
+                        stall: {
+                            afterMs: input.stall?.afterMs ?? STALL_AFTER_MS,
+                            probe: input.stall?.probe
+                                ?? (() => probeModelEndpoints(discoverModelEndpoints()))
+                        }
+                    }),
                 onFirstByte: () => (tFirstByte = Date.now()),
                 onToolCall: call => {
                     if (!loopDetector)
@@ -150,7 +169,8 @@ export async function runWorker(input) {
             workMs,
             ...(leaked ? { leakedToolCall: leaked } : {}),
             ...(loopHit ? { loopHit } : {}),
-            ...(timedOut ? { timedOut: true } : {})
+            ...(timedOut ? { timedOut: true } : {}),
+            ...(result.stalled ? { stalled: true } : {})
         };
     }
 }

package/package.json

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