@mjasnikovs/pi-task 0.38.11 → 0.38.13

package/dist/task/implementation-turn.js

@@ -0,0 +1,263 @@
+/**
+ * Implementation-turn supervision — what happens between "the spec was delivered
+ * to the main session" and "we know how the implementation turn REALLY ended".
+ *
+ * A single `waitForIdle` resolves for four different reasons, and three of them
+ * are not "the model finished":
+ *   • `aborted`     — a user ESC (or the command watchdog) cut the turn short;
+ *   • `compaction`  — a threshold auto-compaction parked the turn at idle without
+ *                     auto-continuing (the runtime expects a manual continue);
+ *   • `error`       — the model/provider died mid-turn after pi's own retries;
+ *   • `stop`        — genuine completion.
+ * `classifyTurnEnd` reads the session entries and names ONE of those, in the
+ * precedence the supervision sequence needs; `superviseImplementation` then
+ * resumes across compactions, lets the user steer after an interrupt, and reports
+ * the terminal outcome. The orchestrator calls it once.
+ */
+import { SessionUI } from '../remote/bridge.js';
+import { consumeWatchdogAbort, WATCHDOG_CANCEL_MARKER } from './command-watchdog.js';
+const isAssistant = (e) => e.message !== undefined && e.message.role === 'assistant';
+/** Index of the last assistant message and of the last compaction boundary. */
+function tailPositions(entries) {
+    let lastAssistant = -1;
+    let lastCompaction = -1;
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        if (isAssistant(e))
+            lastAssistant = i;
+        else if (e.type === 'compaction')
+            lastCompaction = i;
+    }
+    return { lastAssistant, lastCompaction };
+}
+/**
+ * Classify how the most recent turn ended, from the session entries alone.
+ *
+ * Precedence, when several signals are present at once (this is the order the
+ * supervision sequence has always applied, now stated in one place):
+ *   1. `aborted`    — the last assistant message has stopReason "aborted". A user
+ *                     ESC (or watchdog abort) wins over everything: it is not a
+ *                     compaction pause, and the steer loop owns it.
+ *   2. `compaction` — a `compaction` entry sits AFTER the last assistant message.
+ *                     Position-based, not timestamp-based: the runtime appends the
+ *                     boundary to the tail of the branch after the message that
+ *                     triggered it (`appendCompaction` → `_appendEntry` push), so a
+ *                     trailing compaction means we are parked with no continuation.
+ *                     A finished turn ends on an assistant message; an *overflow*
+ *                     compaction self-retries and never leaves us idle here.
+ *   3. `error`      — the last assistant message has stopReason "error": the
+ *                     model/provider died (context-overflow 400, disconnect, 5xx)
+ *                     after pi exhausted its own retries.
+ *   4. `stop`       — anything else, including a session with no assistant turn.
+ */
+export function classifyTurnEnd(entries) {
+    const { lastAssistant, lastCompaction } = tailPositions(entries);
+    const last = lastAssistant >= 0 ? entries[lastAssistant].message : undefined;
+    if (last?.stopReason === 'aborted')
+        return 'aborted';
+    if (lastCompaction > lastAssistant)
+        return 'compaction';
+    if (last?.stopReason === 'error')
+        return 'error';
+    return 'stop';
+}
+/**
+ * The provider's error cause for an `error` turn end — the message the run's
+ * "stopped at …" line quotes so the real cause is not lost. Undefined unless the
+ * last assistant message ended with stopReason "error".
+ */
+export function turnErrorMessage(entries) {
+    const { lastAssistant } = tailPositions(entries);
+    const last = lastAssistant >= 0 ? entries[lastAssistant].message : undefined;
+    if (last?.stopReason !== 'error')
+        return undefined;
+    return last.errorMessage ?? 'model error';
+}
+/** True when the last assistant turn was aborted (ESC / watchdog). */
+const wasInterrupted = (entries) => classifyTurnEnd(entries) === 'aborted';
+/**
+ * True when the watchdog's reminder follow-up has been DELIVERED into the session
+ * after the aborted assistant turn but its own turn has not finished yet — the
+ * artifact that confirms a pending watchdog recovery. Scoped after the LAST
+ * assistant entry so an earlier fire's reminder (already answered by its own
+ * turn) never matches.
+ */
+export function watchdogReminderDelivered(entries) {
+    const { lastAssistant } = tailPositions(entries);
+    for (let i = lastAssistant + 1; i < entries.length; i++) {
+        const m = entries[i].message;
+        if (m === undefined || m.role !== 'user')
+            continue;
+        const content = m.content;
+        const text = typeof content === 'string' ? content
+            : Array.isArray(content) ?
+                content
+                    .map(b => b !== null && typeof b === 'object' && 'text' in b ?
+                    String(b.text)
+                    : '')
+                    .join(' ')
+                : '';
+        if (text.includes(WATCHDOG_CANCEL_MARKER))
+            return true;
+    }
+    return false;
+}
+const STEER_WATCHDOG_DEFAULTS = {
+    consume: consumeWatchdogAbort,
+    graceMs: 10_000,
+    pollMs: 100
+};
+/** Dialog copy for the post-interrupt steering prompt. */
+const STEER_TITLE = 'Paused — steer the model';
+const STEER_PLACEHOLDER = 'Type guidance to continue this task, or leave empty to pause';
+/** Remote-card copy for the same prompt. The browser has no placeholder ghost
+ *  text, so the pause affordance must be spelled out in the question itself
+ *  (Skip = empty answer = pause, same as an empty local submit). */
+const STEER_QUESTION = 'Paused — the implementation was interrupted.\n'
+    + 'Type guidance to continue this task, or Skip to pause the run.';
+/** Bind the supervision deps to a live session context. */
+export function turnDepsFor(ctx, opts = {}) {
+    // Fan the prompt out through the bridge (local TUI input + remote browser
+    // card, first answer wins) instead of a raw ctx.ui.input: an interrupt can
+    // come from the remote Stop button just as well as a terminal ESC, and a
+    // terminal-only dialog leaves the remote viewer staring at a silently
+    // paused run. Remote Skip returns '' → same pause path as an empty local
+    // submit.
+    const ask = opts.promptSteer
+        ?? (c => new SessionUI(c).ask({
+            localTitle: STEER_TITLE,
+            localPlaceholder: STEER_PLACEHOLDER,
+            question: STEER_QUESTION,
+            allowSkip: true
+        }));
+    return {
+        entries: () => ctx.sessionManager.getEntries(),
+        send: text => ctx.sendUserMessage(text, { deliverAs: 'followUp' }),
+        waitForIdle: () => ctx.waitForIdle(),
+        ask: () => ask(ctx),
+        watchdog: { ...STEER_WATCHDOG_DEFAULTS, ...opts.watchdog },
+        log: opts.log
+    };
+}
+// ─── Resume across compactions ───────────────────────────────────────────────
+/**
+ * Nudge that resumes an implementation turn the runtime parked at a compaction
+ * boundary. It must let a turn that was genuinely finished (then tipped over the
+ * threshold by its own final message) confirm completion without inventing busywork
+ * — we cannot tell "paused mid-task by compaction" from "finished, then compacted"
+ * from the boundary alone, so the wording lets a done turn end in one line.
+ */
+export const CONTINUE_AFTER_COMPACTION = 'Your context was automatically compacted. Continue implementing this task from '
+    + 'exactly where you left off, and keep going until it is fully done. If the '
+    + 'implementation is already complete, say so in one line and stop — do not invent '
+    + 'extra work or restart the task.';
+/**
+ * Safety cap on compaction-driven resumes for a single implementation turn. Each
+ * resume follows a real compaction (which only fires after the model produced a
+ * turn large enough to cross the threshold), so a legitimately large task may
+ * resume a handful of times; the cap exists only to stop a pathological loop from
+ * auto-sending forever with no user in the loop. Hitting it stops resuming and lets
+ * the verify gate / `/task-auto-resume` catch any leftover incompleteness.
+ */
+export const MAX_COMPACTION_RESUMES = 20;
+/**
+ * Resume an implementation turn that went idle at a threshold-compaction boundary.
+ * The runtime compacts and parks at idle without auto-continuing; we send a
+ * continue and wait again, repeating across successive compactions until the turn
+ * ends on a real assistant message (genuine completion). A user ESC takes priority
+ * (`classifyTurnEnd` ranks `aborted` above `compaction`, so the steer loop handles
+ * it), and the safety cap bounds a runaway. Returns the number of resumes
+ * performed (0 when the turn did not end on a compaction).
+ */
+export async function resumeAcrossCompactions(deps) {
+    let resumes = 0;
+    while (resumes < MAX_COMPACTION_RESUMES && classifyTurnEnd(deps.entries()) === 'compaction') {
+        deps.log?.(`implementation: parked at a compaction boundary — resume ${resumes + 1}`);
+        await deps.send(CONTINUE_AFTER_COMPACTION);
+        await deps.waitForIdle();
+        resumes++;
+    }
+    return resumes;
+}
+// ─── Steer until done ────────────────────────────────────────────────────────
+/**
+ * Wait for a watchdog abort's queued follow-up turn instead of prompting. The
+ * abort and the reminder follow-up are two separate steps in the watchdog's
+ * onFire, so the steer loop can observe the aborted turn before the reminder is
+ * delivered — poll (bounded) until it lands or the follow-up turn has already
+ * completed. True = recovery observed, re-check the loop; false = grace expired
+ * with no reminder (stale flag) — fall back to the human prompt.
+ */
+async function awaitWatchdogFollowUp(deps) {
+    const wd = deps.watchdog;
+    const deadline = Date.now() + wd.graceMs;
+    for (;;) {
+        if (!wasInterrupted(deps.entries()))
+            return true; // follow-up turn already completed
+        if (watchdogReminderDelivered(deps.entries())) {
+            await deps.waitForIdle(); // let the follow-up turn run to completion
+            return true;
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise(r => setTimeout(r, wd.pollMs));
+    }
+}
+/**
+ * After the implementation turn settles, honour a user ESC by letting them steer.
+ *
+ * `waitForIdle` resolves both on natural completion AND on an ESC (which aborts
+ * the turn → idle). When the last turn was aborted, the host's main input loop is
+ * blocked inside our command handler, so a message typed in the editor would only
+ * queue, never run (interactive-mode routes idle input through onInputCallback,
+ * which is unset while we hold the loop). We therefore solicit the steering text
+ * ourselves and feed it back as another turn via sendUserMessage — which runs to
+ * completion when the session is idle. Repeat until a turn finishes uninterrupted.
+ *
+ * A WATCHDOG abort also ends the turn with stopReason 'aborted' — indistinguishable
+ * from a human ESC by the session entries alone at that instant. The watchdog
+ * queues its own recovery follow-up, so prompting there would show a steering
+ * dialog to an empty room and wedge an unattended run on the race. The one-shot
+ * flag (set synchronously before the abort) routes that case to
+ * {@link awaitWatchdogFollowUp} instead; a stale flag degrades to a bounded wait
+ * followed by the ordinary prompt, never to a suppressed one.
+ *
+ * Returns true when the user declined to steer (empty/cancelled) and the run
+ * should pause; false when the implementation completed (steered or not).
+ */
+export async function steerUntilDone(deps) {
+    while (wasInterrupted(deps.entries())) {
+        if (deps.watchdog.consume() && (await awaitWatchdogFollowUp(deps))) {
+            deps.log?.('implementation: watchdog abort recovered by its own follow-up');
+            continue;
+        }
+        const steer = await deps.ask();
+        if (steer === undefined || steer.trim().length === 0) {
+            deps.log?.('implementation: interrupted, user declined to steer — pausing');
+            return true; // pause
+        }
+        deps.log?.('implementation: interrupted, steering with user text');
+        await deps.send(steer);
+        await deps.waitForIdle();
+    }
+    return false;
+}
+/**
+ * Supervise an implementation turn from the first idle after spec delivery until
+ * its REAL end: resume across any compaction boundaries first (so steering and
+ * error inspection see the turn's actual end, not a compaction pause), then let
+ * the user steer across interrupts, then read how the final turn ended. The
+ * caller has already awaited the first idle.
+ */
+export async function superviseImplementation(ctx, opts = {}) {
+    return superviseWith(turnDepsFor(ctx, opts));
+}
+/** {@link superviseImplementation} over an already-bound deps object (tests). */
+export async function superviseWith(deps) {
+    const resumes = await resumeAcrossCompactions(deps);
+    const interrupted = await steerUntilDone(deps);
+    // A user-declined steer (interrupted) is its own paused path; otherwise
+    // inspect how the turn actually ended.
+    const error = interrupted ? undefined : turnErrorMessage(deps.entries());
+    return { interrupted, error, resumes };
+}

package/dist/task/launch-contract.js

@@ -23,16 +23,36 @@
  * naming any declared script the manifest is missing. FP-safe by construction: an
  * empty/ungrounded list (a design that never backticks a script name) yields no check.
  */
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
-import { tasksDir } from './task-io.js';
+import { makeLedger } from './ledger.js';
 const LAUNCH_CONTRACT_FILE = 'launch-contract.md';
 /** Cap kept entries so a noisy extraction cannot grow the artifact unboundedly. */
 const MAX_SCRIPTS = 40;
 /** npm/package script names are short kebab/colon tokens; reject anything unscript-like. */
 const SCRIPT_NAME_RE = /^[a-z0-9][a-z0-9:_-]{0,39}$/i;
+/** Stored one name per line; a line that is not a script name is skipped on read. */
+const ledger = makeLedger({
+    file: LAUNCH_CONTRACT_FILE,
+    max: MAX_SCRIPTS,
+    key: n => n.toLowerCase(),
+    serialize: n => n,
+    parse: raw => {
+        const seen = new Set();
+        const out = [];
+        for (const line of raw.split('\n')) {
+            const n = line.trim();
+            if (n.length === 0 || !SCRIPT_NAME_RE.test(n))
+                continue;
+            const key = n.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(n);
+        }
+        return out;
+    }
+});
 export function launchContractFile(cwd) {
-    return path.join(tasksDir(cwd), LAUNCH_CONTRACT_FILE);
+    return ledger.path(cwd);
 }
 /**
  * Parse `SCRIPT: <name>` lines out of a child's answer into bare script names. A line
@@ -115,51 +135,15 @@ export function enumerateScriptCandidates(sourceDoc) {
 }
 /** The stored declared-script list ('' when none recorded). */
 export async function readLaunchContractRaw(cwd) {
-    try {
-        return (await fsp.readFile(launchContractFile(cwd), 'utf8')).trim();
-    }
-    catch {
-        return '';
-    }
+    return ledger.readRaw(cwd);
 }
 /** The declared script names recorded for this run (deduped, order preserved). */
 export async function readDeclaredScripts(cwd) {
-    const raw = await readLaunchContractRaw(cwd);
-    const seen = new Set();
-    const out = [];
-    for (const line of raw.split('\n')) {
-        const n = line.trim();
-        if (n.length === 0 || !SCRIPT_NAME_RE.test(n))
-            continue;
-        const key = n.toLowerCase();
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        out.push(n);
-    }
-    return out;
+    return ledger.read(cwd);
 }
 /** Append grounded script names, deduped against what is stored, keeping newest MAX. */
 export async function appendDeclaredScripts(cwd, names) {
-    if (names.length === 0)
-        return;
-    try {
-        const existing = await readDeclaredScripts(cwd);
-        const seen = new Set(existing.map(n => n.toLowerCase()));
-        const merged = [...existing];
-        for (const n of names) {
-            if (seen.has(n.toLowerCase()))
-                continue;
-            seen.add(n.toLowerCase());
-            merged.push(n);
-        }
-        const kept = merged.slice(-MAX_SCRIPTS);
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(launchContractFile(cwd), kept.join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort artifact
-    }
+    await ledger.append(cwd, names);
 }
 /**
  * Boot-class script names: long-running serve/watch shapes the gate's BOOT check

package/dist/task/ledger.d.ts

@@ -0,0 +1,38 @@
+export interface LedgerSpec<T> {
+    /** File name under `.pi-tasks/` (e.g. `contracts.md`). */
+    file: string;
+    /**
+     * Keep the newest `max` records on append (oldest dropped). Absent = uncapped
+     * (a ledger that is only ever overwritten whole, like requirements-owned).
+     */
+    max?: number;
+    /** Dedupe key — two records with equal keys are one record. */
+    key: (item: T) => string;
+    /** One record → one stored line (must not contain '\n'). */
+    serialize: (item: T) => string;
+    /** Stored text → records; skips what it cannot read rather than throwing. */
+    parse: (raw: string) => T[];
+    /**
+     * What `append` does when every incoming item was already stored:
+     *   'rewrite' (default) — write the merged list back anyway, which re-caps an
+     *     over-long file and canonicalises lines the parser normalised or dropped;
+     *   'skip' — leave the file untouched (a single-record "no double-record"
+     *     ledger: a duplicate is a return, not a write).
+     * The two are observably different when the file has drifted from what the
+     * writer produces, so it is an option, not a unification.
+     */
+    onNoop?: 'rewrite' | 'skip';
+}
+export interface Ledger<T> {
+    /** Absolute path of the ledger file for this cwd. */
+    path(cwd: string): string;
+    /** Trimmed stored text; '' when absent or on any read error. */
+    readRaw(cwd: string): Promise<string>;
+    /** Parsed records; [] when absent or on any read error. */
+    read(cwd: string): Promise<T[]>;
+    /** Merge new records in (deduped, capped) and write back. Never throws. */
+    append(cwd: string, items: T[]): Promise<void>;
+    /** Overwrite with exactly these records. Never throws. */
+    write(cwd: string, items: T[]): Promise<void>;
+}
+export declare function makeLedger<T>(spec: LedgerSpec<T>): Ledger<T>;

package/dist/task/ledger.js

@@ -0,0 +1,83 @@
+/**
+ * ledger — the ONE read-modify-write ritual behind every run-level line file under
+ * `.pi-tasks/` (contracts, launch-contract, env-notes, accept-debt, repair-queue,
+ * requirements, requirements-owned).
+ *
+ * Six modules each kept their own copy of the same seven steps: read the file
+ * (ANY error → ''), parse it into records, key the records, drop an incoming item
+ * whose key is already present, cap to the newest MAX (oldest dropped), mkdir the
+ * tasks dir, write the whole file back (`lines.join('\n') + '\n'`, plain
+ * `writeFile`, NOT atomic), and swallow every fault — a ledger is a sharpener or
+ * an auditing aid, never a blocker of the phase or gate that calls it. What
+ * genuinely varied per site is the DATA SHAPE (file name, cap, key, line format,
+ * parser) and exactly one RULE — what an append does when it adds nothing new
+ * (see `onNoop`). Everything else here is the ritual, so a module that keeps a
+ * ledger is an ADAPTER: it declares its ledger and calls read/append/write.
+ *
+ * Contract details a caller can rely on:
+ *   • `readRaw` is the trimmed file text ('' when absent or unreadable). Prompt-block
+ *     builders take this string.
+ *   • `read` is `parse(readRaw)`; every parser skips blank lines and lines it cannot
+ *     read, so a corrupt line is dropped, never thrown on.
+ *   • `append` with an empty batch is a no-op (no read, no write). Within a batch
+ *     the first item with a key wins; a key already stored wins over the batch.
+ *   • `write` overwrites with exactly these records; an empty list writes an empty
+ *     file (this is how a drained queue and a fully-resolved debt ledger look).
+ *   • Neither `append` nor `write` ever throws.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir } from './task-io.js';
+export function makeLedger(spec) {
+    const { file, max, key, serialize, parse } = spec;
+    const onNoop = spec.onNoop ?? 'rewrite';
+    const filePath = (cwd) => path.join(tasksDir(cwd), file);
+    async function readRaw(cwd) {
+        try {
+            return (await fsp.readFile(filePath(cwd), 'utf8')).trim();
+        }
+        catch {
+            return '';
+        }
+    }
+    async function read(cwd) {
+        return parse(await readRaw(cwd));
+    }
+    async function persist(cwd, items) {
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        const content = items.length === 0 ? '' : items.map(serialize).join('\n') + '\n';
+        await fsp.writeFile(filePath(cwd), content, 'utf8');
+    }
+    async function append(cwd, items) {
+        if (items.length === 0)
+            return;
+        try {
+            const existing = await read(cwd);
+            const seen = new Set(existing.map(key));
+            const merged = [...existing];
+            for (const item of items) {
+                const k = key(item);
+                if (seen.has(k))
+                    continue;
+                seen.add(k);
+                merged.push(item);
+            }
+            if (merged.length === existing.length && onNoop === 'skip')
+                return;
+            const kept = max === undefined ? merged : merged.slice(-max);
+            await persist(cwd, kept);
+        }
+        catch {
+            // best-effort ledger
+        }
+    }
+    async function write(cwd, items) {
+        try {
+            await persist(cwd, items);
+        }
+        catch {
+            // best-effort ledger
+        }
+    }
+    return { path: filePath, readRaw, read, append, write };
+}

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

@@ -6,9 +6,9 @@
  *   1. EXACT repeats — the same `(toolName, stable-stringified args)` key appears
  *      `threshold` times within the last `window` events.
  *   2. PATH revisits — the same primary file path is re-targeted `pathThreshold`
- *      times within the window WITHOUT the read offset advancing, which the exact
- *      key misses when `offset/limit` vary call-to-call. Strictly-forward paging
- *      never trips (see countRevisits).
+ *      times within the window over lines it has ALREADY covered, which the exact
+ *      key misses when `offset/limit` vary call-to-call. Forward paging never
+ *      trips (see countRevisits).
  *
  * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
  * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
@@ -45,11 +45,17 @@ export declare class LoopDetector {
     /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call: ToolCall): LoopHit | null;
     /**
-     * Count same-path calls in the window that are "revisits" — accesses whose
-     * offset does not advance past the furthest offset already seen for that
-     * path. Linear paging (strictly increasing offsets) yields zero revisits and
-     * never trips; repeated whole-file re-reads (offset 0 each time), backward
-     * jumps, and path-targeting greps (offset 0) accumulate.
+     * Count same-path calls in the window that are "revisits" — accesses that end
+     * no further into the file than the furthest line already covered for that
+     * path. Paging yields zero revisits and never trips; repeated whole-file
+     * re-reads, backward jumps and path-targeting greps accumulate.
+     *
+     * The comparison is on the RANGE, not the offset. Offset alone scored a page
+     * that re-asks from the same start with a bigger limit — `{offset:80,
+     * limit:400}` after `{offset:80, limit:300}`, real reads from a measured
+     * decompose run — as a revisit, even though it covers 100 lines the child had
+     * never seen. That is the same mistake SingleReadGuard made by keying on the
+     * path alone, and it is corrected the same way.
      */
     private countRevisits;
 }

