@mjasnikovs/pi-task 0.38.28 → 0.38.30

package/dist/task/boot-probe.js

@@ -2,22 +2,21 @@
  * boot-probe — does the assembled product actually START, and does the page it
  * serves actually render?
  *
- * Lifted out of final-gate.ts, where it was 42% of a 2185-line file and the largest
- * of seven unrelated concerns. Nothing inside `src/` imported any of it except the
- * one call site in `runFinalIntegrationGate`; the de-facto module boundary already
- * existed in the CONSUMERS — seven validation harnesses under `scripts/` import
- * exactly this surface and nothing else from the gate.
+ * Its one consumer is final-gate.ts, which imports twelve names from here, calls
+ * `discoverBootCommand` at three sites and `runBootSection` at one, and re-exports
+ * six of them plus `BootSectionVerdict` for its own callers.
  *
- * The public surface is those six names: `discoverBootCommand`, `detectsServedApp`,
- * `runBootCheck`, `bootSkipVerdict`, `nonLaunchScriptReason` and `BootDeps`. The
- * listener parsers stay exported because their tests are worth keeping, but they are
- * now a sibling module's surface rather than noise in the gate's. Everything else —
- * orphan-port recovery, pgid probing, the HTTP evidence probe, port reservation —
- * is private, which it could not be while it shared a file with the gate.
+ * The entry points are `discoverBootCommand`, `detectsServedApp`, `runBootCheck`,
+ * `runBootSection` and `bootSkipVerdict`. Much else is exported too — the three
+ * listener parsers, the port helpers (`pickFreePort`, `isPortFree`,
+ * `preferredDeclaredPort`), `canEnumerateListeners`, `defaultFindPortHolder`,
+ * `recoverOrphanPort`, `rejectedLaunchScript` — because the gate or their own
+ * tests reach for them. Only the pgid helpers, the HTTP evidence probe, the reap
+ * and the spawn/teardown defaults are private.
  *
- * The boot check is deliberately NOT a CLOSURE_SCANS row: it is an async, stateful,
- * port-binding exercise, and every row would need its own escape hatch. This is a
- * file move, not a re-shaping.
+ * The boot check is deliberately NOT a CLOSURE_SCANS row (final-gate.ts): it is an
+ * async, stateful, port-binding exercise, and every row would need its own escape
+ * hatch.
  */
 import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
