@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/env-notes.js

@@ -42,42 +42,44 @@ const MAX_NOTES = 40;
 /** A single fact is one line; anything longer is prose, not a fact. */
 const MAX_NOTE_LENGTH = 240;
 /**
- * Field separator between a fact and its origin in the stored file. A tab never
- * occurs in a one-line fact (facts are prose), so it round-trips cleanly and any
- * stray tab in an emitted fact is normalised to a space before storage.
- */
-const ORIGIN_SEP = '\t';
-/**
- * Parse the stored file into fact+origin records. A line with no separator parses
- * with an empty origin rather than being dropped, so a cache written before
- * provenance existed still reads — and `buildEnvNotesBlock` renders those as
- * "origin unrecorded" instead of silently claiming an author.
+ * Field separator between a note's fields in the stored file. A tab never occurs
+ * in a one-line fact (facts are prose), so it round-trips cleanly and any stray
+ * tab in an emitted fact is normalised to a space before storage.
  */
+const FIELD_SEP = '\t';
+/** Stored line: `fact TAB origin TAB runId TAB subject TAB resolvedBy`, where every
+ *  field after the fact may be absent — a one- or two-field line is what earlier
+ *  versions wrote, and it still reads. */
 export function parseEnvNotes(raw) {
     const out = [];
     for (const line of raw.split('\n')) {
         const t = line.trim();
         if (t.length === 0)
             continue;
-        const i = t.indexOf(ORIGIN_SEP);
-        if (i === -1)
-            out.push({ fact: t, origin: '' });
-        else
-            out.push({ fact: t.slice(0, i).trim(), origin: t.slice(i + 1).trim() });
+        const [fact, origin, runId, subject, resolvedBy] = t.split(FIELD_SEP).map(f => f.trim());
+        out.push({
+            fact,
+            origin: origin ?? '',
+            runId: runId ?? '',
+            // A legacy line carries no subject, so it gets the one the host would
+            // derive for it today — which is what makes the old file dedupe too.
+            subject: subject || deriveSubject(fact),
+            ...(resolvedBy ? { resolvedBy } : {})
+        });
     }
     return out;
 }
 function serializeNote(n) {
-    return n.origin ? `${n.fact}${ORIGIN_SEP}${n.origin}` : n.fact;
+    return [n.fact, n.origin, n.runId, n.subject, n.resolvedBy ?? ''].join(FIELD_SEP).trimEnd();
 }
