@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/task/lint-fix.d.ts

@@ -43,20 +43,18 @@ export interface LintFixDeps {
      */
     introducedBy?: (rel: string) => Promise<string | null>;
     /**
-     * Debug-log sink. This dep did not exist, so all four of this pass's guard
-     * trips were invisible in the trail while the twin (`FinalFixDeps.log`) logged
-     * three of its own — and a guard whose firing leaves no record cannot be
-     * distinguished from one that never armed.
+     * Debug-log sink. Every guard below logs its own trip through it: a guard whose
+     * firing leaves no record cannot be distinguished from one that never armed.
      */
     log?: (msg: string) => void;
 }
 /** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
 export declare const LINT_FIX_TOOLS = "read,edit,bash";
 /**
- * Build the fix child's prompt. The constraints encode both live findings: smallest
- * edits only (the impl re-run's rewrite habit is the defect this pass replaces), and
- * an explicit ban on discarding work (both validation runs reached green via
- * `git checkout` of the work file until the guard existed).
+ * Build the fix child's prompt. Two constraints carry the design: smallest edits
+ * only — the re-run's rewrite habit is the defect this pass replaces — and an
+ * explicit ban on discarding work, which is the cheapest route to a green check and
+ * exactly what the revert-guard exists to catch.
  */
 export declare function buildLintFixPrompt(failReason: string, frozenPaths?: string[]): string;
 /**

package/dist/task/lint-fix.js

@@ -1,17 +1,16 @@
 /**
  * lint-fix — the bounded, graduated resolution for a repo-health verify FAIL.
  *
- * The failure this closes (mx5 run 3, TASK_0017): AUTOFIX's only hammer is a FULL
- * implementation re-run. For a repo-health FAIL of 10 trivial lint findings the live
- * run burned two 36–56-minute impl turns, each REGENERATING a fresh 900-line rewrite
- * that failed lint differently — the loop cannot converge because the tool is bigger
- * than the defect. Validated live on the real TASK_0017 tree: a bounded fix child
- * (read,edit,bash) reached lint-clean in 64s and 106s, 2/2.
+ * WHY A SEPARATE PASS. AUTOFIX's only hammer is a FULL implementation re-run. For a
+ * repo-health FAIL of a few trivial lint findings the re-run REGENERATES the work
+ * rather than editing it, and fresh output fails lint differently — the loop cannot
+ * converge because the tool is bigger than the defect. A bounded fix child
+ * (read,edit,bash) edits only the findings.
  *
- * The same validation caught the design's failure mode: BOTH runs cheated, running
- * `git checkout -- src/test/request.ts` — REVERTING the task's uncommitted work to
- * make the findings vanish. So this pass ships with a deterministic REVERT-GUARD,
- * outcome-based (command filtering can't catch every path to the same effect):
+ * REVERT-GUARD. A fix child can reach lint-clean by DISCARDING the task's
+ * uncommitted work: `git checkout -- <the work file>` makes every finding vanish.
+ * The prompt forbids it, but the guard is outcome-based, because command filtering
+ * cannot catch every path to the same effect:
  *
  *   - Before the child runs: snapshot the full working state (`git add -A` +
  *     `git write-tree`, then unstage) and record which files differ from HEAD.
@@ -28,34 +27,38 @@
  * recommend → AUTOFIX/ACCEPT/dismiss picker, so this pass can only make the loop
  * faster, never change what it can decide.
  *
- * FROZEN-PATH GUARD (mx5 run 12, TASK_0021/0022): the checker's own error text
- * can INSTRUCT an edit to a spec-frozen file (typed ESLint: "playwright/index.ts
- * was not found by the project … Consider either including it in the
- * tsconfig.json") and this child complies — while the task's spec froze
- * `tsconfig.json` and verify's rule-4b prohibition probe then fails the TASK for
- * the gate child's edit. Two gates, contradictory rules, same file; the loop
- * never converges (live: TASK_0021 burned all three unattended AUTOFIX rounds).
- * Prompt framing alone is A/B-proven ~0–1/5 on the weak model (see
- * frozen-path-guard.ts), so the deny is mechanical: the spec's frozen paths are
+ * FROZEN-PATH GUARD. The checker's own error text can INSTRUCT an edit to a
+ * spec-frozen file. Typed ESLint, asked to lint a file outside the tsconfig
+ * `include`, prints:
+ *
+ *     Parsing error: <file> was not found by the project service. Consider either
+ *     including it in the tsconfig.json or including it in allowDefaultProject.
+ *
+ * A child that complies edits `tsconfig.json`. If the task's spec froze that file,
+ * verify's prohibition probe raises rule 4b — "SPEC PROHIBITIONS ARE PART OF THE
+ * BAR — YOU HAVE NO WAIVER AUTHORITY" — and FAILs the TASK for the gate child's
+ * edit. Two gates, contradictory rules, same file; the loop never converges.
+ *
+ * So the deny is mechanical rather than framing: the spec's frozen paths are
  * threaded in via `frozenPaths`, injected into the prompt as a do-not-touch list
- * (belt), and any frozen path the child still changed is deterministically
- * reverted post-child and the fix reported not-applied (suspenders). Only paths
- * that were CLEAN before the child ran are reverted — a frozen path already
- * dirty with (possibly task) work is left alone, in the guard's safe direction:
- * cost time, never work.
+ * (belt), and any frozen path the child still changed is deterministically reverted
+ * post-child and the fix reported not-applied (suspenders). Only paths that were
+ * CLEAN before the child ran are reverted — a frozen path already dirty with
+ * (possibly task) work is left alone, in the guard's safe direction: cost time,
+ * never work.
  *
- * CROSS-TASK DELETION GUARD (mx5 run 12 PROMPT 2, verify-debug.log 17:53:44): the
- * revert-guard above is outcome-based but blind to a CLEAN tracked file — a
- * sibling task's committed deliverable is neither pre-dirty nor pre-untracked, so
- * DELETING it slips both checks, and if the lint converges the pass returns ok
- * (confirmed live: the child deleted TASK_0020's playwright ct files to green a
- * typed-lint it was frozen out of fixing properly). The discriminator is
- * PROVENANCE, not deletion per se: a tracked file the CHILD deleted whose
- * introducing task (per `introducedBy`, git history) differs from the CURRENT
+ * CROSS-TASK DELETION GUARD. The revert-guard above is outcome-based but blind to a
+ * CLEAN tracked file. Delete one and `git status --porcelain` reports ` D <path>`
+ * while it appears in NEITHER of the guard's two lists: it was not pre-dirty (it
+ * matched HEAD) and not pre-untracked (it is tracked). If the lint then converges,
+ * the pass returns ok having destroyed a sibling task's committed deliverable. The
+ * discriminator is PROVENANCE, not deletion per se: a tracked file the CHILD deleted
+ * whose introducing task (per `introducedBy`, git history) differs from the CURRENT
  * task is restored from HEAD and the fix reported not-applied naming the owner.
- * Same-task deletions, unknown provenance, relocations, and any git error all
- * step aside — the guard may only cost time, never work. Armed only when both
- * `currentTaskId` and `introducedBy` are wired.
+ * Same-task deletions, unknown provenance, relocations (a deletion whose basename
+ * reappears among the added paths) and any git error all step aside — the guard may
+ * only cost time, never work. Armed only when both `currentTaskId` and
+ * `introducedBy` are wired.
  */
 import { parseChangedFrozenFiles, pathNamedIn, revertFrozenPaths } from './frozen-path-guard.js';
 import { runFixChild } from './fix-child.js';
