@mjasnikovs/pi-task 0.38.11 → 0.38.12

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

@@ -55,9 +55,10 @@ export declare function extractSpecForVerification(taskBody: string): string | n
  * three of them).
  *
  * Each probe is now an ADAPTER: one row carrying only what is specific to it —
- * the dep field it reads, the empty value it degrades to, how its raw result
- * becomes finding lines, the notice block those lines produce, and the numbered
- * rule the notice routes the child to. The loop owns the ritual. (Same shape as
+ * its key (which names the thunk it reads from `deps.probes`), the empty value it
+ * degrades to, how its raw result becomes finding lines, the notice block those
+ * lines produce, and the numbered rule the notice routes the child to. The loop
+ * owns the ritual. (Same shape as
  * LOCKFILE_CHECKS in final-gate.ts, where a whole package ecosystem is one row.)
  *
  * THIS PROMPT IS A MEASURED ARTIFACT — its wording is A/B-tested on the live
@@ -71,10 +72,48 @@ export declare function extractSpecForVerification(taskBody: string): string | n
  * A row whose rule is woven into the numbered narrative elsewhere (3b inside the
  * substitution rules, 3f, 5c) carries `ruleId` for the reader and no `rule` text.
  */
+/**
+ * What each probe channel's RAW probe returns — the one place a channel's shape
+ * is declared. `ProbeKey` is derived from it, so a channel exists exactly when it
+ * has a row here; delete one and the compiler names its table row and its single
+ * binding line in gate-deps' `buildVerifyProbes`.
+ */
+export interface ProbeRaw {
+    substitution: string[];
+    prohibition: string[];
+    crossTaskDeletion: CrossTaskDeletion[];
+    probeGaming: string[];
+    skipEscape: string[];
+    foreignPath: string[];
+    scriptEscape: string[];
+    runnerGlob: string[];
+    testAssembly: string[];
+}
 /** Stable identity of one probe channel: table row ↔ findings-bag key. */
-export type ProbeKey = 'substitution' | 'prohibition' | 'crossTaskDeletion' | 'probeGaming' | 'skipEscape' | 'foreignPath' | 'scriptEscape' | 'runnerGlob' | 'testAssembly';
+export type ProbeKey = keyof ProbeRaw;
+/**
+ * The channels a CALLER binds — every key but `skipEscape`, which is pure text
+ * analysis of `deps.spec` and is sourced inside its own table row, so it is never
+ * absent and never bound from outside.
+ */
+export type BoundProbeKey = Exclude<ProbeKey, 'skipEscape'>;
+/**
+ * The bound probes: one optional thunk per channel, typed to that channel's raw
+ * shape. Built in ONE place (gate-deps' `buildVerifyProbes`); an absent key means
+ * the row is skipped. Adding a probe is a `ProbeRaw` line, a table row, and a
+ * binding line — nothing else.
+ */
+export type VerifyProbes = {
+    [K in BoundProbeKey]?: () => Promise<ProbeRaw[K]>;
+};
 /** The finding lines each probe channel contributed. Absent/empty ⇒ no block. */
 export type ProbeFindings = Partial<Record<ProbeKey, string[]>>;
+/**
+ * The channels a caller must bind — the table rows that read `deps.probes`, in
+ * table order. Exported so the one binder (gate-deps' `buildVerifyProbes`) can be
+ * checked against the table rather than against a hand-kept list.
+ */
+export declare const BOUND_PROBE_KEYS: readonly BoundProbeKey[];
 /**
  * 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
@@ -131,75 +170,22 @@ export interface VerificationDeps {
         reason: string;
     }>;
     /**
-     * Progress hook for the DETERMINISTIC stage — the repo-health run plus the ten
-     * probes below, all of which run BEFORE the child (and therefore before the
+     * Progress hook for the DETERMINISTIC stage — the repo-health run plus the
+     * `probes` below, all of which run BEFORE the child (and therefore before the
      * child's own status widget exists). Called with a short label as each step
      * starts, so the caller can keep a live line on screen through what was
      * otherwise the run's longest stretch of dead air (MEASURED at 15–69s per
      * repo-health run). ABSENT → no progress reporting, same behaviour as before. */
     onStage?: (stage: string) => void;
     /**
-     * DETERMINISTIC substitution probe (see substitution-probe.ts): scans the task's
-     * changed test files for test-the-copy shapes and returns finding lines to inject
-     * 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[]>;
-    /**
-     * DETERMINISTIC test-assembly probe (see test-assembly.ts): authored test files
-     * that rebuild production WIRING — importing the leaf modules the shipped entry
-     * composes and assembling their own copy instead of the real assembly — become
-     * prompt findings under rule 3f (F4 test-the-copy, 3rd recurrence). Pure import-
-     * graph shape; the child then drives the real assembly before trusting the copy.
-     * ABSENT or empty → no test-assembly block. */
-    testAssemblyProbe?: () => Promise<string[]>;
-    /**
-     * DETERMINISTIC probe-gaming probe (see probe-gaming.ts, run-8 F6): added lines
-     * in the task's diff whose stated purpose is to make a CHECK pass instead of
-     * meeting the requirement it stands for ("return 401 so the verification test
-     * passes"). Injected as findings under rule 4c so the child confirms the
-     * underlying requirement is genuinely met rather than trusting the green check.
-     * Pure diff-text analysis; ABSENT or empty → no probe block. */
-    probeGamingProbe?: () => Promise<string[]>;
-    /**
-     * DETERMINISTIC cross-task deletion probe (see task-provenance.ts, mx5 run 12
-     * PROMPT 2): tracked files the task's diff DELETES whose introducing task (git
-     * provenance) differs from the current task — a sibling's committed deliverable
-     * destroyed, typically to green a check. Injected as prompt findings under rule
-     * 4d (MANDATORY + verdict-gating, the A/B-proven shape — buried rules score
-     * 0/5), and carried structurally on a FAIL outcome so an ACCEPT records each as
-     * a durable debt. ABSENT or empty → no block. */
-    crossTaskDeletionProbe?: () => Promise<CrossTaskDeletion[]>;
-    /**
-     * DETERMINISTIC sandbox-path-leak probe (see foreign-path.ts, mx5 run 13
-     * PROMPT 4 item 1): absolute paths this task committed that exist only inside
-     * the authoring child's own environment — `/workspace/src/shared` in a vite
-     * alias — while the real file sits at `src/shared` here. The probe REPAIRS
-     * what it can deterministically first; only leaks it could not repair reach
-     * this hook, injected under rule 4e (MANDATORY + verdict-gating, the same
-     * shape as 4d — a leak makes the affected command fail to BUILD, so the
-     * checks that would notice never run at all). ABSENT or empty → no block. */
-    foreignPathProbe?: () => Promise<string[]>;
-    /**
-     * DETERMINISTIC neutered-check-script probe (see script-escape.ts, mx5 run 13
-     * PROMPT 4 item 4): check-class scripts in a manifest THIS task changed whose
-     * exit status cannot be non-zero (`… || true`, an inverted-grep launder). The
-     * damage is second-order — the script still "passes", so the gates that run it
-     * report success without measuring anything — which is exactly why the child
-     * cannot discover it by running the check. ABSENT or empty → no block. */
-    scriptEscapeProbe?: () => Promise<string[]>;
-    /**
-     * DETERMINISTIC test-runner glob-collision probe (see runner-globs.ts, mx5 runs
-     * 7 AND 13, PROMPT 4 item 2): the manifest declares two runners whose file sets
-     * are not provably disjoint, so the scanning one imports the other's specs and
-     * dies during COLLECTION. Injected under rule 4g. UNKNOWN (one runner, or
-     * disjointness proven) yields nothing. ABSENT or empty → no block. */
-    runnerGlobProbe?: () => Promise<string[]>;
+     * The DETERMINISTIC probes, one optional thunk per channel (see `PROBE_ADAPTERS`
+     * above for what each channel is and which rule its findings cite; the
+     * substitution, prohibition, test-assembly, probe-gaming, cross-task-deletion,
+     * foreign-path, script-escape and runner-glob probes all live here). Bound in
+     * ONE place — gate-deps' `buildVerifyProbes` — and consumed by the table: an
+     * absent key skips its row, a throwing thunk degrades to the row's empty value.
+     * ABSENT → no probe blocks at all (tests / callers that wire none). */
+    probes?: VerifyProbes;
     /**
      * 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

package/dist/task/verify-work.js

@@ -122,15 +122,21 @@ export function extractSpecForVerification(taskBody) {
  */
 function probeAdapter(row) {
     const { key, stage, block, ruleId, rule } = row;
+    const source = row.source
+        ?? ((deps) => 
+        // One channel per key, so the bag's entry for this key IS this row's
+        // thunk; the cast only re-narrows what the mapped type already says.
+        deps.probes?.[key]);
     return {
         key,
+        bound: !row.source,
         stage,
         block,
         ruleId,
         rule,
         run: async (deps, onStage) => {
-            const probe = row.dep(deps);
-            // Probes are INDEPENDENTLY OPTIONAL: an absent dep is "skipped", and a
+            const probe = source(deps);
+            // 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
             // leak into another row.
@@ -165,7 +171,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'substitution',
         stage: 'substitution probe',
-        dep: deps => deps.probe,
         empty: [],
         findings: asLines,
         ruleId: '3b',
@@ -198,7 +203,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'prohibition',
         stage: 'prohibition probe',
-        dep: deps => deps.prohibitionProbe,
         empty: [],
         findings: asLines,
         ruleId: '4b',
@@ -238,7 +242,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'crossTaskDeletion',
         stage: 'cross-task deletion probe',
-        dep: deps => deps.crossTaskDeletionProbe,
         empty: [],
         findings: crossTaskDeletionVerifyFindings,
         ruleId: '4d',
@@ -277,7 +280,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'probeGaming',
         stage: 'probe-gaming probe',
-        dep: deps => deps.probeGamingProbe,
         empty: [],
         findings: asLines,
         ruleId: '4c',
@@ -322,7 +324,7 @@ const PROBE_ADAPTERS = [
      */
     probeAdapter({
         key: 'skipEscape',
-        dep: deps => () => Promise.resolve(skipEscapeVerifyFindings(findSkipEscapes(deps.spec ?? ''))),
+        source: deps => () => Promise.resolve(skipEscapeVerifyFindings(findSkipEscapes(deps.spec ?? ''))),
         empty: [],
         findings: asLines,
         ruleId: '5c',
@@ -349,7 +351,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'foreignPath',
         stage: 'foreign-path probe',
-        dep: deps => deps.foreignPathProbe,
         empty: [],
         findings: asLines,
         ruleId: '4e',
@@ -392,7 +393,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'scriptEscape',
         stage: 'script-escape probe',
-        dep: deps => deps.scriptEscapeProbe,
         empty: [],
         findings: asLines,
         ruleId: '4f',
@@ -431,7 +431,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'runnerGlob',
         stage: 'runner-glob probe',
-        dep: deps => deps.runnerGlobProbe,
         empty: [],
         findings: asLines,
         ruleId: '4g',
@@ -466,7 +465,6 @@ const PROBE_ADAPTERS = [
     probeAdapter({
         key: 'testAssembly',
         stage: 'test-assembly probe',
-        dep: deps => deps.testAssemblyProbe,
         empty: [],
         findings: asLines,
         ruleId: '3f',
@@ -487,6 +485,12 @@ const PROBE_ADAPTERS = [
         ]
     })
 ];
+/**
+ * The channels a caller must bind — the table rows that read `deps.probes`, in
+ * table order. Exported so the one binder (gate-deps' `buildVerifyProbes`) can be
+ * 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);
 /**
  * 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

package/dist/workers/single-read-extension.d.ts

@@ -4,7 +4,7 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  * blocks, each returning a reason the model receives as an error tool result
  * (agent-loop: block → createErrorToolResult) so the worker continues instead of
  * looping:
- *   - read: blocks any re-read of a file already read this run (path-keyed).
+ *   - read: blocks a re-read of LINES already delivered; forward paging passes.
  *   - grep/find/ls: blocks an identical repeat of the same call (args-keyed).
  * See single-read-guard.ts for why this is scoped to TOOLING.
  */

package/dist/workers/single-read-extension.js

@@ -7,7 +7,7 @@ const DEDUP_TOOLS = new Set(['grep', 'find', 'ls']);
  * blocks, each returning a reason the model receives as an error tool result
  * (agent-loop: block → createErrorToolResult) so the worker continues instead of
  * looping:
- *   - read: blocks any re-read of a file already read this run (path-keyed).
+ *   - read: blocks a re-read of LINES already delivered; forward paging passes.
  *   - grep/find/ls: blocks an identical repeat of the same call (args-keyed).
  * See single-read-guard.ts for why this is scoped to TOOLING.
  */
@@ -16,10 +16,11 @@ export default function (pi) {
     const calls = new RepeatedCallGuard();
     pi.on('tool_call', event => {
         if (event.toolName === 'read') {
-            const path = event.input.path;
-            if (typeof path !== 'string')
+            const input = event.input;
+            if (typeof input.path !== 'string')
                 return;
-            return reads.check(resolve(process.cwd(), path)) ?? undefined;
+            return (reads.check(resolve(process.cwd(), input.path), input.offset, input.limit)
+                ?? undefined);
         }
         if (DEDUP_TOOLS.has(event.toolName)) {
             return calls.check(event.toolName, event.input) ?? undefined;

package/dist/workers/single-read-guard.d.ts

@@ -6,10 +6,22 @@
  * as an error tool result, the worker continues). No kill, no restart: detect-
  * and-kill only re-spawns a model that deterministically re-thrashes.
  *
- *   - SingleReadGuard: "read each file once". Validated against every recorded
- *     mx5 run — a healthy TOOLING worker reads each file exactly once (max
- *     same-file reads = 1 across 7 tasks). TASK_0017 re-read one file up to 50×.
- *     Keyed on the resolved path so any re-read is blocked regardless of offset.
+ *   - SingleReadGuard: "read each LINE of a file once". Validated against every
+ *     recorded mx5 run — a healthy TOOLING worker reads each file exactly once
+ *     (max same-file reads = 1 across 7 tasks). TASK_0017 re-read one file 50×.
+ *
+ *     It used to key on the resolved path alone, blocking any second read
+ *     "regardless of offset". That made a file bigger than one read into a trap.
+ *     Measured 2026-08-17 on a captured auto-decompose request: the planner asked
+ *     for `DESIGN/marketplace.html` with `limit: 80` — the first 80 lines of 743,
+ *     deliberately paging — and its request for offset 80 was refused. It never
+ *     reached the end of the file, and spent the rest of the run asking for the
+ *     remainder: 197 of 200 tool calls were this guard's own refusal. The guard
+ *     did not stop a thrash, it CAUSED one.
+ *
+ *     So the unit is the line range, not the file. A request that extends past
+ *     the furthest line already delivered is forward paging and passes; one that
+ *     lies entirely within ground already delivered is a re-read and is blocked.
  *
  *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls. TASK_0017
  *     also looped on grep({pattern:"^\\s*}",path:".../index.ts"}) ×5 — a path the
@@ -24,17 +36,27 @@ export interface ReadBlock {
     block: true;
     reason: string;
 }
-/** The error text the model receives in place of the re-read's contents. */
-export declare function singleReadReason(path: string): string;
+/**
+ * The error text the model receives in place of the re-read's contents.
+ *
+ * It must say what to do NEXT, and the honest next move depends on whether there
+ * is any of the file left: with `covered` lines already delivered, asking for
+ * line `covered + 1` is always allowed, so the message says so. The old wording
+ * ("Do not read it again") was a dead end for a model that was mid-way through a
+ * file — it had nowhere legal to go and kept asking anyway.
+ */
+export declare function singleReadReason(path: string, covered: number): string;
 export declare class SingleReadGuard {
-    private readonly seen;
+    /** Furthest line already delivered per path; Infinity once a read hit EOF. */
+    private readonly covered;
     /**
-     * Record a read of `resolvedPath`. Returns a ReadBlock the first time a path
-     * is seen a second time (and every time after), else null on the first read.
+     * Record a read of `resolvedPath` over an optional line range. Returns a
+     * ReadBlock when the request lies entirely within lines already delivered,
+     * else null — which includes every first read and every forward page.
      * Callers pass an already-resolved/normalized path so `a.ts` and `./a.ts`
      * dedupe to one entry.
      */
-    check(resolvedPath: string): ReadBlock | null;
+    check(resolvedPath: string, offset?: unknown, limit?: unknown): ReadBlock | null;
 }
 /** The error text the model receives in place of a repeated grep/find/ls call. */
 export declare function repeatedCallReason(toolName: string): string;

package/dist/workers/single-read-guard.js

@@ -6,10 +6,22 @@
  * as an error tool result, the worker continues). No kill, no restart: detect-
  * and-kill only re-spawns a model that deterministically re-thrashes.
  *
- *   - SingleReadGuard: "read each file once". Validated against every recorded
- *     mx5 run — a healthy TOOLING worker reads each file exactly once (max
- *     same-file reads = 1 across 7 tasks). TASK_0017 re-read one file up to 50×.
- *     Keyed on the resolved path so any re-read is blocked regardless of offset.
+ *   - SingleReadGuard: "read each LINE of a file once". Validated against every
+ *     recorded mx5 run — a healthy TOOLING worker reads each file exactly once
+ *     (max same-file reads = 1 across 7 tasks). TASK_0017 re-read one file 50×.
+ *
+ *     It used to key on the resolved path alone, blocking any second read
+ *     "regardless of offset". That made a file bigger than one read into a trap.
+ *     Measured 2026-08-17 on a captured auto-decompose request: the planner asked
+ *     for `DESIGN/marketplace.html` with `limit: 80` — the first 80 lines of 743,
+ *     deliberately paging — and its request for offset 80 was refused. It never
+ *     reached the end of the file, and spent the rest of the run asking for the
+ *     remainder: 197 of 200 tool calls were this guard's own refusal. The guard
+ *     did not stop a thrash, it CAUSED one.
+ *
+ *     So the unit is the line range, not the file. A request that extends past
+ *     the furthest line already delivered is forward paging and passes; one that
+ *     lies entirely within ground already delivered is a re-read and is blocked.
  *
  *   - RepeatedCallGuard: "no identical search twice", for grep/find/ls. TASK_0017
  *     also looped on grep({pattern:"^\\s*}",path:".../index.ts"}) ×5 — a path the
@@ -21,25 +33,64 @@
  * Pure logic, no I/O — the extension does path resolution and tool routing.
  */
 import { stableStringify } from '../task/loop-detector.js';
-/** The error text the model receives in place of the re-read's contents. */
-export function singleReadReason(path) {
-    return (`You already read ${path} earlier in this run — its contents are in your context. `
-        + `Re-reading the same file is blocked. Do not read it again: use what you have already `
-        + `gathered and write your final answer now.`);
+/**
+ * The error text the model receives in place of the re-read's contents.
+ *
+ * It must say what to do NEXT, and the honest next move depends on whether there
+ * is any of the file left: with `covered` lines already delivered, asking for
+ * line `covered + 1` is always allowed, so the message says so. The old wording
+ * ("Do not read it again") was a dead end for a model that was mid-way through a
+ * file — it had nowhere legal to go and kept asking anyway.
+ */
+export function singleReadReason(path, covered) {
+    if (!Number.isFinite(covered)) {
+        return (`You already read all of ${path} earlier in this run — its contents are in your `
+            + `context. Re-reading it is blocked. Use what you have already gathered and write `
+            + `your final answer now.`);
+    }
+    return (`You already read ${path} through line ${covered} earlier in this run — those lines are `
+        + `in your context. Re-reading them is blocked. To see more of this file, read it again `
+        + `starting at line ${covered + 1}; otherwise use what you have already gathered and `
+        + `write your final answer now.`);
+}
+/** Default `limit` pi's read tool applies when the call names none. */
+const DEFAULT_READ_LIMIT = 2000;
+/** The 1-based line a read starts at (`offset` absent or junk means line 1). */
+function startLine(offset) {
+    return typeof offset === 'number' && Number.isFinite(offset) && offset >= 1 ?
+        Math.floor(offset)
+        : 1;
+}
+/**
+ * The last line a read reaches. A `limit` of exactly the tool default is treated
+ * as "no limit given" — indistinguishable at this layer, and the safe reading is
+ * the generous one, since blocking honest paging is the failure this guard had.
+ */
+function endLine(start, limit) {
+    if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0)
+        return Infinity;
+    if (limit >= DEFAULT_READ_LIMIT)
+        return Infinity;
+    return start + Math.floor(limit) - 1;
 }
 export class SingleReadGuard {
-    seen = new Set();
+    /** Furthest line already delivered per path; Infinity once a read hit EOF. */
+    covered = new Map();
     /**
-     * Record a read of `resolvedPath`. Returns a ReadBlock the first time a path
-     * is seen a second time (and every time after), else null on the first read.
+     * Record a read of `resolvedPath` over an optional line range. Returns a
+     * ReadBlock when the request lies entirely within lines already delivered,
+     * else null — which includes every first read and every forward page.
      * Callers pass an already-resolved/normalized path so `a.ts` and `./a.ts`
      * dedupe to one entry.
      */
-    check(resolvedPath) {
-        if (this.seen.has(resolvedPath)) {
-            return { block: true, reason: singleReadReason(resolvedPath) };
+    check(resolvedPath, offset, limit) {
+        const seen = this.covered.get(resolvedPath);
+        const start = startLine(offset);
+        const end = endLine(start, limit);
+        if (seen !== undefined && end <= seen) {
+            return { block: true, reason: singleReadReason(resolvedPath, seen) };
         }
-        this.seen.add(resolvedPath);
+        this.covered.set(resolvedPath, Math.max(seen ?? 0, end));
         return null;
     }
 }

package/package.json

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