@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/spec-doc.js

@@ -0,0 +1,205 @@
+/**
+ * spec-doc — ONE structured read of the source design document.
+ *
+ * The failure this closes: six host-side planning parsers each split the same
+ * markdown their own way, over one flat string. `demark` ran for grounding and
+ * was thrown away, so `findDroppedPlusFragments` re-cleaned the raw quote by a
+ * different rule; requirement candidacy could not tell a sentence from a SQL
+ * column or a router table's guard column. Live, that shipped task titles
+ * carrying `check` (a `check (…)` constraint inside a DDL fence) and
+ * `password) | public |` (two cells of a routing table) as restored spec
+ * constraints, and promoted the document's one-line product description to a
+ * requirement no task could ever own.
+ *
+ * A document is PREAMBLE (whatever sits above the first heading — where a spec
+ * says what the thing IS) plus heading-delimited SECTIONS of BLOCKS. A block is
+ * the smallest unit a quote can be grounded in and the smallest unit a policy can
+ * exclude, and it carries its own `plain`: the text as a model READS it, which is
+ * the single normalisation every grounding guard in the pipeline shares.
+ *
+ * Markdown-shaped but not markdown-dependent: a doc with no headings, no lists
+ * and no tables parses to one paragraph block per paragraph, which is exactly the
+ * flat-string behavior every consumer had before.
+ */
+import { normalise } from './contracts.js';
+/**
+ * Markdown MARKUP dropped before grounding — emphasis runs, list and heading
+ * markers, blockquote markers, table pipes and CODE BACKTICKS. Not content: no
+ * word, number or punctuation inside a sentence is touched, so this cannot make
+ * an invented quote match.
+ *
+ * WHY. A model copies a spec line as it READS, and what it reads is rendered:
+ * `2. **Auth** — sessions, login/logout/me, guards + tests.` comes back as
+ * `Auth — sessions, login/logout/me, guards + tests.` That is a verbatim copy of
+ * the line's TEXT, and the exact-substring test called it fabricated and threw
+ * it away — including, as here, the "+ tests" line that is the restoration
+ * module's own worked example.
+ *
+ * BACKTICKS ARE THE SAME CLASS and were the larger half. A code span renders as
+ * bare text, so `3. **Invites** — create/validate/redeem, \`/join/:token\` page.`
+ * comes back as `Invites — create/validate/redeem, /join/:token page.` Screening
+ * every spec line in its RENDERED form is what makes those quotes match at all.
+ *
+ * The two directions this has to hold in, both run:
+ *   FLOOR   a real spec line with ONE content word altered must NOT be grounded —
+ *           changing `sessions` to `tokens`, or `redeem` to `revoke`, drops it.
+ *   CEILING a real spec line quoted without its markup MUST be grounded — both the
+ *           `2. **Auth** —` numbering-and-bold case and the backticked
+ *           `` `/join/:token` `` case still match.
+ */
+export function demark(s) {
+    return s
+        .replace(/\*\*|__/g, '')
+        .replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, '')
+        .replace(/^\s*>\s?/gm, '')
+        .replace(/^#+\s*/gm, '')
+        .replace(/`/g, '')
+        .replace(/\|/g, ' ');
+}
+const HEADING_RE = /^(#{1,6})\s+(\S.*?)\s*$/;
+const FENCE_RE = /^\s*(```+|~~~+)/;
+const TABLE_ROW_RE = /^\s*\|/;
+const BLOCKQUOTE_RE = /^\s*>/;
+const LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s+\S/;
+/** A thematic break carries no text, so it is not a block of anything. */
+const THEMATIC_BREAK_RE = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+/** The kinds a line OPENS on sight. `null` ⇒ prose, which continues whatever
+ *  block is already open (markdown's lazy continuation) or opens a paragraph. */
+function openingKind(line) {
+    if (TABLE_ROW_RE.test(line))
+        return 'table-row';
+    if (BLOCKQUOTE_RE.test(line))
+        return 'quote';
+    if (LIST_ITEM_RE.test(line))
+        return 'list-item';
+    return null;
+}
+export function parseSpecDoc(text) {
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const doc = { preamble: [], sections: [] };
+    let open = null;
+    const target = () => doc.sections.length > 0 ? doc.sections[doc.sections.length - 1].blocks : doc.preamble;
+    const emit = (kind, body, line) => {
+        const t = body.join('\n');
+        if (t.trim().length > 0)
+            target().push({ kind, text: t, plain: demark(t), line });
+    };
+    const close = () => {
+        if (open)
+            emit(open.kind, open.lines, open.line);
+        open = null;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const fence = FENCE_RE.exec(raw);
+        if (fence) {
+            close();
+            const start = i + 1;
+            const body = [raw];
+            // A fence runs to its closing marker or to EOF — an unclosed fence is
+            // still one block, never a re-read of its contents as prose.
+            while (i + 1 < lines.length) {
+                body.push(lines[++i]);
+                if (lines[i].trimStart().startsWith(fence[1]))
+                    break;
+            }
+            emit('fence', body, start);
+            continue;
+        }
+        const heading = HEADING_RE.exec(raw);
+        if (heading) {
+            close();
+            doc.sections.push({ heading: heading[2], depth: heading[1].length, blocks: [] });
+            continue;
+        }
+        if (raw.trim().length === 0 || THEMATIC_BREAK_RE.test(raw)) {
+            close();
+            continue;
+        }
+        const kind = openingKind(raw);
+        if (kind === 'table-row') {
+            close();
+            emit('table-row', [raw], i + 1);
+            continue;
+        }
+        if (kind === 'quote' && open?.kind === 'quote') {
+            open.lines.push(raw);
+            continue;
+        }
+        if (kind !== null) {
+            close();
+            open = { kind, lines: [raw], line: i + 1 };
+            continue;
+        }
+        if (open === null)
+            open = { kind: 'para', lines: [raw], line: i + 1 };
+        else
+            open.lines.push(raw);
+    }
+    close();
+    return doc;
+}
+/** Every block, in document order. */
+export function blocksOf(doc) {
+    return [...doc.preamble, ...doc.sections.flatMap(s => s.blocks)];
+}
+/**
+ * The blocks above the first CONTENT section — where a spec says what the thing
+ * IS rather than what the work must do.
+ *
+ * Two shapes, both real. A doc can open with prose and then head its sections; or
+ * it can open with its TITLE as the only top-level heading and put the same prose
+ * under it, which is what `# MX-5 Private — Project Design` does. A lone depth-1
+ * heading above deeper ones is a title, not a section, so its body is preamble
+ * too.
+ *
+ * A document with NO sections at all has no preamble: "preamble" means "above the
+ * body", so without a body there is nothing to be above — otherwise a heading-less
+ * prose spec would have its whole content excluded by any preamble policy.
+ */
+export function preambleOf(doc) {
+    const [first, ...rest] = doc.sections;
+    if (first === undefined)
+        return [];
+    const titled = first.depth === 1 && rest.length > 0 && rest.every(s => s.depth > 1);
+    return titled ? [...doc.preamble, ...first.blocks] : doc.preamble;
+}
+/** A heading in `plain` form. Demarked as the LINE it was, `#` run included:
+ *  without it demark reads the `11.` of "11. Security notes" as a list marker. */
+function headingPlain(s) {
+    return demark(`${'#'.repeat(s.depth)} ${s.heading}`);
+}
+/** Heading-delimited section texts in `plain` form, pre-normalised for
+ *  containment tests. The preamble is its own leading section. */
+export function sectionPlains(doc) {
+    const out = [doc.preamble.map(b => b.plain).join('\n')];
+    for (const s of doc.sections)
+        out.push([headingPlain(s), ...s.blocks.map(b => b.plain)].join('\n'));
+    return out.map(normalise).filter(s => s.length > 0);
+}
+/** The whole doc in `plain` form — the flat fallback for a quote that spans
+ *  block boundaries (a model quoting two consecutive bullets as one line). */
+export function specPlain(doc) {
+    return [
+        ...doc.preamble.map(b => b.plain),
+        ...doc.sections.flatMap(s => [headingPlain(s), ...s.blocks.map(b => b.plain)])
+    ].join('\n');
+}
+/**
+ * The first block whose `plain` contains `quote`, both demarked and normalised —
+ * the anchor a grounded quote records. `accept` narrows candidacy: a quote whose
+ * only match lies outside it is NOT grounded, which is how a requirement policy
+ * rejects a DDL column or a table cell the model quoted as an obligation.
+ */
+export function groundIn(doc, quote, accept) {
+    const q = normalise(demark(quote));
+    if (q.length === 0)
+        return null;
+    for (const b of blocksOf(doc)) {
+        if (accept && !accept(b))
+            continue;
+        if (normalise(b.plain).includes(q))
+            return b;
+    }
+    return null;
+}

package/dist/task/spec-model.d.ts

@@ -0,0 +1,70 @@
+/**
+ * spec-model — the composed spec as a VALUE, and the one parser that produces it.
+ *
+ * The spec travelled as an opaque blob: the verify child got a string, the
+ * resolution judge got the same string, the prohibition probe re-scanned it line
+ * by line with its own regex, and the frozen-path guard re-scanned it again
+ * through that. Nothing could ask the spec a question — least of all "where did
+ * this constraint come from" — so a constraint a grill auto-answer invented was
+ * indistinguishable from one the user wrote, and both gates held it unwaivable
+ * (0043).
+ *
+ * So the spec parses once, here, into a value whose constraints carry their
+ * PROVENANCE, and `constraint-policy.ts` turns that provenance into the weight
+ * both gates render. This module knows nothing about gates, prompts or git: it
+ * turns text into a shape.
+ *
+ * NOT this module's job: `extractCapsSection` (refuted-constraint.ts). That reads
+ * the REFINED PROMPT, a different document with a different grammar, written
+ * before any spec exists.
+ */
+import type { QaKind } from './qa-transcript.js';
+/**
+ * Where one constraint came from.
+ *
+ * A `QaKind` means the composer traced it to that numbered Q&A answer. `spec`
+ * means the composer traced it to the refined task itself. `derived` is the
+ * honest default for an untagged constraint — the composer wrote it and named no
+ * source, which is a weaker claim than either of the other two, and the policy
+ * table treats it as such.
+ */
+export type ConstraintProvenance = QaKind | 'spec' | 'derived';
+export interface Constraint {
+    /** The constraint text, with the provenance tag removed. */
+    text: string;
+    provenance: ConstraintProvenance;
+}
+export interface Spec {
+    goal: string;
+    constraints: Constraint[];
+    acceptance: string[];
+    /** The VERIFY section verbatim, fence and all — `spec-validation.ts` owns
+     *  what counts as a runnable block inside it. */
+    verify: string;
+}
+/** Resolves a `Q<n>` tag to the kind of the answer that numbered question got. */
+export type QaResolver = (questionNumber: number) => QaKind | null;
+/**
+ * Parse a composed spec into its value. The SINGLE parser: `extractSpecForVerification`,
+ * `extractProhibitions` and (through the latter) `frozenPathsFromSpec` all read
+ * this shape, so "what the spec says" cannot mean two things in two gates.
+ *
+ * Total — any text parses. A spec missing a section yields that section empty,
+ * which is what the callers already handle (no constraints ⇒ nothing forbidden).
+ */
+export declare function parseSpec(section: string, resolve?: QaResolver): Spec;
+/**
+ * Render a parsed spec back to the four-section text the composer emits. Its
+ * point is the round-trip: `parseSpec(formatSpec(s))` equals `s`, which is what
+ * makes the parser answerable to 21 real specs rather than to its own tests.
+ * Provenance rides back out as the same `[from:]` tag, except for `derived`,
+ * whose absence IS its spelling.
+ */
+export declare function formatSpec(spec: Spec): string;
+/**
+ * Slice the delivered spec out of a task file body: everything under `## spec`
+ * down to the next `## ` heading (a `### ` subheading stays inside). Null when
+ * the section is absent or blank — a task that never reached compose, which the
+ * verify gate treats as nothing to verify.
+ */
+export declare function sliceSpecSection(taskBody: string): string | null;

package/dist/task/spec-model.js

@@ -0,0 +1,139 @@
+/** The tag COMPOSE_PROMPT asks for: `[from: Q3]`, or `[from: spec]`. */
+const FROM_TAG_RE = /\[from:\s*(Q(\d+)|spec)\s*\]/i;
+const SECTION_RE = /^\s*(GOAL|CONSTRAINTS|ACCEPTANCE|VERIFY)\b\s*:?\s*$/i;
+const BULLET_RE = /^\s*[-*]\s+(.*)$/;
+/**
+ * Split a `## spec` section's text into its four parts. A section the spec never
+ * opened is an empty string; the four are independent, so a malformed spec
+ * degrades one part rather than the whole value.
+ */
+function splitSections(section) {
+    const out = {
+        GOAL: [],
+        CONSTRAINTS: [],
+        ACCEPTANCE: [],
+        VERIFY: []
+    };
+    let current = null;
+    for (const line of section.split('\n')) {
+        const header = SECTION_RE.exec(line);
+        if (header) {
+            current = header[1].toUpperCase();
+            continue;
+        }
+        if (current)
+            out[current].push(line);
+    }
+    return out;
+}
+/**
+ * Bullet list → one entry per bullet, with wrapped continuation lines folded back
+ * onto the bullet they belong to.
+ *
+ * Folding is not cosmetic: real specs wrap a constraint over four lines, and the
+ * prohibition probe reads "the line carrying the ban" — split, the ban and the
+ * path it names land in different entries and the probe sees neither.
+ */
+function parseBullets(lines) {
+    const out = [];
+    for (const line of lines) {
+        const bullet = BULLET_RE.exec(line);
+        if (bullet) {
+            out.push(bullet[1].trim());
+            continue;
+        }
+        const text = line.trim();
+        if (text.length === 0 || out.length === 0)
+            continue;
+        out[out.length - 1] = `${out[out.length - 1]}\n${text}`;
+    }
+    return out;
+}
+/**
+ * Read one bullet's `[from:]` tag. An unresolvable `Q<n>` — the transcript is
+ * shorter than the number, or there is no transcript at all — is `derived`, not
+ * an invented kind: a tag naming an answer nobody can produce proves nothing
+ * about the constraint's origin.
+ */
+function readProvenance(text, resolve) {
+    const tag = FROM_TAG_RE.exec(text);
+    if (!tag)
+        return { text, provenance: 'derived' };
+    const stripped = text
+        .replace(FROM_TAG_RE, '')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+    if (tag[2] === undefined)
+        return { text: stripped, provenance: 'spec' };
+    const kind = resolve?.(Number(tag[2])) ?? null;
+    return { text: stripped, provenance: kind ?? 'derived' };
+}
+/**
+ * Parse a composed spec into its value. The SINGLE parser: `extractSpecForVerification`,
+ * `extractProhibitions` and (through the latter) `frozenPathsFromSpec` all read
+ * this shape, so "what the spec says" cannot mean two things in two gates.
+ *
+ * Total — any text parses. A spec missing a section yields that section empty,
+ * which is what the callers already handle (no constraints ⇒ nothing forbidden).
+ */
+export function parseSpec(section, resolve) {
+    const parts = splitSections(section);
+    return {
+        goal: parts.GOAL.join('\n').trim(),
+        constraints: parseBullets(parts.CONSTRAINTS).map(t => readProvenance(t, resolve)),
+        acceptance: parseBullets(parts.ACCEPTANCE),
+        verify: parts.VERIFY.join('\n').trim()
+    };
+}
+/**
+ * Render a parsed spec back to the four-section text the composer emits. Its
+ * point is the round-trip: `parseSpec(formatSpec(s))` equals `s`, which is what
+ * makes the parser answerable to 21 real specs rather than to its own tests.
+ * Provenance rides back out as the same `[from:]` tag, except for `derived`,
+ * whose absence IS its spelling.
+ */
+export function formatSpec(spec) {
+    const tag = (c) => c.provenance === 'derived' ? ''
+        : c.provenance === 'spec' ? ' [from: spec]'
+            : ` [from: ${c.provenance}]`;
+    return [
+        'GOAL',
+        spec.goal,
+        '',
+        'CONSTRAINTS',
+        ...spec.constraints.map(c => `- ${c.text}${tag(c)}`),
+        '',
+        'ACCEPTANCE',
+        ...spec.acceptance.map(a => `- ${a}`),
+        '',
+        'VERIFY:',
+        spec.verify
+    ].join('\n');
+}
+/**
+ * Slice the delivered spec out of a task file body: everything under `## spec`
+ * down to the next `## ` heading (a `### ` subheading stays inside). Null when
+ * the section is absent or blank — a task that never reached compose, which the
+ * verify gate treats as nothing to verify.
+ */
+export function sliceSpecSection(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;
+}

package/dist/task/stall-detector.d.ts

@@ -105,4 +105,4 @@ export declare class StallDetector {
  * because "you ran out of time" tells a model that was working correctly but
  * slowly to truncate its work for no reason.
  */
-export declare function formatStallHint(kind: StallKind): string;
+export declare function formatStallHint(kind: StallKind, visited?: readonly string[]): string;

package/dist/task/stall-detector.js

@@ -46,7 +46,7 @@
  * short-window sibling that trips FAST on an exact repeat; this is the
  * whole-run backstop that trips on sustained non-progress.
  */
-import { stableStringify } from './loop-detector.js';
+import { formatReadSet, stableStringify } from './loop-detector.js';
 /**
  * Consecutive no-new-ground tool results before the child is killed.
  *
@@ -107,7 +107,9 @@ export class StallDetector {
             this.deadStreak++;
         this.seenCalls.add(key);
         if (this.deadStreak >= this.limit) {
-            return { call, count: this.deadStreak, windowSize: 0, stall: 'no-new-ground' };
+            // No windowSize: this rule counts a CONSECUTIVE streak over the whole
+            // run, so there is no window to report and a renderer must not invent one.
+            return { call, count: this.deadStreak, stall: 'no-new-ground' };
         }
         return null;
     }
@@ -142,16 +144,18 @@ export class StallDetector {
  * because "you ran out of time" tells a model that was working correctly but
  * slowly to truncate its work for no reason.
  */
-export function formatStallHint(kind) {
+export function formatStallHint(kind, visited = []) {
     if (kind === 'context-churn') {
         return ('[SYSTEM NOTE: Your previous attempt pulled in more file content than '
             + 'its context window can hold, so the earliest material was dropped and '
             + 'you began re-reading it. Do not re-open files. Read only what you have '
-            + 'not read yet, and write your answer from what you have.]');
+            + 'not read yet, and write your answer from what you have.'
+            + `${formatReadSet(visited)}]`);
     }
     return ('[SYSTEM NOTE: Your previous attempt made a run of tool calls that returned '
         + 'nothing you had not already seen — you were re-opening files you had '
         + 'already read. Read each region of a file AT MOST ONCE, and when a file is '
         + 'too large to read whole, page FORWARD through it rather than re-opening '
-        + 'the start. Write your answer from what you have gathered.]');
+        + 'the start. Write your answer from what you have gathered.'
+        + `${formatReadSet(visited)}]`);
 }

package/dist/task/state-dir.d.ts

@@ -0,0 +1,29 @@
+/** How many of a repository's runs keep their logs. */
+export declare const RUN_LOG_KEEP = 20;
+/** The XDG state-home base. Siblings: `dataHome` (shared/data-home.ts). */
+export declare function stateHome(): string;
+/** Stable directory name for a repository: its absolute path, hashed so one flat
+ *  level holds every repo and no tree layout leaks into a shared directory. */
+export declare function repoHash(cwd: string): string;
+/** Every run's directory for this repository — the unit `pruneRunLogs` walks. */
+export declare function repoStateDir(cwd: string): string;
+/** One run's directory: logs, and (WS9) its gate evidence. */
+export declare function stateDir(cwd: string, runId: string): string;
+/**
+ * The id whose directory a line written now belongs in: the open run's (the run
+ * bracket owns it — `run-context.ts`). A caller outside any bracket, a direct
+ * `runSingleTask` or a test, shares one per-process id so its lines still land
+ * together instead of one directory per line.
+ */
+export declare function currentRunId(cwd: string): string;
+/** A log file in the current run's directory. */
+export declare function runLogPath(cwd: string, file: string): string;
+/**
+ * Drop all but the `keep` most recent runs of this repository, returning the ids
+ * removed. Called once when a run completes: retention that needs a timer would
+ * outlive the session that owns it, and a repo nobody runs keeps what it had.
+ *
+ * Best-effort throughout — a state dir that cannot be read or removed must not
+ * fail the run that just succeeded.
+ */
+export declare function pruneRunLogs(cwd: string, keep?: number): Promise<string[]>;

package/dist/task/state-dir.js

@@ -0,0 +1,80 @@
+/**
+ * Where a run's logs and gate evidence live: OUTSIDE the repository.
+ *
+ * `.pi-tasks/` is committed with every task and rewound by the gates'
+ * `reset --hard`, and `snapshotTrail` copies every file under it across that
+ * rewind. A trail that grows with model chatter therefore costs a re-read, a
+ * re-commit and a full-file copy per task — a real run reached 1.7 MB. None of it
+ * is an artifact of the project, so it belongs in the user's state home,
+ * partitioned per repository and per run so whole generations can be dropped.
+ *
+ * The task FILES stay where they are: those are the deliverable.
+ */
+import * as crypto from 'node:crypto';
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { newRunToken } from '../workers/research-cache.js';
+import { openRunId } from './run-context.js';
+/** How many of a repository's runs keep their logs. */
+export const RUN_LOG_KEEP = 20;
+/** The XDG state-home base. Siblings: `dataHome` (shared/data-home.ts). */
+export function stateHome() {
+    const xdg = process.env.XDG_STATE_HOME?.trim();
+    // XDG says a relative value is to be IGNORED, not resolved against the cwd —
+    // resolving one would scatter log dirs through the user's projects.
+    return xdg && path.isAbsolute(xdg) ? xdg : path.join(os.homedir(), '.local', 'state');
+}
+/** Stable directory name for a repository: its absolute path, hashed so one flat
+ *  level holds every repo and no tree layout leaks into a shared directory. */
+export function repoHash(cwd) {
+    return crypto.createHash('sha256').update(path.resolve(cwd)).digest('hex').slice(0, 16);
+}
+/** Every run's directory for this repository — the unit `pruneRunLogs` walks. */
+export function repoStateDir(cwd) {
+    return path.join(stateHome(), 'pi-task', repoHash(cwd));
+}
+/** One run's directory: logs, and (WS9) its gate evidence. */
+export function stateDir(cwd, runId) {
+    return path.join(repoStateDir(cwd), runId);
+}
+let fallbackRunId;
+/**
+ * The id whose directory a line written now belongs in: the open run's (the run
+ * bracket owns it — `run-context.ts`). A caller outside any bracket, a direct
+ * `runSingleTask` or a test, shares one per-process id so its lines still land
+ * together instead of one directory per line.
+ */
+export function currentRunId(cwd) {
+    return openRunId(cwd) ?? (fallbackRunId ??= newRunToken());
+}
+/** A log file in the current run's directory. */
+export function runLogPath(cwd, file) {
+    return path.join(stateDir(cwd, currentRunId(cwd)), file);
+}
+/**
+ * Drop all but the `keep` most recent runs of this repository, returning the ids
+ * removed. Called once when a run completes: retention that needs a timer would
+ * outlive the session that owns it, and a repo nobody runs keeps what it had.
+ *
+ * Best-effort throughout — a state dir that cannot be read or removed must not
+ * fail the run that just succeeded.
+ */
+export async function pruneRunLogs(cwd, keep = RUN_LOG_KEEP) {
+    const dir = repoStateDir(cwd);
+    const kept = Math.max(0, keep);
+    const entries = await fsp.readdir(dir, { withFileTypes: true }).catch(() => []);
+    const runs = entries.filter(e => e.isDirectory()).map(e => e.name);
+    if (runs.length <= kept)
+        return [];
+    const dated = await Promise.all(runs.map(async (name) => ({
+        name,
+        at: await fsp.stat(path.join(dir, name)).then(s => s.mtimeMs, () => 0)
+    })));
+    // The name breaks an mtime tie: a run token opens with its own base-36
+    // minting time, so it already orders the way the clock does.
+    dated.sort((a, b) => b.at - a.at || b.name.localeCompare(a.name));
+    const drop = dated.slice(kept).map(d => d.name);
+    await Promise.all(drop.map(name => fsp.rm(path.join(dir, name), { recursive: true, force: true }).catch(() => { })));
+    return drop;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * suppression-probe — deterministic detection of a task that reached green by
+ * WIDENING SUPPRESSIONS rather than by fixing what the checker found.
+ *
+ * TASK_0034 shipped sixteen of them in one file — one blanket `eslint-disable`
+ * header and fifteen `@ts-expect-error` lines — and every gate reported success.
+ * Nothing named it, because nothing was looking: the checks were green, which is
+ * exactly what a suppression buys. The verify child cannot discover this by
+ * running the project's commands for the same reason.
+ *
+ * So it is a diff question, not a check question. The probe counts each pattern's
+ * matching lines the task ADDED and subtracts the ones it REMOVED, per file: a
+ * refactor that deletes three `@ts-ignore`s and adds one is net -2 and silent,
+ * while a file that gained one is a finding. Net, not absolute, because a task
+ * that legitimately moves code would otherwise be accused of writing what it only
+ * relocated.
+ *
+ * The registry is DATA, and deliberately cross-ecosystem — a suppression exists
+ * for every checker, and a TypeScript-only list would have made this a TypeScript
+ * feature. Projects add their own through the `suppressionPatterns` config.
+ */
+import type { EcosystemId } from '../workers/docs-ecosystems.js';
+/** One suppression spelling. `ecosystems` narrows a row to the projects where it
+ *  means what it says; absent ⇒ it applies everywhere. */
+export interface SuppressionPattern {
+    id: string;
+    re: RegExp;
+    ecosystems?: EcosystemId[];
+}
+/**
+ * The shipped rows. Each `re` is a LINE test, so a pattern that appears inside a
+ * string literal or a comment still counts — the point is the suppression's
+ * presence in the shipped file, and deciding what is "really" a suppression would
+ * need a parser per language to answer worse.
+ */
+export declare const SUPPRESSION_PATTERNS: readonly SuppressionPattern[];
+/** One diff line the probe reads: which side of the diff it is on, and where. */
+export interface DiffLine {
+    path: string;
+    text: string;
+    added: boolean;
+}
+/** A file that gained suppressions, with the net count per pattern. */
+export interface SuppressionHit {
+    path: string;
+    patternId: string;
+    /** Added matching lines minus removed ones. Always positive — a net-zero or
+     *  net-negative pattern is not a widening and is not reported. */
+    net: number;
+}
+/**
+ * Compile the extra patterns a project configures. An unparseable source is
+ * dropped rather than thrown: a hand-edited config may not break the gate, and a
+ * pattern nobody can compile finds nothing either way.
+ */
+export declare function compileSuppressionPatterns(sources: readonly string[]): SuppressionPattern[];
+/** The rows in force for a project: the shipped ones its ecosystems claim, plus
+ *  every configured one (a user pattern is never ecosystem-gated — they wrote it
+ *  for this repo). */
+export declare function suppressionPatternsFor(ecosystems: readonly EcosystemId[], extra?: readonly SuppressionPattern[]): SuppressionPattern[];
+/**
+ * Net-new suppressions per file and pattern, in a stable order (file, then
+ * registry order) so two runs over the same diff produce the same findings.
+ */
+export declare function findSuppressionWidening(lines: readonly DiffLine[], patterns?: readonly SuppressionPattern[]): SuppressionHit[];
+/** The verify prompt's finding lines for the suppression-widening row. */
+export declare function suppressionVerifyFindings(hits: readonly SuppressionHit[]): string[];