-/** Keyed on the fact alone (case-insensitive): a fact already present keeps its
- *  ORIGINAL origin — provenance traces to who first established it. */
+/** Keyed on the SUBJECT (case-insensitive), latest statement wins. */
 const ledger = makeLedger({
     file: ENV_NOTES_FILE,
     max: MAX_NOTES,
-    key: n => n.fact.toLowerCase(),
+    key: n => n.subject.toLowerCase(),
     serialize: serializeNote,
-    parse: parseEnvNotes
+    parse: parseEnvNotes,
+    conflict: 'replace'
 });
 export function envNotesFile(cwd) {
     return ledger.path(cwd);
@@ -86,24 +88,91 @@ export function envNotesFile(cwd) {
 export async function readEnvNotes(cwd) {
     return ledger.readRaw(cwd);
 }
+/** Leading words a subject may be built from: the generic ones say nothing about
+ *  which fact this is. */
+const SUBJECT_STOPWORDS = new Set([
+    'the',
+    'this',
+    'that',
+    'these',
+    'those',
+    'and',
+    'but',
+    'for',
+    'from',
+    'with',
+    'current',
+    'still',
+    'now',
+    'not',
+    'are',
+    'was',
+    'were'
+]);
+function subjectWords(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(t => t.length > 2 && !SUBJECT_STOPWORDS.has(t));
+}
+/**
+ * The subject of a fact the child did not name one for.
+ *
+ * A fact identifies what it is ABOUT by naming it first, and three rungs cover
+ * what an environment fact names: the SERVICE it reached (a URL authority), the
+ * COMMAND it ran (the first code span, by its basename so a tool named by path is
+ * the same tool), or — for the rest — its leading words.
+ *
+ * Measured against the 40-note cache a real 21-task run left behind, where 34
+ * slots restate two facts: it resolves them to nine subjects, so the twelfth
+ * re-measurement of one database replaces the eleventh instead of joining it.
+ */
+export function deriveSubject(fact) {
+    const url = /\b[a-z][a-z0-9+.-]*:\/\/(?:[^\s/@`]*@)?([^\s/`,;)]+)/i.exec(fact);
+    if (url)
+        return url[1].toLowerCase();
+    const code = /`([^`]+)`/.exec(fact);
+    if (code) {
+        // A leading `VAR=value` is the environment of the command, not the command.
+        const word = code[1]
+            .trim()
+            .split(/\s+/)
+            .find(w => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w));
+        if (word !== undefined && word.length > 0) {
+            const bare = /^\.{0,2}\//.test(word) ? (word.split('/').pop() ?? word) : word;
+            if (bare.length > 0)
+                return bare.toLowerCase();
+        }
+    }
+    return subjectWords(fact).slice(0, 2).join(' ');
+}
 /**
- * Pull `ENV-NOTE: <fact>` lines out of a child's answer text: trimmed,
- * deduplicated case-insensitively, and dropped when empty or over
- * MAX_NOTE_LENGTH. Run: a `VERDICT:` line and even a near-miss `ENV-NOTES:` line
+ * Pull the facts out of a child's answer text. Three forms are accepted:
+ * `ENV-NOTE[<subject>]: <fact>` (what the instruction asks for), the bare
+ * `ENV-NOTE: <fact>` whose subject the host derives, and
+ * `ENV-NOTE-RESOLVED[<subject>]: <what was observed>`, which retracts a recorded
+ * claim. Facts are trimmed, deduped case-insensitively, and dropped when empty or
+ * over MAX_NOTE_LENGTH. A `VERDICT:` line and even a near-miss `ENV-NOTES:` line
  * match nothing, so a verdict cannot leak into the fact cache.
  */
 export function extractEnvNotes(text) {
     const notes = [];
     const seen = new Set();
-    for (const m of text.matchAll(/^[ \t]*ENV-NOTE:[ \t]*(.+)$/gm)) {
-        const note = m[1].trim();
-        if (note.length === 0 || note.length > MAX_NOTE_LENGTH)
+    const line = /^[ \t]*ENV-NOTE(-RESOLVED)?(?:\[([^\]\n]*)\])?:[ \t]*(.+)$/gm;
+    for (const m of text.matchAll(line)) {
+        const fact = m[3].trim();
+        if (fact.length === 0 || fact.length > MAX_NOTE_LENGTH)
             continue;
-        const key = note.toLowerCase();
+        const key = fact.toLowerCase();
         if (seen.has(key))
             continue;
         seen.add(key);
-        notes.push(note);
+        const named = (m[2] ?? '').trim();
+        notes.push({
+            subject: named.length > 0 ? named : deriveSubject(fact),
+            fact,
+            ...(m[1] ? { resolved: true } : {})
+        });
     }
     return notes;
 }
@@ -140,50 +209,77 @@ export function isExcuseNote(fact) {
     return EXCUSE_PATTERNS.some(re => re.test(fact));
 }
 /**
- * Append newly discovered facts to the cache, deduplicated against what is
- * already there (case-insensitive fact match), keeping the newest MAX_NOTES.
- * Each new fact is stamped with the `origin` task that recorded it; a fact already
- * present keeps its ORIGINAL origin, so provenance traces to whoever first
- * established it. Confirmed by re-appending the same fact under a different task:
- * one entry survives, still carrying the first writer.
+ * Store what a child shared, keyed by SUBJECT: a fresh statement about a subject
+ * REPLACES the one the cache held, so the newest measurement is the one later
+ * children read and a stale fact cannot outlive its correction. Each note is
+ * stamped with the `origin` task and the `runId` that recorded it — the run is
+ * what the prompt block scopes on, the task is the provenance a reader is told to
+ * re-validate against.
+ *
+ * A retraction stores the observation that closed the subject and marks it
+ * RESOLVED, so it stays as an audit line without being carried into another
+ * child's prompt.
  *
  * Tabs in an emitted fact are normalised to spaces before storage, which is what
  * keeps the separator unambiguous. The cap holds too — sixty further facts leave
  * MAX_NOTES stored. Failures are swallowed: the cache is a sharpener, never a
  * blocker.
  */
-export async function appendEnvNotes(cwd, notes, origin = '') {
+export async function appendEnvNotes(cwd, notes, origin = '', runId = '') {
     const fresh = [];
     for (const note of notes) {
-        const fact = note.trim().replace(/\t/g, ' ');
-        if (fact.length === 0)
+        const fact = note.fact.trim().replace(/\t/g, ' ');
+        const subject = note.subject.trim().replace(/\t/g, ' ');
+        if (fact.length === 0 || subject.length === 0)
             continue;
-        fresh.push({ fact, origin: origin.trim() });
+        fresh.push({
+            fact,
+            origin: origin.trim(),
+            runId: runId.trim(),
+            subject,
+            // The field is the resolved FLAG as well as its provenance, so an
+            // unattributed retraction still needs a value to survive the round-trip.
+            ...(note.resolved ? { resolvedBy: origin.trim() || 'unrecorded' } : {})
+        });
     }
     await ledger.append(cwd, fresh);
 }
+function noteLine(n) {
+    const origin = n.origin ? ` — recorded by ${n.origin}` : ' — origin unrecorded';
+    const flag = isExcuseNote(n.fact) ?
+        '  [EXCUSE-CLASS — re-validate in the CURRENT tree before citing this to wave off any failure]'
+        : '';
+    return `- ${n.fact}${origin}${flag}`;
+}
 /**
  * The prompt block a gate child receives when notes exist. Two things are
  * load-bearing: the no-waiver caveat (facts save re-discovery time but grant no
  * license to prepare/repair) and the trust discipline (a note is second-hand
  * until re-validated; an EXCUSE-CLASS note may not wave off a failure without a
  * live re-check; a grep of a generated artifact is not evidence of absence).
+ *
+ * THIS RUN leads. A fact measured by a sibling task minutes ago describes the tree
+ * the child is standing in; one from a run last week describes a tree that has
+ * moved since, and reading the two as one list is how a stale fact gets cited as
+ * current. Resolved subjects are dropped from both lists: a retracted claim is
+ * exactly the thing that must not be carried forward. `runId` '' (a cache written
+ * before runs were stamped) reads as an earlier run.
  */
-export function buildEnvNotesBlock(raw) {
-    const notes = parseEnvNotes(raw);
+export function buildEnvNotesBlock(raw, runId = '') {
+    const notes = parseEnvNotes(raw).filter(n => n.resolvedBy === undefined);
     if (notes.length === 0)
         return '';
-    const lines = notes.map(n => {
-        const origin = n.origin ? ` — recorded by ${n.origin}` : ' — origin unrecorded';
-        const flag = isExcuseNote(n.fact) ?
-            '  [EXCUSE-CLASS — re-validate in the CURRENT tree before citing this to wave off any failure]'
-            : '';
-        return `- ${n.fact}${origin}${flag}`;
-    });
+    const inRun = (n) => runId.length > 0 && n.runId === runId;
+    const mine = notes.filter(inRun);
+    const earlier = notes.filter(n => !inRun(n));
+    const earlierBlock = earlier.length === 0 ? []
+        : mine.length === 0 ? earlier.map(noteLine)
+            : ['', 'From EARLIER runs (an older tree — trust these less):', ...earlier.map(noteLine)];
     return [
         'KNOWN ENVIRONMENT FACTS — recorded by earlier verification passes in this run',
         '(second-hand, may be stale or WRONG):',
-        ...lines,
+        ...mine.map(noteLine),
+        ...earlierBlock,
         '',
         'These facts only save you re-discovery time (where credentials/config live, which',
         'tools are installed, which services are reachable). They are NOT a license to',
@@ -216,8 +312,14 @@ export const ENV_NOTE_EMIT_INSTRUCTION = [
     'ENVIRONMENT FACTS — share what you discover: when you establish a durable fact about',
     'THIS MACHINE or the project environment (a service reachable/absent at an address, where',
     'credentials/config live, a tool or runtime present/missing and its version), emit a line',
-    '  ENV-NOTE: <one-line fact>',
-    'anywhere in your answer, one per fact. A fact is something you OBSERVED to be true of the',
+    '  ENV-NOTE[<subject>]: <one-line fact>',
+    'anywhere in your answer, one per fact. <subject> names WHAT the fact is about in a word or',
+    'two — the service, the tool, the command (`postgres:5432`, `bun test`, `docker compose`).',
+    'It is the cache key: a fact you emit under a subject REPLACES the one recorded for it, so',
+    'a re-measurement corrects the record instead of stacking another copy beside it. If a fact',
+    'listed above turns out NOT to be true any more, retract it with',
+    '  ENV-NOTE-RESOLVED[<subject>]: <what you observed instead>',
+    'A fact is something you OBSERVED to be true of the',
     'machine or environment — never a task verdict, never spec content, never a judgment about',
     'the code. In particular do NOT record an absence you inferred from grepping a built or',
     'minified artifact (identifiers there are mangled — a zero-hit grep proves nothing), and',

package/dist/task/external-context.js

@@ -23,6 +23,8 @@
  * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
 import { chooseEcosystem, declaredDepNames, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
+import { queryTokenKey } from '../workers/research-cache.js';
+import { cachedWorkerCall, workerAnswer, workerUnavailable } from '../workers/shared.js';
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
 import { formatNpmVersionSection, npmVersionLookup } from '../workers/npm-version.js';
@@ -121,6 +123,21 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
         return '';
     return `EXTERNAL CONTEXT\n${sections.join('\n\n')}\n\n`;
 }
+/**
+ * One enrichment lookup, through the per-run research cache (workers/shared.ts).
+ *
+ * A null result is a lookup that produced no answer — a refused ecosystem, a dead
+ * registry, a page that would not fetch — and is never stored, so a transient
+ * failure costs one task's block rather than the whole run's. The cached value is
+ * the RESULT, not rendered text: the block assembly below formats it.
+ */
+async function cached(cwd, tool, key, run) {
+    const { details } = await cachedWorkerCall(cwd, tool, key, async () => {
+        const value = await run();
+        return value === null ? workerUnavailable('', value, 'no-answer') : workerAnswer('', value);
+    });
+    return details;
+}
 /**
  * The RESEARCH-phase binding: raw workers, no caps, live versions for every
  * named dep, truncated bodies, timed, and short-circuited when there is nothing
@@ -147,7 +164,7 @@ export async function gatherExternalContext(refined, deps) {
         const info = await npmVersionFn(pkg, { signal: deps.signal });
         return info ? { info, label: 'npm' } : null;
     };
-    const versionLookup = async (pkg) => {
+    const liveVersion = async (pkg) => {
         const choice = chooseEcosystem({
             cwd: deps.cwd,
             declaresPackage: p => p.declaredRange(p.parentPackage(pkg), deps.cwd) !== null,
@@ -171,8 +188,11 @@ export async function gatherExternalContext(refined, deps) {
         const info = await choice.profile.latest(pkg, io);
         return info ? { info, label: choice.profile.registryLabel } : null;
     };
+    // A registry round-trip per declared dependency, per task. The answer does not
+    // move within a run, so the first task of the run pays for it.
+    const versionLookup = (pkg) => cached(deps.cwd, 'enrichment:version', pkg, () => liveVersion(pkg));
     return buildExternalContext(refined, deps, {
-        docs: async (pkg) => {
+        docs: pkg => cached(deps.cwd, 'enrichment:docs', `${pkg}\u0000${queryTokenKey(docsQuery)}`, async () => {
             const r = await docsRawFn({
                 pkg,
                 query: docsQuery,
@@ -189,11 +209,11 @@ export async function gatherExternalContext(refined, deps) {
                         .slice(0, RAW_BODY_LIMIT)
                     : undefined
             };
-        },
-        url: async (url) => {
+        }),
+        url: url => cached(deps.cwd, 'enrichment:url', url, async () => {
             const r = await fetchRawFn({ url, signal: deps.signal });
             return { body: r.markdown.slice(0, RAW_BODY_LIMIT) };
-        },
+        }),
         search: deps.searchFn
     }, {
         versionLookup,

package/dist/task/fix-context.d.ts

@@ -0,0 +1,39 @@
+/**
+ * fix-context — what an AUTOFIX re-run is told about the failure it exists to fix.
+ *
+ * It used to be one prose string: the FAIL reason, plus a diagnosis paragraph if
+ * a judge happened to produce one. Everything the gate had already computed
+ * stayed behind — which CLASS of failure it was, how many attempts had already
+ * been spent on it, what the deterministic probes found, and whether the spec
+ * contradicts itself. So the re-run re-derived what the gate knew, and in 0034 it
+ * re-derived it wrong: told only "lint fails", it widened suppressions until the
+ * check went quiet.
+ *
+ * A value, then, and one renderer. The banner keeps its RE-ATTEMPT opening — it
+ * is the sentence the implementer reads first and the one thing about the old
+ * string worth keeping.
+ */
+import type { Disposition, SpecContradiction } from './gate-resolution.js';
+import type { ProbeFindings, VerifyOutcome } from './verify-work.js';
+export interface FixContext {
+    outcome: VerifyOutcome;
+    disposition: Disposition;
+    /** The deterministic findings the verify pass computed for this verdict. */
+    probes: ProbeFindings;
+    /** Which unattended re-run this is, 1-based. */
+    attempt: number;
+    contradiction?: SpecContradiction | null;
+    /** The resolution judge's located cause, when it found one beyond the FAIL text. */
+    diagnosis?: string;
+    /** What the user typed instead of picking a card. */
+    guidance?: string;
+}
+/**
+ * The RE-ATTEMPT banner prepended to the delivered spec.
+ *
+ * The fail CLASS leads because it decides what a fix may even look like: a
+ * `repo-health` failure is about the project's own statics, a `model-verdict` one
+ * is about behavior the spec demanded, and confusing the two is how a re-run
+ * "fixes" a verdict by silencing a linter.
+ */
+export declare function formatFixBanner(ctx: FixContext): string;

package/dist/task/fix-context.js

@@ -0,0 +1,58 @@
+import { VERIFY_FAIL_PREFIX } from './verify-work.js';
+const PROBE_LABELS = {
+    repoHealth: 'inherited repo health (NOT yours to fix)',
+    substitution: 'tests this task itself wrote',
+    prohibition: 'spec-forbidden paths this task modified',
+    crossTaskDeletion: "another task's deliverables this task deletes",
+    probeGaming: 'lines written to quiet a check',
+    skipEscape: 'VERIFY commands that skip themselves',
+    foreignPath: 'absolute paths that resolve nowhere here',
+    scriptEscape: 'check scripts that cannot fail',
+    runnerGlob: 'test runners claiming the same files',
+    testAssembly: 'tests that rebuild production wiring',
+    suppressionWidening: 'suppressions this task added'
+};
+function probeBlock(probes) {
+    const out = [];
+    for (const [key, findings] of Object.entries(probes)) {
+        if (!findings || findings.length === 0)
+            continue;
+        out.push(`- ${PROBE_LABELS[key] ?? key}:`);
+        for (const f of findings)
+            out.push(`    ${f}`);
+    }
+    return out.length === 0 ? [] : ['', 'WHAT THE DETERMINISTIC PROBES ALREADY FOUND:', ...out];
+}
+/**
+ * The RE-ATTEMPT banner prepended to the delivered spec.
+ *
+ * The fail CLASS leads because it decides what a fix may even look like: a
+ * `repo-health` failure is about the project's own statics, a `model-verdict` one
+ * is about behavior the spec demanded, and confusing the two is how a re-run
+ * "fixes" a verdict by silencing a linter.
+ */
+export function formatFixBanner(ctx) {
+    const failClass = ctx.outcome.failClass;
+    const lines = [
+        'RE-ATTEMPT — your previous implementation of this task FAILED verification.',
+        "Fix the cause below, then make the spec's VERIFY block pass. Do NOT start over;",
+        'change only what is needed to resolve the failure.',
+        '',
+        `ATTEMPT ${ctx.attempt} of this task's fix budget.`
+    ];
+    if (failClass) {
+        lines.push(`FAILURE CLASS: ${failClass} — ${VERIFY_FAIL_PREFIX[failClass]}. A fix that does not`, 'move THIS class has not fixed anything; suppressing, disabling, deleting or', 'skipping the check that reported it is a defect, not a fix.');
+    }
+    lines.push('', `VERIFICATION FAILURE:\n${(ctx.outcome.reason ?? '').trim()}`);
+    if (ctx.diagnosis && ctx.diagnosis.trim().length > 0) {
+        lines.push('', `DIAGNOSIS (a read-only investigation of this failure found):\n${ctx.diagnosis.trim()}`);
+    }
+    lines.push(...probeBlock(ctx.probes));
+    if (ctx.contradiction) {
+        lines.push('', `SPEC CONTRADICTION: \`${ctx.contradiction.frozenPath}\` is frozen by this task's own`, `spec, and ${ctx.contradiction.criterion || 'the failing check'} cannot be satisfied`, 'without editing it. Do NOT edit the frozen path. Report the contradiction in your', 'summary and fix whatever else you can reach.');
+    }
+    if (ctx.guidance && ctx.guidance.trim().length > 0) {
+        lines.push('', `User guidance: ${ctx.guidance.trim()}`);
+    }
+    return lines.join('\n');
+}

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

