@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/verify-work.js

@@ -42,6 +42,11 @@ import { buildEnvNotesBlock, ENV_NOTE_EMIT_INSTRUCTION, extractEnvNotes } from '
 import { buildContractsVerifyBlock } from './contracts.js';
 import { findSkipEscapes, skipEscapeVerifyFindings } from './skip-escape.js';
 import { crossTaskDeletionVerifyFindings } from './task-provenance.js';
+import { classifyHealthDelta, inheritedHealthFindings } from './health-baseline.js';
+import { parseSpec, sliceSpecSection } from './spec-model.js';
+import { qaKindsFromRecord } from './qa-transcript.js';
+import { annotateConstraints, anyBinding, renderConstraintPolicy } from './constraint-policy.js';
+import { suppressionVerifyFindings } from './suppression-probe.js';
 /**
  * The verification child gets exactly two tools: `read` and `bash`.
  *
@@ -99,33 +104,12 @@ export function isStaticClass(cls) {
     return cls === 'repo-health' || cls === 'static-checks';
 }
 /**
- * Slice the delivered spec (GOAL / CONSTRAINTS / ACCEPTANCE / VERIFY) out of a
- * task file body. The compose and critique phases write the section named `spec`,
- * so the composed spec lives under `## spec` and runs to the next line matching
- * `## ` plus non-space (`## phase timings`); a `### ` subheading stays inside.
- * Returns null when there is no spec section or it is blank (a task that never
- * reached compose), which the caller treats as a pass — nothing to verify against.
+ * The delivered spec's TEXT, for the children that must read its prose verbatim.
+ * The slicing itself lives in spec-model.ts beside the parser, so "the spec
+ * section" is one definition rather than one per consumer.
  */
 export function extractSpecForVerification(taskBody) {
-    const lines = taskBody.split('\n');
-    let start = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/^##\s+spec\s*$/i.test(lines[i])) {
-            start = i + 1;
-            break;
-        }
-    }
-    if (start === -1)
-        return null;
-    let end = lines.length;
-    for (let i = start; i < lines.length; i++) {
-        if (/^##\s+\S/.test(lines[i])) {
-            end = i;
-            break;
-        }
-    }
-    const spec = lines.slice(start, end).join('\n').trim();
-    return spec.length > 0 ? spec : null;
+    return sliceSpecSection(taskBody);
 }
 /**
  * Build one row. Generic in the probe's return type so `empty`/`findings` stay
@@ -146,8 +130,8 @@ function probeAdapter(row) {
         block,
         ruleId,
         rule,
-        run: async (deps, onStage) => {
-            const probe = source(deps);
+        run: async (deps, onStage, pre) => {
+            const probe = source(deps, pre);
             // Probes are INDEPENDENTLY OPTIONAL: an absent probe is "skipped", and a
             // probe that throws degrades to its own empty value — it is a sharpener,
             // never a blocker, so a fault in one can neither block the gate nor
@@ -171,6 +155,68 @@ const asLines = (raw) => raw;
 /** The table. ROW ORDER IS THE NOTICE-BLOCK ORDER IN THE PROMPT: `buildVerifyPrompt`
  *  flatMaps this array to build the notices, so reordering rows reorders the prompt. */
 const PROBE_ADAPTERS = [
+    /**
+     * The project's own check and build commands, ALREADY RUN by the parent against
+     * this exact tree (see gate-evidence.ts). The one row that supplies a RESULT
+     * rather than a warning, and the one row rule 1 switches on: a child handed the
+     * output spends its turn judging it instead of reproducing a suite the previous
+     * child already ran.
+     */
+    probeAdapter({
+        key: 'evidence',
+        stage: 'project checks',
+        empty: [],
+        findings: asLines,
+        ruleId: '1',
+        block: findings => [
+            'EVIDENCE (deterministic, run by the orchestrator against THIS tree, just now):',
+            "the project's own check and build commands have ALREADY BEEN RUN for you. Each",
+            'line is the command, how it ended, and the file holding its complete output:',
+            ...findings.map(f => `- ${f}`),
+            'Read those files with your `read` tool. A command listed here does not need',
+            'running again (rule 1) — re-run only a targeted subset: a single test file, or',
+            'one command whose reported result you have a concrete reason to doubt. SKIPPED',
+            'means the command could not run on this machine at all, so it is evidence of',
+            'nothing in either direction — rules 5 and 5c decide what its absence means.',
+            ''
+        ]
+    }),
+    /**
+     * PRE-EXISTING repo health (see health-baseline.ts): static checks that were
+     * ALREADY failing, the same way, before this task started. They used to be an
+     * absolute FAIL that short-circuited the whole pass, so the task answered for
+     * a sibling's defect and its own probe findings were never computed. As a row
+     * they are stated to the child instead: judge this task's work, and do not
+     * read a check that was red on arrival as evidence about it either way.
+     */
+    probeAdapter({
+        key: 'repoHealth',
+        source: (_deps, pre) => () => Promise.resolve(pre.repoHealth),
+        empty: [],
+        findings: asLines,
+        ruleId: '4h',
+        block: findings => [
+            'INHERITED REPO-HEALTH NOTICE (deterministic, computed by the orchestrator by',
+            "re-running the project's own static checks and comparing them against the",
+            'baseline taken before this task started): these checks were ALREADY failing,',
+            'with the same exit code, before any of this work existed:',
+            ...findings.map(f => `- ${f}`),
+            "They are NOT this task's defect and must not decide this verdict — rule 4h.",
+            'Equally, a red check that was red before proves nothing about this work: do',
+            'not read its output as evidence that the shipped behavior is correct.',
+            ''
+        ],
+        rule: [
+            "4h. AN INHERITED RED CHECK IS NOT THIS TASK'S FAIL, AND NOT ITS PROOF — when the",
+            '   INHERITED REPO-HEALTH NOTICE above names a check, that check failed identically',
+            '   before this task ran. Do NOT fail this work for it: the defect belongs to',
+            '   whatever put it there, it is recorded as durable debt, and the run-end gate',
+            '   re-checks it. Do NOT lean on it either — a command that was already exiting',
+            "   non-zero tells you nothing about this task's behavior, so verify that behavior",
+            '   another way. A check that is failing DIFFERENTLY, or one absent from the notice,',
+            "   is this task's to answer for in the ordinary way."
+        ]
+    }),
     /**
      * Deterministic self-verification probe (see substitution-probe.ts): test
      * files this task itself authored or changed, with their added-line counts.
@@ -212,27 +258,33 @@ const PROBE_ADAPTERS = [
         block: findings => [
             '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:',
+            'the spec forbids modifying, each tagged with the weight of the constraint',
+            'that forbids it:',
             ...findings.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.',
+            ...(anyBinding(findings) ?
+                [
+                    'Read the exact constraint wording in the spec. Unless that wording itself',
+                    'states an exception that covers this change, a BINDING one 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.'
+                ]
+                : [
+                    'Every one of these is ADVISORY — automation, not a person, wrote the',
+                    'constraint that forbids it (rule 4b). Report each in your findings, and do',
+                    'NOT fail the work for it unless an ACCEPTANCE criterion also fails. The',
+                    'acceptance criteria are the bar here.'
+                ]),
             ''
         ],
         rule: [
-            '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.'
+            ...renderConstraintPolicy('4b.'),
+            '   Applying that to a PROHIBITION ("Do NOT modify X", "MUST NOT touch Y"): check the',
+            "   task's own diff against the spec's prohibitions — a forbidden file can be",
+            '   modified without any test noticing. For a BINDING one, 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.'
         ]
     }),
     /**
@@ -485,6 +537,43 @@ const PROBE_ADAPTERS = [
             'fails where the test passes, report FAIL and name the wiring seam.',
             ''
         ]
+    }),
+    /**
+     * Deterministic suppression-widening probe (see suppression-probe.ts): checker
+     * suppressions this task NET added, per file. The child cannot find these by
+     * running the checks — a suppression's whole purpose is that the check goes
+     * quiet — so the count has to arrive as a finding (0034 shipped sixteen and
+     * every gate reported success).
+     */
+    probeAdapter({
+        key: 'suppressionWidening',
+        stage: 'suppression probe',
+        empty: [],
+        findings: suppressionVerifyFindings,
+        ruleId: '4i',
+        block: findings => [
+            'SUPPRESSION WIDENING NOTICE (deterministic, computed by the orchestrator by',
+            "counting each suppression pattern's added minus removed lines in this task's",
+            'diff): this task added checker suppressions:',
+            ...findings.map(f => `- ${f}`),
+            'A suppression makes a checker SILENT, not satisfied. You cannot discover this',
+            "by running the project's checks — they are green because of these lines. For",
+            'each, read the surrounding code and decide whether the underlying defect was',
+            'FIXED or merely silenced, and whether the spec asked for the suppression at',
+            'all (rule 4i).',
+            ''
+        ],
+        rule: [
+            '4i. A SILENCED CHECKER IS NOT A SATISFIED ONE — when the SUPPRESSION WIDENING',
+            '   NOTICE above names added suppressions (`@ts-expect-error`, `eslint-disable`,',
+            '   `# noqa`, `//nolint`, `#[allow(…)]`, `as unknown as` …), the green check they',
+            '   produce is not evidence about the code under them. Judge each one: a',
+            '   suppression the spec explicitly asked for, or one narrowly scoped to a',
+            '   documented third-party defect the task cannot fix, is fine and you say so. A',
+            '   suppression that exists so a checker would stop reporting a defect this task',
+            '   introduced is that defect, still shipped — verdict FAIL naming the file and the',
+            '   finding it hides. A blanket file-level disable is never the narrow case.'
+        ]
     })
 ];
 /**
@@ -493,6 +582,43 @@ const PROBE_ADAPTERS = [
  * checked against the table rather than against a hand-kept list.
  */
 export const BOUND_PROBE_KEYS = PROBE_ADAPTERS.filter(a => a.bound).map(a => a.key);
