@mjasnikovs/pi-task 0.38.10 → 0.38.12

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

@@ -1,7 +1,8 @@
 import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { FetchAndCleanError } from './html-clean.js';
-import { fetchFocused, formatResultText } from './fetch-core.js';
+import { fetchFocused } from './fetch-core.js';
+import { formatResultText } from '../shared/child-output.js';
 import { makeWorkerTool } from './shared.js';
 import { normalizeQuery } from './research-cache.js';
 import { isAbstention } from './abstention.js';
@@ -51,7 +52,8 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                 if (result.failure !== undefined) {
                     return { text: result.failure, details: { childExitCode: result.childExitCode } };
                 }
-                const body = formatResultText({ answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
+                const body = formatResultText('', // a fetched page answer carries no package header
+                { answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
                 // The coverage miss is the one outcome that carries an instruction. It goes
                 // in the TEXT, not only in details: details are for the harness, and the
                 // worker acts on what it reads.
@@ -90,7 +92,7 @@ export function registerPiWorkerFetch(pi, internals = {}) {
         // otherwise). The URL is kept verbatim (path case can matter); the query is
         // normalised. Both parts key the entry — same page, different question is a
         // different answer.
-        cacheKey: params => `${params.url.trim()}::${normalizeQuery(params.query)}`,
+        cacheKey: fetchCacheKey,
         // Only a completed fetch (child exited 0) is a real answer; invalid-URL,
         // fetch failures, and aborts omit childExitCode:0 and fall through.
         // F-2(e), on the fetch channel. A child that ran fine and answered
@@ -99,6 +101,19 @@ export function registerPiWorkerFetch(pi, internals = {}) {
         // the same dead-end-paid-many-times shape pi-worker-docs already closed
         // for packages, with escalation unable to re-fire because the miss never
         // recurred. One predicate now covers every corpus (workers/abstention.ts).
-        cacheable: (d, text) => d.childExitCode === 0 && !isAbstention(text)
+        cacheable: fetchCacheable
     });
 }
+/**
+ * The F-2(e) cache rule for the fetch channel, named for the same reason as
+ * `docsCacheable`: pi-worker-fetch.test.ts carried a hand-retyped copy driving four
+ * tests, which a change to the shipped rule would leave green.
+ */
+export function fetchCacheable(d, text) {
+    return d.childExitCode === 0 && !isAbstention(text);
+}
+/** The fetch cache key. URL verbatim (path case can matter), question normalised —
+ *  same page, different question is a different answer. */
+export function fetchCacheKey(params) {
+    return `${params.url.trim()}::${normalizeQuery(params.query)}`;
+}

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.10",
+    "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",