@mjasnikovs/pi-task 0.38.14 → 0.38.16

package/dist/task/final-gate.js

@@ -51,10 +51,8 @@ import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.
 import { deriveOpenDebts, rerunDebtVerifyCommand } from './accept-debt.js';
 import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts } from './launch-contract.js';
 import { readLaunchManifest, inertLaunchContractNote, packageScripts, makeHasTarget } from './launch-manifest.js';
-import { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners, recoverOrphanPort, defaultFindPortHolder } from './boot-probe.js';
+import { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners } from './boot-probe.js';
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
-import { runRenderCheck } from './render-check.js';
-import { runDeepRenderCheck } from './deep-render-check.js';
 import { resolveRunner, runnerEnv } from './runner-resolve.js';
 import { classifyCommandRun, spawnCommand, INFRA_GAP_OUTPUT_RE } from './command-run.js';
 import { findLaunchConfigGap, probeEnv, configGapUnobservedNote } from './launch-config-gap.js';
@@ -255,19 +253,26 @@ function resolveCommandBody(bin, args, scripts, makefile) {
  * passes `extraGapRe` (launch scripts), missing external infrastructure. Only a
  * command that actually ran and exited non-zero for a real reason fails.
  */
-function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe, 
+async function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe, 
 /** Replaces the child's environment wholesale (config-gap probe re-run only —
  *  see launch-config-gap.ts). Absent ⇒ `runnerEnv(runner)`, i.e. unchanged. */
 envOverride, 
 /** The spawner. Injected so the gate's own tests can script a verdict. */
-run = spawnCommand) {
+run = spawnCommand, signal) {
     // Runner resolution (mx5 run 16): a login-shell-stripped PATH left `bun`
     // unspawnable, so every dynamic check skipped and the gate went blind. The
     // resolved binary is spawned, and its directory rides on the child's PATH so
     // the SCRIPT CHAIN can re-invoke the runner (`bun run test` runs `bun test`
     // inside — a bare 127 there is the same blindness one level down).
     const runner = resolveRunner(bin);
-    const verdict = classifyCommandRun(run({ cwd, bin: runner.bin, args, timeoutMs, env: envOverride ?? runnerEnv(runner) }), extraGapRe ? [extraGapRe] : []);
+    const verdict = classifyCommandRun(await run({
+        cwd,
+        bin: runner.bin,
+        args,
+        timeoutMs,
+        env: envOverride ?? runnerEnv(runner),
+        ...(signal === undefined ? {} : { signal })
+    }), extraGapRe ? [extraGapRe] : []);
     if (verdict.outcome === 'gap') {
         return { outcome: 'skip', spawnFailed: verdict.gap === 'spawn-failed' };
     }
@@ -288,7 +293,7 @@ export { taskThatIntroduced };
 // src/). Re-exported so the seven validation harnesses under scripts/ — which have
 // always imported exactly this surface and nothing else from the gate — keep
 // working unchanged. Same pattern as taskThatIntroduced above.
-export { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
+export { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
 // The ACCEPT-debt re-check (`deriveOpenDebts`, `rerunDebtVerifyCommand`) lives in
 // accept-debt.ts with the ledger it reads and writes; re-exported so the
 // orchestrator and the harnesses under scripts/ keep working unchanged.
@@ -394,12 +399,18 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
             return inertClosure();
         }
     }, trackedFiles: trackedFilesFn = trackedFiles } = opts;
-    const stat = runRepoHealthCheck(cwd);
+    // ASYNC: the run-end gate no longer blocks the event loop for the project's own
+    // lint (measured 15s mx5 / 69s aiz-client with zero timer ticks), so a loader can
+    // paint and a cancel can reach the child.
+    const stat = await runRepoHealthCheck(cwd, {
+        run: runCmd,
+        ...(opts.signal === undefined ? {} : { signal: opts.signal })
+    });
     // Debts are derived once, before any section runs, and ride on every verdict
     // shape (GateTally.verdict): `reason` stays the mechanical failure because it
     // seeds the autofix child's prompt — run 11's fix child executed a recorded
     // claim as an instruction.
