@mjasnikovs/pi-task 0.38.10 → 0.38.12

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-3025%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-3797%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -233,13 +233,17 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | `CHROME_BIN` | verify-work render check | Explicit headless Chrome-family binary. Tried before the Playwright cache and a browser on `PATH`. No browser found ⇒ the render check SKIPs; it never installs one. |
 | `PLAYWRIGHT_BROWSERS_PATH` | verify-work render check | Where to look for a cached Playwright Chromium (defaults to `~/.cache/ms-playwright`, or `~/Library/Caches/ms-playwright` on macOS). |
 
-Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your `.gitignore` if you don't want them checked in.
+Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. A run also keeps small
+line-oriented ledgers beside them — contracts, launch contract, environment
+notes, accepted debt, repair queue, requirements — plus `*-debug.log` when
+**debug logs** is on. Add `.pi-tasks/` to your `.gitignore` if you don't want
+them checked in.
 
 ## Development
 
 ```sh
 bun install
-bun run test       # 3028 tests across 173 files
+bun run test       # 3800 tests across 214 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/shared/child-process.d.ts

@@ -81,6 +81,14 @@ export interface LoopHit {
     call: ToolCall;
     count: number;
     windowSize: number;
+    /**
+     * Set when the kill came from the whole-run StallDetector rather than the
+     * short-window LoopDetector, naming which of its two rules tripped
+     * (task/stall-detector.ts). Absent for an ordinary loop hit. Carried here so
+     * a stall rides the kill/restart plumbing the loop hit already has instead of
+     * needing a second channel.
+     */
+    stall?: 'no-new-ground' | 'context-churn';
 }
 export interface ContextSnapshot {
     tokens: number;

package/dist/shared/command-watchdog.d.ts

@@ -54,7 +54,7 @@ export interface WatchdogDeps {
 }
 /**
  * Stable substring of {@link reminderMessage}, used by the steer loop
- * (orchestrator steerUntilDone) to recognise the watchdog's follow-up turn in
+ * (implementation-turn steerUntilDone) to recognise the watchdog's follow-up turn in
  * the session entries — the artifact that distinguishes a watchdog abort from a
  * human ESC. Interpolated into the message so the detector and the text cannot
  * drift apart.

package/dist/shared/command-watchdog.js

@@ -53,7 +53,7 @@ function correction() {
 }
 /**
  * Stable substring of {@link reminderMessage}, used by the steer loop
- * (orchestrator steerUntilDone) to recognise the watchdog's follow-up turn in
+ * (implementation-turn steerUntilDone) to recognise the watchdog's follow-up turn in
  * the session entries — the artifact that distinguishes a watchdog abort from a
  * human ESC. Interpolated into the message so the detector and the text cannot
  * drift apart.

package/dist/task/accept-debt.d.ts

@@ -1,3 +1,4 @@
+import { type CommandRunner } from './command-run.js';
 /**
  * Provenance of a recorded defect:
  *   - 'accepted'       — the user chose ACCEPT despite a verify-FAIL (the original class).
@@ -226,3 +227,49 @@ export declare function buildAcceptDebtNote(open: AcceptDebt[]): string;
  * origin falls back to the 'accepted' class exactly as the branch chain did.
  */
 export declare function describeDebt(d: AcceptDebt): string;
+/**
+ * ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
+ * the user accepted despite a verify-FAIL and re-check each against the CURRENT
+ * tree. A static-class debt whose statics now pass is provably RESOLVED (a later
+ * task fixed it) and pruned from the ledger; every other debt cannot be proven
+ * resolved deterministically, so it stays OPEN and is surfaced — a run may not
+ * complete silently carrying an accepted defect. FP-safe by construction (see
+ * accept-debt.ts). Best-effort: a ledger read/write failure must never break the
+ * caller.
+ *
+ * FACTORED OUT of runFinalIntegrationGate (nexttask 6): the derivation has to be
+ * runnable at a SECOND moment — after a converged final-gate autofix, where the
+ * orchestrator used to rebuild its gate outcome as a bare `{ok, reason}` and drop
+ * `openDebts` entirely. The report a run ends on has to be derived from the tree
+ * the run ends with, not from the tree as it was before the fix pass.
+ *
+ * `staticOk` is the caller's claim about the CURRENT statics, and it is the only
+ * thing that can auto-close a static-class debt — so a caller that does not know
+ * must pass `false` (unprovable ⇒ stays open), never a guess.
+ */
+export declare function deriveOpenDebts(cwd: string, staticOk: boolean): Promise<{
+    openDebts: AcceptDebt[];
+    debtNote?: string;
+    trail?: string[];
+}>;
+/**
+ * Re-run ONE debt's stored VERIFY command for the re-check, with the no-write guard
+ * (`inv-no-write`) wrapped around it.
+ *
+ * A VERIFY command is the project's own command and may legitimately write (a build
+ * emits `dist/`, a suite writes a snapshot). What it may NOT do is turn the tree into
+ * a passing tree and have that count as the debt being fixed — the run would then be
+ * certifying its own side effect. So tracked state is captured before and after, and
+ * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
+ * change named. Untracked output is left alone: it is what a build legitimately
+ * produces, and `git status --porcelain` in a repo with the usual ignores does not
+ * see it.
+ *
+ * A repository the guard cannot read (no git, git absent) is not a licence to skip
+ * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
+ * assumption rather than an observation.
+ */
+export declare function rerunDebtVerifyCommand(cwd: string, command: string, 
+/** The spawner, for BOTH the command and the tracked-state reads. Injected so
+ *  the guard's four outcomes are testable without a repo or a real command. */
+run?: CommandRunner): VerifyRerunResult;

package/dist/task/accept-debt.js

@@ -25,10 +25,14 @@
  * model, so it is SURFACED, never auto-closed — biasing hard toward informing the
  * user rather than re-hiding a live defect. "Nothing still open = clean."
  */
-import * as fsp from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import * as path from 'node:path';
+import * as fsp from 'node:fs/promises';
+import { runVerifyCommandLine, spawnCommand } from './command-run.js';
+import { taskThatIntroduced } from './task-provenance.js';
+import { makeLedger } from './ledger.js';
 import { parseVerifyBlockStrict } from './spec-validation.js';
-import { taskFilePath, tasksDir } from './task-io.js';
+import { taskFilePath } from './task-io.js';
 import { isUnfailableCommand } from './unfailable-command.js';
 const ACCEPT_DEBT_FILE = 'accept-debt.md';
 /** Cap kept records so a run that accepts many FAILs cannot grow the report unboundedly. */
@@ -69,16 +73,11 @@ function isKnownOrigin(origin) {
     return origin !== undefined && Object.hasOwn(DEBT_LABELS, origin);
 }
 export function acceptDebtFile(cwd) {
-    return path.join(tasksDir(cwd), ACCEPT_DEBT_FILE);
+    return ledger.path(cwd);
 }
 /** The raw stored ledger ('' when none recorded yet). Parse with parseAcceptDebts. */
 export async function readAcceptDebtsRaw(cwd) {
-    try {
-        return (await fsp.readFile(acceptDebtFile(cwd), 'utf8')).trim();
-    }
-    catch {
-        return '';
-    }
+    return ledger.readRaw(cwd);
 }
 /**
  * Parse the stored ledger into records. Fields are tab-separated: `id`, `reason`, and
@@ -117,7 +116,7 @@ export function parseAcceptDebts(raw) {
 }
 /** Read + parse in one step. */
 export async function readAcceptDebts(cwd) {
-    return parseAcceptDebts(await readAcceptDebtsRaw(cwd));
+    return ledger.read(cwd);
 }
 function normaliseReason(reason) {
     return reason
@@ -142,6 +141,18 @@ function serialize(d) {
 function debtKey(d) {
     return `${d.origin ?? 'accepted'} ${d.taskId.toLowerCase()} ${d.reason.toLowerCase()}`;
 }
+/**
+ * The debt ledger. `onNoop: 'skip'` — a duplicate is a return, not a rewrite: the
+ * file is touched only when a NEW debt enters it.
+ */
+const ledger = makeLedger({
+    file: ACCEPT_DEBT_FILE,
+    max: MAX_DEBTS,
+    key: debtKey,
+    serialize,
+    parse: parseAcceptDebts,
+    onNoop: 'skip'
+});
 /**
  * Append one accepted-despite-FAIL record, deduplicated against what is already
  * stored (case-insensitive on task id + reason), keeping the newest MAX_DEBTS.
@@ -158,13 +169,7 @@ async function appendDebt(cwd, entry) {
         const verifyCommand = entry.verifyCommand ?? (await classifyVerifyCommand(cwd, entry.taskId, entry.reason));
         if (verifyCommand !== null && verifyCommand !== undefined)
             entry = { ...entry, verifyCommand };
-        const existing = parseAcceptDebts(await readAcceptDebtsRaw(cwd));
-        const seen = new Set(existing.map(debtKey));
-        if (seen.has(debtKey(entry)))
-            return;
-        const kept = [...existing, entry].slice(-MAX_DEBTS);
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(acceptDebtFile(cwd), kept.map(serialize).join('\n') + '\n', 'utf8');
+        await ledger.append(cwd, [entry]);
     }
     catch {
         // best-effort ledger
@@ -217,17 +222,7 @@ export function extractDeletedDebtPath(reason) {
 }
 /** Overwrite the ledger with exactly these records (used to prune resolved debts). */
 export async function writeAcceptDebts(cwd, debts) {
-    try {
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        if (debts.length === 0) {
-            await fsp.writeFile(acceptDebtFile(cwd), '', 'utf8');
-            return;
-        }
-        await fsp.writeFile(acceptDebtFile(cwd), debts.map(serialize).join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort ledger
-    }
+    await ledger.write(cwd, debts);
 }
 /**
  * STATIC-CLASS debt: one whose accepted FAIL was the deterministic whole-repo static
@@ -484,3 +479,107 @@ export function buildAcceptDebtNote(open) {
 export function describeDebt(d) {
     return isKnownOrigin(d.origin) ? DEBT_LABELS[d.origin] : DEBT_LABELS.accepted;
 }
+/**
+ * ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
+ * the user accepted despite a verify-FAIL and re-check each against the CURRENT
+ * tree. A static-class debt whose statics now pass is provably RESOLVED (a later
+ * task fixed it) and pruned from the ledger; every other debt cannot be proven
+ * resolved deterministically, so it stays OPEN and is surfaced — a run may not
+ * complete silently carrying an accepted defect. FP-safe by construction (see
+ * accept-debt.ts). Best-effort: a ledger read/write failure must never break the
+ * caller.
+ *
+ * FACTORED OUT of runFinalIntegrationGate (nexttask 6): the derivation has to be
+ * runnable at a SECOND moment — after a converged final-gate autofix, where the
+ * orchestrator used to rebuild its gate outcome as a bare `{ok, reason}` and drop
+ * `openDebts` entirely. The report a run ends on has to be derived from the tree
+ * the run ends with, not from the tree as it was before the fix pass.
+ *
+ * `staticOk` is the caller's claim about the CURRENT statics, and it is the only
+ * thing that can auto-close a static-class debt — so a caller that does not know
+ * must pass `false` (unprovable ⇒ stays open), never a guess.
+ */
+export async function deriveOpenDebts(cwd, staticOk) {
+    const { open: openRaw, resolved, trail } = recheckAcceptDebts(await readAcceptDebts(cwd), {
+        staticOk,
+        // Cross-task-deletion debts auto-close iff the deleted file is back in the
+        // tree — a deterministic existence check, corroborating the per-file
+        // provenance the record already carries.
+        fileExists: rel => existsSync(path.join(cwd, rel)),
+        // VERIFY-COMMAND class (nexttask 5): a debt that NAMES a command is settled
+        // by running that command, under the gate's own env-gap contract and behind
+        // the no-write guard below.
+        rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd)
+    });
+    if (resolved.length > 0)
+        await writeAcceptDebts(cwd, openRaw);
+    // Conflicting-claim annotation (mx5 run 11): an existence-as-failure debt whose
+    // named file is another task's committed deliverable is a plan defect — surface
+    // the contradiction with the debt so nobody (human or child) treats the claim as
+    // a deletion instruction. Pure git-history lookup; degrades to no annotation.
+    const openDebts = annotateDebtConflicts(openRaw, p => taskThatIntroduced(cwd, p));
+    const debtNote = buildAcceptDebtNote(openDebts);
+    return { openDebts, ...(debtNote ? { debtNote } : {}), ...(trail.length > 0 ? { trail } : {}) };
+}
+/** Per-command ceiling for a debt re-run (`inv-bounded`). */
+const DEBT_RERUN_TIMEOUT_MS = 300_000;
+/**
+ * Extra infrastructure-gap shapes recognised ONLY when re-running a debt's command,
+ * never in the gate's own verdicts. A driver that reports its connection simply
+ * closed (`ERR_POSTGRES_CONNECTION_CLOSED` — what bun's SQL client says when the
+ * database is not there at all, as on this box with the mx5 container stopped) is an
+ * absent dependency, and calling that "the defect is still present" would be a
+ * finding the environment invented. Kept out of INFRA_GAP_OUTPUT_RE on purpose: in a
+ * gate verdict the same wording can be a real fault the suite must own, and only the
+ * debt re-check needs the conservative reading — where it costs nothing, because gap
+ * and fail both leave the debt open.
+ */
+const DEBT_INFRA_GAP_RE = /ERR_POSTGRES_CONNECTION_CLOSED|ERR_MYSQL_CONNECTION|ECONNRESET/i;
+/**
+ * Re-run ONE debt's stored VERIFY command for the re-check, with the no-write guard
+ * (`inv-no-write`) wrapped around it.
+ *
+ * A VERIFY command is the project's own command and may legitimately write (a build
+ * emits `dist/`, a suite writes a snapshot). What it may NOT do is turn the tree into
+ * a passing tree and have that count as the debt being fixed — the run would then be
+ * certifying its own side effect. So tracked state is captured before and after, and
+ * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
+ * change named. Untracked output is left alone: it is what a build legitimately
+ * produces, and `git status --porcelain` in a repo with the usual ignores does not
+ * see it.
+ *
+ * A repository the guard cannot read (no git, git absent) is not a licence to skip
+ * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
+ * assumption rather than an observation.
+ */
+export function rerunDebtVerifyCommand(cwd, command, 
+/** The spawner, for BOTH the command and the tracked-state reads. Injected so
+ *  the guard's four outcomes are testable without a repo or a real command. */
+run = spawnCommand) {
+    const tracked = () => {
+        const r = run({
+            cwd,
+            bin: 'git',
+            args: ['status', '--porcelain', '--untracked-files=no'],
+            timeoutMs: 60_000
+        });
+        return r.failedToStart || r.status !== 0 ? null : r.stdout;
+    };
+    const before = tracked();
+    const r = runVerifyCommandLine(cwd, command, DEBT_RERUN_TIMEOUT_MS, DEBT_INFRA_GAP_RE, run);
+    if (r.outcome === 'fail')
+        return { outcome: 'fail', detail: `exit ${r.status} — ${r.tail}` };
+    if (r.outcome === 'gap')
+        return { outcome: 'gap', detail: r.detail };
+    const after = tracked();
+    if (before === null || after === null) {
+        return { outcome: 'gap', detail: 'tracked-state guard could not read git status' };
+    }
+    if (before !== after) {
+        return {
+            outcome: 'gap',
+            detail: 'the re-run itself CHANGED tracked files — a command that edits the tree into a pass proves nothing'
+        };
+    }
+    return { outcome: 'pass' };
+}

package/dist/task/auto-orchestrator.js

@@ -20,16 +20,13 @@ import { drainRepairQueue, mergeRepairCandidates, planHasRepairFor, parseRepairT
 import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasksDir } from './task-io.js';
 import { readTextFile } from '../shared/fs-text.js';
 import { findPhantomImports, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
-import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
+import { prependHint, USER_CANCELLED } from './child-runner.js';
 import { requestCancel, resetCancel, isCancelRequested, cancelCheckpoint } from './cancel-points.js';
-import { armCancelListener, disarmCancelListener } from './cancel-input.js';
-import { beginRun, endRun } from './mid-run-input.js';
-import { reportDroppedInput } from './dropped-input.js';
+import { withRun, announceTerminal } from './run-bracket.js';
 import { refineExistingFilesBlock, SINGLE_READ_EXTENSION_PATH } from './phases.js';
 import { SessionUI, registerBridgeCommand, publishLifecycleNotice } from '../remote/bridge.js';
-import { pushNotify } from '../remote/push.js';
-import { startAutoLoader } from './widget.js';
-import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
+import { getParentContextWindow } from './context-usage.js';
+import { ChildStatus, runPlanningChild, statusCallbacks } from './child-status.js';
 import { buildGateDeps, collectTreeChanges } from './gate-deps.js';
 import { runGatesForTask } from './task-gates.js';
 import { runFinalGateStage } from './run-final-gate.js';
@@ -428,7 +425,7 @@ export async function orientFeature(cwd, feature, deps) {
     // same deterministic, no-LLM strike at the single point that feeds both planning
     // children. Silent + no-op when nothing is flagged or the runtime's types aren't
     // installed.
-    const planPhantoms = findPhantomImports(rawFeatureForModel, cwd);
+    const planPhantoms = await findPhantomImports(rawFeatureForModel, cwd);
     const featureForModel = planPhantoms.length === 0 ?
         rawFeatureForModel
         : rewritePhantomSpecifiers(rawFeatureForModel, planPhantoms);
@@ -1126,12 +1123,11 @@ const AUTO_PLAN_STEPS = {
 };
 const AUTO_PLAN_STEP_TOTAL = 2;
 function defaultDeps(ctx, cwd, signal, title) {
-    // Captured by the planning loader's getState so the widget mirrors the child's
-    // latest output line and context usage, exactly like the single-task phase
-    // widget. (The gate children manage their own loaders inside buildGateDeps.)
-    let lastLine;
-    let contextUsage;
+    // The planning loader mirrors the child's latest output line and context
+    // usage, exactly like the single-task phase widget. (The gate children have
+    // their own ChildStatus inside buildGateDeps.)
     const parentContextWindow = getParentContextWindow(ctx);
+    const status = new ChildStatus({ parentContextWindow });
     const phaseDeps = {
         cwd,
         taskId: '',
@@ -1143,41 +1139,31 @@ function defaultDeps(ctx, cwd, signal, title) {
         // it has already opened can only be thrash — which makes the read-once
         // block safe here in a way it is not for a phase that must explore.
         childExtensions: [SINGLE_READ_EXTENSION_PATH],
-        onChildOutput: (line) => {
-            lastLine = line;
-        },
-        onContextUsage: snapshot => {
-            contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
-        }
+        ...statusCallbacks(status)
     };
     return {
         // Planning-only seam. The shared gate surface (runTask/commit/verify/
         // enforce/recommend/revert) comes from buildGateDeps below — identical to
         // what /task builds, so both commands gate the same way.
-        runChild: async (name, tools, prompt) => {
-            // Planning children are slow LLM calls with no UI of their own; show
-            // the same status block as /task so this never goes silent until the
-            // drill dialog.
-            lastLine = undefined;
-            contextUsage = undefined;
-            const startedAt = Date.now();
-            const { step, stepNum } = AUTO_PLAN_STEPS[name] ?? { step: name, stepNum: 1 };
-            const stopLoader = startAutoLoader(ctx, () => ({
+        //
+        // Planning children are slow LLM calls with no UI of their own; the
+        // shared loader shows the same status block as /task so this never goes
+        // silent until the drill dialog.
+        runChild: (name, tools, prompt) => runPlanningChild({
+            ctx,
+            status,
+            phaseDeps,
+            name,
+            tools,
+            prompt,
+            loader: {
                 title,
-                step,
-                stepNum,
-                stepTotal: AUTO_PLAN_STEP_TOTAL,
-                startedAt,
-                lastLine,
-                contextUsage
-            }));
-            try {
-                return await runPhaseChild(phaseDeps, name, tools, prompt);
+                step: n => ({
+                    ...(AUTO_PLAN_STEPS[n] ?? { step: n, stepNum: 1 }),
+                    stepTotal: AUTO_PLAN_STEP_TOTAL
+                })
             }
-            finally {
-                stopLoader();
-            }
-        },
+        }),
         ...buildGateDeps({ signal, parentContextWindow, runTask: gateRunTask }),
         // Loop-level repo integrity + run-end gate glue (see AutoDeps docs).
         unmergedPaths: cwd2 => gitUnmergedPaths(cwd2, signal),
@@ -1185,7 +1171,7 @@ function defaultDeps(ctx, cwd, signal, title) {
         // The final integration gate follows the `verify work` switch: it is the
         // run-level half of the same verification story.
         finalGate: (cwd2, planText) => getConfig().verifyWork ?
-            runFinalIntegrationGate(cwd2, undefined, undefined, undefined, planText)
+            runFinalIntegrationGate(cwd2, { planText })
             : Promise.resolve({ ok: true, reason: 'disabled' }),
         // Uncommitted paths, for the stranded-sub-fix handling around the final-gate
         // picker (mx5 run 13 PROMPT 4 item 3). Every task is committed by the time
@@ -1213,12 +1199,7 @@ export function requestAutoCancel() {
  * runSingleTask without notifyFinish, so they stay silent).
  */
 function announceDone(ctx, msg, level) {
-    ctx.ui.notify(msg, 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. Mirror it
-    // into the session view too (errors become a persistent red bubble).
-    publishLifecycleNotice(msg, level);
-    void pushNotify('Task finished', msg, 'pi-end').catch(() => { });
+    announceTerminal(ctx, msg, level);
 }
 export async function runAutoLoop(ctx, cwd, id, deps) {
     resetCancel();
@@ -1461,46 +1442,45 @@ async function handleTaskAuto(args, ctx) {
         return;
     }
     autoRunning = true;
-    beginRun(); // the whole loop owns the session, not just the task inside it
-    // Take delivery of a typed /task-auto-cancel for the WHOLE run, planning
-    // included — planning is children too, so the host is not streaming and the
-    // ordinary command path cannot reach us.
-    armTerminalCancel(ctx);
+    // The whole loop owns the session, not just the task inside it — and the
+    // bracket takes delivery of a typed /task-auto-cancel for the WHOLE run,
+    // planning included: planning is children too, so the host is not streaming
+    // and the ordinary command path cannot reach us.
     try {
-        // Stamp a fresh per-run research-cache id (F10) BEFORE planning so enrichment and
-        // every task's research phase share one run's cache; disabled ⇒ clears any token a
-        // prior run left, so nothing is cached.
-        configureResearchRun(getConfig().researchCache);
-        const abort = new AbortController();
-        const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
-        let id;
-        try {
-            id = await planAuto(ctx, cwd, raw, deps);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg === USER_CANCELLED) {
+        await withRun(ctx, { onCancel: terminalCancel }, async () => {
+            // Stamp a fresh per-run research-cache id (F10) BEFORE planning so enrichment and
+            // every task's research phase share one run's cache; disabled ⇒ clears any token a
+            // prior run left, so nothing is cached.
+            configureResearchRun(getConfig().researchCache);
+            const abort = new AbortController();
+            const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
+            let id;
+            try {
+                id = await planAuto(ctx, cwd, raw, deps);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg === USER_CANCELLED) {
+                    announceDone(ctx, '/task-auto cancelled.', 'warning');
+                    return;
+                }
+                announceDone(ctx, `/task-auto planning failed: ${msg}`, 'error');
+                return;
+            }
+            if (!id)
+                return;
+            // Check for a cancel that was requested during the planning phase before the
+            // loop resets the flag.
+            if (isCancelRequested()) {
+                resetCancel();
                 announceDone(ctx, '/task-auto cancelled.', 'warning');
                 return;
             }
-            announceDone(ctx, `/task-auto planning failed: ${msg}`, 'error');
-            return;
-        }
-        if (!id)
-            return;
-        // Check for a cancel that was requested during the planning phase before the
-        // loop resets the flag.
-        if (isCancelRequested()) {
-            resetCancel();
-            announceDone(ctx, '/task-auto cancelled.', 'warning');
-            return;
-        }
-        await runAutoLoop(ctx, cwd, id, deps);
+            await runAutoLoop(ctx, cwd, id, deps);
+        });
     }
     finally {
         autoRunning = false;
-        reportDroppedInput(endRun(), ctx);
-        disarmCancelListener();
     }
 }
 async function handleTaskAutoResume(args, ctx) {
@@ -1529,28 +1509,27 @@ async function handleTaskAutoResume(args, ctx) {
     const id = candidate.id;
     await updateTaskFrontMatter(cwd, id, { state: 'in_progress' });
     autoRunning = true;
-    beginRun(); // the whole loop owns the session, not just the task inside it
-    armTerminalCancel(ctx);
+    // The whole loop owns the session, not just the task inside it.
     try {
-        // Reuse the interrupted run's research-cache id, dropping only the entries whose
-        // own package moved version (F10). mx5 run 13 resumed three times and each
-        // resume's fresh id discarded a working 201-entry cache; run 14 then showed a
-        // whole-file freshness gate can never hold on a greenfield run that installs
-        // packages as it goes, so invalidation is per entry. See resumeResearchRun.
-        const research = await resumeResearchRun(cwd, getConfig().researchCache);
-        if (research.reused) {
-            logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `
-                + `dropped ${research.dropped} stale`);
-        }
-        const abort = new AbortController();
-        // Resume only runs the loop (runTask); no planning children, so the loader
-        // title is unused here — pass the id for clarity if that ever changes.
-        await runAutoLoop(ctx, cwd, id, defaultDeps(ctx, cwd, abort.signal, id));
+        await withRun(ctx, { onCancel: terminalCancel }, async () => {
+            // Reuse the interrupted run's research-cache id, dropping only the entries whose
+            // own package moved version (F10). mx5 run 13 resumed three times and each
+            // resume's fresh id discarded a working 201-entry cache; run 14 then showed a
+            // whole-file freshness gate can never hold on a greenfield run that installs
+            // packages as it goes, so invalidation is per entry. See resumeResearchRun.
+            const research = await resumeResearchRun(cwd, getConfig().researchCache);
+            if (research.reused) {
+                logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `
+                    + `dropped ${research.dropped} stale`);
+            }
+            const abort = new AbortController();
+            // Resume only runs the loop (runTask); no planning children, so the loader
+            // title is unused here — pass the id for clarity if that ever changes.
+            await runAutoLoop(ctx, cwd, id, defaultDeps(ctx, cwd, abort.signal, id));
+        });
     }
     finally {
         autoRunning = false;
-        reportDroppedInput(endRun(), ctx);
-        disarmCancelListener();
     }
 }
 // eslint-disable-next-line @typescript-eslint/require-await
@@ -1571,24 +1550,22 @@ async function handleTaskAutoCancel(_args, ctx) {
 const CANCEL_ACK = 'Stopping /task-auto at the next safe checkpoint…';
 /**
  * Deliver a /task-auto-cancel typed in the terminal while a run owns the main
- * loop. `armCancelListener` watches raw stdin, so it works during the spec
- * phases and the gates — the windows where pi would otherwise queue the line
- * until after the run (see cancel-input.ts). The remote path is unaffected:
- * dispatchRemoteLine invokes the handler directly.
+ * loop — the run bracket's `onCancel`. The armed listener watches raw stdin, so
+ * it works during the spec phases and the gates — the windows where pi would
+ * otherwise queue the line until after the run (see cancel-input.ts). The
+ * remote path is unaffected: dispatchRemoteLine invokes the handler directly.
  */
-function armTerminalCancel(ctx) {
-    armCancelListener(ctx, live => {
-        requestAutoCancel();
-        // `live` is the ctx the listener is currently installed on — the captured
-        // one is stale the moment a task replaces the session.
-        try {
-            live.ui.notify(CANCEL_ACK, 'warning');
-        }
-        catch {
-            /* the acknowledgement must never break the cancel itself */
-        }
-        publishLifecycleNotice(CANCEL_ACK, 'warning');
-    });
+function terminalCancel(live) {
+    requestAutoCancel();
+    // `live` is the ctx the listener is currently installed on — the captured
+    // one is stale the moment a task replaces the session.
+    try {
+        live.ui.notify(CANCEL_ACK, 'warning');
+    }
+    catch {
+        /* the acknowledgement must never break the cancel itself */
+    }
+    publishLifecycleNotice(CANCEL_ACK, 'warning');
 }
 // ─── Registration ────────────────────────────────────────────────────────────
 export function registerTaskAuto(pi) {