@mjasnikovs/pi-task 0.18.32 → 0.18.34

package/dist/task/auto-orchestrator.js

@@ -19,6 +19,8 @@ import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasks
 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 { requestCancel, resetCancel, isCancelRequested, cancelCheckpoint } from './cancel-points.js';
+import { armCancelListener, disarmCancelListener } from './cancel-input.js';
 import { refineExistingFilesBlock } from './phases.js';
 import { SessionUI, registerBridgeCommand, publishLifecycleNotice } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
@@ -915,10 +917,9 @@ function defaultDeps(ctx, cwd, signal, title) {
     };
 }
 // ─── Loop ────────────────────────────────────────────────────────────────────
-let cancelRequested = false;
 let autoRunning = false;
 export function requestAutoCancel() {
-    cancelRequested = true;
+    requestCancel();
 }
 /**
  * Announce a terminal /task-auto-overall outcome both in the terminal and to
@@ -936,7 +937,7 @@ function announceDone(ctx, msg, level) {
     void pushNotify('Task finished', msg, 'pi-end').catch(() => { });
 }
 export async function runAutoLoop(ctx, cwd, id, deps) {
-    cancelRequested = false;
+    resetCancel();
     // Each task runs in its own fresh session (deps.runTask → ctx.newSession),
     // which tears down the current session and leaves the ctx we passed in stale.
     // Adopt the replacement ctx the runner hands back and use it for all further
@@ -944,7 +945,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
     let active = ctx;
     try {
         for (;;) {
-            if (cancelRequested) {
+            if (cancelCheckpoint('loop-top')) {
                 announceDone(active, `${id} cancelled — resume with /task-auto-resume.`, 'warning');
                 return;
             }
@@ -959,6 +960,14 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 // complete. On a FAIL the user decides: accept (complete anyway) or
                 // leave the run failed — a resume re-enters this branch and re-runs
                 // the gate, so fixing and resuming converges.
+                // SAFE CHECKPOINT (pre-final-gate): every task is checked off and
+                // committed and the whole-repo gate has not started. A resume
+                // re-enters this same branch and runs the gate then, so the run is
+                // left exactly where it was — not silently declared complete.
+                if (cancelCheckpoint('pre-final-gate')) {
+                    announceDone(active, `${id} cancelled before the final integration gate — resume with /task-auto-resume.`, 'warning');
+                    return;
+                }
                 if (deps.finalGate) {
                     active.ui.notify(`${id}: running final integration gate…`, 'info');
                     // Run-level gate trail on the parent task file — same durable
@@ -1229,6 +1238,14 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             // during the task (impl model or any child) and left behind is called
             // out instead of silently waiting to detonate in a later task.
             const stashBefore = deps.stashRef ? await deps.stashRef(cwd) : undefined;
+            // SAFE CHECKPOINT (pre-task): the tree is committed and no inner task
+            // is stamped yet, so stopping here just leaves this entry unchecked —
+            // a resume restarts it from scratch. Cheapest possible stop, and the
+            // last one before we commit to a ~30-minute task.
+            if (cancelCheckpoint('pre-task')) {
+                announceDone(active, `${id} cancelled before "${next.title}" — resume with /task-auto-resume.`, 'warning');
+                return;
+            }
             const res = await deps.runTask(active, cwd, next.title, {
                 resumeId,
                 // Fence this step against re-expanding the whole referenced spec:
@@ -1255,6 +1272,16 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 announceDone(active, `${id} paused at "${next.title}" — resume with /task-auto-resume.`, 'warning');
                 return;
             }
+            // A phase-boundary cancel surfaces here as a plain !res.ok: the runner
+            // caught its own USER_CANCELLED and wrote state 'cancelled' (resumable)
+            // to the inner file. Claim it BEFORE the failure branch, or a
+            // user-requested stop is announced in red as "stopped … fix and
+            // resume". The inner file is already resumable and the parent stays
+            // in_progress, matching the loop-top cancel.
+            if (!res.ok && isCancelRequested()) {
+                announceDone(active, `${id} cancelled during "${next.title}" — resume with /task-auto-resume.`, 'warning');
+                return;
+            }
             if (!res.ok) {
                 // Demote the INNER task file too: it reads `completed` from
                 // spec-handoff, and leaving it that way is how a failed run's task
@@ -1336,7 +1363,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
         announceDone(active, `${id} stopped: ${msg} — fix and run /task-auto-resume.`, 'error');
     }
     finally {
-        cancelRequested = false;
+        resetCancel();
     }
 }
 // ─── Command handlers ────────────────────────────────────────────────────────
@@ -1350,40 +1377,45 @@ async function handleTaskAuto(args, ctx) {
         return;
     }
     autoRunning = true;
-    // 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;
+    // 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);
     try {
-        id = await planAuto(ctx, cwd, raw, deps);
-    }
-    catch (err) {
-        autoRunning = false;
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg === USER_CANCELLED) {
+        // 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;
+        await runAutoLoop(ctx, cwd, id, deps);
     }
-    if (!id) {
-        autoRunning = false;
-        return;
-    }
-    // Check for a cancel that was requested during the planning phase before the
-    // loop resets the flag.
-    if (cancelRequested) {
-        cancelRequested = false;
+    finally {
         autoRunning = false;
-        announceDone(ctx, '/task-auto cancelled.', 'warning');
-        return;
+        disarmCancelListener();
     }
-    await runAutoLoop(ctx, cwd, id, deps);
-    autoRunning = false;
 }
 async function handleTaskAutoResume(_args, ctx) {
     await ctx.waitForIdle();
@@ -1396,19 +1428,25 @@ async function handleTaskAutoResume(_args, ctx) {
     ctx.ui.notify(`Resuming ${id}…`, 'info');
     await updateTaskFrontMatter(cwd, id, { state: 'in_progress' });
     autoRunning = true;
-    // Reuse the interrupted run's research-cache id when the cache proves it still
-    // describes the same dependency surface (F10). mx5 run 13 resumed three times and
-    // each resume's fresh id discarded a working 201-entry cache; anything inconclusive
-    // still falls back to a fresh id and a re-fetch. See resumeResearchRun.
-    const research = await resumeResearchRun(cwd, getConfig().researchCache);
-    if (research.reused) {
-        logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies)`);
+    armTerminalCancel(ctx);
+    try {
+        // Reuse the interrupted run's research-cache id when the cache proves it still
+        // describes the same dependency surface (F10). mx5 run 13 resumed three times and
+        // each resume's fresh id discarded a working 201-entry cache; anything inconclusive
+        // still falls back to a fresh id and a re-fetch. See resumeResearchRun.
+        const research = await resumeResearchRun(cwd, getConfig().researchCache);
+        if (research.reused) {
+            logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies)`);
+        }
+        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;
+        disarmCancelListener();
     }
-    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));
-    autoRunning = false;
 }
 // eslint-disable-next-line @typescript-eslint/require-await
 async function handleTaskAutoCancel(_args, ctx) {
@@ -1417,7 +1455,35 @@ async function handleTaskAutoCancel(_args, ctx) {
         return;
     }
     requestAutoCancel();
-    ctx.ui.notify('Stopping /task-auto after the current task…', 'warning');
+    ctx.ui.notify(CANCEL_ACK, 'warning');
+}
+/**
+ * What the user is told the moment the request lands. Deliberately does NOT
+ * promise "after the current task": the request is now honoured at the next safe
+ * checkpoint (see cancel-points.ts), which mid-spec-pipeline is the end of the
+ * current phase, not the end of the task.
+ */
+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.
+ */
+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');
+    });
 }
 // ─── Registration ────────────────────────────────────────────────────────────
 export function registerTaskAuto(pi) {

package/dist/task/cancel-input.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Raw-terminal delivery for /task-auto-cancel.
+ *
+ * THE PROBLEM. While a /task-auto run is in flight, the host's interactive main
+ * loop is parked at `await session.prompt("/task-auto …")` and never loops back
+ * to read input. pi's editor submit handler (interactive-mode.js) has two paths:
+ *
+ *   - streaming    → session.prompt(text, {streamingBehavior:"steer"}), and
+ *                    agent-session.prompt() runs extension commands immediately.
+ *   - not streaming → pendingUserInputs.push(text) — a queue only the parked
+ *                    main loop drains.
+ *
+ * The host session is NOT streaming for most of a run: the spec phases and every
+ * gate are child `pi` processes, not host turns. So a /task-auto-cancel typed
+ * during them was pushed onto that queue and executed only after the run had
+ * already finished — by which point `autoRunning` is false and it answers "No
+ * /task-auto loop is running." The command was, for most of a run, inert.
+ *
+ * THE FIX. `ctx.ui.onTerminalInput` (→ TUI.addInputListener) is a raw stdin
+ * listener that the TUI dispatches BEFORE the focused component sees the bytes,
+ * independently of the parked main loop. We watch for the submit key, read what
+ * the editor is holding, and if it is the cancel command we raise the request
+ * ourselves and `consume` the keystroke so the line is never queued for a
+ * post-run replay of the confusing "no loop is running" message.
+ *
+ * Nothing else is intercepted: every other keystroke is passed straight through,
+ * so typing, history, and the ESC/steer path are untouched. Deliberately no
+ * bare-key shortcut — ESC already means "interrupt the turn" during the
+ * implementation turn, and hijacking it would break steerUntilDone.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+/**
+ * Would this keystroke, against this editor content, submit /task-auto-cancel?
+ * Pure so the decision is testable without a TUI.
+ */
+export declare function isCancelSubmission(data: string, editorText: string): boolean;
+/**
+ * Watch raw terminal input for a submitted /task-auto-cancel and call `onCancel`
+ * the moment it is typed, however deep in a run we are.
+ *
+ * Returns an unsubscribe function. A host without the raw input hook or the
+ * editor accessor (the shimmed remote ctx — which does not need this, since
+ * dispatchRemoteLine calls handlers directly) gets a no-op.
+ *
+ * Prefer the arm/rearm/disarm trio below over calling this directly: the
+ * listener does not survive a session replacement.
+ */
+export declare function installCancelListener(ctx: ExtensionCommandContext, onCancel: (live: ExtensionCommandContext) => void): () => void;
+/** Begin listening for a typed /task-auto-cancel. Replaces any previous arm. */
+export declare function armCancelListener(ctx: ExtensionCommandContext, onCancel: (live: ExtensionCommandContext) => void): void;
+/**
+ * Re-point the armed listener at a replacement ctx. A no-op when nothing is
+ * armed, so the runner can call it unconditionally on every session swap
+ * (including for a plain /task, which has no cancel listener of its own).
+ */
+export declare function rearmCancelListener(ctx: ExtensionCommandContext): void;
+/** Stop listening, so a cancel typed after the run goes back through the
+ *  ordinary command path (which then reports there is no loop running). */
+export declare function disarmCancelListener(): void;
+/** Whether a listener is currently armed (tests). */
+export declare function isCancelListenerArmed(): boolean;

package/dist/task/cancel-input.js

@@ -0,0 +1,113 @@
+/** The command this listener delivers. Accepts a leading slash only — matching
+ *  bare "task-auto-cancel" would fire on prose about the command. */
+const CANCEL_RE = /^\/task-auto-cancel\s*$/;
+/** Enter, in the encodings a terminal actually sends. A bare "\n" is what many
+ *  terminals emit in raw mode; "\r" is the usual CR. */
+function isSubmitKey(data) {
+    return data === '\r' || data === '\n' || data === '\r\n';
+}
+/**
+ * Would this keystroke, against this editor content, submit /task-auto-cancel?
+ * Pure so the decision is testable without a TUI.
+ */
+export function isCancelSubmission(data, editorText) {
+    return isSubmitKey(data) && CANCEL_RE.test(editorText.trim());
+}
+/**
+ * Watch raw terminal input for a submitted /task-auto-cancel and call `onCancel`
+ * the moment it is typed, however deep in a run we are.
+ *
+ * Returns an unsubscribe function. A host without the raw input hook or the
+ * editor accessor (the shimmed remote ctx — which does not need this, since
+ * dispatchRemoteLine calls handlers directly) gets a no-op.
+ *
+ * Prefer the arm/rearm/disarm trio below over calling this directly: the
+ * listener does not survive a session replacement.
+ */
+export function installCancelListener(ctx, onCancel) {
+    const ui = ctx.ui;
+    if (typeof ui.onTerminalInput !== 'function' || typeof ui.getEditorText !== 'function') {
+        return () => { };
+    }
+    const getText = ui.getEditorText.bind(ui);
+    const setText = typeof ui.setEditorText === 'function' ? ui.setEditorText.bind(ui) : undefined;
+    let unsubscribe = () => { };
+    try {
+        unsubscribe = ui.onTerminalInput(data => {
+            let text;
+            try {
+                text = getText();
+            }
+            catch {
+                // A torn-down editor (session replacement mid-run) must never
+                // take the run down with it — fall through to normal handling.
+                return undefined;
+            }
+            if (!isCancelSubmission(data, text))
+                return undefined;
+            // Clear what we swallowed, so the editor does not sit there holding a
+            // command the user believes they submitted.
+            try {
+                setText?.('');
+            }
+            catch {
+                /* cosmetic only */
+            }
+            // Hand back the ctx this listener is installed on: after a session
+            // replacement the original is stale and using it throws.
+            onCancel(ctx);
+            return { consume: true };
+        });
+    }
+    catch {
+        return () => { };
+    }
+    return () => {
+        try {
+            unsubscribe();
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+}
+// ─── Armed listener (survives session replacement) ────────────────────────────
+/**
+ * The listener does NOT survive `ctx.newSession()`. pi's InteractiveMode
+ * registers `setBeforeSessionInvalidate(() => this.resetExtensionUI())`, and
+ * `resetExtensionUI` calls `clearExtensionTerminalInputListeners()` — so every
+ * per-task session replacement silently drops it. That replacement happens at
+ * the START of each task, which is exactly the window this listener exists to
+ * cover, so the run must re-arm against the fresh ctx as soon as one appears
+ * (runSingleTask, where the new ctx is also handed to the remote bridge).
+ *
+ * Module-level rather than threaded through the deps: the re-arm point is deep
+ * inside the runner, which must not learn about /task-auto's cancel plumbing.
+ */
+let armed = null;
+/** Begin listening for a typed /task-auto-cancel. Replaces any previous arm. */
+export function armCancelListener(ctx, onCancel) {
+    disarmCancelListener();
+    armed = { dispose: installCancelListener(ctx, onCancel), onCancel };
+}
+/**
+ * Re-point the armed listener at a replacement ctx. A no-op when nothing is
+ * armed, so the runner can call it unconditionally on every session swap
+ * (including for a plain /task, which has no cancel listener of its own).
+ */
+export function rearmCancelListener(ctx) {
+    if (!armed)
+        return;
+    armed.dispose();
+    armed = { dispose: installCancelListener(ctx, armed.onCancel), onCancel: armed.onCancel };
+}
+/** Stop listening, so a cancel typed after the run goes back through the
+ *  ordinary command path (which then reports there is no loop running). */
+export function disarmCancelListener() {
+    armed?.dispose();
+    armed = null;
+}
+/** Whether a listener is currently armed (tests). */
+export function isCancelListenerArmed() {
+    return armed !== null;
+}

package/dist/task/cancel-points.d.ts

@@ -0,0 +1,58 @@
+/**
+ * /task-auto-cancel — the cancel request and the SAFE CHECKPOINTS that observe it.
+ *
+ * A cancel is a *request*, never a kill. It is honoured only where the on-disk
+ * state is durable and /task-auto-resume provably continues from it. Killing a
+ * child mid-phase would also stop the run (the abort signal already reaches
+ * every child's process group) but throws away that phase's work and can leave
+ * a half-written tree — so the flag is polled at boundaries instead.
+ *
+ * The checkpoint set, and why each one is safe:
+ *
+ *   loop-top       the previous task is checked off + committed and the next one
+ *                  has not started. The original (and until now the ONLY) point.
+ *   pre-task       after the pre-task checkpoint commit, before the runner is
+ *                  constructed: tree committed, no inner id stamped yet, so the
+ *                  entry is simply still unchecked and a resume restarts it.
+ *   phase:<name>   inside the runner's phase loop, after setTaskSection +
+ *                  postCommitPhase have persisted the phase output and
+ *                  front-matter `phase` names the NEXT phase. This is exactly
+ *                  the state /task-resume already resumes from (PHASE_INDEX
+ *                  skip-forward), so a cancel here costs nothing.
+ *   pre-final-gate every task is checked off and committed; the whole-repo gate
+ *                  has not started. A resume re-enters the same branch.
+ *
+ * DELIBERATELY NOT checkpoints — stopping here is not safe:
+ *   - mid implementation turn: uncommitted, half-applied edits. The user's ESC
+ *     (declined steer) path already covers "stop now, I accept a partial tree".
+ *   - between the implementation turn and the gates, or inside the gates: the
+ *     work is written but unverified and uncommitted; the gates are what make it
+ *     durable. Cancel is observed on the far side, at loop-top.
+ */
+/** Every place the cancel flag is polled. Kept as a closed union so the A/B
+ *  harness and the tests enumerate the same set the loop does. */
+export type CancelCheckpoint = 'loop-top' | 'pre-task' | 'pre-final-gate' | `phase:${string}`;
+export declare function requestCancel(): void;
+export declare function isCancelRequested(): boolean;
+/**
+ * Clear the request so the next run does not inherit it. Called when a run
+ * starts and in its `finally`.
+ *
+ * The checkpoint trail is deliberately NOT cleared here: the run's `finally`
+ * calls this, and a harness or test that inspects where the run stopped has to
+ * read the trail AFTER the loop returns. Use `resetCheckpointTrail` at the start
+ * of a trial to get a clean slate.
+ */
+export declare function resetCancel(): void;
+/** Drop the recorded checkpoint trail (A/B + tests). */
+export declare function resetCheckpointTrail(): void;
+/**
+ * Poll the cancel flag at a safe checkpoint. Records the visit either way, so a
+ * test can prove a checkpoint is reached at all (a checkpoint that never runs is
+ * indistinguishable from one that never fires).
+ *
+ * @returns true when the caller must stop here.
+ */
+export declare function cancelCheckpoint(where: CancelCheckpoint): boolean;
+/** Checkpoints crossed since the last reset (A/B + tests). */
+export declare function checkpointsCrossed(): readonly CancelCheckpoint[];

package/dist/task/cancel-points.js

@@ -0,0 +1,77 @@
+/**
+ * /task-auto-cancel — the cancel request and the SAFE CHECKPOINTS that observe it.
+ *
+ * A cancel is a *request*, never a kill. It is honoured only where the on-disk
+ * state is durable and /task-auto-resume provably continues from it. Killing a
+ * child mid-phase would also stop the run (the abort signal already reaches
+ * every child's process group) but throws away that phase's work and can leave
+ * a half-written tree — so the flag is polled at boundaries instead.
+ *
+ * The checkpoint set, and why each one is safe:
+ *
+ *   loop-top       the previous task is checked off + committed and the next one
+ *                  has not started. The original (and until now the ONLY) point.
+ *   pre-task       after the pre-task checkpoint commit, before the runner is
+ *                  constructed: tree committed, no inner id stamped yet, so the
+ *                  entry is simply still unchecked and a resume restarts it.
+ *   phase:<name>   inside the runner's phase loop, after setTaskSection +
+ *                  postCommitPhase have persisted the phase output and
+ *                  front-matter `phase` names the NEXT phase. This is exactly
+ *                  the state /task-resume already resumes from (PHASE_INDEX
+ *                  skip-forward), so a cancel here costs nothing.
+ *   pre-final-gate every task is checked off and committed; the whole-repo gate
+ *                  has not started. A resume re-enters the same branch.
+ *
+ * DELIBERATELY NOT checkpoints — stopping here is not safe:
+ *   - mid implementation turn: uncommitted, half-applied edits. The user's ESC
+ *     (declined steer) path already covers "stop now, I accept a partial tree".
+ *   - between the implementation turn and the gates, or inside the gates: the
+ *     work is written but unverified and uncommitted; the gates are what make it
+ *     durable. Cancel is observed on the far side, at loop-top.
+ */
+let requested = false;
+/** Checkpoints actually reached since the last reset, in order. Instrumentation
+ *  for the A/B harness and the unit tests — never read by the loop itself. */
+const crossed = [];
+export function requestCancel() {
+    requested = true;
+}
+export function isCancelRequested() {
+    return requested;
+}
+/**
+ * Clear the request so the next run does not inherit it. Called when a run
+ * starts and in its `finally`.
+ *
+ * The checkpoint trail is deliberately NOT cleared here: the run's `finally`
+ * calls this, and a harness or test that inspects where the run stopped has to
+ * read the trail AFTER the loop returns. Use `resetCheckpointTrail` at the start
+ * of a trial to get a clean slate.
+ */
+export function resetCancel() {
+    requested = false;
+}
+/** Drop the recorded checkpoint trail (A/B + tests). */
+export function resetCheckpointTrail() {
+    crossed.length = 0;
+}
+/**
+ * Poll the cancel flag at a safe checkpoint. Records the visit either way, so a
+ * test can prove a checkpoint is reached at all (a checkpoint that never runs is
+ * indistinguishable from one that never fires).
+ *
+ * @returns true when the caller must stop here.
+ */
+export function cancelCheckpoint(where) {
+    crossed.push(where);
+    // A/B ONLY (scripts/cancel-latency-ab.ts): reproduce the pre-checkpoint
+    // behaviour — the flag was observed at the loop top and nowhere else — so the
+    // two arms differ in exactly the thing under test and share every other path.
+    if (process.env.CANCEL_AB_ARM === 'baseline' && where !== 'loop-top')
+        return false;
+    return requested;
+}
+/** Checkpoints crossed since the last reset (A/B + tests). */
+export function checkpointsCrossed() {
+    return crossed;
+}

package/dist/task/orchestrator.js

@@ -34,6 +34,9 @@ import { runGatesForTask } from './task-gates.js';
 import { parseVerifyBlock } from './spec-validation.js';
 import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phantom-imports.js';
 import { titleForDisplay } from './parsers.js';
+import { USER_CANCELLED } from './child-runner.js';
+import { cancelCheckpoint } from './cancel-points.js';
+import { rearmCancelListener } from './cancel-input.js';
 import { formatTimings } from './timings.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
 // ─── Module-level state ──────────────────────────────────────────────────────
@@ -237,6 +240,18 @@ export class TaskRunner {
                 await setTaskSection(cwd, id, phase.section, out);
                 this._pc[phase.field] = out;
                 await postCommitPhase(phase, this._deps, this._pc, out);
+                // SAFE CHECKPOINT (phase boundary): this phase's output is on disk
+                // and the next `advance()` has not moved front-matter forward, so a
+                // resume re-enters at exactly this phase. Without this the whole
+                // spec pipeline (refine→critique, ~4.5 min on the mx5 run, research
+                // alone ~3 min) runs to completion after a cancel is requested.
+                // Throwing USER_CANCELLED reuses the existing cancellation path:
+                // handleFailure leaves the task resumable and /task-auto's catch
+                // announces the resume hint.
+                if (cancelCheckpoint(`phase:${phase.name}`)) {
+                    this._deps.logDebug?.(`cancel: stopping after phase ${phase.name}`);
+                    throw new Error(USER_CANCELLED);
+                }
             }
             // All phases done — hand off the spec.
             await advance('done');
@@ -594,6 +609,11 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
         withSession: async (newCtx) => {
             freshCtx = newCtx;
             getBridge().currentCtx = newCtx; // keep remote dispatch ctx fresh across session replacement
+            // Same reason, for the terminal: pi clears every extension terminal
+            // input listener when the old session is invalidated, and that
+            // happens at the START of each task — precisely the window a typed
+            // /task-auto-cancel has to survive. No-op unless a run armed one.
+            rearmCancelListener(newCtx);
             const runner = new TaskRunner(newCtx, cwd, rawPrompt, opts.resumeId, async (spec) => {
                 await newCtx.sendUserMessage(spec);
                 if (opts.waitForImplementation) {

package/dist/workers/docs-retrieve.js

@@ -3,11 +3,23 @@ const DEFAULT_BUDGET = 24_000;
 const MIN_TOKEN_LEN = 2;
 const FALLBACK_DTS_CHARS = 12_000;
 const FALLBACK_README_CHARS = 4_000;
+/**
+ * Split on any run of non-identifier characters — NOT on whitespace alone.
+ *
+ * Splitting on /\s+/ and then stripping punctuation INSIDE each token silently welds
+ * multi-part identifiers into one string that occurs nowhere in the corpus:
+ *   "src/server/routes/auth.ts"  ->  "srcserverroutesauthts"
+ *   "Bun.password.hash"          ->  "Bunpasswordhash"
+ * Because buildFtsQuery ORs the tokens, such a token contributes no MATCH at all, so the
+ * single most informative term in the query — the path, or the dotted API symbol — was
+ * dropped and ranking fell to the surrounding prose. Measured on the 141 real project
+ * queries of mx5 run 13, that cost 18% of them any chunk from the file they named
+ * (82% -> 99% retrieved once split on punctuation); on the 44 gradable npm queries,
+ * discriminative-symbol recall 89.5% -> 96.4%.
+ * See scripts/live-project-docs-retrieval-ab.ts and scripts/live-npm-tokenizer-regression.ts.
+ */
 function tokenize(query) {
-    return query
-        .split(/\s+/)
-        .map(t => t.replace(/[^a-zA-Z0-9_]/g, ''))
-        .filter(t => t.length >= MIN_TOKEN_LEN);
+    return query.split(/[^a-zA-Z0-9_]+/).filter(t => t.length >= MIN_TOKEN_LEN);
 }
 function buildFtsQuery(tokens) {
     return tokens.map(t => `"${t}"`).join(' OR ');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.32",
+    "version": "0.18.34",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",