-    const debts = await deriveOpenDebts(cwd, stat.ok);
+    const debts = await deriveOpenDebts(cwd, stat.ok, runCmd, opts.signal);
     // Every section below RECORDS into the tally (failures ranked, the four
     // dynamic counters, the notes) and the verdict is assembled ONCE at the end —
     // see gate-tally.ts for what each method means.
@@ -446,7 +457,7 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
         for (const cmd of list) {
             const label = `${cmd[0]} ${cmd[1].join(' ')}`;
             tally.attempted(cmd[0]);
-            const r = runGateCommand(cwd, cmd, timeoutMs, undefined, undefined, runCmd);
+            const r = await runGateCommand(cwd, cmd, timeoutMs, undefined, undefined, runCmd, opts.signal);
             if (r.outcome === 'skip') {
                 if (r.spawnFailed)
                     tally.spawnFailure(cmd[0]);
@@ -496,7 +507,7 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
             const cmd = ['bun', ['run', name]];
             const label = `${cmd[0]} ${cmd[1].join(' ')}`;
             tally.attempted(cmd[0]);
-            const r = runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, undefined, runCmd);
+            const r = await runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, undefined, runCmd, opts.signal);
             if (r.outcome === 'skip') {
                 if (r.spawnFailed)
                     tally.spawnFailure(cmd[0]);
@@ -525,7 +536,7 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
                     env: process.env
                 });
                 if (gap) {
-                    const probe = runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, probeEnv(runnerEnv(resolveRunner(cmd[0])), gap), runCmd);
+                    const probe = await runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, probeEnv(runnerEnv(resolveRunner(cmd[0])), gap), runCmd, opts.signal);
                     if (probe.outcome === 'pass') {
                         // Nothing about this script was OBSERVED: the real run could
                         // not reach it and the probe run is a diagnostic, never an
@@ -585,83 +596,33 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
     // statement about when they are meaningful.
     if (!boot && tally.silent())
         return tally.verdict(debts);
-    if (boot) {
-        const label = `${boot[0]} ${boot[1].join(' ')}`;
-        tally.attempted(boot[0]);
-        const expectServer = detectsServedApp(cwd, planText);
-        // Render check (mx5 runs 8/11): for a served app, load the live page in a
-        // headless browser and judge the RENDERED DOM — curl can't run JS, so a
-        // blank-mount app passed every prior "renders" check. Default to the real
-        // probe; tests inject their own. runRenderCheck env-gap-SKIPs when no
-        // browser exists, so a box without one never gets a false FAIL.
-        // Authenticated deep-render check (mx5 run 17): the page above renders, so
-        // now sign in with the account the project's own dotenv declares (the same
-        // ADMIN_PHONE/ADMIN_PASSWORD the launch contract's seed step consumes) and
-        // require the session to actually work. WEB-ONLY by construction — it hangs
-        // off the served-app branch and never runs for C++, Godot, CLI or library
-        // projects. It may only FAIL when the SERVER authenticated us; no browser,
-        // no credentials, an undrivable form or rejected credentials all skip as
-        // env gaps (judgeDeepSession).
-        const bootDepsWithRender = {
-            ...bootDeps,
-            renderProbe: bootDeps.renderProbe ?? runRenderCheck,
-            deepRenderProbe: bootDeps.deepRenderProbe ?? (url => runDeepRenderCheck(url, cwd)),
-            preferredPort: bootDeps.preferredPort ?? (() => preferredDeclaredPort(cwd))
-        };
-        let b = await runBootCheck(cwd, boot, bootGraceMs, {
-            expectServer,
-            deps: bootDepsWithRender
-        });
-        if (b.outcome === 'orphan-port') {
-            b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDepsWithRender, expectServer);
-        }
-        if (b.outcome !== 'skip')
-            tally.observed();
-        else if (b.spawnFailed)
-            tally.spawnFailure(boot[0]);
-        tally.bootUnobserved(bootSkipVerdict({
-            label,
-            skipped: b.outcome === 'skip',
-            expectServer
-        }));
-        if (b.outcome === 'fail') {
-            // OBSERVED (nexttask 19A). Every path that produces `fail` here is a
-            // probe that looked: the render judge saw an empty body, the deep
-            // session saw the authenticated half dead, the enumerator saw no
-            // listener, or the launch command itself exited non-zero. The one
-            // condition that means "we could not look" — no ss/netstat/lsof, mx5
-            // run 14 — returns PASS stamped UNOBSERVED and never reaches here
-            // (`b0f90a7`, final-gate.ts `if (!canEnumerate) return passAndKill(…)`).
-            tally.failObserved(`boot check: \`${label}\` ${b.detail}`, 0);
-        }
-        else if (b.outcome === 'orphan-port') {
-            // Could not clear the port. Distinct HARNESS diagnosis, never a bare app
-            // FAIL: name the port and (when known) the process squatting on it.
-            const holder = b.port !== null ? (bootDeps.findPortHolder ?? defaultFindPortHolder)(b.port) : null;
-            const who = holder ? ` — held by an orphaned process (pid ${holder.pid}: ${holder.command})`
-                : b.port !== null ? ` — port ${b.port} is held by another process`
-                    : '';
-            tally.fail(`boot check: \`${label}\` could not bind: orphaned process / port already in use${who} (harness condition, not an app fault)`, 0);
-        }
-        else if (b.outcome === 'pass') {
-            tally.ran(label);
-            // A listener that served, but whose page could not be OBSERVED to render
-            // (no browser, undeterminable port) → UNOBSERVED warning, not a silent pass.
-            if (b.renderNote)
-                tally.warn(b.renderNote);
-        }
-    }
-    else {
-        // Nothing to boot — but if the reason is that the project's only launch
-        // script was REJECTED as not-a-launch (2A), that is not the same thing as a
-        // project with no launch surface, and it must not degrade into silence.
-        const rejected = rejectedLaunchScript(cwd);
-        if (rejected && detectsServedApp(cwd, planText)) {
-            tally.bootUnobserved(`boot check: this project's only launch script (\`${rejected.name}\`) is not a `
-                + `launch — ${rejected.reason} — so nothing was started and the app was never `
-                + 'observed to run.');
-        }
+    // The boot CONCEPT lives in boot-probe.ts (runBootSection): discovery,
+    // served-app detection, the probe defaults, the boot check, orphan-port
+    // recovery, the port-holder diagnosis, the skip verdict and the
+    // rejected-launch-script branch. This is the record, and nothing else.
+    const bootSection = await runBootSection(cwd, {
+        ...(planText === undefined ? {} : { planText }),
+        ...(bootGraceMs === undefined ? {} : { graceMs: bootGraceMs }),
+        deps: bootDeps
+    });
+    if (bootSection.attempted)
+        tally.attempted(bootSection.attempted);
+    if (bootSection.observed)
+        tally.observed();
+    else if (bootSection.spawnFailedBin)
+        tally.spawnFailure(bootSection.spawnFailedBin);
+    tally.bootUnobserved(bootSection.unobservedNote ?? null);
+    if (bootSection.failure) {
+        const { detail, rank, observed } = bootSection.failure;
+        if (observed)
+            tally.failObserved(detail, rank);
+        else
+            tally.fail(detail, rank);
     }
+    if (bootSection.ranLabel)
+        tally.ran(bootSection.ranLabel);
+    for (const w of bootSection.warnings)
+        tally.warn(w);
     // Full-skip blindness guard (mx5 run 16): commands were discovered but every
     // one skipped → rank-0 failure, never a static-only PASS. Runner resolvability
     // is checked through resolveRunner so the failure text can name the missing

package/dist/task/gate-deps.js

@@ -24,7 +24,7 @@ import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { readContracts } from './contracts.js';
 import { recordDebt } from './accept-debt.js';
 import { recordRepairCandidate } from './root-cause-repair.js';
-import { runRepoHealthCheck, runRepoHealthCheckAsync } from './repo-health-check.js';
+import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels, discoverGateCommandBodies } from './final-gate.js';
 import { runFinalGateAutofix } from './final-gate-fix.js';
 import { researchResolution } from './verify-resolution.js';