+/**
+ * Rule 1 in its two states, picked by whether the evidence row supplied anything.
+ *
+ * A child told "run the project's own commands" directly under a block listing
+ * those commands' results runs them again — the instruction and the notice
+ * contradict each other, and the instruction is the numbered one. So the rule
+ * moves with the evidence rather than sitting beside it. Without evidence (no
+ * verified tooling, or a caller that binds no probes) the original obligation is
+ * the only correct one.
+ */
+const RULE_1_RUN_THEM = [
+    "1. Run the project's OWN commands — the verbatim scripts / targets / binaries it",
+    '   ships (package.json scripts, Makefile targets, the command the spec names) —',
+    '   exactly as written, in the workspace as you found it. Judge the artifact or',
+    "   output they actually PRODUCE. The project's own command and its real output are",
+    "   the bar; also run the spec's VERIFY block, but it does not override that bar."
+];
+const RULE_1_ALREADY_RUN = [
+    "1. The project's OWN check and build commands have ALREADY BEEN RUN against this",
+    '   exact tree, and the EVIDENCE block above names each one, its real exit code and',
+    '   the file holding its complete output. READ THOSE FILES — that output is the bar,',
+    '   and a command reported there does not need running again. Re-run only a TARGETED',
+    '   SUBSET: a single test file, or one command whose reported result you have a',
+    '   concrete reason to doubt (its output contradicts itself, or it never ran).',
+    "   Judge the artifact or output the commands actually PRODUCED. Also run the spec's",
+    '   VERIFY block, and any command the evidence does not cover, but neither overrides',
+    '   that bar.'
+];
+/**
+ * The spec as a VALUE, with each constraint's `[from:]` tag resolved against the
+ * task's own Q&A record. Shared by the verify prompt and the resolution judge, so
+ * one constraint cannot carry two weights.
+ */
+export function specValue(spec, qaRecord) {
+    const kinds = qaRecord === undefined ? [] : qaKindsFromRecord(qaRecord);
+    return parseSpec(spec, n => kinds[n - 1] ?? null);
+}
 /**
  * Build the verification child's prompt. Kept pure so the wording is unit-tested
  * without spawning pi. The contract: run the spec's own verification in the real
@@ -503,7 +629,7 @@ export const BOUND_PROBE_KEYS = PROBE_ADAPTERS.filter(a => a.bound).map(a => a.k
  * block — the probes are independently optional.
  */
 export function buildVerifyPrompt(spec, findings = {}, context = {}) {
-    const { envNotes, contracts } = context;
+    const { envNotes, envRunId, contracts } = context;
     // NOTICE BLOCKS in table order; RULES sorted by their hand-assigned number.
     const noticeBlocks = PROBE_ADAPTERS.flatMap(adapter => {
         const lines = findings[adapter.key];
@@ -514,8 +640,16 @@ export function buildVerifyPrompt(spec, findings = {}, context = {}) {
         : a.ruleId > b.ruleId ? 1
             : 0)
         .flatMap(a => [...(a.rule ?? []), '']);
-    const envBlock = envNotes && envNotes.trim().length > 0 ? [buildEnvNotesBlock(envNotes)] : [];
+    const envBlock = envNotes && envNotes.trim().length > 0 ? [buildEnvNotesBlock(envNotes, envRunId)] : [];
     const contractsBlock = contracts && contracts.trim().length > 0 ? [buildContractsVerifyBlock(contracts)] : [];
+    const weights = annotateConstraints(specValue(spec, context.qaRecord).constraints);
+    const weightsBlock = weights === null ?
+        []
+        : [
+            "THE SPEC'S CONSTRAINTS, BY WEIGHT (rule 4b says what each weight is worth):",
+            weights,
+            ''
+        ];
     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"',
@@ -531,15 +665,12 @@ export function buildVerifyPrompt(spec, findings = {}, context = {}) {
         '',
         ...envBlock,
         ...contractsBlock,
+        ...weightsBlock,
         ...noticeBlocks,
         'How to verify — verify the REAL, shipped deliverable exactly as an unaided fresh',
         'checkout (or CI run) would experience it:',
         '',
-        "1. Run the project's OWN commands — the verbatim scripts / targets / binaries it",
-        '   ships (package.json scripts, Makefile targets, the command the spec names) —',
-        '   exactly as written, in the workspace as you found it. Judge the artifact or',
-        "   output they actually PRODUCE. The project's own command and its real output are",
-        "   the bar; also run the spec's VERIFY block, but it does not override that bar.",
+        ...((findings.evidence?.length ?? 0) > 0 ? RULE_1_ALREADY_RUN : RULE_1_RUN_THEM),
         '',
         '2. Do NOT prepare, repair, reconfigure, or stand in for the run to make a check',
         '   pass. Concretely, to reach a green result you must NOT: set or export an',
@@ -764,15 +895,28 @@ export async function runWorkVerification(deps) {
             // progress reporting must never break the gate
         }
     };
+    // DIFFERENTIAL, not absolute. A red check is this task's FAIL only when the
+    // baseline says it was not already red the same way; otherwise it is stated to
+    // the child as a probe row and recorded as inherited debt, and the pass
+    // continues — the short-circuit is what used to throw away every deterministic
+    // finding about the task's OWN work.
+    const pre = { repoHealth: [] };
+    let inheritedHealth;
     if (deps.repoHealth) {
         stage('repo health');
         const h = await deps.repoHealth();
         if (!h.ok) {
-            return { ok: false, failClass: 'repo-health', reason: `repo health: ${h.reason}` };
+            const baseline = deps.healthBaseline ? await deps.healthBaseline() : null;
+            if (classifyHealthDelta(baseline?.outcome ?? null, h) === 'regressed') {
+                return { ok: false, failClass: 'repo-health', reason: `repo health: ${h.reason}` };
+            }
+            pre.repoHealth = inheritedHealthFindings(h);
+            inheritedHealth = `repo health: ${h.reason} — already failing before this task`;
         }
     }
+    const inherited = inheritedHealth === undefined ? {} : { inheritedHealth };
     if (!deps.spec || deps.spec.trim().length === 0) {
-        return { ok: true, reason: 'no spec to verify' };
+        return { ok: true, reason: 'no spec to verify', ...inherited };
     }
     // Every deterministic probe, one table row each (see PROBE_ADAPTERS): the row
     // knows which dep it reads, what it degrades to, and which notice block its
@@ -781,10 +925,17 @@ export async function runWorkVerification(deps) {
     const findings = {};
     const rawResults = new Map();
     for (const adapter of PROBE_ADAPTERS) {
-        const result = await adapter.run(deps, stage);
+        const result = await adapter.run(deps, stage, pre);
         findings[adapter.key] = result.findings;
         rawResults.set(adapter.key, result.raw);
     }
+    // Everything the gate now knows deterministically, carried on the outcome so
+    // an AUTOFIX re-run is TOLD it (fix-context.ts) rather than re-deriving it —
+    // which is what a re-run told only "lint fails" does by widening suppressions.
+    // Only channels that FOUND something: a bag of empty arrays is not knowledge,
+    // and every consumer would have to filter it back out.
+    const found = Object.fromEntries(Object.entries(findings).filter(([, lines]) => lines.length > 0));
+    const probed = Object.keys(found).length === 0 ? {} : { probes: found };
     // The one probe whose RAW value is needed beyond the prompt: cross-task deletion
     // findings ride on a FAIL outcome (structured) so an ACCEPT can record them as
     // durable debts. The row's `empty` is `[]`, so this is always an array.
@@ -818,7 +969,12 @@ export async function runWorkVerification(deps) {
     for (let attempt = 1;; attempt++) {
         let text;
         try {
-            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings, { envNotes, contracts }), deps.signal);
+            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings, {
+                envNotes,
+                ...(deps.qaRecord === undefined ? {} : { qaRecord: deps.qaRecord }),
+                ...(deps.envNotes?.runId === undefined ? {} : { envRunId: deps.envNotes.runId }),
+                contracts
+            }), deps.signal);
         }
         catch (err) {
             if (err instanceof Error && err.message === USER_CANCELLED)
@@ -830,7 +986,9 @@ export async function runWorkVerification(deps) {
             return {
                 ok: false,
                 failClass: 'harness-fault',
-                reason: `${VERIFY_FAIL_PREFIX['harness-fault']} ${msg}`
+                reason: `${VERIFY_FAIL_PREFIX['harness-fault']} ${msg}`,
+                ...inherited,
+                ...probed
             };
         }
         // Capture the environment facts the child shared — regardless of verdict
@@ -853,13 +1011,18 @@ export async function runWorkVerification(deps) {
                 continue;
             return {
                 ok: false,
+                // The child judged a tree it had itself changed — the FAULT is the
+                // pass, not the work, so no implementation re-run can move it.
+                failClass: 'harness-fault',
                 reason: 'verify child mutated repo state and its verdict was discarded '
-                    + `(state restored: ${mutation.detail.slice(0, 200)})`
+                    + `(state restored: ${mutation.detail.slice(0, 200)})`,
+                ...inherited,
+                ...probed
             };
         }
         const verdict = parseVerifyVerdict(text);
         if (verdict.pass)
-            return { ok: true };
+            return { ok: true, ...inherited, ...probed };
         if (verdict.detail === 'no verdict emitted' && attempt === 1)
             continue;
         // Structured cross-task deletion findings ride on every FAIL outcome: if the
@@ -875,14 +1038,18 @@ export async function runWorkVerification(deps) {
                 unobserved: true,
                 failClass: 'unobserved',
                 reason: `work unobserved: ${verdict.detail}`,
-                ...deletions
+                ...deletions,
+                ...inherited,
+                ...probed
             };
         }
         return {
             ok: false,
             failClass: 'model-verdict',
             reason: `work did not verify: ${verdict.detail}${verdict.detail === 'no verdict emitted' ? ' (after verify retry)' : ''}`,
-            ...deletions
+            ...deletions,
+            ...inherited,
+            ...probed
         };
     }
 }

