@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/git-state-guard.js

@@ -2,41 +2,43 @@
  * git-state-guard — deterministic repo-state snapshot/reconcile around the
  * read-only gate children (verify, recommend).
  *
- * The failure this closes (proven twice on mx5): those children hold a `read,bash`
- * contract whose "never modify the tree" clause is prompt-level only, and the live
- * local model breaks it. Run 6's verify child ran `git stash; git checkout HEAD~1;
- * tsc; git checkout HEAD` with NO pop — the task's whole uncommitted implementation
- * vanished into a stash, the verify judged an empty tree (a full re-implementation
- * was burned), and the orphaned stash detonated two days later when a later impl
- * turn popped it onto a 14-commits-newer HEAD (unresolvable UU conflict, the
- * /task-auto checklist reverted to a stale state). The same child has been observed
- * running `eslint --fix .` mid-verification and ad-hoc DDL against the test DB.
+ * Those children hold a `read,bash` contract whose "never modify the tree" clause
+ * is PROMPT-LEVEL ONLY: `bash` can stash, check out, commit and rewrite files, and
+ * nothing but the prompt says not to. A child that stashes the task's uncommitted
+ * work and never pops it leaves the verify judging an empty tree AND leaves an
+ * orphan stash that only detonates when something later pops it onto a moved HEAD.
+ * So this is capability-shaped rather than prompt-shaped: snapshot the repo state
+ * BEFORE the child runs, deterministically restore whatever it moved afterwards,
+ * no model in the loop.
  *
- * Prompt rules are evidence-insufficient for this class (FROZEN-CONTRACT framing
- * A/B'd 0–1/5 compliance), so this is a capability-shaped fix: snapshot the repo
- * state BEFORE the child runs, and afterwards deterministically restore anything
- * it moved — no model in the loop.
- *
- * What is captured / reconciled:
- *   - HEAD (sha + symbolic branch ref): a child that checked out another commit
- *     and never came back is checked back out.
- *   - The WORKTREE CONTENT as a git tree object, built through a temporary index
- *     (`read-tree --empty` + `add -A` + `write-tree`, excluding .pi-tasks — the
- *     gate's own debug logs land there DURING the run). This snapshots tracked
- *     *and* untracked (non-ignored) files without touching the real index or the
- *     stash. Restoration re-materialises every changed/deleted file from the
- *     snapshot tree and deletes files the child created.
+ * What is captured and reconciled — each one run against a real repo:
+ *   - HEAD (sha + symbolic branch ref). A child that checked out another commit,
+ *     detached, is put back on its branch AND its sha. LIMIT: a child that COMMITS
+ *     on the current branch is NOT undone — the restore checks out
+ *     `before.branchRef`, and that branch now points at the child's commit, so the
+ *     `checked HEAD back out to <branch>` line is honest about the ref and says
+ *     nothing about the sha. The move is still classed verdict-tainting, so the
+ *     verdict is discarded; the commit stays.
+ *   - The WORKTREE CONTENT as a git tree object, built through a THROWAWAY index
+ *     (`read-tree --empty` + `add -A` + `write-tree`, excluding `.pi-tasks` — the
+ *     gate's own debug logs land there DURING the run). Measured on a repo with a
+ *     staged file, an untracked file, a gitignored file and a `.pi-tasks/` log: the
+ *     tree holds the tracked and untracked files and neither of the other two, and
+ *     the REAL index still shows the same staged path afterwards. Restoration
+ *     re-materialises every changed or deleted file and deletes what the child
+ *     created.
  *   - The STASH ref: entries the child pushed are dropped AFTER the worktree is
- *     restored from the snapshot (the snapshot, not the stash, is the source of
- *     truth), so no landmine stash survives the reconcile.
+ *     restored from the snapshot — the snapshot, not the stash, is the source of
+ *     truth — so no orphan stash survives the reconcile.
  *
  * The real index's staging state is deliberately NOT restored: pre-commit gate
  * children run against a tree whose work is unstaged, and the auto-commit that
- * follows re-stages everything with `add -A` anyway.
+ * follows re-stages everything with `git add -A` (auto-commit.ts:192).
  *
- * Everything is best-effort: a repo where git itself fails (not a work tree, git
- * missing) disables the guard (capture returns ok:false and reconcile no-ops) —
- * the gate must keep working in non-git projects exactly as before.
+ * Everything is best-effort: a repo where git fails disables the guard — capture
+ * returns `ok: false` and reconcile no-ops. Measured: a fresh `git init` with no
+ * commits answers non-zero to `rev-parse -q --verify HEAD`, which is the unborn-HEAD
+ * case the capture bails on.
  */
 import { readFileSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
@@ -48,29 +50,30 @@ import { isRegenerableArtifact } from './regenerable-artifacts.js';
 const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
 /**
  * Untracked paths that are regenerable test/build OUTPUT, not graded source. A gate
- * child creating or rewriting one of these has not mutated the work under judgement,
- * so its verdict stands. Gitignored files never reach the snapshot (git add -A skips
- * them); this list is for the ones a typical project leaves UNIGNORED — Playwright's
- * `test-results/` and `playwright-report/` above all, the exact churn that discarded
- * verify verdicts across mx5 run 9. Kept deliberately narrow: anything not matched
- * here that a child modifies/deletes is treated as graded state (verdict-tainting).
+ * child creating or rewriting one of these has not mutated the work under
+ * judgement, so its verdict stands. Gitignored files never reach the snapshot at
+ * all — measured, `add -A` skips them — so this list is for the ones a typical
+ * project leaves UNIGNORED, `test-results/` and `playwright-report/` above all.
+ * Kept deliberately narrow: anything NOT matched here that a child modifies or
+ * deletes is graded state, and taints the verdict.
  *
- * The list itself now lives in `regenerable-artifacts.ts` — the deletion guard and
- * the per-task commit need the same knowledge, and three private copies of it is
- * how mx5 run 20 spent two thirds of its repair budget on three screenshots.
+ * The list lives in `regenerable-artifacts.ts` because three call sites need the
+ * same knowledge — this guard, the write-guard's deletion check, and the per-task
+ * commit — and three private copies would drift.
  */
 const isBenignArtifact = isRegenerableArtifact;
 /**
- * Regenerable machine state that is benign EVEN WHEN TRACKED — a project that
- * mistakenly commits it (mx5 run 10 does exactly this) must not have a gate child's
- * incidental rewrite of it discard the verdict. Two classes:
- *   - Playwright component-test build cache (`ctCacheDir` — run 10 committed 60+
- *     `.playwright-cache/assets/*.js` bundles; a `test:ct` run rewrites them every
- *     time), and
- *   - the test runner's `.last-run.json` run-state file.
- * DELIBERATELY narrow: snapshot BASELINE images (`*-snapshots/*.png`) are NOT here —
+ * Regenerable machine state that is benign EVEN WHEN TRACKED, so a project that
+ * commits it does not have a child's incidental rewrite discard the verdict. Two
+ * classes: the component-test build cache under `ctCacheDir`, which a component
+ * test run rewrites every time, and the test runner's `.last-run.json` run-state
+ * file.
+ *
+ * DELIBERATELY narrow. Snapshot BASELINE images (`*-snapshots/*.png`) are NOT here:
  * a child that rewrites a baseline to make a screenshot test pass is the real
- * mutate-to-pass catch (run 10's other half), so those stay verdict-tainting.
+ * mutate-to-pass catch. Measured on a real repo — a tracked file under a custom
+ * `ctCacheDir` and a tracked `.last-run.json` both restore WITHOUT tainting, while
+ * a tracked `tests/a-snapshots/x.png` taints.
  */
 const ALWAYS_REGENERABLE_PATTERNS = [/(?:^|\/)\.last-run\.json$/];
 /** Playwright config files that may declare a custom `ctCacheDir`. */
