@mjasnikovs/pi-task 0.38.29 → 0.38.30

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-thinking.d.ts

@@ -2,41 +2,43 @@
  * Hold the host session at the `implementation` group's thinking level for the
  * duration of one implementation turn, then put it back.
  *
- * WHY THIS IS NOT LIKE THE OTHER SIX GROUPS
- * -----------------------------------------
- * Every other group is a child process, so its level is one argv flag and it
- * dies with the child. The implementation turn runs in the USER'S OWN session
- * (orchestrator.ts `sendSpec` → sendUserMessage → superviseImplementation), so
- * the only lever is `pi.setThinkingLevel`, which is session-global and visible.
+ * WHY THIS GROUP IS NOT LIKE THE OTHERS
+ * -------------------------------------
+ * Every other reasoning group runs in a child process, so its level is one argv
+ * flag (`--thinking <level>`, built in reasoning-args.ts) and it dies with the
+ * child. The implementation turn runs in the USER'S OWN session
+ * (orchestrator.ts `sendSpec` -> `sendUserMessage` -> `superviseImplementation`),
+ * so the only lever is `pi.setThinkingLevel`, which is session-global.
  *
- * THREE THINGS pi DOES that this has to survive. All three read from
- * pi-coding-agent's agent-session `setThinkingLevel`:
+ * THREE THINGS pi DOES that this has to survive:
  *
- *  1. IT PERSISTS. On a real change it calls
- *     `settingsManager.setDefaultThinkingLevel(...)`, writing
- *     `~/.pi/agent/settings.json`. This is not a session-local toggle — without
- *     the restore, running one task would silently rewrite the user's global
- *     default. That makes `release()` load-bearing, not tidy-up.
- *  2. IT CLAMPS, to what the model declares it supports. We may ask for `medium`
- *     and be given `off`. So the restore writes back what was READ after
- *     setting, never what was asked for — otherwise a clamp would ratchet the
- *     stored default a little further every run.
- *  3. IT IS OBSERVABLE, and the user can change it mid-turn (shift+tab cycles
- *     the level). Restoring blindly would clobber a choice they just made. We
- *     detect it by comparing the live level at release against what we applied:
- *     if it has moved, somebody else moved it, and we leave it alone.
+ *  1. IT PERSISTS. pi-coding-agent's agent-session `setThinkingLevel` calls
+ *     `settingsManager.setDefaultThinkingLevel(...)` whenever the effective
+ *     level actually changes, and that writes pi's global settings file
+ *     (`~/.pi/agent/settings.json`). Without the restore, running one task would
+ *     silently rewrite the user's global default. That makes `release()`
+ *     load-bearing, not tidy-up.
+ *  2. IT CLAMPS, to the levels the model declares. A model with no reasoning
+ *     support offers only `off`, so asking for `medium` yields `off`. The
+ *     restore therefore writes back what was READ after setting, never what was
+ *     asked for — otherwise a clamp would ratchet the stored default a little
+ *     further every run.
+ *  3. IT IS OBSERVABLE, and the user can change it mid-turn: `shift+tab` is the
+ *     default binding for `app.thinking.cycle`, and a change invalidates the
+ *     footer. Restoring blindly would clobber a choice they just made. We detect
+ *     it by comparing the live level at release against what we applied: if it
+ *     has moved, somebody else moved it, and we leave it alone.
  *