@@ -755,14 +755,19 @@ export function buildGateDeps(params) {
                 // own lint/typecheck and fails on a real non-zero exit, independent of
                 // the model-authored VERIFY block (which may not lint at all). ASYNC:
                 // the sync runner froze the event loop for the whole lint (see above).
-                repoHealth: () => deadAirBaseline ?
-                    Promise.resolve(runRepoHealthCheck(cwd2))
-                    : runRepoHealthCheckAsync(cwd2, {
-                        signal,
-                        onCommand: c => {
-                            stageLine = `repo health · ${c}`;
-                        }
-                    }),
+                // ONE call, both arms. The baseline arm used to call this
+                // without the signal or the progress hook, because
+                // `runRepoHealthCheck` was SYNCHRONOUS and blocking the event
+                // loop was the thing being measured. It is async now, so that
+                // branch measured treatment against treatment — and it also
+                // made `DEADAIR_AB_ARM=baseline` silently uncancellable and
+                // mute. The arm's real difference is the LOADER, above.
+                repoHealth: () => runRepoHealthCheck(cwd2, {
+                    signal,
+                    onCommand: c => {
+                        stageLine = `repo health · ${c}`;
+                    }
+                }),
                 // The deterministic probes, bound in one place (buildVerifyProbes
                 // above); the PROBE_ADAPTERS table in verify-work.ts runs them.
                 probes: buildVerifyProbes({
@@ -814,7 +819,7 @@ export function buildGateDeps(params) {
                 signal,
                 failReason,
                 runChild: gateChild(fixCtx, cwd2, taskTitle, 'lint-fix', 'verify-debug.log'),
-                repoHealth: () => runRepoHealthCheckAsync(cwd2, { signal }),
+                repoHealth: () => runRepoHealthCheck(cwd2, { signal }),
                 git: async (args) => {
                     const r = await git(cwd2, args, signal);
                     return { exitCode: r.exitCode, stdout: r.stdout };
@@ -846,7 +851,7 @@ export function buildGateDeps(params) {
                 startedAt,
                 lastLine: running ? `repo health · ${running}` : 'repo health'
             }));
-            return runRepoHealthCheckAsync(cwd2, {
+            return runRepoHealthCheck(cwd2, {
                 signal,
                 onCommand: c => {
                     running = c;
@@ -865,7 +870,9 @@ export function buildGateDeps(params) {
             runChild: gateChild(fixCtx, cwd2, 'final integration gate', 'final-fix', 'final-gate-debug.log'),
             // The gate re-run is the only arbiter of convergence, and the
             // shrink guard's discovery is the gate's own (see final-gate.ts).
-            gate: c => runFinalIntegrationGate(c),
+            // The run's cancel reaches the re-run too. Without it the whole
+            // `FinalGateOptions.signal` path is inert in the shipped code.
+            gate: c => runFinalIntegrationGate(c, { signal }),
             discoverLabels: discoverGateCommandLabels,
             discoverBodies: discoverGateCommandBodies,
             discard: discardTreeEdits,
@@ -893,7 +900,7 @@ export function buildGateDeps(params) {
             // depend on it.
             ignoredSnapshot: () => collectIgnoredSnapshot(cwd2, signal),
             ...(ignoredKnown && ignoredKnown.length > 0 ? { ignoredKnown } : {}),
-            gateWithoutIgnored: paths => gatePassesWithoutIgnored(cwd2, paths, c => runFinalIntegrationGate(c), makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))),
+            gateWithoutIgnored: paths => gatePassesWithoutIgnored(cwd2, paths, c => runFinalIntegrationGate(c, { signal }), makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))),
             log: makeDebugAppender(path.join(tasksDir(cwd2), 'final-gate-debug.log'))
         }),
         recommend: async (recCtx, cwd2, taskTitle, taskId, failReason) => {

package/dist/task/orchestrator.d.ts

@@ -20,6 +20,7 @@ import { type WidgetState } from './widget.js';
 import { type RunTaskFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
 import { type PhaseDeps } from './child-runner.js';
+import { type RunEnd } from './run-end.js';
 import type { SpawnFn } from '../shared/child-process.js';
 import { type SuperviseOptions } from './implementation-turn.js';
 /**
@@ -45,6 +46,16 @@ export interface TaskRunnerOptions {
      * the child is a premise of the test, not its subject.
      */
     runChild?: PhaseDeps['runChild'];
+    /**
+     * Test seam: `PhaseDeps.runWorker(label, input)`. Present → every research
+     * worker is answered BY NAME, so the three Research retry gates and the
+     * fatal/runaway/empty classification are reachable from a runner-driven test
+     * without matching a marker sentence inside the prompt.
+     */
+    runWorker?: PhaseDeps['runWorker'];
+    /** Test seam: the four EXTERNAL CONTEXT lookups plus the file inventory. Each
+     *  defaults to the real implementation when absent. */
+    lookups?: Pick<PhaseDeps, 'getFileInventory' | 'docsRaw' | 'fetchRaw' | 'npmVersionLookup' | 'docsFocused' | 'fetchFocused' | 'searchFn'>;
     /** Called with the resolved task id once its file exists, before any phase
      *  work. Lets callers record the id (e.g. stamp the /task-auto entry) so an
      *  interrupted run can be resumed instead of restarted. */
@@ -110,7 +121,13 @@ export declare class TaskRunner {
      *  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<void>;
+    /**
+     * Run the task and NAME how it ended.
+     *
+     * 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.
+     */
+    run(): Promise<RunEnd>;
     private _run;
     /** Stop the phase widget — clearing both the terminal and remote surfaces —
      *  exactly once. Nulling the disposer makes repeat calls no-ops, so the
@@ -129,7 +146,7 @@ export declare class TaskRunner {
      */
     private _specForDelivery;
 }
-export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId' | 'spawnFn' | 'runChild' | 'onStart' | 'planContext' | 'fixInstruction'> {
+export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId' | 'spawnFn' | 'runChild' | 'runWorker' | 'lookups' | 'onStart' | 'planContext' | 'fixInstruction'> {
     /** Await the session going idle after the spec is delivered, so the caller
      *  blocks until the agent has implemented it. Default false. */
     waitForImplementation?: boolean;
@@ -152,8 +169,15 @@ export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId'
 }
 export interface RunSingleTaskResult {
     taskId: string;
-    ok: boolean;
-    sessionCancelled: boolean;
+    /**
+     * 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.
+     */
+    end: RunEnd;
     /**
      * The session context the caller must use for any work after this call. A
      * successful run replaces the session via ctx.newSession(), which leaves the
@@ -163,30 +187,15 @@ export interface RunSingleTaskResult {
      * only so test fakes that don't model session replacement can omit it.
      */
     ctx?: ExtensionCommandContext;
-    /**
-     * Set when the user interrupted the implementation (ESC) and then declined to
-     * steer (submitted an empty steer prompt) — i.e. they want the run to pause
-     * rather than continue. Only meaningful with waitForImplementation. The
-     * /task-auto loop reads this to pause (resumable) instead of checking the task
-     * off and advancing. A plain ESC that the user follows with steering text does
-     * NOT set this — that case loops on the same task until a turn finishes
-     * uninterrupted.
-     */
-    interrupted?: boolean;
-    /**
-     * Why the run is not ok, when known. Set when a waitForImplementation turn
-     * ended with stopReason "error" (the model/provider died mid-implementation —
-     * e.g. a context-overflow 400 — after the task file was already marked
-     * `completed` at spec-handoff). The /task-auto loop surfaces this in its
-     * "stopped at …" message so the real cause isn't lost. Undefined otherwise.
-     */
-    reason?: string;
 }
 /**
  * Run one prompt through the full single-task pipeline in a fresh session and
  * deliver its spec. With waitForImplementation, block until the agent finishes
- * implementing the delivered spec. Success is read off the produced task file's
- * front-matter state (TaskRunner.run never throws).
+ * 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.
  */
 export declare function runSingleTask(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, opts?: RunSingleTaskOptions): Promise<RunSingleTaskResult>;
 /**

package/dist/task/orchestrator.js

@@ -39,6 +39,7 @@ import { cancelCheckpoint } from './cancel-points.js';
 import { rearmCancelListener } from './cancel-input.js';
 import { takeHeldInput } from './mid-run-input.js';
 import { withRun, announceTerminal } from './run-bracket.js';
+import { RUN_END_POLICY, runSucceeded } from './run-end.js';
 import { formatTimings } from './timings.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
 import { superviseImplementation } from './implementation-turn.js';
@@ -111,6 +112,8 @@ export class TaskRunner {
             signal: this._abort.signal,
             spawn: opts.spawnFn,
             runChild: opts.runChild,
+            runWorker: opts.runWorker,
+            ...opts.lookups,
             // Deliberately NOT a ChildStatus (child-status.ts): the phase widget's
             // state is the whole-run WidgetState — task id, phase, label — shared by
             // reference with PhaseContext and written by the phases themselves
@@ -160,6 +163,12 @@ export class TaskRunner {
      *  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.
+     *
+     * 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.
+     */
     async run() {
         return withRun(this._ctx, {}, () => this._run());
     }
@@ -279,6 +288,7 @@ export class TaskRunner {
             await setTaskSection(cwd, id, 'phase timings', formatTimings(this._timings));
             await setTaskSection(cwd, id, 'handoff', `handoff_at: ${new Date().toISOString()}`);
             await this._deliverSpec(ctx);
+            return { kind: 'completed' };
         }
         catch (err) {
             this._disposeWidget();
@@ -292,7 +302,12 @@ export class TaskRunner {
                     /* ignore — preserve original failure */
                 }
             }
-            await handleFailure(err, ctx, cwd, id, this._abort.signal.aborted);
+            // `classifyFailure` already decided whether this was a cancel or a
+            // fault; the value is the answer, not a side effect of writing a file.
+            const c = await handleFailure(err, ctx, cwd, id, this._abort.signal.aborted);
+            return c.state === 'cancelled' ?
+                { kind: 'cancelled' }
+                : { kind: 'failed', ...(c.reason === undefined ? {} : { reason: c.reason }) };
         }
         finally {
             this._disposeWidget();
@@ -374,11 +389,17 @@ export class TaskRunner {
 /**
  * Run one prompt through the full single-task pipeline in a fresh session and
  * deliver its spec. With waitForImplementation, block until the agent finishes
- * implementing the delivered spec. Success is read off the produced task file's
- * front-matter state (TaskRunner.run never throws).
+ * 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.
  */
 export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
     let taskId = '';
+    // How the runner said it ended. `no-session` until it has run at all — the
+    // withSession callback below may never be entered.
+    let runEnd = { kind: 'no-session' };
     // The newSession replacement ctx, captured so the caller can keep driving the
     // UI after the original ctx is torn down. Defaults to the original for the
     // cancellation path (where no replacement occurs).
@@ -422,12 +443,14 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                 },
                 spawnFn: opts.spawnFn,
                 runChild: opts.runChild,
+                runWorker: opts.runWorker,
+                lookups: opts.lookups,
                 onStart: opts.onStart,
                 planContext: opts.planContext,
                 fixInstruction: opts.fixInstruction,
                 implAwaited: opts.waitForImplementation
             });
-            await runner.run();
+            runEnd = await runner.run();
             taskId = runner.taskId;
         }
     });