package/dist/task/yolo.d.ts

@@ -1,5 +1,4 @@
 import type { AutoAnswer } from './parsers.js';
-import type { ResolutionChoice } from './verify-resolution.js';
 import type { FinalGateChoice } from './final-gate-fix.js';
 /**
  * Visible provenance marker on the artifacts an auto-pick writes: gate trail lines
@@ -52,18 +51,6 @@ export declare function yoloPickAnswer(enabled: boolean, opts: {
  * pattern-matching the answer text.
  */
 export declare function yoloPickAutoAnswer(enabled: boolean, auto: AutoAnswer): YoloPick;
-/**
- * The verify-FAIL picker policy: ACCEPT (and write a debt), never AUTOFIX.
- *
- * Not a preference — a bound. task-gates.ts consults this only after its own
- * unattended paths are exhausted: `autoFixNow` has run AUTOFIX up to
- * MAX_AUTO_AUTOFIX times while the research recommended it, and the YOLO rescue has
- * spent its one attempt on an ACCEPT recommendation with an untouched budget.
- * Answering AUTOFIX here would restart that budget from the very site that proves
- * it ran out. So YOLO takes the terminal option and records the defect under the
- * `'yolo-accepted'` debt origin, which a human decision never produces.
- */
-export declare function yoloVerifyResolution(enabled: boolean): ResolutionChoice | null;
 /**
  * The final-integration-gate policy: keep autofixing WHILE the picker still offers
  * that card — run-final-gate.ts withdraws it from `options` after

package/dist/task/yolo.js

@@ -9,13 +9,15 @@
  * WHY PER-SITE, NOT ONE HOOK (the trap this module exists to avoid): the single
  * interactive choke point is SessionUI.ask() (remote/bridge.ts) — auto-picking
  * "index 0" inside it would be one tiny patch, and it would be wrong. One way the
- * verify-FAIL picker is reached is after MAX_AUTO_AUTOFIX unattended autofix
- * attempts have all failed, and it STILL tints AUTOFIX as recommended, because the
- * research still recommends it. A central hook would pick AUTOFIX forever and
- * defeat the exact cap that exists to break a non-converging loop. So every site
- * decides for itself, BEFORE ask() is called — which also means the prompt
- * notification (bridge.ts holds exactly one pushNotify, inside ask()) is
- * suppressed structurally, with zero suppression code.
+ * verify-FAIL picker is reached is after every unattended autofix attempt has
+ * failed, and it STILL tints AUTOFIX as recommended, because the research still
+ * recommends it. A central hook would pick AUTOFIX forever and defeat the exact
+ * cap that exists to break a non-converging loop. So every site decides for
+ * itself, BEFORE ask() is called — which also means the prompt notification
+ * (bridge.ts holds exactly one pushNotify, inside ask()) is suppressed
+ * structurally, with zero suppression code. The verify gate's own site is
+ * gate-resolution.ts's decision table, which reads {@link isYoloMode} as its
+ * `unattended` input.
  *
  * Guard direction (repo constraint): an auto-pick may cost time, never work.
  * Anything this module cannot stand behind — no recommendation to take, an answer
@@ -85,20 +87,6 @@ export function yoloPickAutoAnswer(enabled, auto) {
         })
     });
 }
-/**
- * The verify-FAIL picker policy: ACCEPT (and write a debt), never AUTOFIX.
- *
- * Not a preference — a bound. task-gates.ts consults this only after its own
- * unattended paths are exhausted: `autoFixNow` has run AUTOFIX up to
- * MAX_AUTO_AUTOFIX times while the research recommended it, and the YOLO rescue has
- * spent its one attempt on an ACCEPT recommendation with an untouched budget.
- * Answering AUTOFIX here would restart that budget from the very site that proves
- * it ran out. So YOLO takes the terminal option and records the defect under the
- * `'yolo-accepted'` debt origin, which a human decision never produces.
- */
-export function yoloVerifyResolution(enabled) {
-    return enabled ? { action: 'accept' } : null;
-}
 /**
  * The final-integration-gate policy: keep autofixing WHILE the picker still offers
  * that card — run-final-gate.ts withdraws it from `options` after

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

@@ -399,6 +399,12 @@ export interface RunWorkerResult {
  */
 interface RestartState {
     loopHit?: LoopHit;
+    /**
+     * The killed attempt's read-set (loop-detector.ts). A runaway kill discards
+     * every byte the child read and nothing else records what that was, so it is
+     * what the loop and stall hints carry in place of answer text.
+     */
+    visited: readonly string[];
     commandKill?: CommandKill;
     streamStalled?: {
         idleMs: number;
@@ -462,5 +468,19 @@ interface RestartRule {
     /** Backoff before re-spawning, in ms. Only the connection rule waits. */
     backoffMs?: (s: RestartState) => number;
 }
+/**
+ * The restart ladder, in precedence order. FIRST MATCH WINS.
+ *
+ * Read the `!loopHit` guards as "a loop kill outranks me even when it has no
+ * budget left". They are not redundant with row order: when a loop is detected
+ * but the shared budget is spent, row 1 declines, and without those guards row 2
+ * or 4 would then restart the same runaway child under a hint that does not
+ * describe why it died.
+ *
+ * The whole ritual — check the budget, set the hint, spend the counters, record
+ * and announce the discarded attempt, sleep, re-spawn — belongs to the loop in
+ * `runWorker`, so a new failure mode is one row here and cannot be added without
+ * becoming visible in `restarts`.
+ */
 export declare const RESTART_RULES: readonly RestartRule[];
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;

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

@@ -102,7 +102,9 @@ const CARRY_FORWARD_LIMIT = 24_000;
  * `worker-timeout` and `connection-error` all discard work the model genuinely
  * did. A loop kill and a leaked tool call do not — the first is by definition the
  * same call repeated, the second is malformed protocol text, and replaying either
- * would feed the failure back to itself.
+ * would feed the failure back to itself. A loop kill also fires from the tool-call
+ * hook, before any answer text streams, so there is nothing to carry; what it
+ * hands the re-spawn is the READ-SET instead (`RestartState.visited`).
  */
 const CARRY_FORWARD_REASONS = CARRY_FORWARD_IDS;
 /**
@@ -245,6 +247,15 @@ absoluteCeilingMs) {
         }
     };
 }
+/**
+ * A stall hit counts a streak or a byte total, not calls in a window, so printing
+ * the loop shape would misname why the attempt died.
+ */
+function loopDetail(hit) {
+    if (hit.stall)
+        return `${hit.call.name} ${hit.stall} ×${hit.count}`;
+    return `${hit.call.name} ×${hit.count}${hit.windowSize === undefined ? '' : `/${hit.windowSize}`}`;
+}
 /**
  * The restart ladder, in precedence order. FIRST MATCH WINS.
  *
@@ -259,15 +270,6 @@ absoluteCeilingMs) {
  * `runWorker`, so a new failure mode is one row here and cannot be added without
  * becoming visible in `restarts`.
  */
-/**
- * A stall hit carries no meaningful windowSize (rule 1 sets it to 0), so
- * printing the loop shape would misname why the attempt died.
- */
-function loopDetail(hit) {
-    return hit.stall ?
-        `${hit.call.name} ${hit.stall} ×${hit.count}`
-        : `${hit.call.name} ×${hit.count}/${hit.windowSize}`;
-}
 export const RESTART_RULES = [
     {
         // A loop-kill is restarted with a hint naming the offending call so the
@@ -276,7 +278,9 @@ export const RESTART_RULES = [
         detect: s => s.loopHit && s.restartBudgetSpent < MAX_LOOP_RESTARTS ?
             { detail: loopDetail(s.loopHit) }
             : null,
-        hint: s => s.loopHit.stall ? formatStallHint(s.loopHit.stall) : formatLoopHint(s.loopHit),
+        hint: s => s.loopHit.stall ?
+            formatStallHint(s.loopHit.stall, s.visited)
+            : formatLoopHint(s.loopHit, s.visited),
         counters: { shared: true }
     },
     {
@@ -599,6 +603,7 @@ export async function runWorker(input) {
         // cancel: a user who pressed ESC between attempts must not buy a spawn.
         const state = {
             ...(loopHit ? { loopHit } : {}),
+            visited: loopDetector?.visited() ?? [],
             ...(commandKill ? { commandKill } : {}),
             ...(streamStalled ? { streamStalled } : {}),
             stalled,

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

@@ -96,12 +96,13 @@ export declare function excerptFabricated(check: {
  * the test imports the rule it is checking.
  */
 export declare function docsCacheable(d: Pick<DocsDetails, 'typeOnly' | 'excerptVerified' | 'excerptFabricated' | 'abstained'>): boolean;
-/** The docs cache key: a package's answer is per (module, question), with the question
- *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns
- *  null for the project-source `.` lookup, which is never cached — the working tree
- *  mutates as tasks implement.
+/** The docs cache key: a package's answer is per (module, question), the question
+ *  reduced to its sorted distinctive tokens so phrasing variants share one entry and a
+ *  narrower question can be answered from a wider one's digest (research-cache.ts).
+ *  Returns null for the project-source `.` lookup, which is never cached — the working
+ *  tree mutates as tasks implement.
  *
- *  The ecosystem joins the key only when the caller named one, so the keys of every
+ *  The ecosystem joins the key only when the caller named one, so the subjects of every
  *  call that lets the manifest decide are the ones they always were. */
 export declare function docsCacheKey(params: {
     module: string;

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

@@ -13,7 +13,7 @@ import { npmVersionLookup as defaultNpmVersionLookup, formatNpmVersionSection }
 import { childFailureReason, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
 import { isTypeOnlyAnswer } from '../task/type-only-answer.js';
 import { logDocsAnswer } from './typeonly-log.js';
-import { normalizeQuery } from './research-cache.js';
+import { normalizeQuery, queryTokenKey } from './research-cache.js';
 import { projectDocsRaw } from './docs-project.js';
 import { projectDocsBudget, projectDocsBudgetExhausted } from '../task/research-fanout-budget.js';
 import { isAbstention } from './abstention.js';
@@ -433,18 +433,19 @@ export function docsCacheable(d) {
     // real answer and memoised the dead end for the whole run.
     return d.typeOnly !== true && d.excerptFabricated !== true && d.abstained !== true;
 }
-/** The docs cache key: a package's answer is per (module, question), with the question
- *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns
- *  null for the project-source `.` lookup, which is never cached — the working tree
- *  mutates as tasks implement.
+/** The docs cache key: a package's answer is per (module, question), the question
+ *  reduced to its sorted distinctive tokens so phrasing variants share one entry and a
+ *  narrower question can be answered from a wider one's digest (research-cache.ts).
+ *  Returns null for the project-source `.` lookup, which is never cached — the working
+ *  tree mutates as tasks implement.
  *
- *  The ecosystem joins the key only when the caller named one, so the keys of every
+ *  The ecosystem joins the key only when the caller named one, so the subjects of every
  *  call that lets the manifest decide are the ones they always were. */
 export function docsCacheKey(params) {
     if (params.module === '.')
         return null;
     const scope = params.ecosystem ? `${params.ecosystem}::` : '';
-    return `${scope}${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`;
+    return `${scope}${normalizeQuery(params.module)}\u0000${queryTokenKey(params.query)}`;
 }
 /** Package provenance for per-entry resume invalidation: the package ROOT of the
  *  specifier (`hono/client` → `hono`), and undefined for the project-source `.`.