@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/loop-detector.js

@@ -12,7 +12,19 @@
  *
  * Either pattern returns a LoopHit so the caller can kill the child and re-spawn
  * with a hint. No I/O. No imports from index.ts. Trivially unit-testable.
+ *
+ * The three tuning constants live here rather than in child-runner.ts because
+ * worker-profiles.ts reads them at module top level to build DEFAULT_LOOP_DETECTOR.
+ * From child-runner.ts that is a cycle — child-runner → worker-profiles →
+ * child-runner — and the failure is a TDZ ReferenceError on import order, which
+ * no compile step catches. This module imports nothing, so it cannot close one.
  */
+/** Recent tool calls the exact-repeat rule looks back over. */
+export const LOOP_WINDOW = 20;
+/** Repeats of one key within the window that trip the detector. */
+export const LOOP_THRESHOLD = 5;
+/** Re-spawns allowed after a loop kill — 3 attempts total with the initial one. */
+export const MAX_LOOP_RESTARTS = 2;
 /**
  * JSON.stringify with sorted object keys so {a:1,b:2} and {b:2,a:1} hash equal.
  * Arrays preserve their order (positional). undefined / primitives passthrough.
@@ -28,6 +40,14 @@ export function stableStringify(value) {
         return sorted;
     });
 }
+/**
+ * The exact-match identity of a tool call. Exported because implementation-guards.ts
+ * keys its own per-call strike count on it, and a second hand-written copy of this
+ * expression is free to drift away from the one `record` uses.
+ */
+export function loopKey(call) {
+    return `${call.name}\x00${stableStringify(call.args)}`;
+}
 /**
  * The primary file path a tool call targets, mirroring summarizeToolArgs' field
  * precedence. Returns null when the call names no path (e.g. bash, or a grep
@@ -52,7 +72,11 @@ function readOffset(args) {
     const o = args.offset;
     return typeof o === 'number' && Number.isFinite(o) ? o : 0;
 }
-/** Default `limit` pi's read tool applies when the call names none. */
+/**
+ * pi's read tool truncates its output at `DEFAULT_MAX_LINES` lines (its
+ * `core/tools/truncate` module). A `limit` at or above that asks for as much as
+ * the tool will ever return, so it is treated the same as naming no limit at all.
+ */
 const DEFAULT_READ_LIMIT = 2000;
 /**
  * The last line a call reaches, so a page can be told from a re-read. Absent,
@@ -74,7 +98,7 @@ export class LoopDetector {
     threshold;
     pathThreshold;
     buf = [];
-    constructor(window = 20, threshold = 5, 
+    constructor(window = LOOP_WINDOW, threshold = LOOP_THRESHOLD, 
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     pathThreshold = threshold) {
         this.window = window;
@@ -83,7 +107,7 @@ export class LoopDetector {
     }
     /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call) {
-        const key = `${call.name}\x00${stableStringify(call.args)}`;
+        const key = loopKey(call);
         const offset = readOffset(call.args);
         this.buf.push({ key, path: primaryPath(call.args), offset, end: readEnd(call.args, offset) });
         if (this.buf.length > this.window)
@@ -96,9 +120,8 @@ export class LoopDetector {
         if (exact >= this.threshold)
             return { call, count: exact, windowSize: this.buf.length };
         // 2. Path-aware loop: the same file re-targeted without forward progress.
-        // Caught here precisely because varied offset/limit make the exact key
-        // miss it (TASK_0017: auth.ts read/grepped ~12× with changing args until
-        // the wall-clock timeout, never tripping the exact detector).
+        // Caught here precisely because varied offset/limit change the exact key on
+        // every call, so pattern 1 above can never see it.
         const path = this.buf[this.buf.length - 1].path;
         if (path !== null) {
             const revisits = this.countRevisits(path);
@@ -111,15 +134,16 @@ export class LoopDetector {
     /**
      * Count same-path calls in the window that are "revisits" — accesses that end
      * no further into the file than the furthest line already covered for that
-     * path. Paging yields zero revisits and never trips; repeated whole-file
-     * re-reads, backward jumps and path-targeting greps accumulate.
+     * path. The FIRST call on a path is therefore never a revisit: it sets the
+     * high-water mark. Paging yields zero revisits and never trips; repeated
+     * whole-file re-reads, backward jumps, narrower re-reads and repeated
+     * path-targeting greps all accumulate.
      *
-     * The comparison is on the RANGE, not the offset. Offset alone scored a page
-     * that re-asks from the same start with a bigger limit — `{offset:80,
-     * limit:400}` after `{offset:80, limit:300}`, real reads from a measured
-     * decompose run — as a revisit, even though it covers 100 lines the child had
-     * never seen. That is the same mistake SingleReadGuard made by keying on the
-     * path alone, and it is corrected the same way.
+     * The comparison is on the RANGE, not the offset. Keying on offset alone scores
+     * `{offset:80, limit:400}` after `{offset:80, limit:300}` as a revisit, even
+     * though it covers 100 lines the child has never seen. That is the same mistake
+     * SingleReadGuard made by keying on the path alone, and it is corrected the same
+     * way.
      */
     countRevisits(path) {
         let maxEnd = -1;

package/dist/task/mid-run-input.d.ts

@@ -1,26 +1,28 @@
 /**
  * What a typed message DOES while a task run owns the session.
  *
- * Before this module the two surfaces disagreed, and both were wrong whenever the
- * host session was idle — which is most of a run, since the spec phases and every
- * gate are child `pi` processes, not host turns:
+ * Both surfaces — the terminal Enter listener and the remote browser — need ONE
+ * rule, because for most of a run the HOST session is idle: the spec phases and
+ * every gate are child `pi` processes, not host turns. Left to itself each surface
+ * has its own failure on an idle session:
  *
- *   - browser  → `sendUserMessage` with no delivery mode, which starts a SECOND
- *                turn alongside the run. Reproduced live on pi 0.82.1 (issue #8):
- *                that turn ran the write tool into the project, and when it was
- *                still streaming as the pipeline delivered its spec the run died
- *                with "TASK_0001 failed: Agent is already processing."
- *   - terminal → pi's `pendingUserInputs` queue, drained only by the main loop
- *                that our own command handler is parked inside — so the line sat
- *                there silently and then fired minutes later against a finished
- *                run.
+ *   - browser  → `sendUserMessage` with no delivery mode. pi's own API docs call it
+ *                "Always triggers a turn", so it opens a SECOND turn beside the run,
+ *                with the write tool in hand. If that turn is still streaming when
+ *                the pipeline delivers its spec, the spec's own send hits pi's
+ *                guard: "Agent is already processing. Specify streamingBehavior
+ *                ('steer' or 'followUp') to queue the message."
+ *   - terminal → pi's `pendingUserInputs` queue, which only `getUserInput()` drains
+ *                — and that is the main loop our own command handler is parked
+ *                inside. The line sits there silently, then fires against a
+ *                finished run.
  *
- * The shared rule both surfaces now follow:
+ * The shared rule both surfaces follow:
  *
- *   agent streaming → steer the live turn (unchanged; this half always worked)
+ *   agent streaming → steer the live turn
  *   agent idle, run active → HOLD it here, show it as pending, and deliver it as
  *                            a steer when the next task turn starts
- *   no run active → ordinary message, unchanged
+ *   no run active → ordinary message
  *
  * Holding is what makes the two surfaces agree AND keeps the run safe: a held
  * line never becomes a competing turn, and it is never silently replayed after

package/dist/task/mid-run-input.js

@@ -1,26 +1,28 @@
 /**
  * What a typed message DOES while a task run owns the session.
  *
- * Before this module the two surfaces disagreed, and both were wrong whenever the
- * host session was idle — which is most of a run, since the spec phases and every
- * gate are child `pi` processes, not host turns:
+ * Both surfaces — the terminal Enter listener and the remote browser — need ONE
+ * rule, because for most of a run the HOST session is idle: the spec phases and
+ * every gate are child `pi` processes, not host turns. Left to itself each surface
+ * has its own failure on an idle session:
  *
- *   - browser  → `sendUserMessage` with no delivery mode, which starts a SECOND
- *                turn alongside the run. Reproduced live on pi 0.82.1 (issue #8):
- *                that turn ran the write tool into the project, and when it was
- *                still streaming as the pipeline delivered its spec the run died
- *                with "TASK_0001 failed: Agent is already processing."
- *   - terminal → pi's `pendingUserInputs` queue, drained only by the main loop
- *                that our own command handler is parked inside — so the line sat
- *                there silently and then fired minutes later against a finished
- *                run.
+ *   - browser  → `sendUserMessage` with no delivery mode. pi's own API docs call it
+ *                "Always triggers a turn", so it opens a SECOND turn beside the run,
+ *                with the write tool in hand. If that turn is still streaming when
+ *                the pipeline delivers its spec, the spec's own send hits pi's
+ *                guard: "Agent is already processing. Specify streamingBehavior
+ *                ('steer' or 'followUp') to queue the message."
+ *   - terminal → pi's `pendingUserInputs` queue, which only `getUserInput()` drains
+ *                — and that is the main loop our own command handler is parked
+ *                inside. The line sits there silently, then fires against a
+ *                finished run.
  *
- * The shared rule both surfaces now follow:
+ * The shared rule both surfaces follow:
  *
- *   agent streaming → steer the live turn (unchanged; this half always worked)
+ *   agent streaming → steer the live turn
  *   agent idle, run active → HOLD it here, show it as pending, and deliver it as
  *                            a steer when the next task turn starts
- *   no run active → ordinary message, unchanged
+ *   no run active → ordinary message
  *
  * Holding is what makes the two surfaces agree AND keeps the run safe: a held
  * line never becomes a competing turn, and it is never silently replayed after

package/dist/task/orchestrator.d.ts

@@ -12,8 +12,9 @@
  *   /task-cancel           cancel the running task (soft-terminal — still resumable)
  *
  * The orchestrator persists after every phase boundary to
- * <cwd>/.pi-tasks/TASK_NNNN.md. All user interaction during phases runs through
- * ctx.ui dialogs; the main pi chat only receives the final spec.
+ * <cwd>/.pi-tasks/TASK_NNNN.md. User interaction during phases runs through the
+ * SessionUI bridge — a local ctx.ui dialog raced against a remote browser card —
+ * never through the main conversation, which only receives the final spec.
  */
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type WidgetState } from './widget.js';
@@ -43,12 +44,13 @@ export interface TaskRunnerOptions {
      * `spawn` drives the Error-triage ladder or a real process. `runChild(name,
      * tools, prompt)` answers every phase child BY NAME, with none of the
      * ladder's guards — use it when the child is a premise of the test, not its
-     * subject. `runWorker(label, input)` answers every research worker by name,
-     * so the three Research retry gates are reachable without matching a marker
-     * sentence inside a prompt. The EXTERNAL CONTEXT lookups and the file
+     * subject. `runWorker(label, input)` answers every research worker by name, so
+     * the research phase's retry gates (`zeroRetrievalRetry`, `retryIfSilent`, the
+     * restart ladder) are reachable without matching a marker sentence inside a
+     * prompt. The EXTERNAL CONTEXT lookups and the file
      * inventory each default to the real implementation when absent. `timeoutMs`,
