@mjasnikovs/pi-task 0.38.10 → 0.38.12

package/dist/task/plan-orchestrator.js

@@ -20,7 +20,7 @@
  * /task receives that a bare /task would not is the decisions block.
  */
 import * as path from 'node:path';
-import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
+import { prependHint, USER_CANCELLED } from './child-runner.js';
 import { PLAN_QUESTION_PROMPT, PLAN_ANSWER_PROMPT } from './plan-prompts.js';
 import { runPlanSession, ASK_TITLE } from './plan-session.js';
 import { allocatePlanId, buildPlanBody, buildHandoffPrompt, formatPlanDecisions } from './plan-io.js';
@@ -32,12 +32,13 @@ import { deriveTitle } from './parsers.js';
 import { renderInlineMarkdown } from './inline-markdown.js';
 import { expandFeatureMentions } from './auto-orchestrator.js';
 import { runSingleTask, runGatedTask } from './orchestrator.js';
-import { startAutoLoader } from './widget.js';
-import { SessionUI, publishViewer, publishNotify, publishLifecycleNotice, registerBridgeCommand } from '../remote/bridge.js';
+import { SessionUI, publishViewer, publishLifecycleNotice, registerBridgeCommand } from '../remote/bridge.js';
+import { withRun, announceTerminal } from './run-bracket.js';
 import { getConfig } from '../config/config.js';
 import { isYoloMode } from './yolo.js';
 import { gateDebugWriter } from './debug-log.js';