@@ -80,7 +83,10 @@ const CT_CONFIG_FILES = [
     'playwright.config.ts',
     'playwright.config.js'
 ];
-/** ctCacheDir defaults Playwright uses when a config does not override it. */
+/** The ctCacheDir values assumed when no config declares one. Playwright is not a
+ *  dependency here, so these are not verifiable against an installed package —
+ *  what IS verified is that a config declaring `ctCacheDir: './custom-cache/'` is
+ *  parsed and its directory treated as regenerable. */
 const DEFAULT_CT_CACHE_DIRS = ['.playwright-cache', 'playwright/.cache'];
 /**
  * The component-test cache dir(s) for this project: the `ctCacheDir` any Playwright
@@ -183,14 +189,15 @@ function pushCapped(actions, verb, paths) {
 }
 /**
  * Restore every file recorded in `beforeTree` (content + deletions) and remove
- * files that exist in `afterTree` but not in `beforeTree` (files the child
- * created). Uses a throwaway index seeded from the snapshot tree; `checkout-index
+ * files that exist in `afterTree` but not in `beforeTree` — the ones the child
+ * created. Uses a throwaway index seeded from the snapshot tree; `checkout-index
  * -a -f` re-materialises the snapshot verbatim.
  *
- * Returns whether any restored change was *verdict-tainting* — a modified/deleted
- * path that is tracked-in-HEAD or an untracked non-artifact (see isBenignArtifact).
- * Creations and test-runner-artifact churn restore identically but do NOT taint.
- * Each changed path is itemised (capped) so the gate trail says WHICH files moved.
+ * Returns whether any restored change was *verdict-tainting*: a modified or
+ * deleted path that is tracked-in-HEAD, or an untracked non-artifact (see
+ * isBenignArtifact). Creations and test-runner-artifact churn restore identically
+ * but do NOT taint. Each changed path is itemised, capped, so the gate trail says
+ * WHICH files moved.
  */
 async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, ctCacheDirs, actions) {
     const tmpIndex = path.join(os.tmpdir(), `pi-task-guard-restore-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
@@ -209,8 +216,11 @@ async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, ctCache
                 const trimmed = line.trim();
                 if (trimmed.length === 0)
                     continue;
-                // "M\tpath", "A\tpath", "D\tpath", "T\tpath" — no -M, so renames show
-                // as a D + an A pair; both get classified on their own merits.
+                // "M\tpath", "A\tpath", "D\tpath", "T\tpath" — no -M, so a rename
+                // shows as a D + an A pair and each half is classified on its own
+                // merits. Measured: renaming a tracked `a.txt` to `b.txt` yields
+                // "removed child-created file b.txt" plus "restored deleted file
+                // a.txt", and taints.
                 const tab = trimmed.indexOf('\t');
                 if (tab < 0)
                     continue;
@@ -225,7 +235,7 @@ async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, ctCache
                     || (isBenignArtifact(name) && !tracked.has(name))) {
                     // Regenerable test/build output — not graded work. Either an
                     // always-regenerable class (ct cache / run-state, benign even when
-                    // tracked — mx5 run 10) or untracked test-runner output.
+                    // tracked) or untracked test-runner output.
                     artifactChanges.push(name);
                 }
                 else if (code === 'D') {
@@ -268,11 +278,11 @@ async function restoreWorktree(cwd, git, beforeTree, afterTree, tracked, ctCache
  * whatever a gate child moved. Ordering matters:
  *
  *   1. HEAD first — a child parked on another commit must be back on the original
- *      ref before the worktree comparison/restore makes sense.
- *   2. Worktree content from the snapshot TREE (not from any stash the child may
- *      have pushed — the snapshot is the authoritative "as the child found it").
- *   3. Child-pushed stash entries are dropped LAST, once the work they swallowed
- *      is already restored — this is exactly the orphan that detonated mx5 run 6.
+ *      ref before the worktree comparison and restore make sense.
+ *   2. Worktree content from the snapshot TREE, never from a stash the child may
+ *      have pushed: the snapshot is the authoritative "as the child found it".
+ *   3. Child-pushed stash entries are dropped LAST, once the work they swallowed is
+ *      already restored — dropping first would destroy the only other copy.
  *
  * Never throws; failures degrade to actions[] lines so the caller can log them.
  */
@@ -308,9 +318,9 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
         }
     }
     // 3. Stash entries the child pushed. Drop stash@{0} until the ref matches the
-    //    snapshot again (bounded — a child pushes at most a handful; 10 is beyond
-    //    anything observed). A stash the child POPPED (ref gone/behind) cannot be
-    //    reconstructed — report it instead of guessing.
+    //    snapshot again, bounded at 10 so a runaway cannot loop here. A stash the
+    //    child POPPED — the ref is gone or no longer contains the snapshot's tip —
+    //    cannot be reconstructed, so report it instead of guessing.
     const stashNow = async () => {
         const s = await git(['rev-parse', '-q', '--verify', 'refs/stash']);
         return s.exitCode === 0 ? s.stdout.trim() : null;
@@ -318,7 +328,7 @@ export async function reconcileGitState(cwd, before, signal, spawnFn) {
     let stash = await stashNow();
     if (stash !== before.stashSha) {
         // A child that pushed/popped a stash moved graded work in or out of the tree
-        // (mx5 run 6's stash-and-abandon) — always verdict-tainting.
+        // (a stash-and-abandon) — always verdict-tainting.
         tainted = true;
         if (before.stashSha === null || (await stashContains(git, stash, before.stashSha))) {
             let dropped = 0;

package/dist/task/impl-widget.d.ts

@@ -1,24 +1,30 @@
 /**
  * Implementation-turn status widget.
  *
- * The phase widget (widget.ts) is disposed at spec-handoff, so the host agent's
- * implementation turn — the longest, most visible part of a run — otherwise shows
- * only pi's bare "⠸ Working…" indicator. This module keeps the SAME rich status
- * block alive across that turn (task id · implementing/elapsed/context bar · ↳ last
- * tool), driven by the host's own live `ctx.getContextUsage()`.
+ * `TaskRunner._deliverSpec` is preceded by `_disposeWidget()`, so the phase widget
+ * (widget.ts) is gone before the spec is handed off. Without this module the host
+ * agent's implementation turn — the longest, most visible part of a run — would
+ * show only pi's own working indicator, whose default message is the literal
+ * `"Working..."`. This keeps the SAME rich status block alive across that turn
+ * (task id · implementing/elapsed/context bar · ↳ last tool), driven by the host's
+ * own live `ctx.getContextUsage()`, which pi declares as
+ * `getContextUsage(): ContextUsage | undefined`.
  *
- * It is event-driven rather than poll-wrapped because the two delivery paths differ:
+ * Event-driven rather than poll-wrapped, because the two delivery paths differ:
  *
- *   • /task (fire-and-forget): the command returns right after `sendUserMessage`,
- *     so the host runs the impl turn AFTER our code is gone — only an `agent_start`
- *     handler can pick it up. Armed one-shot: `agent_end` disarms it.
- *   • /task-auto (awaited): the caller blocks across `waitForIdle` plus any
- *     compaction-resume / steer turns. Armed sticky: each `agent_start` re-shows the
- *     widget, `agent_end` only hides it between turns, and the caller disarms once
- *     the whole implementation phase has settled.
+ *   • /task (fire-and-forget): the command returns right after
+ *     `piApi.sendUserMessage(spec, {deliverAs: 'followUp'})`, so the host runs the
+ *     impl turn AFTER this code is gone and only an `agent_start` handler can pick
+ *     it up. Armed one-shot, and `agent_end` disarms it.
+ *   • /task-auto (awaited): the caller blocks across `waitForIdle` plus any resume
+ *     or steer turns. Armed sticky — each `agent_start` re-shows the widget,
+ *     `agent_end` only hides it between turns, and the caller disarms in a
+ *     `finally` once the whole implementation phase has settled.
  *
- * Only one task runs at a time (single active task), so a single module-level slot
- * is sufficient.
+ * `_deliverSpec` picks between them with `oneShot: !this._implAwaited`.
+ *
+ * A single module-level slot is enough because only one task runs at a time —
+ * `orchestrator.ts` keeps one module-level `activeTask`.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 export interface ImplWidgetMeta {
@@ -36,5 +42,8 @@ export declare function armImplWidget(meta: ImplWidgetMeta, opts: {
 }): void;
 /** Tear down the widget and clear the armed slot (sticky/awaited path). */
 export declare function disarmImplWidget(): void;
-/** Wire the agent-lifecycle handlers that drive the widget. Call once at setup. */
+/** Wire the agent-lifecycle handlers that drive the widget. Call once at setup.
+ *  All three events are pi's own: `agent_start`, `tool_execution_start` and
+ *  `agent_end` each have an `on()` overload, and ToolExecutionStartEvent carries
+ *  the `toolName` and `args` read below. */
 export declare function setupImplWidget(pi: ExtensionAPI): void;

package/dist/task/impl-widget.js

@@ -1,24 +1,30 @@
 /**
  * Implementation-turn status widget.
  *
- * The phase widget (widget.ts) is disposed at spec-handoff, so the host agent's
- * implementation turn — the longest, most visible part of a run — otherwise shows
- * only pi's bare "⠸ Working…" indicator. This module keeps the SAME rich status
- * block alive across that turn (task id · implementing/elapsed/context bar · ↳ last
- * tool), driven by the host's own live `ctx.getContextUsage()`.
+ * `TaskRunner._deliverSpec` is preceded by `_disposeWidget()`, so the phase widget
+ * (widget.ts) is gone before the spec is handed off. Without this module the host
+ * agent's implementation turn — the longest, most visible part of a run — would
+ * show only pi's own working indicator, whose default message is the literal
+ * `"Working..."`. This keeps the SAME rich status block alive across that turn
+ * (task id · implementing/elapsed/context bar · ↳ last tool), driven by the host's
+ * own live `ctx.getContextUsage()`, which pi declares as
+ * `getContextUsage(): ContextUsage | undefined`.
  *
- * It is event-driven rather than poll-wrapped because the two delivery paths differ:
+ * Event-driven rather than poll-wrapped, because the two delivery paths differ:
  *
- *   • /task (fire-and-forget): the command returns right after `sendUserMessage`,
- *     so the host runs the impl turn AFTER our code is gone — only an `agent_start`
- *     handler can pick it up. Armed one-shot: `agent_end` disarms it.
- *   • /task-auto (awaited): the caller blocks across `waitForIdle` plus any
- *     compaction-resume / steer turns. Armed sticky: each `agent_start` re-shows the
- *     widget, `agent_end` only hides it between turns, and the caller disarms once
- *     the whole implementation phase has settled.
+ *   • /task (fire-and-forget): the command returns right after
+ *     `piApi.sendUserMessage(spec, {deliverAs: 'followUp'})`, so the host runs the
+ *     impl turn AFTER this code is gone and only an `agent_start` handler can pick
+ *     it up. Armed one-shot, and `agent_end` disarms it.
+ *   • /task-auto (awaited): the caller blocks across `waitForIdle` plus any resume
+ *     or steer turns. Armed sticky — each `agent_start` re-shows the widget,
+ *     `agent_end` only hides it between turns, and the caller disarms in a
+ *     `finally` once the whole implementation phase has settled.
  *
- * Only one task runs at a time (single active task), so a single module-level slot
- * is sufficient.
+ * `_deliverSpec` picks between them with `oneShot: !this._implAwaited`.
+ *
+ * A single module-level slot is enough because only one task runs at a time —
+ * `orchestrator.ts` keeps one module-level `activeTask`.
  */
 import { WIDGET_KEY, WIDGET_REFRESH_MS, buildImplLines, buildImplData } from './widget.js';
 import { setTaskWidget } from '../remote/session-state.js';
@@ -27,7 +33,8 @@ let lastLine;
 let timer = null;
 let activeCtx = null;
 /** Map the host's live context usage to the widget snapshot, or undefined when the
- *  token count is unknown (e.g. right after compaction, before the next response). */
+ *  token count is unknown. pi types `ContextUsage.tokens` as `number | null` and
+ *  documents the null as "right after compaction, before next LLM response". */
 function snapshot(ctx) {
     const u = ctx.getContextUsage?.();
     if (!u || u.tokens == null)
@@ -100,7 +107,10 @@ export function disarmImplWidget() {
     activeCtx = null;
     lastLine = undefined;
 }
-/** Wire the agent-lifecycle handlers that drive the widget. Call once at setup. */
+/** Wire the agent-lifecycle handlers that drive the widget. Call once at setup.
+ *  All three events are pi's own: `agent_start`, `tool_execution_start` and
+ *  `agent_end` each have an `on()` overload, and ToolExecutionStartEvent carries
+ *  the `toolName` and `args` read below. */
 export function setupImplWidget(pi) {
     pi.on('agent_start', (_event, ctx) => {
         if (!armed)

package/dist/task/implementation-guards.d.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/** `oneShot` mirrors the impl widget's split: fire-and-forget lets the settle
+ *  event disarm; an awaited run spans resume/steer turns and disarms in its finally. */
+export declare function armImplementationGuard(opts: {
+    oneShot: boolean;
+}): void;
+export declare function disarmImplementationGuard(): void;
+/** @internal Test seam: is a turn currently guarded? */
+export declare function implementationGuardArmed(): boolean;
+/**
+ * Present tense, unlike `formatLoopHint`, which addresses a re-spawned child
+ * about an attempt that does not exist here.
+ *
+ * It claims nothing about the call's RESULT, which this hook fires too early to
+ * see, and it does not offer "change the call" — that is an escape, not advice:
+ * one altered byte is a new key and a clean slate on both counters.
+ */
+export declare function blockedCallReason(toolName: string, count: number): string;
+/** The reason on the final block, which also ends the turn. */
+export declare function terminalCallReason(): string;
+export declare function consumeGuardTermination(): boolean;
+/**
+ * Inert until armed. Registering ANY `tool_call` handler switches on pi's
+ * `beforeToolCall` for every call in the session, so the armed check comes first.
+ */
+export declare function registerImplementationGuards(pi: ExtensionAPI): void;

package/dist/task/implementation-guards.js

@@ -0,0 +1,177 @@
+import { LoopDetector, loopKey, LOOP_THRESHOLD, LOOP_WINDOW, MAX_LOOP_RESTARTS } from './loop-detector.js';
+/**
+ * Runaway guard for the IMPLEMENTATION TURN — the one model surface with none.
+ *
+ * MEASURED: one turn ran 5h16m and 6,760 tool calls, alternating two
+ * byte-identical bash commands 3,300 times each with its output frozen and zero
+ * edits. The command watchdog is per call (each took ~2.5s), the stream was never
+ * silent, and MAX_COMPACTION_RESUMES counts only compactions that PARK at idle,
+ * while all 18 of these were inside the turn. The two detectors are built only in
+ * the CHILD spawn paths, and this turn runs in the user's own session.
+ *
+ * IT BLOCKS RATHER THAN KILLS because there is no re-spawn here — the argument
+ * single-read-extension.ts already makes: "detect-and-kill only re-spawns a model
+ * that deterministically re-thrashes". pi's ctx.abort() would also empty the
+ * queued-message list into the user's editor. That also raises the bar on false
+ * positives: a `gate` child killed by mistake costs one attempt of three, this
+ * costs the user their turn.
+ *
+ * WHY PROGRESS IS READ OFF THE CALL, NOT THE RESULT. The gate profile pairs its
+ * LoopDetector with a StallDetector, which judges results. That cannot work here:
+ * pi's edit tool returns the constant `Successfully replaced N block(s) in <path>.`
+ * and puts the diff in `details`, not `content`, so every real edit to one file is
+ * byte-identical result text and scores as dead ground. An edit's ARGUMENTS carry
+ * the progress its result throws away, so an edit is what resets the window.
+ *
+ * Known blind spots, all deliberate: a bash-driven mutation (`sed -i`, `>`,
+ * `git apply`) does not reset; one varying `write` per iteration buys unlimited
+ * immunity; a repeat cycle of LOOP_WINDOW/LOOP_THRESHOLD or longer never fills the
+ * window; polling a booting server with an identical curl trips at five; and
+ * schema-invalid calls never reach this hook at all, since pi validates first.
+ */
+/** Tool names that mutate the tree. pi ships exactly seven core tools, and
+ *  pi-task's own four (pi-worker, -search, -fetch, -docs) are all read-only. */
+const MUTATING_TOOLS = new Set(['edit', 'write']);
+/**
+ * Path-revisit is OFF for both detectors (that is the Infinity). MEASURED: at the
+ * default threshold, six DISTINCT edits to one file trip the path rule, because
+ * an edit names a `file_path` and no `limit`, so the first one sets the
+ * high-water mark and every later one scores as already-covered ground. Six edits
+ * to one file is the most ordinary thing an implementation turn does. mx5
+ * TASK_0002 is the same lesson from the other side: the rule killed an enforce
+ * child that was editing one file as its job.
+ */
+function freshDetector() {
+    return new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD, Number.POSITIVE_INFINITY);
+}
+/** The armed turn's state, or null outside one. One slot: one task runs at a time. */
+let armed = null;
+/** Built, never spread from the previous state: a leaked `terminating` would
+ *  block every call for the rest of an awaited run. */
+function freshArmedState(oneShot) {
+    return {
+        loop: freshDetector(),
+        edits: freshDetector(),
+        strikes: new Map(),
+        terminating: false,
+        oneShot
+    };
+}
+/** `oneShot` mirrors the impl widget's split: fire-and-forget lets the settle
+ *  event disarm; an awaited run spans resume/steer turns and disarms in its finally. */
+export function armImplementationGuard(opts) {
+    armed = freshArmedState(opts.oneShot);
+}
+export function disarmImplementationGuard() {
+    armed = null;
+}
+/** @internal Test seam: is a turn currently guarded? */
+export function implementationGuardArmed() {
+    return armed !== null;
+}
+/**
+ * Present tense, unlike `formatLoopHint`, which addresses a re-spawned child
+ * about an attempt that does not exist here.
+ *
+ * It claims nothing about the call's RESULT, which this hook fires too early to
+ * see, and it does not offer "change the call" — that is an escape, not advice:
+ * one altered byte is a new key and a clean slate on both counters.
+ */
+export function blockedCallReason(toolName, count) {
+    return (`Blocked: this is the ${count}th identical ${toolName} call in this turn. `
+        + `Use what you already have, or do something different, then continue the task.`);
+}
+/** The reason on the final block, which also ends the turn. */
+export function terminalCallReason() {
+    return (`Blocked: this turn repeated one call past every warning, so it is being stopped `
+        + `here. Nothing further will run.`);
+}
+/**
+ * One-shot: the guard ended a turn, and nothing in the session state says so.
+ *
+ * `terminate` lets the agent loop finish normally — the last assistant message
+ * keeps `stopReason: "toolUse"`, so `classifyTurnEnd` reads `'stop'` and the run
+ * reports a clean finish over work that was cut off mid-task. Verified against a
+ * live model: a real guard-terminated turn ends exactly that way. Same shape as
+ * `consumeWatchdogAbort`, and consumed for the same reason — one reader, then it
+ * is gone.
+ */
+let terminatedTurn = false;
+export function consumeGuardTermination() {
+    const hit = terminatedTurn;
+    terminatedTurn = false;
+    return hit;
+}
+/**
+ * Inert until armed. Registering ANY `tool_call` handler switches on pi's
+ * `beforeToolCall` for every call in the session, so the armed check comes first.
+ */
+export function registerImplementationGuards(pi) {
+    pi.on('tool_call', event => {
+        const state = armed;
+        if (!state)
+            return;
+        try {
+            // Every call, whatever it is: pi terminates only when EVERY finalized
+            // result in the batch carries the flag (agent-loop.js
+            // shouldTerminateToolBatch). The batch that trips it has already
+            // finalized its earlier calls without it and so survives; the next one
+            // ends. One batch, and it is the only bound this path has.
+            if (state.terminating) {
+                return { block: true, terminate: true, reason: terminalCallReason() };
+            }
+            const call = { name: event.toolName, args: event.input };
+            const mutating = MUTATING_TOOLS.has(event.toolName);
+            const hit = mutating ? state.edits.record(call) : state.loop.record(call);
+            if (!hit) {
+                if (mutating) {
+                    state.loop = freshDetector();
+                    // Strikes go with the window. Keeping them made a LATER episode
+                    // terminate on its first hit, skipping both warnings, because an
+                    // earlier one had part-spent the budget. MEASURED over 494 real
+                    // turns: this loses no catch — the incident still ends at call
+                    // 173 of 6,760, both live-model loops still end — and drops one
+                    // termination of a turn that was editing between episodes.
+                    // A determined model is still bounded: three hits inside ONE
+                    // episode terminate, which is the runaway shape (it makes no
+                    // edits at all).
+                    state.strikes.clear();
+                }
+                return;
+            }
+            const key = loopKey(call);
+            const strikes = (state.strikes.get(key) ?? 0) + 1;
+            state.strikes.set(key, strikes);
+            // Blocking alone does not stop a determined model: nothing prevents the
+            // next identical call.
+            if (strikes > MAX_LOOP_RESTARTS) {
+                state.terminating = true;
+                terminatedTurn = true;
+                return { block: true, terminate: true, reason: terminalCallReason() };
+            }
+            return { block: true, reason: blockedCallReason(event.toolName, hit.count) };
+        }
+        catch {
+            // pi does not guard this hook, and a throw here would block a
+            // legitimate call. A broken guard must cost nothing.
+            return;
+        }
+    });
+    // NOT `agent_end`, which fires again for every auto-retry, every threshold
+    // compaction and every queued message — pi drives those with `agent.continue()`,
+    // each a fresh agent loop. The measured runaway compacted 18 times INSIDE its
+    // turn, so a one-shot disarm on agent_end would have retired the guard after the
+    // first ~375 of its 6,760 calls. `agent_settled` is the boundary that means what
+    // this needs: no retry, compaction or queued continuation left to run.
+    pi.on('agent_settled', () => {
+        if (!armed)
+            return;
+        if (armed.oneShot)
+            disarmImplementationGuard();
+        // An awaited run spans resume and steer turns. Counters are per TURN, so a
+        // fresh one starts clean rather than inheriting the last one's strikes.
+        else
+            armed = freshArmedState(false);
+    });
+    pi.on('session_shutdown', disarmImplementationGuard);
+}