-     * `sleepFor`, `childExtensions` and `logDebug` are seams too, and were
-     * unreachable from here until this became one field.
+     * `sleepFor`, `childExtensions` and `logDebug` are seams too, and travel in the
+     * same field.
      */
     seams?: PhaseSeams;
     /** Called with the resolved task id once its file exists, before any phase
@@ -96,9 +98,9 @@ export declare class TaskRunner {
     private readonly _deps;
     private readonly _pc;
     /**
-     * Per-phase wall-clock durations collected during the run. Written to the
-     * `## phase timings` section on successful completion so we can spot
-     * regressions and target future speed work. Each top-level entry is a
+     * Per-phase wall-clock durations collected during the run, written to the
+     * `## phase timings` section — on completion, and again from the catch so a
+     * failed run still records what it got through. Each top-level entry is a
      * phase (refine/research/grill/compose/critique); children are optional
      * sub-step splits the phase chose to record via deps.recordSubStep.
      */
@@ -111,16 +113,15 @@ export declare class TaskRunner {
     status(): WidgetState | null;
     /** Cancel the running task by aborting the signal. */
     cancel(): void;
-    /** Execute the full task lifecycle. Mid-run input holds instead of starting
-     *  a competing turn for the whole of it, and the terminal interception is
-     *  armed for the same window (`withRun`); nested inside `runGatedTask` or
-     *  the `/task-auto` loop the bracket refcounts, so this changes nothing there
-     *  and covers the fire-and-forget `runSingleTask` path on its own. */
     /**
-     * Run the task and NAME how it ended.
+     * Run the task and NAME how it ended (`RunEnd`), so no caller has to re-read
+     * the task file to find out.
      *
-     * This returned `void`, so the caller re-read the task file to learn what had
-     * just happened here — see run-end.ts for the report that got wrong.
+     * Mid-run input holds instead of starting a competing turn for the whole of
+     * it, and the terminal interception is armed for the same window (`withRun`);
+     * nested inside `runGatedTask` or the `/task-auto` loop the bracket refcounts,
+     * so this changes nothing there and covers the fire-and-forget
+     * `runSingleTask` path on its own.
      */
     run(): Promise<RunEnd>;
     private _run;
@@ -163,8 +164,8 @@ export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId'
     notifyFinish?: boolean;
     /**
      * How the implementation turn's thinking level is read and written. Defaults
-     * to the live pi session; injected by tests, which must be able to assert
-     * the restore without a real session to restore.
+     * to the live pi session; injectable so the hold-and-restore is assertable
+     * with no real session to restore.
      */
     thinkingControl?: ThinkingControl;
 }