- * We compare rather than subscribe because `pi.on` returns no unsubscribe
- * handle, so a per-turn listener could only ever be added, never removed. The
- * comparison answers the same question with no accumulating state.
+ * We compare rather than subscribe because the extension API's `on(...)` returns
+ * `void` — there is no unsubscribe handle — so a per-turn listener could only
+ * ever be added, never removed. The comparison answers the same question with no
+ * accumulating state.
  */
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 import { type GroupSetting } from '../config/reasoning.js';
 /**
- * The slice of the extension API this needs, named so tests can drive it without
- * a live pi session. Every other dependency in `RunSingleTaskOptions` is
- * injectable; this one has to be too, or the restore logic is only exercisable
- * by running a real task.
+ * The slice of the extension API this needs, named so tests can drive the
+ * hold-and-restore with a fake object instead of a live pi session.
  */
 export interface ThinkingControl {
     get(): ThinkingLevel;
@@ -47,8 +49,8 @@ export interface ThinkingControl {
  * that puts it back. Always call the returned function — `finally`, not the
  * happy path.
  *
- * `inherit` makes NO call at all, not even a redundant set-to-current: a set
- * that happens to be a no-op still goes through pi's change detection, and the
- * shipped default must not touch the user's settings file.
+ * `inherit` makes NO call at all, not even a redundant set-to-current. It means
+ * the same thing here as in `thinkingArgs`, which emits no `--thinking` flag for
+ * it: leave the level wherever it already is.
  */
 export declare function holdImplementationThinking(control: ThinkingControl, setting?: GroupSetting): () => void;

package/dist/task/implementation-thinking.js

@@ -5,9 +5,9 @@ import { resolveReasoning } from '../config/reasoning.js';
  * that puts it back. Always call the returned function — `finally`, not the
  * happy path.
  *
- * `inherit` makes NO call at all, not even a redundant set-to-current: a set
- * that happens to be a no-op still goes through pi's change detection, and the
- * shipped default must not touch the user's settings file.
+ * `inherit` makes NO call at all, not even a redundant set-to-current. It means
+ * the same thing here as in `thinkingArgs`, which emits no `--thinking` flag for
+ * it: leave the level wherever it already is.
  */
 export function holdImplementationThinking(control, setting = resolveReasoning('implementation', getConfig())) {
     if (setting === 'inherit')
@@ -21,9 +21,8 @@ export function holdImplementationThinking(control, setting = resolveReasoning('
         return () => { };
     let released = false;
     return () => {
-        // Idempotent: the caller's `finally` may run alongside an outer one on an
-        // abort path, and a second restore would fight a user change made in
-        // between.
+        // Idempotent by contract: only the first call restores. A later call
+        // would write `before` on top of whatever the level is by then.
         if (released)
             return;
         released = true;

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

@@ -7,12 +7,13 @@
  *   • `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;
+ *   • `error`       — the model or provider failed after pi exhausted the retries
+ *                     in its own retry settings;
  *   • `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.
+ * `classifyTurnEnd` reads the session entries and names ONE of those;
+ * `superviseImplementation` then resumes across compactions, lets the user steer
+ * after an interrupt, and reports the terminal outcome. The orchestrator calls it
+ * from one place, inside the `sendSpec` closure.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 /** How the most recent implementation turn ended. See {@link classifyTurnEnd}. */
@@ -34,21 +35,20 @@ export type SessionEntryLike = {
 /**
  * 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):
+ * Precedence, when several signals are present at once:
  *   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
+ *                     Position-based, not timestamp-based: `appendCompaction`
+ *                     pushes the boundary onto the tail of the entry list, and
+ *                     `getEntries()` returns that list in append order, 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.
+ *                     A finished turn ends on an assistant message. An overflow
+ *                     compaction that is going to retry continues the turn itself
+ *                     and never reaches us idle.
+ *   3. `error`      — the last assistant message has stopReason "error": the model
+ *                     or provider failed after pi exhausted its own retries.
  *   4. `stop`       — anything else, including a session with no assistant turn.
  */
 export declare function classifyTurnEnd(entries: ReadonlyArray<SessionEntryLike>): TurnEnd;
@@ -78,10 +78,11 @@ export type SteerCtx = ExtensionCommandContext & {
 };
 /**
  * Timing knobs for the watchdog-abort guard in {@link steerUntilDone}, injectable
- * so tests exercise the grace expiry without a 10-second wait. `graceMs` bounds
- * how long the loop waits for the watchdog's follow-up to be DELIVERED (not to
- * finish — its turn may legitimately run for minutes afterwards); delivery is
- * normally near-instant, so the grace only expires on a stale flag.
+ * so a test can exercise the grace expiry without waiting it out. `graceMs`
+ * bounds how long the loop waits for the watchdog's follow-up to be DELIVERED,
+ * not to finish: once it lands, the wait for its turn is unbounded. `onFire`
+ * sends the follow-up in the same block that raised the flag, so the grace
+ * expires only when the flag was already stale.
  */
 export interface SteerWatchdogDeps {
     consume: () => boolean;
@@ -124,18 +125,18 @@ export declare function turnDepsFor(ctx: SteerCtx, opts?: SuperviseOptions): Imp
 /**
  * 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.
+ * threshold by its own final message) confirm completion without inventing busywork.
+ * The classifier sees only the boundary's POSITION, so it cannot tell "paused
+ * mid-task by compaction" from "finished, then compacted"; the wording lets a done
+ * turn end in one line.
  */
 export declare const CONTINUE_AFTER_COMPACTION: string;
 /**
  * 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.
+ * resume follows a real compaction, which pi only runs once `shouldCompact` says
+ * the context crossed its threshold. The cap exists to stop a pathological loop
+ * from auto-sending forever with no user watching. Hitting it stops resuming and
+ * lets the verify gate and `/task-auto-resume` catch any leftover incompleteness.
  */
 export declare const MAX_COMPACTION_RESUMES = 20;
 /**
@@ -154,10 +155,12 @@ export declare function resumeAcrossCompactions(deps: ImplementationTurnDeps): P
  * `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.
+ * queue, never run: interactive-mode's submit handler calls `onInputCallback` when
+ * the session is idle, and that callback is set only inside `getUserInput()` — the
+ * REPL loop we are holding — so the text lands in `pendingUserInputs` instead. We
+ * therefore solicit the steering text ourselves and feed it back as another turn
+ * via `sendUserMessage`, which forwards to `prompt()` and, on an idle session, runs
+ * the turn rather than queueing it. 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