@@ -98,9 +97,9 @@ function isWatcherOnlyMultiplexer(member, scripts) {
 }
 /**
  * Why this script is NOT a launch of the shipped app, or null when it plausibly
- * is one (mx5 run 18, validated).
+ * is one.
  *
- * Run 18's boot command resolved to `bun run dev`, whose body is
+ * A boot command can resolve to `bun run dev`, whose body is
  * `docker compose -f docker-compose.dev.yml up -d && until docker compose … pg_isready
  * … && concurrently "bun run dev:css" "bun run dev:js" "bun run --watch
  * src/server/index.ts"`. The gate sandbox has no docker, so the chain died at 127 and
@@ -112,15 +111,22 @@ function isWatcherOnlyMultiplexer(member, scripts) {
  * producing an unfalsifiable skip.
  *
  * CONSERVATIVE AND LEXICAL BY CONSTRUCTION. Only two shapes are rejected, both
- * decidable from the script text alone:
+ * decidable from the script text alone, and both run against every case named
+ * below:
  *   1. the chain OPENS with container orchestration (docker/podman/nerdctl … up|start|run);
  *   2. the whole body is a multiplexer (concurrently/npm-run-all/run-p/run-s/turbo)
  *      whose every child is an ASSET watcher in watch mode (tailwind/tsc/esbuild/…),
  *      i.e. nothing in it can ever listen.
- * Anything else — `vite`, `next dev`, `node dist/index.js`, `nodemon`, `bun --watch
- * src/index.ts`, and any multiplexer with one non-asset child — is accepted
- * unchanged. Deciding whether a watcher actually SERVES is not attempted here; that
- * is exactly what the static serve-entry check is for.
+ * Anything else — `vite`, `next dev`, `node dist/index.js`, `nodemon`, `bun run
+ * --watch src/index.ts`, and any multiplexer with one non-asset child — is accepted
+ * unchanged. All of those were run and accepted; so was a bare
+ * `tailwindcss … --watch`, which is only rejected INSIDE a multiplexer. A chain
+ * opening `docker compose … up` is rejected even when a real launch follows it,
+ * while `bun run docker-compose.dev.yml` is accepted, since the verb must be a
+ * bare token.
+ *
+ * Deciding whether a watcher actually SERVES is not attempted here; that is exactly
+ * what the static serve-entry check is for.
  */
 export function nonLaunchScriptReason(body, scripts = {}) {
     const members = chainMembers(body);
@@ -139,7 +145,7 @@ export function nonLaunchScriptReason(body, scripts = {}) {
  * else `dev`; Makefile `run`). null means the project has nothing to boot —
  * the boot check degrades to nothing-to-run.
  *
- * A script that is not a LAUNCH at all (nonLaunchScriptReason — mx5 run 18's
+ * A script that is not a LAUNCH at all (nonLaunchScriptReason — an
  * `docker compose up` orchestrator) is rejected here and falls through to the
  * next candidate, then to null. Discovering nothing is strictly better than
  * discovering something unfalsifiable: an env-gap skip of an orchestration script
@@ -161,7 +167,7 @@ export function discoverBootCommand(cwd) {
 }
 /**
  * The launch script that EXISTS but was rejected as not-a-launch, if any. Without
- * this the rejection would trade run 18's unfalsifiable skip for pure silence: no
+ * this the rejection would trade an unfalsifiable skip for pure silence: no
  * boot command means bootSkipVerdict has no label to name, and a project whose test
  * suite ran still reports `observed > 0`, so unobservedVerdict stays quiet too. A
  * served app whose only declared launch script cannot start it was not observed to
@@ -245,11 +251,14 @@ export function parseSsListeners(stdout) {
     return out;
 }
 /**
- * `netstat -tlnp` rows → {pid, port} (mx5 run 14, validated: the agent-sandbox
- * image ships NEITHER ss NOR lsof — only ps and netstat — so the served-app boot
- * check could never observe a listener and failed unfalsifiably). The pid rides
- * in the trailing "PID/Program name" column ("1234/bun"); rows the kernel will
- * not attribute to us print "-" there and are skipped.
+ * `netstat -tlnp` rows → {pid, port}. Three parsers exist because no single
+ * enumerator is present everywhere — a box may ship netstat and no ss, or ss and
+ * no netstat — and without SOME enumerator the served-app check can never observe
+ * a listener and fails unfalsifiably.
+ *
+ * The pid rides in the trailing "PID/Program name" column ("1234/bun"); rows the
+ * kernel will not attribute to us print "-" there and are skipped. Both run as
+ * described.
  */
 export function parseNetstatListeners(stdout) {
     const out = [];
@@ -309,7 +318,7 @@ function listeningSockets() {
     return [];
 }
 /**
- * Can ANY socket-enumeration tool run here at all? (mx5 run 14: the sandbox had
+ * Can ANY socket-enumeration tool run here at all? (a sandbox may have
  * none, so `groupHasListener` returned false forever and the boot check emitted
  * "never opened a listening socket" no matter what the app did — an unfalsifiable
  * FAIL that failed a run whose app demonstrably served.) This is a CAPABILITY
@@ -318,8 +327,10 @@ function listeningSockets() {
  * must degrade to the survival rule exactly like win32 — never a false FAIL on a
  * platform we cannot probe.
  *
- * "Ran" = spawned without ENOENT and either exited 0 or printed something (lsof
- * exits 1 on an empty match set; a netstat that rejects `-p` prints nothing).
+ * "Ran" = spawned without ENOENT and either exited 0 or printed something. Both
+ * halves of that disjunction are load-bearing: `lsof` really does exit 1 on an
+ * empty match set (checked), and a netstat that rejects `-p` prints nothing, so
+ * neither an exit code nor output alone would answer the question.
  * Memoised: the answer is a property of the box, not of the run.
  */
 let listenerToolCapability = null;
@@ -341,10 +352,10 @@ export function canEnumerateListeners() {
 }
 /**
  * A free TCP port on the loopback interface, or null if one cannot be reserved.
- * The boot check hands this to the child as PORT so that a successful HTTP
- * request to it is OWNERSHIP evidence: nobody else knows the number (mx5 runs
- * 8/10/11 — orphaned servers from earlier checks answered curl on the
- * conventional :3000 and passed checks the app had not earned).
+ * The boot check hands this to the child as PORT so that a successful HTTP request
+ * to it is OWNERSHIP evidence: nobody else knows the number, whereas an orphaned
+ * server left by an earlier check still answers on a conventional port and would
+ * pass a check the app had not earned.
  */
 export function pickFreePort() {
     return new Promise(resolve => {
@@ -362,7 +373,8 @@ export function pickFreePort() {
         }
     });
 }
-/** Can we bind 127.0.0.1:`port` right now? (Free ⇒ the boot child can have it.) */
+/** Can we bind 127.0.0.1:`port` right now? Free ⇒ the boot child can have it.
+ *  Run: true for a just-reserved port, false while anything holds it. */
 export function isPortFree(port) {
     return new Promise(resolve => {
         try {
@@ -388,8 +400,9 @@ export async function preferredDeclaredPort(cwd) {
     return (await isPortFree(port)) ? port : null;
 }
 /**
- * Does anything answer HTTP on 127.0.0.1:`port`? Any response at all (404, 500 —
- * a status is a listener) counts; only a connection error or timeout is a no.
+ * Does anything answer HTTP on 127.0.0.1:`port`? Any response at all counts — a
+ * status IS a listener, and a live server answering 404 on an unknown path is the
+ * ordinary case — so only a connection error or a timeout is a no.
  * Runs in a throwaway child of our own runtime so it needs no curl on PATH and
  * stays synchronous inside the boot poll.
  */
@@ -493,9 +506,10 @@ function defaultSpawnBoot(bin, args, o) {
 /**
  * The real group teardown, best-effort. A group already gone is not an error.
  *
- * Windows has no process groups / negative-pid kill: `taskkill /T` tears down the
- * whole tree (the detached child plus any grandchildren it spawned) and `/F`
- * forces it, so the SIGTERM→SIGKILL escalation collapses to one idempotent call.
+ * On POSIX the negative pid signals the whole group, which is what makes a
+ * `detached` spawn reapable together with anything it backgrounded. Windows has
+ * neither process groups nor a negative-pid kill, so that branch shells out to
+ * `taskkill /T /F` as a single forced tree teardown instead of escalating.
  */
 function defaultKillGroup(pid, sig) {
     try {
@@ -511,8 +525,11 @@ function defaultKillGroup(pid, sig) {
     }
 }
 /**
- * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
- * command's own fate within the grace window decides:
+ * Exercise the start command ONCE. All four outcomes below were run against real
+ * child processes in throwaway projects.
+ *
+ * For a CLI project (`expectServer` false) the command's own fate within the grace
+ * window decides:
  *
  *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
  *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
@@ -522,22 +539,21 @@ function defaultKillGroup(pid, sig) {
  * For a SERVED app (`expectServer` true — the spec/plan promised an HTTP server) mere
  * survival is not enough: a watcher (`dev` = tailwind/bundler --watch) stays alive
  * forever without ever listening, and a type-only entrypoint exits 0 in <1s having
- * served nothing (mx5 run 10 — both were blessed by the survival rule). The boot then
+ * served nothing. The boot then
  * PASSes only once a LISTENing socket owned by our process group is observed; if the
  * command exits, or the grace window closes, with no listener ever seen → FAIL naming
  * that a listening server was expected.
  *
- * OBSERVABILITY is a precondition of that FAIL (mx5 run 14, validated). The listener
- * requirement needs pgid-attributed socket enumeration; win32 has none, and neither
- * does a Linux image shipping no ss/netstat/lsof — run 14's sandbox was exactly that,
- * so the check emitted "never opened a listening socket" against an app that
- * demonstrably served, three autofix passes could not falsify it, and the run was
- * recorded failed. Two defences, in order:
+ * OBSERVABILITY is a precondition of that FAIL. The listener requirement needs
+ * pgid-attributed socket enumeration; win32 has none, and neither does a Linux
+ * image shipping no ss, netstat or lsof. Without a defence the check would emit
+ * "never opened a listening socket" against an app that demonstrably serves, and
+ * no amount of fixing could falsify it. Two defences, in order:
  *
  *   - the child is spawned with a freshly reserved, otherwise-unused PORT, and an
  *     HTTP answer on THAT port proves a listener regardless of tooling. The private
  *     port is what makes the HTTP probe trustworthy: an orphaned server from an
- *     earlier check answers on :3000, but nobody else knows this number.
+ *     earlier check answers on:3000, but nobody else knows this number.
  *   - if nothing can enumerate listeners AND the assigned port never answered, the
  *     served-app requirement is unobservable here, so `expectServer` collapses to
  *     the survival rule and the PASS is stamped UNOBSERVED. An app that ignores PORT
@@ -545,8 +561,10 @@ function defaultKillGroup(pid, sig) {
  *     not an app defect, and it may not be reported as one.
  *
  * A child that EXITS non-zero still FAILs in every environment: "the process died"
- * needs no socket probe, so run 14's original true positive (a `--hot` runtime
- * pinning a crashed app) stays reportable wherever the tooling exists.
+ * needs no socket probe. Confirmed — a start script exiting 3 comes back as
+ * `exited 3` with the output tail attached, with no listener question asked. That
+ * is what keeps a crashed app reportable even where a hot-reloading runtime would
+ * otherwise hold the process open.
  *
  * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
  * inside the chain (exit 127, or the runner's own wording where the platform
@@ -563,11 +581,11 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
     // a client whose base URL was baked in at build time calls that origin and no
     // other, so serving it anywhere else makes the whole authenticated half
     // unobservable. Anything else — no declaration, a port already held — falls back
-    // to the freshly reserved private port that run 14's ownership evidence needs.
+    // to the freshly reserved private port that the ownership evidence needs.
     const noPreference = () => Promise.resolve(null);
     const preferred = expectServer ? await (opts.deps?.preferredPort ?? noPreference)() : null;
     const assignedPort = preferred ?? (expectServer ? await (opts.deps?.pickPort ?? pickFreePort)() : null);
-    // Runner resolution (mx5 run 16): same contract as runGateCommand — resolve
+    // Runner resolution: same contract as runGateCommand — resolve
     // the runner and carry its directory on PATH so the boot script's own chain
     // can re-invoke it.
     const runner = resolveRunner(bin);
@@ -610,7 +628,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
         };
         const reapGroup = opts.deps?.killGroup ?? defaultKillGroup;
         const killGroup = (sig) => {
-            // Truthiness, deliberately: `process.kill(-0, sig)` signals the
+            // Truthiness, deliberately: `process.kill(0, sig)` signals the
             // CALLER's own process group, so a pid of 0 turns a best-effort
             // teardown into self-termination. Node's spawn never yields 0, but
             // `spawnBoot` is a seam now and a fake or future child could.
@@ -630,7 +648,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
         };
         // Served apps only: poll for a listening socket owned by our process group.
         // As soon as one appears the boot has demonstrably served → run the render
-        // check against the LIVE listener (mx5 runs 8/11: a listener that serves a
+        // check against the LIVE listener (a listener that serves a
         // permanently blank page passed every curl-shaped check), then PASS/FAIL.
         // The probe is spawnSync, so the interval cannot re-enter mid-check.
         // The deep probe is asynchronous (it drives a browser session), so the
@@ -671,7 +689,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                         : undefined);
                 }
                 // The page renders. Now sign in and prove the AUTHENTICATED half
-                // is alive (mx5 run 17): the server accepted the login and the
+                // is alive: the server accepted the login and the
                 // client never used it. Async, so the interval is held off by
                 // `probing` until this settles.
                 probing = true;
@@ -705,7 +723,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                 // Blind here (no enumeration tool, and the assigned port never
                 // answered) ⇒ we cannot tell "never listened" from "ignores PORT".
                 // Survival rule, stamped UNOBSERVED — an observer limitation is not
-                // an app defect (mx5 run 14).
+                // an app defect.
                 if (!canEnumerate)
                     return passAndKill(UNOBSERVED_LISTENER_NOTE);
                 settle({
@@ -745,7 +763,7 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
             const tail = outputTail(out, err);
             // A bind collision is an environment condition, not an app defect — hand
             // it back distinctly so the gate can reap our own orphan and retry rather
-            // than reporting the app "crashed" (mx5 run 9 item 3).
+            // than reporting the app "crashed".
             if (isAddressInUse(`${out}\n${err}`)) {
                 settle({
                     outcome: 'orphan-port',
@@ -760,9 +778,9 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
 }
 /**
  * The SAME third verdict, at the door unobservedVerdict cannot reach: the boot
- * check specifically (mx5 run 18, validated).
+ * check specifically.
  *
- * Run 18 shipped an app with no HTTP server behind a converged final gate. Its
+ * A run can ship an app with no HTTP server behind a converged final gate. Its
  * `src/server/index.ts` ends at `export {app}` — no `Bun.serve`, no
  * `export default app`, no `start` script — so `bun run src/server/index.ts` exits
  * 0 immediately and the product cannot be started at all. The gate's boot command
@@ -771,26 +789,27 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
  * contribute nothing to `dynObserved`, and `bun run test`, `test:ct`, `build`,
  * `lint`, `seed` and `migrate` all ran — so `dynObserved > 0`, the full-skip
  * blindness guard (observabilityGapFailure) stayed correctly quiet, and the trail
- * read `final-gate: autofix converged — statics + … passed` with 24/24 tasks green.
+ * report then reads `final-gate: autofix converged — statics + … passed`, with
+ * every task green.
  *
  * The defect is that "the app was never observed to boot" and "the app booted
- * fine" produced BYTE-IDENTICAL gate output. That is the class scripts/ab-verdict.ts
+ * fine" produced BYTE-IDENTICAL gate output. That is the class the verdict check
  * exists to kill one layer up: absence of evidence rendered in the shape of
  * evidence. So a discovered-but-skipped boot now names itself, and — unlike every
  * other skip — it CANNOT be cancelled by observations from other commands.
- * Component tests are the trap here, not the alibi: run 18 had 51 green Playwright
+ * Component tests are the trap here, not the alibi: a suite of green Playwright
  * CT tests, and CT mounts components in a browser without ever assembling or
  * starting the server.
  *
  * DECIDED, do not silently re-open:
  *  - NOT a FAIL. A boot skip on a docker-less box is a genuine environment gap, and
- *    failing it re-creates run 16's unfalsifiable-FAIL mistake pointing the other
+ *    failing it re-creates the unfalsifiable-FAIL mistake pointing the other
  *    way. UNOBSERVED blocks nothing while being loud and durable (the caller records
  *    it as final-gate debt the next run re-surfaces), and it keeps "boot never ran"
  *    out of the autofix child's seed — a child cannot fix a missing docker, so the
  *    highest-probability response would be to FABRICATE a bootable command, the
  *    class that refuted the `## verified tooling` harvest.
- *  - BOTH skip flavours count. Run 18's skip carried `spawnFailed: false` (127 inside
+ *  - BOTH skip flavours count. A skip can carry `spawnFailed: false` (127 inside
  *    the script chain, not an ENOENT on the runner), so keying off spawnFailed would
  *    have missed the actual defect.
  *  - SERVED APPS ONLY. `expectServer === false` (a CLI/library project) is fenced off
@@ -850,13 +869,13 @@ export async function runBootSection(cwd, opts = {}) {
         return { observed: false, warnings };
     }
     const label = `${boot[0]} ${boot[1].join(' ')}`;
-    // Render check (mx5 runs 8/11): for a served app, load the live page in a
+    // Render check: 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. 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
+    // Authenticated deep-render check: 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
@@ -887,18 +906,18 @@ export async function runBootSection(cwd, opts = {}) {
     if (unobserved !== null)
         verdict.unobservedNote = unobserved;
     if (b.outcome === 'fail') {
-        // OBSERVED (nexttask 19A). Every path that produces `fail` here is a probe
+        // OBSERVED. 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
+        // look" — no ss/netstat/lsof — returns PASS stamped UNOBSERVED
         // and never reaches here.
         verdict.failure = { detail: `boot check: \`${label}\` ${b.detail}`, rank: 0, observed: true };
     }
     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. The
-        // holder lookup reads the SAME deps the boot ran under — it used to be a
+        // holder lookup reads the SAME deps the boot ran under. A
         // second reach into `BootDeps` from the gate, one layer away from the run.
         const holder = b.port !== null ? (deps.findPortHolder ?? defaultFindPortHolder)(b.port) : null;
         const who = holder ? ` — held by an orphaned process (pid ${holder.pid}: ${holder.command})`

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

@@ -3,12 +3,15 @@
  *
  * THE PROBLEM. While a /task-auto run is in flight, the host's interactive main
  * loop is parked at `await session.prompt("/task-auto …")` and never loops back
- * to read input. pi's editor submit handler (interactive-mode.js) has two paths:
+ * to read input. pi's editor submit handler — `modes/interactive/interactive-mode.js`
+ * — has two paths, and both are verbatim in the installed package:
  *
- *   - streaming    → session.prompt(text, {streamingBehavior:"steer"}), and
- *                    agent-session.prompt() runs extension commands immediately.
- *   - not streaming → pendingUserInputs.push(text) — a queue only the parked
- *                    main loop drains.
+ *   - streaming    → `session.prompt(text, {streamingBehavior: "steer"})`. pi's own
+ *                    comment on that branch says it "handles extension commands
+ *                    (execute immediately)".
+ *   - not streaming → `pendingUserInputs.push(text)`, reached only when no
+ *                    `onInputCallback` is registered — i.e. exactly when the main
+ *                    loop is parked. `getUserInput()` is the sole drain.
  *
  * The host session is NOT streaming for most of a run: the spec phases and every
  * gate are child `pi` processes, not host turns. So a /task-auto-cancel typed
@@ -16,12 +19,17 @@
  * already finished — by which point `autoRunning` is false and it answers "No
  * /task-auto loop is running." The command was, for most of a run, inert.
  *
- * THE FIX. `ctx.ui.onTerminalInput` (→ TUI.addInputListener) is a raw stdin
- * listener that the TUI dispatches BEFORE the focused component sees the bytes,
- * independently of the parked main loop. We watch for the submit key, read what
- * the editor is holding, and if it is the cancel command we raise the request
- * ourselves and `consume` the keystroke so the line is never queued for a
- * post-run replay of the confusing "no loop is running" message.
+ * THE FIX. `ctx.ui.onTerminalInput` (→ `TUI.addInputListener`) is a raw stdin
+ * listener, and the ordering it depends on is real: `handleTerminalInput` runs
+ * every registered input listener FIRST, returning immediately on the first one
+ * that answers `{consume: true}`, before any focused-component dispatch below it.
+ * That happens independently of the parked main loop.
+ *
+ * So we watch for the submit key, read what the editor is holding, and if it is
+ * the cancel command we raise the request ourselves and `consume` the keystroke —
+ * otherwise the line sits in the queue and replays after the run as the confusing
+ * "No /task-auto loop is running." auto-orchestrator emits when nothing is in
+ * flight.
  *
  * WHAT ELSE IT NOW CARRIES. The same interception makes the terminal behave like
  * the browser for everything else typed mid-run, instead of feeding pi's queue:
@@ -32,7 +40,9 @@
  *     task turn, rather than starting a competing turn or being replayed after
  *     the run.
  *
- * Three things are deliberately NOT intercepted, and each would be a regression:
+ * Three things are deliberately NOT intercepted, and each would be a regression
+ * (the key test: ESC against a full editor is not a submission, and neither is any
+ * ordinary character):
  *   - a keystroke that is not a submit, so typing and history are untouched;
  *   - anything typed while a prompt/dialog is open (the raw listener sees keys
  *     BEFORE the focused component, so swallowing here would eat the user's
@@ -65,10 +75,14 @@ export declare function installCancelListener(ctx: ExtensionCommandContext, onCa
  * Begin intercepting mid-run terminal input. Refcounted, because runs nest:
  * /task-auto arms for its loop and every task inside it arms again, so a plain
  * "replace" would let the first inner run's end silently un-arm the rest of the
- * loop. The first `onCancel` wins — /task-auto passes one so a typed
- * /task-auto-cancel can post its acknowledgement through the live ctx; a plain
- * /task passes none and lets the generic bridge dispatch handle that command
- * like any other.
+ * loop. Run: three nested arms produce ONE install and take three disarms to
+ * release.
+ *
+ * The first `onCancel` wins — /task-auto passes one so a typed /task-auto-cancel
+ * can post its acknowledgement through the live ctx; a plain /task passes none
+ * and lets the generic bridge dispatch handle that command like any other. An arm
+ * that adds a callback where there was none upgrades in place, reinstalling
+ * against the same refcount rather than starting a second one.
  */
 export declare function armCancelListener(ctx: ExtensionCommandContext, onCancel?: (live: ExtensionCommandContext) => void): void;
 /**

package/dist/task/cancel-input.js

@@ -1,11 +1,14 @@
 import { holdInput, isRunActive } from './mid-run-input.js';
 import { getBridge } from '../remote/bridge.js';
 import { getState } from '../remote/session-state.js';
-/** The command this listener delivers. Accepts a leading slash only — matching
- *  bare "task-auto-cancel" would fire on prose about the command. */
+/** The command this listener delivers. Anchored at both ends and requiring the
+ *  leading slash, so bare "task-auto-cancel", "/task-auto-cancel now" and
+ *  "please run /task-auto-cancel" all fail to match — prose about the command must
+ *  never fire it. Surrounding whitespace is tolerated. */
 const CANCEL_RE = /^\/task-auto-cancel\s*$/;
 /** Enter, in the encodings a terminal actually sends. A bare "\n" is what many
- *  terminals emit in raw mode; "\r" is the usual CR. */
+ *  terminals emit in raw mode; "\r" is the usual CR; "\r\n" covers the pair. All
+ *  three submit; nothing else does, ESC included. */
 function isSubmitKey(data) {
     return data === '\r' || data === '\n' || data === '\r\n';
 }
@@ -132,10 +135,12 @@ export function installCancelListener(ctx, onCancel) {
 }
 // ─── Armed listener (survives session replacement) ────────────────────────────
 /**
- * The listener does NOT survive `ctx.newSession()`. pi's InteractiveMode
- * registers `setBeforeSessionInvalidate(() => this.resetExtensionUI())`, and
- * `resetExtensionUI` calls `clearExtensionTerminalInputListeners()` — so every
- * per-task session replacement silently drops it. That replacement happens at
+ * The listener does NOT survive `ctx.newSession()`, and the chain is all three
+ * links, each present in the installed package: `InteractiveMode` registers
+ * `setBeforeSessionInvalidate(() => this.resetExtensionUI())`, `resetExtensionUI`
+ * calls `clearExtensionTerminalInputListeners()`, and that clears the very set
+ * this listener lives in — so every per-task session replacement silently drops
+ * it. That replacement happens at
  * the START of each task, which is exactly the window this listener exists to
  * cover, so the run must re-arm against the fresh ctx as soon as one appears
  * (runSingleTask, where the new ctx is also handed to the remote bridge).
@@ -148,10 +153,14 @@ let armed = null;
  * Begin intercepting mid-run terminal input. Refcounted, because runs nest:
  * /task-auto arms for its loop and every task inside it arms again, so a plain
  * "replace" would let the first inner run's end silently un-arm the rest of the
- * loop. The first `onCancel` wins — /task-auto passes one so a typed
- * /task-auto-cancel can post its acknowledgement through the live ctx; a plain
- * /task passes none and lets the generic bridge dispatch handle that command
- * like any other.
+ * loop. Run: three nested arms produce ONE install and take three disarms to
+ * release.
+ *
+ * The first `onCancel` wins — /task-auto passes one so a typed /task-auto-cancel
+ * can post its acknowledgement through the live ctx; a plain /task passes none
+ * and lets the generic bridge dispatch handle that command like any other. An arm
+ * that adds a callback where there was none upgrades in place, reinstalling
+ * against the same refcount rather than starting a second one.
  */
 export function armCancelListener(ctx, onCancel) {
     if (armed) {

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

@@ -3,24 +3,30 @@
  *
  * A cancel is a *request*, never a kill. It is honoured only where the on-disk
  * state is durable and /task-auto-resume provably continues from it. Killing a
- * child mid-phase would also stop the run (the abort signal already reaches
- * every child's process group) but throws away that phase's work and can leave
- * a half-written tree — so the flag is polled at boundaries instead.
+ * child mid-phase would also stop the run — the abort signal reaches every
+ * child's process group — but it throws away that phase's work and can leave a
+ * half-written tree, so the flag is polled at boundaries instead.
  *
- * The checkpoint set, and why each one is safe:
+ * The checkpoint set is exactly these four, one call site each:
  *
- *   loop-top       the previous task is checked off + committed and the next one
- *                  has not started. The original (and until now the ONLY) point.
- *   pre-task       after the pre-task checkpoint commit, before the runner is
- *                  constructed: tree committed, no inner id stamped yet, so the
- *                  entry is simply still unchecked and a resume restarts it.
- *   phase:<name>   inside the runner's phase loop, after setTaskSection +
- *                  postCommitPhase have persisted the phase output and
- *                  front-matter `phase` names the NEXT phase. This is exactly
- *                  the state /task-resume already resumes from (PHASE_INDEX
- *                  skip-forward), so a cancel here costs nothing.
- *   pre-final-gate every task is checked off and committed; the whole-repo gate
- *                  has not started. A resume re-enters the same branch.
+ *   loop-top       (auto-orchestrator) the previous task is checked off and
+ *                  committed and the next one has not started.
+ *   pre-task       (auto-orchestrator) after the pre-task checkpoint commit,
+ *                  before the runner is constructed: tree committed, no inner id
+ *                  stamped yet, so the entry is simply still unchecked and a
+ *                  resume restarts it.
+ *   phase:<name>   (orchestrator, inside the phase loop) after setTaskSection and
+ *                  postCommitPhase have persisted this phase's output. Front-matter
+ *                  `phase` still names the phase that JUST FINISHED, not the next
+ *                  one: `advance()` writes it at the TOP of each iteration and
+ *                  nothing moves it afterwards — postCommitPhase writes only
+ *                  `title` and `label`. Since the resume skip rule is
+ *                  `idx < resumeIdx`, a resume therefore RE-ENTERS this phase and
+ *                  runs it again. Nothing is lost, because its section is already
+ *                  on disk; the cost is repeating one phase, not zero.
+ *   pre-final-gate (run-final-gate) every task is checked off and committed; the
+ *                  whole-repo gate has not started. A resume re-enters the same
+ *                  branch.
  *
  * DELIBERATELY NOT checkpoints — stopping here is not safe:
  *   - mid implementation turn: uncommitted, half-applied edits. The user's ESC
@@ -29,8 +35,9 @@
  *     work is written but unverified and uncommitted; the gates are what make it
  *     durable. Cancel is observed on the far side, at loop-top.
  */
-/** Every place the cancel flag is polled. Kept as a closed union so the A/B
- *  harness and the tests enumerate the same set the loop does. */
+/** Every place the cancel flag is polled. A closed union so the tests enumerate
+ *  the same set the loop does — and they do: cancel-points.test.ts asserts on the
+ *  recorded trail rather than on the loop's own bookkeeping. */
 export type CancelCheckpoint = 'loop-top' | 'pre-task' | 'pre-final-gate' | `phase:${string}`;
 export declare function requestCancel(): void;
 export declare function isCancelRequested(): boolean;
@@ -44,7 +51,7 @@ export declare function isCancelRequested(): boolean;
  * of a trial to get a clean slate.
  */
 export declare function resetCancel(): void;
-/** Drop the recorded checkpoint trail (A/B + tests). */
+/** Drop the recorded checkpoint trail. */
 export declare function resetCheckpointTrail(): void;
 /**
  * Poll the cancel flag at a safe checkpoint. Records the visit either way, so a
@@ -54,5 +61,5 @@ export declare function resetCheckpointTrail(): void;
  * @returns true when the caller must stop here.
  */
 export declare function cancelCheckpoint(where: CancelCheckpoint): boolean;
-/** Checkpoints crossed since the last reset (A/B + tests). */
+/** Checkpoints crossed since the last reset. */
 export declare function checkpointsCrossed(): readonly CancelCheckpoint[];