@@ -436,32 +459,29 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
         if (opts.notifyFinish) {
             void pushNotify('Task finished', `${taskId || 'Task'} cancelled — could not start a session.`, 'pi-end').catch(() => { });
         }
-        return { taskId, ok: false, sessionCancelled: true, ctx };
-    }
-    let ok = false;
-    let state;
-    if (taskId) {
-        try {
-            const { frontMatter } = await readTaskFile(cwd, taskId);
-            state = frontMatter.state;
-            ok = state === 'completed';
-        }
-        catch {
-            ok = false;
-        }
+        return { taskId, end: { kind: 'no-session' }, ctx };
     }
-    // The file reads `completed` from spec-handoff even when the implementation
-    // turn then died. Demote to a failure so /task-auto stops here (leaving the
-    // entry unchecked and resumable) instead of committing and advancing.
-    if (ok && implError)
-        ok = false;
+    // The runner already named the ending. What the SUPERVISION adds is the two
+    // endings the runner cannot see, because they happen after the spec is
+    // 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.
+    let end = runEnd;
+    if (end.kind === 'completed' && interrupted)
+        end = { kind: 'interrupted' };
+    else if (end.kind === 'completed' && implError)
+        end = { kind: 'failed', reason: implError };
     if (opts.notifyFinish) {
-        // One push per top-level /task or /task-resume, on any terminal end. The
-        // file state is the source of truth: 'completed' on success, 'failed' /
-        // 'cancelled' otherwise; an unreadable/absent file falls back to 'ended'.
-        void pushNotify('Task finished', `${taskId || 'Task'} ${state ?? 'ended'}.`, 'pi-end').catch(() => { });
+        // One push per top-level /task or /task-resume, on any terminal end.
+        void pushNotify('Task finished', `${taskId || 'Task'} ${end.kind}.`, 'pi-end').catch(() => { });
     }