@@ -64,10 +67,10 @@ import { findCrossTaskDeletions } from './task-provenance.js';
 /** The fix child edits and runs the checker; bash exists to RUN the check, not git. */
 export const LINT_FIX_TOOLS = 'read,edit,bash';
 /**
- * Build the fix child's prompt. The constraints encode both live findings: smallest
- * edits only (the impl re-run's rewrite habit is the defect this pass replaces), and
- * an explicit ban on discarding work (both validation runs reached green via
- * `git checkout` of the work file until the guard existed).
+ * Build the fix child's prompt. Two constraints carry the design: smallest edits
+ * only — the re-run's rewrite habit is the defect this pass replaces — and an
+ * explicit ban on discarding work, which is the cheapest route to a green check and
+ * exactly what the revert-guard exists to catch.
  */
 export function buildLintFixPrompt(failReason, frozenPaths = []) {
     const frozenBlock = frozenPaths.length === 0 ?
@@ -123,7 +126,7 @@ export function revertGuardViolations(preDirty, stillDirty) {
 const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
 /**
  * Files differing from HEAD, or null when git itself failed. The distinction is
- * load-bearing: mx5 run 4 rolled back two GOOD converged fixes because a git
+ * load-bearing: without it a run rolls back GOOD converged fixes because a git
  * failure after the child read as "[] files still dirty" → every pre-existing work
  * file looked reverted → false "discarded work". A git error is INCONCLUSIVE, not
  * evidence of destruction.
@@ -205,12 +208,10 @@ export async function runBoundedLintFix(deps) {
     // guard for this run (inconclusive ≠ evidence).
     const deletionGuardArmed = Boolean(deps.currentTaskId && deps.introducedBy);
     const preChanges = deletionGuardArmed ? await treeChanges(deps) : null;
-    // The four-rung ladder lives in task/fix-child.ts. A cancel still propagates
-    // (it THROWS, so the caller's USER_CANCELLED path is unchanged); what is new
-    // here is the BLOCKED rung, which this pass instructed in its prompt and then
-    // discarded the reply of — so a child that reported BLOCKED still paid the
-    // whole guard stack and a repo-health re-run (15–69s measured) to be told
-    // `did not converge`, instead of its own stated reason.
+    // The four-rung ladder lives in task/fix-child.ts: a cancel propagates as a
+    // THROW (so the caller's USER_CANCELLED path is unchanged), a child that threw
+    // for any other reason is `error`, a self-declared BLOCKED is `blocked`, and
+    // anything else is `done`.
     const end = await runFixChild({
         runChild: deps.runChild,
         tools: LINT_FIX_TOOLS,
@@ -228,10 +229,10 @@ export async function runBoundedLintFix(deps) {
     // where the twin consults its own.
     // REVERT-GUARD: every pre-existing work file must still differ from HEAD, and
     // every pre-existing untracked file must still exist. Trip → restore snapshot.
-    // Every comparison requires git to have actually SUCCEEDED: a git error after
-    // the child is inconclusive (proven live: it flagged the whole untracked file
-    // list as "discarded" while the child had verifiably edited only lint findings)
-    // — then the guard steps aside and the converge check below still decides.
+    // Every comparison requires git to have actually SUCCEEDED. A git error after
+    // the child reads as "nothing is dirty", which would flag every pre-existing
+    // work file as discarded — inconclusive, not evidence. The guard then steps
+    // aside and the converge check below still decides.
     const stillDirtyList = await dirtyFiles(deps);
     let guardNote;
     const violations = [];
@@ -271,10 +272,9 @@ export async function runBoundedLintFix(deps) {
     }
     // CROSS-TASK DELETION GUARD: a tracked file the CHILD deleted whose
     // introducing task differs from the current task is a sibling's committed
-    // deliverable destroyed to go green (mx5 run 12: the child deleted TASK_0020's
-    // playwright ct files and the pass returned ok — the revert-guard above only
-    // watches pre-dirty and pre-untracked files, and a clean tracked sibling file
-    // is neither). Restore JUST those paths from HEAD (they were clean pre-child,
+    // deliverable destroyed to go green. The revert-guard above only watches
+    // pre-dirty and pre-untracked files, and a clean tracked sibling file is
+    // neither. Restore JUST those paths from HEAD (they were clean pre-child,
     // so nothing of the task's work can be lost) and report not-applied naming the
     // owner. Inconclusive on any side — git error, unknown provenance, same-task
     // deletion, relocation — steps aside.
@@ -300,14 +300,13 @@ export async function runBoundedLintFix(deps) {
             }
         }
     }
-    // FROZEN-PATH GUARD: a frozen path that was clean pre-child and is changed
-    // now is the child's edit — the exact write verify's rule-4b prohibition
-    // probe is guaranteed to fail the TASK for (mx5 run 12: ESLint's own error
-    // text instructed the tsconfig.json edit and the child complied, 5/5 in the
-    // live A/B). Revert JUST those paths (they were clean, so HEAD == pre-state:
-    // no work can be lost) and report not-applied so the caller falls through to
-    // the ordinary recommend → AUTOFIX/ACCEPT picker. Inconclusive git (either
-    // side) → guard steps aside; the verify probe still catches what survives.
+    // FROZEN-PATH GUARD: a frozen path that was clean pre-child and is changed now
+    // is the child's edit — the exact write verify's rule-4b prohibition probe
+    // fails the TASK for. Revert JUST those paths (they were clean, so HEAD ==
+    // pre-state: no work can be lost) and report not-applied so the caller falls
+    // through to the ordinary recommend → AUTOFIX/ACCEPT picker. Inconclusive git
+    // (either side) → guard steps aside; the verify probe still catches what
+    // survives.
     if (preFrozenDirty !== null) {
         const postFrozenDirty = await frozenDirtySet(deps, frozen);
         if (postFrozenDirty !== null) {
@@ -341,18 +340,17 @@ export async function runBoundedLintFix(deps) {
     // while the child's edits sit in the working tree.
     //
     // So BLOCKED does not decide; it only supplies a better REASON when the check
-    // agrees nothing converged. That was the durable half of the win. Skipping the
-    // re-run was the other half, and it is not worth this.
+    // agrees nothing converged. Skipping the re-run on the marker alone is not
+    // worth that risk.
     const health = await deps.repoHealth();
     if (!health.ok) {
         if (end.kind === 'blocked') {
             return { ok: false, reason: `fix child blocked: ${end.note}` };
         }
-        // FROZEN-PATH TRACE on non-convergence (PROMPT 1 layer B): when the child
-        // was honest — it did NOT touch the frozen path, so the guard above never
-        // tripped — but the check is still red and its own output NAMES a frozen
-        // path (typed ESLint: "playwright/index.ts was not found by the project …
-        // consider including it in the tsconfig.json"), the findings can only be
+        // FROZEN-PATH TRACE on non-convergence: when the child was honest — it did
+        // NOT touch the frozen path, so the guard above never tripped — but the
+        // check is still red and its own output NAMES a frozen path (the typed
+        // ESLint message quoted in this file's header), the findings can only be
         // fixed by an edit this task's spec forbids. Report it under the same
         // `frozen-path:` prefix as the guard trip, so the gate loop can route
         // straight to the human picker instead of burning unattended AUTOFIX

package/dist/task/loop-detector.d.ts

@@ -47,15 +47,16 @@ export declare 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.
      */
     private countRevisits;
 }

package/dist/task/loop-detector.js

@@ -52,7 +52,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,
@@ -96,9 +100,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 +114,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>;
 /**