@@ -172,11 +173,7 @@ export interface RunSingleTaskResult {
     taskId: string;
     /**
      * How the run ended, named by the runner rather than re-derived from disk.
-     *
-     * This was `ok: boolean` plus `sessionCancelled`, `interrupted` and `reason`
-     * — four fields for one fact, three of them smuggled out of the `withSession`
-     * closure through mutable captures. `/task-cancel` fell into the `!ok` arm
-     * and was reported as a failure; see run-end.ts.
+     * One value for one fact: see run-end.ts for the endings and their policy.
      */
     end: RunEnd;
     /**
@@ -194,9 +191,8 @@ export interface RunSingleTaskResult {
  * deliver its spec. With waitForImplementation, block until the agent finishes
  * implementing the delivered spec.
  *
- * The ending comes from `TaskRunner.run`. It used to be read back off the task
- * file's front matter — a disk round-trip this process made to learn what it had
- * just done, and one that could not tell a cancel from a failure.
+ * The ending in the result comes from `TaskRunner.run` itself, not from re-reading
+ * the task file's front matter — which cannot tell a cancel from a failure.
  */
 export declare function runSingleTask(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, opts?: RunSingleTaskOptions): Promise<RunSingleTaskResult>;
 /**

package/dist/task/orchestrator.js

@@ -12,8 +12,9 @@
  *   /task-cancel           cancel the running task (soft-terminal — still resumable)
  *
  * The orchestrator persists after every phase boundary to
- * <cwd>/.pi-tasks/TASK_NNNN.md. All user interaction during phases runs through
- * ctx.ui dialogs; the main pi chat only receives the final spec.
+ * <cwd>/.pi-tasks/TASK_NNNN.md. User interaction during phases runs through the
+ * SessionUI bridge — a local ctx.ui dialog raced against a remote browser card —
+ * never through the main conversation, which only receives the final spec.
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -25,6 +26,7 @@ import { readTextFile } from '../shared/fs-text.js';
 import { allocateTaskId, ensureTasksDir, readSection, readTaskFile, setTaskSection, taskFilePath, tasksDir, updateTaskFrontMatter, writeTaskFile } from './task-io.js';
 import { startWidget } from './widget.js';
 import { armImplWidget, disarmImplWidget, setupImplWidget } from './impl-widget.js';
+import { armImplementationGuard, disarmImplementationGuard } from './implementation-guards.js';
 import { publishViewer, publishNotify, registerBridgeCommand, getBridge } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
@@ -61,11 +63,12 @@ let piApi = null;
 /**
  * The live session's thinking level, as a {@link ThinkingControl}.
  *
- * Goes through `piApi` rather than the command ctx because
- * `ExtensionCommandContext` exposes `thinkingLevel` READ-ONLY; the setter lives
- * on the extension API. Before `registerTask(pi)` has run there is nothing to
- * control, so this degrades to a no-op pair rather than throwing — a task that
- * cannot move the level should still run.
+ * Goes through `piApi` rather than the command ctx because `ExtensionContext`
+ * (which the command ctx extends) carries `thinkingLevel` as a plain optional
+ * VALUE with no setter; `setThinkingLevel` lives on `ExtensionAPI`. Before
+ * `registerTask(pi)` has run there is nothing to control, so this degrades to a
+ * no-op pair rather than throwing — a task that cannot move the level should
+ * still run.
  */
 function piThinkingControl() {
     const api = piApi;
@@ -93,9 +96,9 @@ export class TaskRunner {
     _deps;
     _pc;
     /**
-     * Per-phase wall-clock durations collected during the run. Written to the
-     * `## phase timings` section on successful completion so we can spot
-     * regressions and target future speed work. Each top-level entry is a
+     * Per-phase wall-clock durations collected during the run, written to the
+     * `## phase timings` section — on completion, and again from the catch so a
+     * failed run still records what it got through. Each top-level entry is a
      * phase (refine/research/grill/compose/critique); children are optional
      * sub-step splits the phase chose to record via deps.recordSubStep.
      */
@@ -113,8 +116,8 @@ export class TaskRunner {
         this._fixInstruction = opts.fixInstruction;
         this._implAwaited = opts.implAwaited ?? false;
         this._startedAt = Date.now();
-        // We'll populate id/title/phase lazily in run().
-        // Placeholder — real values set in run().
+        // Placeholder: id/title/phase are only known once run() has allocated or
+        // read the task file.
         this._widgetState = {
             taskId: '',
             title: '',
@@ -137,7 +140,7 @@ export class TaskRunner {
             },
             // Handed DOWN so the child's own snapshot carries a window and the
             // StallDetector's churn rule can arm; resolveContextUsage below stays
-            // as the fallback for a child that still reports none (issue #16).
+            // as the fallback for a child that still reports none.
             contextWindow: parentContextWindow,
             onContextUsage: snapshot => {
                 this._widgetState.contextUsage = resolveContextUsage(snapshot, this._widgetState.contextUsage, parentContextWindow);
@@ -175,16 +178,15 @@ export class TaskRunner {
     cancel() {
         this._abort.abort();
     }
-    /** Execute the full task lifecycle. Mid-run input holds instead of starting
-     *  a competing turn for the whole of it, and the terminal interception is
-     *  armed for the same window (`withRun`); nested inside `runGatedTask` or
-     *  the `/task-auto` loop the bracket refcounts, so this changes nothing there
-     *  and covers the fire-and-forget `runSingleTask` path on its own. */
     /**
-     * Run the task and NAME how it ended.
+     * Run the task and NAME how it ended (`RunEnd`), so no caller has to re-read
+     * the task file to find out.
      *
-     * This returned `void`, so the caller re-read the task file to learn what had
-     * just happened here — see run-end.ts for the report that got wrong.
+     * Mid-run input holds instead of starting a competing turn for the whole of
+     * it, and the terminal interception is armed for the same window (`withRun`);
+     * nested inside `runGatedTask` or the `/task-auto` loop the bracket refcounts,
+     * so this changes nothing there and covers the fire-and-forget
+     * `runSingleTask` path on its own.
      */
     async run() {
         return withRun(this._ctx, {}, () => this._run());
@@ -226,11 +228,12 @@ export class TaskRunner {
             await this._onStart(id);
         // Wire up per-task debug log (<cwd>/.pi-tasks/TASK_XXXX-debug.log).
         const debugLogPath = path.join(tasksDir(cwd), `${id}-debug.log`);
-        // Left UNSET at level `off`, so the ~39 `logDebug?.(…)` sites downstream
-        // short-circuit before they format a string and the file is never created.
-        // A caller-supplied `logDebug` seam WINS: it is the only way to observe
-        // the ~39 trail decisions from a runner-driven test, and production never
-        // sets one, so the file writer is unaffected.
+        // `gateDebugWriter` returns undefined at level `off`, so every
+        // `logDebug?.(…)` site downstream short-circuits before it formats a string
+        // and the file is never created. A caller-supplied `logDebug` seam WINS
+        // (`??=`): it is the only way to observe the trail decisions from a
+        // runner-driven test, and production never sets one, so the file writer is
+        // unaffected.
         this._deps.logDebug ??= gateDebugWriter((msg) => {
             const line = `${new Date().toISOString()} ${msg}\n`;
             fsp.appendFile(debugLogPath, line).catch(() => {
@@ -295,9 +298,9 @@ export class TaskRunner {
                 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.
+                // resume re-enters at exactly this phase. Without a checkpoint here
+                // the whole refine→critique pipeline 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.
@@ -362,12 +365,24 @@ export class TaskRunner {
         };
         if (this._sendSpec) {
             armImplWidget(meta, { oneShot: !this._implAwaited });
+            // Same lifetime as the widget, and for the same reason: an awaited run
+            // spans resume and steer turns, a fire-and-forget one does not.
+            armImplementationGuard({ oneShot: !this._implAwaited });
+            let delivered = false;
             try {
                 await this._sendSpec(spec);
+                delivered = true;
             }
             finally {
-                if (this._implAwaited)
+                // Arming precedes delivery because the turn can begin inside it. So a
+                // delivery that THREW leaves a guard watching a turn that will never
+                // run: pi's `prompt` rejects on a compaction already in progress, a
+                // missing model, or a failed auth. The next unrelated turn would
+                // inherit it, and this guard can end a turn outright.
+                if (this._implAwaited || !delivered) {
                     disarmImplWidget();
+                    disarmImplementationGuard();
+                }
             }
             return;
         }
@@ -375,11 +390,24 @@ export class TaskRunner {
             throw new Error('extension not initialised (no ExtensionAPI captured)');
         }
         armImplWidget(meta, { oneShot: true });
-        // Always name a delivery mode. pi ignores it when the session is idle and
-        // uses it when something else is streaming — so this one call is correct
-        // in both cases, where an isIdle() check is a check-then-act race that
-        // loses to any turn starting in between (issue #8).
-        piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
+        armImplementationGuard({ oneShot: true });
+        // Same reason as the awaited path's `delivered` flag: this send can throw
+        // SYNCHRONOUSLY — the loader gates every ExtensionAPI action behind
+        // `assertActive()` — and a guard left armed over a turn that never starts
+        // is inherited by the next one, which it can terminate.
+        // Always name a delivery mode. pi's `prompt()` consults `streamingBehavior`
+        // only inside `if (this.isStreaming)`, so naming one is inert on an idle
+        // session and queues on a busy one — correct in both cases, where an
+        // isIdle() check is a check-then-act race that loses to any turn starting
+        // in between.
+        try {
+            piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
+        }
+        catch (e) {
+            disarmImplWidget();
+            disarmImplementationGuard();
+            throw e;
+        }
     }
     /**
      * The spec as the implementer should receive it (Layer B). Layer A strips phantom
@@ -418,9 +446,8 @@ export class TaskRunner {
  * deliver its spec. With waitForImplementation, block until the agent finishes
  * implementing the delivered spec.
  *
- * The ending comes from `TaskRunner.run`. It used to be read back off the task
- * file's front matter — a disk round-trip this process made to learn what it had
- * just done, and one that could not tell a cancel from a failure.
+ * The ending in the result comes from `TaskRunner.run` itself, not from re-reading
+ * the task file's front matter — which cannot tell a cancel from a failure.
  */
 export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
     let taskId = '';
@@ -441,10 +468,12 @@ 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.
+            // Same reason, for the terminal: pi wires
+            // `setBeforeSessionInvalidate(() => this.resetExtensionUI())`, and
+            // `resetExtensionUI` calls `clearExtensionTerminalInputListeners()`.
+            // Every extension listener dies 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({
                 ctx: newCtx,
@@ -460,7 +489,8 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                     // here rather than at either call site.
                     const release = holdImplementationThinking(opts.thinkingControl ?? piThinkingControl());
                     try {
-                        // Queue-or-run: never throws, whatever else is on the session (issue #8).
+                        // Queue-or-run: naming a delivery mode means pi's
+                        // "Agent is already processing" throw is unreachable here.
                         await newCtx.sendUserMessage(spec, { deliverAs: 'followUp' });
                         if (opts.waitForImplementation) {
                             await newCtx.waitForIdle();
@@ -502,12 +532,9 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
     // delivered and the task file already reads `completed`:
     //
     //   • the user interrupted and declined to steer — a pause, not a fault;
-    //   • the implementation turn died with stopReason "error" (a context-overflow
-    //     400, say), which must stop /task-auto here rather than let it commit and
-    //     advance on a file that says `completed`.
-    //
-    // Both used to reach the caller as extra fields beside a boolean, and both are
-    // endings.
+    //   • the implementation turn died with stopReason "error", which must stop
+    //     /task-auto here rather than let it commit and advance on a file that
+    //     says `completed`.
     let end = runEnd;
     if (end.kind === 'completed' && interrupted)
         end = { kind: 'interrupted' };
@@ -536,9 +563,9 @@ export const gateRunTask = (c, cwd, t, opts) => runSingleTask(c, cwd, t, {
     // NO `seams` here, deliberately. Threading them would need a field on
     // `GateParams` and another on `GateDeps`, and nothing — production or
     // test — would set either: the gate is reached through two orchestrators
-    // that build their params from a task file. An unused field on a seam
-    // roster is the `WorkerOutcome.reason` shape (written twelve times, read
-    // by nothing), so this stays unplumbed until a test actually needs it.
+    // that build their params from a task file. `WorkerOutcome.reason` is what
+    // that costs: written at every `workerUnavailable` call site and read
+    // nowhere. So this stays unplumbed until a test actually needs it.
 });
 /**
  * Demote a task file to a resumable state after a gate (or its implementation)
@@ -567,15 +594,13 @@ export async function markResumable(cwd, taskId) {
 export async function runGatedTask(ctx, cwd, raw, opts = {}) {
     // The GATES are part of the run, and they are child processes with the host
     // session idle — the same hold window as the spec phases. Bracketing only
-    // TaskRunner would leave verify/enforce looking like "no run", which a live
-    // run on pi 0.82.1 showed as runActive=false while the widget still read
-    // "verifying work" (issue #8). The body has many early returns, so the
-    // bracket lives in this wrapper rather than in a dozen places. The same
-    // bracket arms the raw-stdin interception for the WHOLE run: without it a
-    // plain /task had no terminal path at all — only /task-auto armed one — so a
-    // line typed during it went into pi's queue and fired after the run (seen
-    // live). No onCancel: a typed /task-auto-cancel goes through the generic
-    // bridge dispatch here.
+    // TaskRunner would leave verify/enforce reading as "no run" while the widget
+    // still says "verifying work". The body has many early returns, so the bracket
+    // lives in this wrapper rather than in a dozen places. The same bracket arms
+    // the raw-stdin interception for the WHOLE run: without it a line typed during
+    // a plain /task lands in pi's `pendingUserInputs` and fires after the run. No
+    // onCancel: a typed /task-auto-cancel goes through the generic bridge dispatch
+    // here.
     await withRun(ctx, {}, () => runGatedTaskInner(ctx, cwd, raw, opts));
 }
 async function runGatedTaskInner(ctx, cwd, raw, opts = {}) {
@@ -595,10 +620,8 @@ async function runGatedTaskInner(ctx, cwd, raw, opts = {}) {
     const res = await deps.runTask(active, cwd, raw, { resumeId: opts.resumeId });
     active = res.ctx ?? active;
     const tag = res.taskId || 'Task';
-    // One dispatch over the named ending. The four-branch ladder this replaces put
-    // a CANCELLED run into the `!ok` arm, so `/task-cancel` overwrote the file's
-    // `cancelled` with `failed` and told the user their task had stopped and needed
-    // fixing. Resumability comes from RUN_END_POLICY; the wording stays here,
+    // One dispatch over the named ending, so a cancel can never be reported as a
+    // failure. Resumability comes from RUN_END_POLICY; the wording stays here,
     // because `/task-auto` says `/task-auto-resume` where this says `/task-resume`.
     if (!runSucceeded(res.end)) {
         const policy = RUN_END_POLICY[res.end.kind];
@@ -656,7 +679,7 @@ async function handleTask(args, ctx) {
     // When a gate is enabled, /task awaits the implementation and runs the same
     // verify + enforce gates a /task-auto sub-task does. With both gates off
     // (the default), /task stays fire-and-forget: hand the spec to the main
-    // conversation and return immediately, exactly as before.
+    // conversation and return immediately.
     const cfg = getConfig();
     if (cfg.verifyWork || cfg.enforceGuidelines) {
         await runGatedTask(ctx, cwd, raw);