-    return { taskId, ok, sessionCancelled: false, ctx: freshCtx, interrupted, reason: implError };
+    return { taskId, end, ctx: freshCtx };
 }
 // ─── Gated single-task flow ────────────────────────────────────────────────────
 /**
@@ -533,19 +553,21 @@ 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';
-    if (res.sessionCancelled) {
-        announce(`${tag} — could not start a fresh session for /task.`, 'warning');
-        return;
-    }
-    if (res.interrupted) {
-        await markResumable(cwd, res.taskId);
-        announce(`${tag} paused — resume with /task-resume.`, 'warning');
-        return;
-    }
-    if (!res.ok) {
-        await markResumable(cwd, res.taskId);
-        const why = res.reason ? ` — ${res.reason.slice(0, 160)}` : '';
-        announce(`${tag} stopped${why} — fix and run /task-resume.`, 'error');
+    // 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,
+    // because `/task-auto` says `/task-auto-resume` where this says `/task-resume`.
+    if (!runSucceeded(res.end)) {
+        const policy = RUN_END_POLICY[res.end.kind];
+        if (policy.resumable)
+            await markResumable(cwd, res.taskId);
+        const why = res.end.kind === 'failed' && res.end.reason ? ` — ${res.end.reason.slice(0, 160)}` : '';
+        const msg = res.end.kind === 'no-session' ? `${tag} — could not start a fresh session for /task.`
+            : res.end.kind === 'cancelled' ? `${tag} cancelled.`
+                : res.end.kind === 'interrupted' ? `${tag} paused — resume with /task-resume.`
+                    : `${tag} stopped${why} — fix and run /task-resume.`;
+        announce(msg, policy.level);
         return;
     }
     // The composed task's own front-matter title — used in commit messages and
@@ -598,8 +620,8 @@ async function handleTask(args, ctx) {
         await runGatedTask(ctx, cwd, raw);
         return;
     }
-    const { sessionCancelled } = await runSingleTask(ctx, cwd, raw, { notifyFinish: true });
-    if (sessionCancelled) {
+    const { end } = await runSingleTask(ctx, cwd, raw, { notifyFinish: true });
+    if (end.kind === 'no-session') {
         ctx.ui.notify('Could not start a fresh session for /task.', 'warning');
     }
 }
@@ -687,8 +709,8 @@ async function handleTaskResume(args, ctx) {
         await runGatedTask(ctx, cwd, '', { resumeId: id });
         return;
     }
-    const { sessionCancelled } = await runSingleTask(ctx, cwd, '', { resumeId: id, notifyFinish: true });
-    if (sessionCancelled) {
+    const { end } = await runSingleTask(ctx, cwd, '', { resumeId: id, notifyFinish: true });
+    if (end.kind === 'no-session') {
         ctx.ui.notify('Could not start a fresh session for /task-resume.', 'warning');
     }
 }