package/dist/task/loop-detector.js

@@ -6,9 +6,9 @@
  *   1. EXACT repeats — the same `(toolName, stable-stringified args)` key appears
  *      `threshold` times within the last `window` events.
  *   2. PATH revisits — the same primary file path is re-targeted `pathThreshold`
- *      times within the window WITHOUT the read offset advancing, which the exact
- *      key misses when `offset/limit` vary call-to-call. Strictly-forward paging
- *      never trips (see countRevisits).
+ *      times within the window over lines it has ALREADY covered, which the exact
+ *      key misses when `offset/limit` vary call-to-call. Forward paging never
+ *      trips (see countRevisits).
  *
  * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
  * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
@@ -52,6 +52,23 @@ function readOffset(args) {
     const o = args.offset;
     return typeof o === 'number' && Number.isFinite(o) ? o : 0;
 }
+/** Default `limit` pi's read tool applies when the call names none. */
+const DEFAULT_READ_LIMIT = 2000;
+/**
+ * The last line a call reaches, so a page can be told from a re-read. Absent,
+ * junk, or at-the-tool-default `limit` all mean "to the end of the file": at this
+ * layer they are indistinguishable, and the generous reading is the safe one —
+ * scoring an honest page as a revisit is the failure this rule had.
+ */
+function readEnd(args, offset) {
+    if (!args || typeof args !== 'object')
+        return Infinity;
+    const l = args.limit;
+    if (typeof l !== 'number' || !Number.isFinite(l) || l <= 0 || l >= DEFAULT_READ_LIMIT) {
+        return Infinity;
+    }
+    return offset + Math.floor(l) - 1;
+}
 export class LoopDetector {
     window;
     threshold;
@@ -67,7 +84,8 @@ export class LoopDetector {
     /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call) {
         const key = `${call.name}\x00${stableStringify(call.args)}`;
-        this.buf.push({ key, path: primaryPath(call.args), offset: readOffset(call.args) });
+        const offset = readOffset(call.args);
+        this.buf.push({ key, path: primaryPath(call.args), offset, end: readEnd(call.args, offset) });
         if (this.buf.length > this.window)
             this.buf.shift();
         // 1. Exact-match loop: identical (name, args) repeated past threshold.
@@ -91,20 +109,26 @@ export class LoopDetector {
         return null;
     }
     /**
-     * Count same-path calls in the window that are "revisits" — accesses whose
-     * offset does not advance past the furthest offset already seen for that
-     * path. Linear paging (strictly increasing offsets) yields zero revisits and
-     * never trips; repeated whole-file re-reads (offset 0 each time), backward
-     * jumps, and path-targeting greps (offset 0) accumulate.
+     * Count same-path calls in the window that are "revisits" — accesses that end
+     * no further into the file than the furthest line already covered for that
+     * path. Paging yields zero revisits and never trips; repeated whole-file
+     * re-reads, backward jumps and path-targeting greps accumulate.
+     *
+     * The comparison is on the RANGE, not the offset. Offset alone scored a page
+     * that re-asks from the same start with a bigger limit — `{offset:80,
+     * limit:400}` after `{offset:80, limit:300}`, real reads from a measured
+     * decompose run — as a revisit, even though it covers 100 lines the child had
+     * never seen. That is the same mistake SingleReadGuard made by keying on the
+     * path alone, and it is corrected the same way.
      */
     countRevisits(path) {
-        let maxOffset = -1;
+        let maxEnd = -1;
         let revisits = 0;
         for (const e of this.buf) {
             if (e.path !== path)
                 continue;
-            if (e.offset > maxOffset)
-                maxOffset = e.offset; // progress: new ground
+            if (e.end > maxEnd)
+                maxEnd = e.end; // progress: new ground
             else
                 revisits++; // revisit: already-covered ground
         }