-import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
+import { getParentContextWindow } from './context-usage.js';
+import { ChildStatus, runPlanningChild, statusCallbacks } from './child-status.js';
 import * as fsp from 'node:fs/promises';
 /** Loader labels for the two planning children. */
 const PLAN_STEPS = {
@@ -52,10 +53,8 @@ const PLAN_STEPS = {
 export function buildPlanDeps(ctx, cwd, planId, task, signal) {
     const ui = new SessionUI(ctx);
     const theme = ctx.ui.theme;
-    let lastLine;
     let status;
-    let contextUsage;
-    const parentContextWindow = getParentContextWindow(ctx);
+    const childStatus = new ChildStatus({ parentContextWindow: getParentContextWindow(ctx) });
     const title = deriveTitle(task);
     const logDebug = gateDebugWriter((msg) => {
         const line = `${new Date().toISOString()} ${msg}\n`;
@@ -65,12 +64,7 @@ export function buildPlanDeps(ctx, cwd, planId, task, signal) {
         cwd,
         taskId: planId,
         signal,
-        onChildOutput: line => {
-            lastLine = line;
-        },
-        onContextUsage: snapshot => {
-            contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
-        },
+        ...statusCallbacks(childStatus),
         ...(logDebug && { logDebug })
     };
     /**
@@ -82,25 +76,23 @@ export function buildPlanDeps(ctx, cwd, planId, task, signal) {
      * the plan file itself is written.
      */
     const child = async (name, prompt) => {
-        lastLine = undefined;
-        contextUsage = undefined;
-        const startedAt = Date.now();
-        const stopLoader = startAutoLoader(ctx, () => ({
-            command: '/task-plan',
-            title,
-            step: status ?? PLAN_STEPS[name] ?? name,
-            stepNum: 1,
-            stepTotal: 1,
-            startedAt,
-            lastLine,
-            contextUsage
-        }));
         const before = await collectTreeChanges(cwd, signal).catch(() => null);
         try {
-            return await runPhaseChild(phaseDeps, name, PLAN_TOOLS, prompt);
+            return await runPlanningChild({
+                ctx,
+                status: childStatus,
+                phaseDeps,
+                name,
+                tools: PLAN_TOOLS,
+                prompt,
+                loader: {
+                    command: '/task-plan',
+                    title,
+                    step: n => ({ step: status ?? PLAN_STEPS[n] ?? n, stepNum: 1, stepTotal: 1 })
+                }
+            });
         }
         finally {
-            stopLoader();
             // Outside a git repo `before` is null and there is nothing to compare
             // against — the same degrade every other tree-reading guard here takes.
             if (before) {
@@ -264,6 +256,16 @@ export async function handleTaskPlan(args, ctx, commandDeps = DEFAULT_COMMAND_DE
         title: deriveTitle(raw)
     };
     await writeTaskFile(cwd, fm, buildPlanBody(task));
+    // The plan session owns the session the way a run does: its children run
+    // with the host idle, so an unbracketed line typed then went into pi's queue
+    // (terminal) or started a competing turn (browser) — the issue #8 shape.
+    // /task-auto brackets its planning for the same reason; this one was left
+    // out when /task-plan landed. Held lines reach the handed-off /task run's
+    // first turn (the bracket nests), or are reported when the plan ends without
+    // one. No onCancel: /task-auto-cancel is not this command's to acknowledge.
+    await withRun(ctx, {}, () => runPlanCommand(ctx, cwd, planId, task, commandDeps));
+}
+async function runPlanCommand(ctx, cwd, planId, task, commandDeps) {
     const abort = new AbortController();
     let outcome;
     try {
@@ -275,9 +277,9 @@ export async function handleTaskPlan(args, ctx, commandDeps = DEFAULT_COMMAND_DE
             state: msg === USER_CANCELLED ? 'cancelled' : 'failed',
             reason: msg.slice(0, 200)
         }).catch(() => { });
-        const line = `${planId} stopped — ${msg.slice(0, 160)}`;
-        ctx.ui.notify(line, 'error');
-        publishLifecycleNotice(line, 'error');
+        // No push: a plan is a conversation, not a task; the run it hands off
+        // to pushes its own ending.
+        announceTerminal(ctx, `${planId} stopped — ${msg.slice(0, 160)}`, 'error', { push: false });
         return;
     }
     if (outcome.kind === 'cancelled') {
@@ -289,8 +291,7 @@ export async function handleTaskPlan(args, ctx, commandDeps = DEFAULT_COMMAND_DE
         const line = outcome.entries.length === 0 ?
             `${planId} cancelled — nothing planned.`
             : `${planId} cancelled — ${outcome.entries.length} entr${outcome.entries.length === 1 ? 'y' : 'ies'} kept in .pi-tasks/${planId}.md`;
-        ctx.ui.notify(line, 'warning');
-        publishNotify(line, 'warning');
+        announceTerminal(ctx, line, 'warning', { push: false });
         return;
     }
     const prompt = buildHandoffPrompt(task, outcome.entries);

package/dist/task/requirements.d.ts

@@ -147,7 +147,7 @@ export declare function ownedRequirementsFile(cwd: string): string;
 /** Persist the task-mapped requirements (host-side, plan time). Overwrites —
  *  the mapping is recomputed whole per plan round. Best-effort like the carried
  *  artifact. */
-export declare function writeOwnedRequirements(cwd: string, owned: OwnedRequirement[]): Promise<void>;
+export declare function writeOwnedRequirements(cwd: string, entries: OwnedRequirement[]): Promise<void>;
 export declare function readOwnedRequirements(cwd: string): Promise<OwnedRequirement[]>;
 export declare function parseOwnedRequirements(text: string): OwnedRequirement[];
 /** The owned entries whose plan title matches THIS task's title (normalised

package/dist/task/requirements.js

@@ -30,10 +30,8 @@
  * is exactly what gets injected, and compose's VERIFY rules fold it into every
  * applicable task's runnable verification.
  */
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
-import { tasksDir } from './task-io.js';
 import { normalise } from './contracts.js';
+import { makeLedger } from './ledger.js';
 const REQUIREMENTS_FILE = 'requirements.md';
 /** Cap kept entries so the injected block stays bounded on a large design. */
 const MAX_REQUIREMENTS = 40;
@@ -41,8 +39,22 @@ const MAX_REQUIREMENTS = 40;
 const MAX_REQUIREMENT_LENGTH = 300;
 /** Too short to state an obligation (and to ground unambiguously). */
 const MIN_QUOTE_LENGTH = 6;
+function carriedLineKey(line) {
+    const q = /"([^"]+)"/.exec(line);
+    return normalise(q ? q[1] : line);
+}
+const carried = makeLedger({
+    file: REQUIREMENTS_FILE,
+    max: MAX_REQUIREMENTS,
+    key: c => c.key,
+    serialize: c => c.line,
+    parse: raw => raw
+        .split('\n')
+        .filter(l => l.trim().length > 0)
+        .map(line => ({ line, key: carriedLineKey(line) }))
+});
 export function requirementsFile(cwd) {
-    return path.join(tasksDir(cwd), REQUIREMENTS_FILE);
+    return carried.path(cwd);
 }
 /** Parse `REQUIREMENT: "<quote>" [anchor: …]` lines (mirrors parseContractLines). */
 export function parseRequirementLines(text) {
@@ -485,12 +497,7 @@ export function accountCoverage(requirements, mappings) {
 // ─── The carried-requirements artifact + injection block ────────────────────
 /** The stored carried-requirements text ('' when none recorded). */
 export async function readRequirements(cwd) {
-    try {
-        return (await fsp.readFile(requirementsFile(cwd), 'utf8')).trim();
-    }
-    catch {
-        return '';
-    }
+    return carried.readRaw(cwd);
 }
 function formatEntry(e, marker) {
     const anchor = e.anchor ? ` [anchor: ${e.anchor}]` : '';
@@ -516,45 +523,23 @@ function formatEntry(e, marker) {
  *     judge areas they are host-authored strings, not source quotes.
  */
 export async function appendCarriedRequirements(cwd, crossCutting, unresolved = [], judgeFlagged = [], danglingArtifacts = []) {
-    if (crossCutting.length === 0
-        && unresolved.length === 0
-        && judgeFlagged.length === 0
-        && danglingArtifacts.length === 0) {
-        return;
-    }
-    try {
-        const existing = (await readRequirements(cwd)).split('\n').filter(l => l.trim().length > 0);
-        const seen = new Set(existing.map(l => {
-            const q = /"([^"]+)"/.exec(l);
-            return normalise(q ? q[1] : l);
-        }));
-        const merged = [...existing];
-        for (const [entries, marker] of [
-            [crossCutting, undefined],
-            [unresolved, 'no task owns this — surfaced at plan time'],
-            [
-                judgeFlagged.map(q => ({ quote: q, anchor: '' })),
-                'judge-flagged uncovered area, no task owns this — surfaced at plan time'
-            ],
-            [
-                danglingArtifacts.map(q => ({ quote: q, anchor: '' })),
-                'dangling runtime artifact, nothing produces it — surfaced at plan time'
-            ]
-        ]) {
-            for (const e of entries) {
-                const key = normalise(e.quote);
-                if (seen.has(key))
-                    continue;
-                seen.add(key);
-                merged.push(formatEntry(e, marker));
-            }
-        }
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(requirementsFile(cwd), merged.slice(-MAX_REQUIREMENTS).join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort artifact
+    const fresh = [];
+    for (const [entries, marker] of [
+        [crossCutting, undefined],
+        [unresolved, 'no task owns this — surfaced at plan time'],
+        [
+            judgeFlagged.map(q => ({ quote: q, anchor: '' })),
+            'judge-flagged uncovered area, no task owns this — surfaced at plan time'
+        ],
+        [
+            danglingArtifacts.map(q => ({ quote: q, anchor: '' })),
+            'dangling runtime artifact, nothing produces it — surfaced at plan time'
+        ]
+    ]) {
+        for (const e of entries)
+            fresh.push({ line: formatEntry(e, marker), key: normalise(e.quote) });
     }
+    await carried.append(cwd, fresh);
 }
 /**
  * The read-only block refine/compose receive when carried requirements exist.
@@ -593,31 +578,30 @@ export function buildRequirementsBlock(requirements) {
 // assigned to a task must travel INTO that task as verbatim authoritative text,
 // exactly like the cross-cutting channel that measurably works.
 const OWNED_REQUIREMENTS_FILE = 'requirements-owned.md';
+/**
+ * Uncapped and never appended to — the mapping is recomputed whole per plan
+ * round and rewritten by the DETACH/CLAIM passes, so the key is the quote only
+ * for the ledger's contract; nothing dedupes through it.
+ */
+const ownedLedger = makeLedger({
+    file: OWNED_REQUIREMENTS_FILE,
+    key: o => normalise(o.quote),
+    serialize: o => `OWNED: "${o.quote}"${o.anchor ? ` [anchor: ${o.anchor}]` : ''}`
+        + (o.pending && o.pending.length > 0 ? ` [pending: ${o.pending.join(', ')}]` : '')
+        + ` [title: ${o.title.replace(/\n/g, ' ')}]`,
+    parse: parseOwnedRequirements
+});
 export function ownedRequirementsFile(cwd) {
-    return path.join(tasksDir(cwd), OWNED_REQUIREMENTS_FILE);
+    return ownedLedger.path(cwd);
 }
 /** Persist the task-mapped requirements (host-side, plan time). Overwrites —
  *  the mapping is recomputed whole per plan round. Best-effort like the carried
  *  artifact. */
-export async function writeOwnedRequirements(cwd, owned) {
-    try {
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        const lines = owned.map(o => `OWNED: "${o.quote}"${o.anchor ? ` [anchor: ${o.anchor}]` : ''}`
-            + (o.pending && o.pending.length > 0 ? ` [pending: ${o.pending.join(', ')}]` : '')
-            + ` [title: ${o.title.replace(/\n/g, ' ')}]`);
-        await fsp.writeFile(ownedRequirementsFile(cwd), lines.join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort artifact
-    }
+export async function writeOwnedRequirements(cwd, entries) {
+    await ownedLedger.write(cwd, entries);
 }
 export async function readOwnedRequirements(cwd) {
-    try {
-        return parseOwnedRequirements(await fsp.readFile(ownedRequirementsFile(cwd), 'utf8'));
-    }
-    catch {
-        return [];
-    }
+    return ownedLedger.read(cwd);
 }
 export function parseOwnedRequirements(text) {
     const out = [];

package/dist/task/root-cause-repair.js

@@ -43,9 +43,7 @@
  * fails, it lands in the ledger like any other task and is never re-spawned, which
  * is what keeps this from looping.
  */
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
-import { tasksDir } from './task-io.js';
+import { makeLedger } from './ledger.js';
 /** A path-like token: at least one directory separator, ending in a file name. */
 const PATH_TOKEN_RE = /(?:[\w.@-]+\/)+[\w.@-]+\.\w+/g;
 /**
@@ -219,7 +217,7 @@ function normalisePath(p) {
 // `.pi-tasks/` — the same durability contract as accept-debt.ts: it survives
 // discardEdits and the git-state guard, and a resume picks up what a crash left.
 export function repairQueueFile(cwd) {
-    return path.join(tasksDir(cwd), REPAIR_QUEUE_FILE);
+    return ledger.path(cwd);
 }
 function serialize(c) {
     return [c.file, c.owner, c.blamedTask, c.verifyCommand ?? '', c.defect]
@@ -249,28 +247,22 @@ export function parseRepairQueue(raw) {
     }
     return out;
 }
+/**
+ * The queue. Keyed on file + blamed task ("cap 1 repair task per file per run" is
+ * enforced at drain; here a re-detection of the same accusation is a return, not a
+ * second record — hence `onNoop: 'skip'`).
+ */
+const ledger = makeLedger({
+    file: REPAIR_QUEUE_FILE,
+    max: MAX_QUEUED,
+    key: x => `${x.file.toLowerCase()} ${x.blamedTask.toLowerCase()}`,
+    serialize,
+    parse: parseRepairQueue,
+    onNoop: 'skip'
+});
 /** Append one candidate. Best-effort — the queue never blocks a gate. */
 export async function recordRepairCandidate(cwd, c) {
-    try {
-        const existing = parseRepairQueue(await readQueueRaw(cwd));
-        const key = (x) => `${x.file.toLowerCase()} ${x.blamedTask.toLowerCase()}`;
-        if (existing.some(e => key(e) === key(c)))
-            return;
-        const kept = [...existing, c].slice(-MAX_QUEUED);
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(repairQueueFile(cwd), kept.map(serialize).join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort ledger
-    }
-}
-async function readQueueRaw(cwd) {
-    try {
-        return (await fsp.readFile(repairQueueFile(cwd), 'utf8')).trim();
-    }
-    catch {
-        return '';
-    }
+    await ledger.append(cwd, [c]);
 }
 /**
  * Read the queue and CLEAR it. Draining is what makes the "cap 1 repair task per
@@ -279,16 +271,12 @@ async function readQueueRaw(cwd) {
  * {@link planHasRepairFor}) or was already covered by one.
  */
 export async function drainRepairQueue(cwd) {
-    const parsed = parseRepairQueue(await readQueueRaw(cwd));
+    const parsed = await ledger.read(cwd);
     if (parsed.length === 0)
         return [];
-    try {
-        await fsp.writeFile(repairQueueFile(cwd), '', 'utf8');
-    }
-    catch {
-        // best-effort; a failed clear at worst re-offers candidates that
-        // planHasRepairFor then rejects.
-    }
+    // Best-effort clear; a failed clear at worst re-offers candidates that
+    // planHasRepairFor then rejects.
+    await ledger.write(cwd, []);
     return parsed;
 }
 /**

package/dist/task/run-bracket.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The run bracket: what "a command owns the session" MEANS, in one place.
+ *
+ * Every long-running command — `/task`, `/task-auto`, `/task-auto-resume`,
+ * `/task-plan`, and `TaskRunner.run` inside all of them — spends most of its
+ * life with the host session idle: the spec phases, the planning children and
+ * every gate are child `pi` processes, not host turns. Two things must be true
+ * for exactly that window, and both are refcounted because the runs nest
+ * (`/task-auto` brackets its loop, each task inside brackets its own run):
+ *
+ *   1. mid-run input is HELD, not queued or turned into a competing turn
+ *      (`mid-run-input.ts`: `beginRun`/`endRun`);
+ *   2. the raw-stdin interception that makes the terminal behave like the
+ *      browser is ARMED (`cancel-input.ts`: `armCancelListener`/`disarm…`).
+ *
+ * Before this module the pair — begin, arm, … finally disarm, end, report the
+ * dropped lines — was written out at four sites in two files, and the `finally`
+ * halves disagreed on order (the orchestrator disarmed first; `/task-auto` ended
+ * first). The order is not observable — both halves are synchronous, the
+ * listener only consults `isRunActive()` on a keystroke, and no keystroke can
+ * land between two statements of one tick — so there is ONE order here, not an
+ * option: stop listening, then release the hold and report what it dropped.
+ *
+ * The two refcounts stay two, deliberately. `runDepth` is read by the remote
+ * bridge (`isRunActive`) with no ctx in hand and by the listener itself;
+ * `armed.depth` guards a live stdin subscription that is re-pointed on every
+ * session replacement (`rearmCancelListener`) and is armed on its own by the
+ * cancel-latency harness and cancel-points tests. Collapsing them means one
+ * module's counter driving the other's lifecycle, or a third counter with both
+ * modules demoted to flags — a wider change than the drift it prevents. What
+ * prevents drift now is that this bracket is the ONLY production caller of
+ * either pair.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+export interface RunBracketOptions {
+    /**
+     * Delivered when `/task-auto-cancel` is typed mid-run, with the ctx the
+     * listener is currently installed on (the captured one goes stale the moment
+     * a task replaces the session). The FIRST run to pass one wins for the whole
+     * nest — `/task-auto` passes one so its acknowledgement posts through the
+     * live ctx; a plain `/task` passes none and lets the generic bridge dispatch
+     * handle the command like any other.
+     */
+    onCancel?: (live: ExtensionCommandContext) => void;
+}
+/**
+ * Run `fn` as the owner of the session: hold mid-run input and arm the terminal
+ * interception for exactly its duration, then release both — on return AND on
+ * throw — and tell the user about any held line that never found a turn.
+ * Nests: an inner bracket neither re-renders the surfaces nor un-arms the outer.
+ */
+export declare function withRun<T>(ctx: ExtensionCommandContext, opts: RunBracketOptions, fn: () => Promise<T>): Promise<T>;
+export type AnnounceLevel = 'info' | 'warning' | 'error';
+export interface AnnounceOptions {
+    /**
+     * Also send a web push ("Task finished") to backgrounded devices. Default
+     * true — a run's terminal outcome is what a phone left on the desk needs to
+     * hear. `/task-plan` passes false: its cancelled/failed endings are the end
+     * of a CONVERSATION, before any task exists, and the plan that does hand off
+     * gets the run's own push from `/task`.
+     */
+    push?: boolean;
+}
+/**
+ * Say how a run ended, once, on every surface: the terminal toast, the remote
+ * session view (an error becomes a persistent red bubble; the rest a transient
+ * notify), and — unless opted out — a web push whose body is the exact terminal
+ * message, so a backgrounded phone learns the same thing the TUI shows.
+ *
+ * Terminal points ONLY: the overall `/task-auto` outcome, `/task`'s outcome
+ * after its gates, `/task-plan`'s failed or cancelled ending. Never per internal
+ * task — those run through `runSingleTask` without `notifyFinish` and stay
+ * silent.
+ */
+export declare function announceTerminal(ctx: ExtensionCommandContext, message: string, level: AnnounceLevel, opts?: AnnounceOptions): void;

package/dist/task/run-bracket.js

@@ -0,0 +1,41 @@
+import { armCancelListener, disarmCancelListener } from './cancel-input.js';
+import { beginRun, endRun } from './mid-run-input.js';
+import { reportDroppedInput } from './dropped-input.js';
+import { publishLifecycleNotice } from '../remote/bridge.js';
+import { pushNotify } from '../remote/push.js';
+/**
+ * Run `fn` as the owner of the session: hold mid-run input and arm the terminal
+ * interception for exactly its duration, then release both — on return AND on
+ * throw — and tell the user about any held line that never found a turn.
+ * Nests: an inner bracket neither re-renders the surfaces nor un-arms the outer.
+ */
+export async function withRun(ctx, opts, fn) {
+    beginRun();
+    armCancelListener(ctx, opts.onCancel);
+    try {
+        return await fn();
+    }
+    finally {
+        disarmCancelListener();
+        reportDroppedInput(endRun(), ctx);
+    }
+}
+/**
+ * Say how a run ended, once, on every surface: the terminal toast, the remote
+ * session view (an error becomes a persistent red bubble; the rest a transient
+ * notify), and — unless opted out — a web push whose body is the exact terminal
+ * message, so a backgrounded phone learns the same thing the TUI shows.
+ *
+ * Terminal points ONLY: the overall `/task-auto` outcome, `/task`'s outcome
+ * after its gates, `/task-plan`'s failed or cancelled ending. Never per internal
+ * task — those run through `runSingleTask` without `notifyFinish` and stay
+ * silent.
+ */
+export function announceTerminal(ctx, message, level, opts = {}) {
+    ctx.ui.notify(message, level);
+    // ctx.ui.notify is terminal-only and pushNotify is a backgrounded-device web
+    // push — neither shows up in a remote viewer that's watching live.
+    publishLifecycleNotice(message, level);
+    if (opts.push !== false)
+        void pushNotify('Task finished', message, 'pi-end').catch(() => { });
+}

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

@@ -0,0 +1,110 @@
+/**
+ * Progress-based runaway guard for phase children — the replacement for a
+ * wall-clock cap.
+ *
+ * WHY NOT SECONDS. PHASE_CHILD_TIMEOUT_MS was sized against "measured HEALTHY
+ * planning children" on one local backend: decompose 89s, so 600s looked like a
+ * 6x margin. That sizing is not a property of the pathology, it is a property of
+ * that day's model, that day's samplers and that day's design doc. Measured on
+ * the same 27B backend with reasoning ON (2026-08-17, n=10 replays of one
+ * captured auto-decompose request, everything else byte-identical): every single
+ * healthy run took 610-927s and produced 26-42 correct titles. The cap would
+ * have killed 10 out of 10 GOOD runs. A slower model, a bigger design doc or a
+ * longer reasoning budget moves that number again — so any constant in seconds
+ * is wrong for someone.
+ *
+ * WHAT REPLACES IT. Two bounds, both dimensionless — invariant to model speed,
+ * project size and reasoning budget:
+ *
+ *   1. NO NEW GROUND. Count CONSECUTIVE tool calls whose RESULT taught the child
+ *      nothing: an error, or bytes it has already been given. A child paging
+ *      forward through a 25 KB design file gets different bytes every call and
+ *      never trips, however slow it is. A child re-opening the same four files
+ *      trips after NO_PROGRESS_LIMIT of them, however fast it is.
+ *
+ *      Judged on the RESULT, not the arguments, because the arguments lie. The
+ *      thrash measured on 2026-08-17 was 197 of 200 calls REFUSED by the
+ *      single-read guard, each at a different rising offset — so by arguments it
+ *      looked like textbook forward paging, and both an offset rule and the loop
+ *      detector's path rule waved all 200 through. By result it is 197 identical
+ *      refusals in a row, which is what it actually was.
+ *
+ *   2. CONTEXT CHURN. Sum the bytes of tool RESULTS the child has pulled in. Once
+ *      that exceeds CONTEXT_CHURN_FACTOR times its own context window and it
+ *      still has not answered, it has necessarily forgotten what it read first
+ *      and is re-reading to fill a window pi keeps compacting. That is the
+ *      mx5-n 2026-08-14 shape: 16m23s at 117,370 of a 120,064-token window,
+ *      ~56k tokens of tool output per minute, forward-paging the whole time so
+ *      rule 1 alone would not have caught it. The bound scales with the model's
+ *      OWN window, so a 1M-context model gets a 1M-context allowance.
+ *
+ * Neither rule can fire on a child that is thinking rather than calling tools:
+ * that case is bounded by the model's max tokens (server-enforced) and by the
+ * stream watchdog if the stream goes silent. Between the three there is no
+ * runaway left that needs a clock.
+ *
+ * Pure logic, no I/O, no timers. LoopDetector (loop-detector.ts) is the
+ * short-window sibling that trips FAST on an exact repeat; this is the
+ * whole-run backstop that trips on sustained non-progress.
+ */
+import type { LoopHit, ToolCall } from '../shared/child-process.js';
+/**
+ * Consecutive no-new-ground tool results before the child is killed.
+ *
+ * Eight, because the honest reasons to get back something you have already seen
+ * are few and bounded: re-checking a file after an edit, a grep that lands in a
+ * file already read, a retry after a malformed call, a missing path. A child
+ * doing real work interleaves those with progress and resets the counter. In the
+ * replayed thrash the counter never resets at all — the observed runs made
+ * 188-201 consecutive dead calls. The gap between "a handful" and "two hundred"
+ * is wide enough that the exact value is not load-bearing.
+ */
+export declare const NO_PROGRESS_LIMIT = 8;
+/**
+ * Multiples of the child's OWN context window of tool output it may pull before
+ * being called stuck. Two, so a child is allowed to fill its window once and
+ * still have a whole window of budget left for legitimate re-reading after pi
+ * compacts. Past that it is provably re-reading what it can no longer hold.
+ */
+export declare const CONTEXT_CHURN_FACTOR = 2;
+/** Which rule tripped, so the caller can hint at the right mistake. */
+export type StallKind = 'no-new-ground' | 'context-churn';
+export declare class StallDetector {
+    private readonly limit;
+    private readonly churnFactor;
+    /** Every distinct result the child has been handed, for the WHOLE run. */
+    private readonly seenResults;
+    /** Exact (name, args) keys already issued — the fallback signal for a
+     *  transport that reports calls but not results. */
+    private readonly seenCalls;
+    private deadStreak;
+    private resultChars;
+    private contextWindow;
+    constructor(limit?: number, churnFactor?: number);
+    /**
+     * Record a tool call. Returns a LoopHit (tagged with `stall`) when either
+     * rule has tripped, so it rides the kill/restart path the loop detector
+     * already has, else null.
+     *
+     * The verdict is read here but EARNED in noteResult: this is the hook the
+     * child runner can kill from, and a result only arrives after its call has
+     * been let through.
+     */
+    record(call: ToolCall): LoopHit | null;
+    /**
+     * A tool call finished. Its result is what actually entered the context, so
+     * it — not the arguments — decides whether the child learned anything. An
+     * error, or bytes already handed over earlier in this run, is dead ground.
+     */
+    noteResult(text: string, isError?: boolean): void;
+    /** Latest context-window size reported by the child. 0 until one arrives. */
+    noteContext(contextWindow: number): void;
+    private churnTripped;
+}
+/**
+ * Restart hint for a child killed by the stall detector. Names the specific
+ * mistake — re-reading covered ground vs pulling in more than it can hold —
+ * because "you ran out of time" (the old wall-clock hint) told a model that was
+ * working correctly but slowly to truncate its work for no reason.
+ */
+export declare function formatStallHint(kind: StallKind): string;