@@ -1,10 +1,13 @@
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { GateDeps } from './task-gates.js';
+import { type HealthBaseline } from './health-baseline.js';
 import { type VerifyProbes } from './verify-work.js';
+import type { CommandRunner } from './command-run.js';
 import { type FinalFixResult } from './final-gate-fix.js';
 import { type AddedLine } from './probe-gaming.js';
 import { type ChangedFile } from './substitution-probe.js';
 import { type TreeChangeSummary, type IgnoredSnapshot } from './write-guard.js';
+import { type DiffLine, type SuppressionHit } from './suppression-probe.js';
 /** A function that re-runs a task's implementation turn (AUTOFIX). Injected by the
  *  command so this module stays free of the orchestrators (avoids an import cycle). */
 export type RunTaskFn = GateDeps['runTask'];
@@ -152,6 +155,25 @@ export declare function collectTestAssemblyFindings(cwd: string, changed: Change
  * would otherwise be the same four-line try/catch at four gate sites.
  */
 export declare function readSpecForVerification(cwd: string, taskId: string): Promise<string | null>;
+/**
+ * The task's rendered Q&A, which is what a constraint's `[from: Q<n>]` tag
+ * resolves against (see qa-transcript's `qaKindsFromRecord`). Null when the task
+ * asked nothing, or the file cannot be read — both mean every tagged constraint
+ * reads as `derived`, and `constraint-policy.ts` says what that is worth.
+ */
+export declare function readQaRecordForVerification(cwd: string, taskId: string): Promise<string | null>;
+/**
+ * The health baseline the verify gate's differential needs: the one stored on the
+ * task file, or — for a task file that has none — one established lazily from a
+ * DETACHED WORKTREE at HEAD and written back, so the next resolution round does
+ * not pay for it again.
+ *
+ * Everything here is best-effort. A baseline that cannot be established is null,
+ * and `classifyHealthDelta` already states what an absent baseline means; failing
+ * the gate because the differential could not run would be the harness blaming
+ * the work for its own gap.
+ */
+export declare function healthBaselineFor(cwd: string, taskId: string, signal: AbortSignal): Promise<HealthBaseline | null>;
 /**
  * Bind the deterministic verify probes — THE one place the collectors above meet
  * the probe table in verify-work.ts. One entry per `BoundProbeKey`; the table row
@@ -169,8 +191,35 @@ export declare function buildVerifyProbes(params: {
     signal?: AbortSignal;
     taskId: string;
     spec: string | null;
+    /** The task's `## grill Q&A`, so a prohibition carries the WEIGHT of the
+     *  constraint that states it rather than being unwaivable by default. */
+    qaRecord?: string | null;
     log?: (msg: string) => void;
+    /** Names the gate-evidence command currently running, for the caller's live
+     *  status line — the same channel `runRepoHealthCheck` takes. */
+    onCommand?: (cmd: string) => void;
+    /** The spawner for the gate-evidence commands, as `runRepoHealthCheck` takes
+     *  one: injected so a session's command count is assertable without a shell. */
+    run?: CommandRunner;
 }): VerifyProbes;
+/**
+ * The task's net-new suppressions: the files its work touched (the same tree
+ * shape the write-guard reads), diffed against the checkpoint HEAD, counted per
+ * pattern.
+ *
+ * The pattern set follows the repo's detected ecosystems, so a Go project is not
+ * scanned for `@ts-expect-error` and a TypeScript one is not scanned for
+ * `//nolint`; `suppressionPatterns` in the config adds project-specific rows.
+ * Failures degrade to no findings — a sharpener, never a blocker.
+ */
+export declare function collectSuppressionHits(cwd: string, signal?: AbortSignal): Promise<SuppressionHit[]>;
+/**
+ * A unified diff's content lines, tagged with their side and their file. The `+++`
+ * header names the file and the `---`/`+++` headers themselves are excluded, which
+ * is the one thing a naive `startsWith('+')` scan gets wrong — it counts every
+ * changed file's own header as an added line.
+ */
+export declare function parseDiffLines(diff: string): DiffLine[];
 /**
  * Build the gate deps for one command run. `runTask` is the orchestrator's
  * implementation re-runner, injected by the caller. The returned object also drives