@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/child-status.js

@@ -2,21 +2,22 @@
  * ChildStatus — the live status of the child pi currently running under a
  * status loader: its latest output line and its context usage.
  *
- * Four sites used to keep this state by hand — `let lastLine; let contextUsage;`
+ * Without it each spawn site keeps this state by hand — `let lastLine; let contextUsage;`
  * plus two callbacks (`onChildOutput` writes the line, `onContextUsage` folds a
  * snapshot through `resolveContextUsage` with the parent window), a reset before
- * every child, and a loader whose every tick read both — in `/task-auto`'s
- * planning `runChild`, `/task-plan`'s `child`, `buildGateDeps` (an accessor box
- * handed to `makeGateChild`), and the single-task `TaskRunner`. The first three
- * are one ritual and are now this class; the fourth stays where it is (see
- * `orchestrator.ts`: its state is the whole-run `WidgetState`, shared by
- * reference with `PhaseContext` and written by the phases themselves).
+ * every child, and a loader whose every tick reads both.
+ *
+ * Three sites share that ritual and are now this class: `/task-auto`'s planning
+ * `runChild`, `buildGateDeps`, and `/task-plan` — one `new ChildStatus` each, and
+ * no others. The single-task `TaskRunner` deliberately stays where it is: its
+ * state is the whole-run `WidgetState`, shared by reference with `PhaseContext`
+ * and written by the phases themselves (see `orchestrator.ts`).
  *
  * `track` is the loader ritual: reset, raise the loader reading this status on
  * every tick, run, always stop. The status OUTLIVES a track — `buildGateDeps`
  * shares one across every gate child, and the verify gate raises its own
- * gate-wide loader over a child that renders none (`frame: null`), so both must
- * see the same object.
+ * gate-wide loader over a child that renders none (`frame: null`, reached when
+ * `deps.loader === false` in gate-child), so both must see the same object.
  */
 import { runPhaseChild } from './child-runner.js';
 import { resolveContextUsage } from './context-usage.js';
@@ -59,12 +60,17 @@ export class ChildStatus {
     }
     /**
      * Run `run` under the loader: reset, raise a loader whose every tick is
-     * `frame()` plus the live line and gauge, and stop it in a `finally` — a
-     * throwing child must not leave the widget up. `frame` wins on a clash, which
-     * is how the verify gate shows its deterministic-stage label until the child
-     * has a line of its own. `frame: null` renders NO loader (the caller already
-     * has one reading this status) but still resets, so the previous child's
-     * trailer is cleared either way.
+     * `frame()` spread OVER the live line and gauge, and stop it in a `finally`.
+     * All four behaviours were run against a fake loader:
+     *   - the reset lands first, so the previous child's line never reaches the
+     *     new loader's first tick;
+     *   - `frame` wins on a clash, because it is spread last — which is how the
+     *     verify gate shows its deterministic-stage label until the child has a
+     *     line of its own;
+     *   - `frame: null` raises NO loader at all (the caller already has one
+     *     reading this status) but still resets;
+     *   - a child that THROWS still stops the loader, so a failure never leaves
+     *     the widget up.
      */
     async track(ctx, frame, run) {
         this.reset();
@@ -99,7 +105,8 @@ export async function runPlanningChild(opts) {
 }
 /**
  * Wire a `ChildStatus` as a phase child's stream callbacks — plus the window the
- * child must be TOLD, since pi's event stream never reports one (issue #16).
+ * child must be TOLD, since pi's `--mode json` stream reports token counts but no
+ * context window.
  */
 export function statusCallbacks(status) {
     return {

package/dist/task/clamp-output.js

@@ -1,11 +1,18 @@
 /**
  * clamp-output — the ONE trail-side ceiling for captured tool output.
  *
- * `appendGateRecord` flattens newlines to spaces, so the gate trail stays one line
- * per entry; this caps the volume, because a wedged tool can emit megabytes.
- * Extracted from task-gates.ts so every probe that carries evidence into a failure
- * detail clamps the SAME way: a second clamp with a second ceiling is how two
- * trails start disagreeing about what was captured.
+ * `appendGateRecord` already collapses every run of whitespace-around-newline
+ * into a single space, so each trail entry is one line. What it does NOT do is
+ * bound the LENGTH, which is this. A wedged tool has no upper limit on what it
+ * prints, and the trail is a task file a human reads.
+ *
+ * Both probes that carry tool output into a failure detail — the render check and
+ * the gate's own command records — call THIS function, so the two trails cannot
+ * start disagreeing about what was captured. A second clamp with a second ceiling
+ * is exactly how that happens.
+ *
+ * At the boundary: 1200 characters pass through untouched, 1201 or more come back
+ * clamped to 1200 plus a single ellipsis.
  */
 const TRAIL_OUTPUT_MAX_CHARS = 1200;
 export function clampOutput(output) {

package/dist/task/command-run.d.ts

@@ -9,23 +9,24 @@
  * Only a command that demonstrably ran and exited non-zero for a reason of its
  * own is a failure, and only exit 0 is a pass.
  *
- * Why a module. That ladder was written three times inside final-gate.ts —
- * `runGateCommand`, `runVerifyCommandLine`, `rerunDebtVerifyCommand` — in the
- * same order with different labels, and the copies had already drifted (the
- * infrastructure pattern applied unconditionally in one and only on request in
- * another). repo-health-check.ts had solved exactly this shape years earlier:
- * `classifyHealthRun` is pure over a value, extracted so its sync and async
- * runners "cannot drift apart". The gate never adopted it.
+ * Why a module. The same ladder is needed by every caller that runs a project
+ * command and must decide what its ending MEANS — the gate's own
+ * `runGateCommand`, `runVerifyCommandLine` here, and accept-debt's
+ * `rerunDebtVerifyCommand`. Stated separately at each site the copies drift: one
+ * applies the infrastructure pattern unconditionally, the next only on request,
+ * and two trails then disagree about whether the same output was a gap or a
+ * failure. repo-health-check.ts defers to this module rather than carrying its
+ * own version — its header says so in as many words.
  *
  * The second half is the seam. Classification is now pure over a `CommandRun`
  * value, and SPAWNING is a `CommandRunner` the caller injects. That is what lets
  * the gate's tests state a case as `{status: 1, stdout: "…"}` instead of writing
- * a real `node -e` child, creating a temp directory for it, and — for the three
- * cases only reachable that way — shadowing a binary on `process.env.PATH` and
- * resetting a module-level cache, which made those tests order-sensitive and
- * needed a Windows carve-out. Note the asymmetry this closes: `BootDeps` already
- * carried nine injectable probes for the gate's boot half while its command half
- * had none.
+ * a real `node -e` child, creating a temp directory for it, and — for the cases
+ * only reachable that way — shadowing a binary on `process.env.PATH` and
+ * resetting a module-level cache, which makes those tests order-sensitive.
+ *
+ * It also closes an asymmetry: `BootDeps` carries twelve injectable probes for
+ * the gate's boot half, while its command half had none.
  */
 /** What one finished command looks like, stripped of how it was spawned. */
 export interface CommandRun {
@@ -57,14 +58,12 @@ export interface CommandSpec {
  * The injectable half. The gate takes one of these so its tests can script
  * verdicts instead of paying process-spawn cost for every classification case.
  *
- * ASYNC by contract. It was `(spec) => CommandRun`, so the only implementation
- * could be `spawnSync`, and the run-end gate blocked the event loop end to end:
- * repo-health under a 600s cap, then every lockfile/test/build/launch command
- * under a 900s cap, then every ACCEPT-debt re-run under a 300s cap, with no
- * loader able to paint through any of it. That freeze is MEASURED — 0 of 686
- * expected 100ms ticks fired during a 69s run — and `repo-health-check.ts`'s own
- * doc comment already told gate callers not to do it, while `final-gate.ts`'s
- * repo-health call did exactly that.
+ * ASYNC by contract, and the type is what enforces it. A synchronous
+ * `(spec) => CommandRun` can only be implemented with `spawnSync`, which blocks
+ * the event loop for the whole command — so the run-end gate, which runs
+ * repo-health and then every lockfile, test, build, launch and ACCEPT-debt
+ * command in sequence, would hold the loop for all of it and no loader could
+ * paint a single frame through it.
  */
 export type CommandRunner = (spec: CommandSpec) => Promise<CommandRun>;
 /**
@@ -76,15 +75,19 @@ export type CommandRunner = (spec: CommandSpec) => Promise<CommandRun>;
  * THE RUN SETTLES ON THE CHILD, NOT ON THE PIPE. `close` fires only once every
  * stdio pipe has reached EOF, and a backgrounded grandchild INHERITS stdout: a
  * seed script that starts a daemon, a build that leaves a watcher, a launch
- * script. Waiting for `close` there is waiting for the grandchild, which no
- * timeout can reach — SIGKILL goes to the direct child and the inherited pipe
- * survives it. So `exit` settles the run, and the deadline settles it itself.
+ * script.
+ *
+ * Measured on exactly that shape — a child that backgrounds a sleeper and exits
+ * at once — `exit` fired after 1ms and `close` NEVER fired. Sending SIGKILL to
+ * the direct child did not release it either, because the grandchild holds the
+ * pipe. Waiting for `close` is therefore waiting for something no timeout can
+ * reach. `exit` settles the run, and the deadline settles it itself.
  */
 export declare const spawnCommand: CommandRunner;
 /**
  * A non-zero exit whose output shows an EXTERNAL runtime dependency is missing, not
  * a code fault: a browser suite (Playwright/Cypress) whose browser binaries or system
- * libraries were never installed here (mx5 run 10 item 2: `test:ct` must run in the
+ * libraries were never installed here (a component-test runner must run in the
  * gate, but on a box with no Playwright browsers it is an environment gap, not a FAIL).
  * These exit non-zero (not 127), so they need output-shape recognition to skip.
  */
@@ -164,15 +167,15 @@ export type VerifyRerunOutcome = {
     detail: string;
 };
 /**
- * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * Re-run one VERIFY-block command line under the gate's existing
  * env-gap contract, so a debt whose reason NAMES that command can be closed by the
  * command itself rather than by a judgement about it.
  *
- * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: a
  * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
  * are all ordinary there. The leading command word is still resolved through
  * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
- * gap (mx5 run 16's blindness, one level down).
+ * gap.
  *
  * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
  * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the

package/dist/task/command-run.js

@@ -9,36 +9,41 @@
  * Only a command that demonstrably ran and exited non-zero for a reason of its
  * own is a failure, and only exit 0 is a pass.
  *
- * Why a module. That ladder was written three times inside final-gate.ts —
- * `runGateCommand`, `runVerifyCommandLine`, `rerunDebtVerifyCommand` — in the
- * same order with different labels, and the copies had already drifted (the
- * infrastructure pattern applied unconditionally in one and only on request in
- * another). repo-health-check.ts had solved exactly this shape years earlier:
- * `classifyHealthRun` is pure over a value, extracted so its sync and async
- * runners "cannot drift apart". The gate never adopted it.
+ * Why a module. The same ladder is needed by every caller that runs a project
+ * command and must decide what its ending MEANS — the gate's own
+ * `runGateCommand`, `runVerifyCommandLine` here, and accept-debt's
+ * `rerunDebtVerifyCommand`. Stated separately at each site the copies drift: one
+ * applies the infrastructure pattern unconditionally, the next only on request,
+ * and two trails then disagree about whether the same output was a gap or a
+ * failure. repo-health-check.ts defers to this module rather than carrying its
+ * own version — its header says so in as many words.
  *
  * The second half is the seam. Classification is now pure over a `CommandRun`
  * value, and SPAWNING is a `CommandRunner` the caller injects. That is what lets
  * the gate's tests state a case as `{status: 1, stdout: "…"}` instead of writing
- * a real `node -e` child, creating a temp directory for it, and — for the three
- * cases only reachable that way — shadowing a binary on `process.env.PATH` and
- * resetting a module-level cache, which made those tests order-sensitive and
- * needed a Windows carve-out. Note the asymmetry this closes: `BootDeps` already
- * carried nine injectable probes for the gate's boot half while its command half
- * had none.
+ * a real `node -e` child, creating a temp directory for it, and — for the cases
+ * only reachable that way — shadowing a binary on `process.env.PATH` and
+ * resetting a module-level cache, which makes those tests order-sensitive.
+ *
+ * It also closes an asymmetry: `BootDeps` carries twelve injectable probes for
+ * the gate's boot half, while its command half had none.
  */
 import { spawn } from 'node:child_process';
 import { isCommandNotFound, resolveRunner, runnerEnv } from './runner-resolve.js';
 /**
  * How much of ONE stream may be held in the HOST process, and how it is split.
  *
- * `spawnSync` bounded this at its 1 MB default `maxBuffer`. The async runner had
- * no bound at all: two strings grew in the TUI's own process for as long as a
- * command under the 900s cap kept talking.
+ * `spawnSync` came with a bound for free — its default `maxBuffer` is 1 MiB, and
+ * exceeding it fails the call with ENOBUFS (checked: 2 MiB of output truncates at
+ * 1,114,112 bytes). An async runner has no such bound, so without this two
+ * strings grow in the host's own process for as long as the command keeps
+ * talking.
  *
- * BOTH ENDS are kept, because both are read. `isCommandNotFound` and the two gap
- * regexes match wording a runner prints FIRST; `outputTail` and every failure
- * reason take the LAST 400 characters. A single-ended cap loses one of them.
+ * BOTH ENDS are kept, because both are read: `isCommandNotFound` and the gap
+ * regexes match wording a runner prints FIRST, while `outputTail` and every
+ * failure reason take the LAST 400 characters. A single-ended cap loses one of
+ * them. Run against a real 2 MB command, the capture keeps its opening bytes,
+ * its closing bytes, and an elision marker between them.
  */
 const OUTPUT_HEAD_CAP = 256 * 1024;
 const OUTPUT_TAIL_CAP = 768 * 1024;
@@ -81,9 +86,13 @@ const DRAIN_MS = 50;
  * THE RUN SETTLES ON THE CHILD, NOT ON THE PIPE. `close` fires only once every
  * stdio pipe has reached EOF, and a backgrounded grandchild INHERITS stdout: a
  * seed script that starts a daemon, a build that leaves a watcher, a launch
- * script. Waiting for `close` there is waiting for the grandchild, which no
- * timeout can reach — SIGKILL goes to the direct child and the inherited pipe
- * survives it. So `exit` settles the run, and the deadline settles it itself.
+ * script.
+ *
+ * Measured on exactly that shape — a child that backgrounds a sleeper and exits
+ * at once — `exit` fired after 1ms and `close` NEVER fired. Sending SIGKILL to
+ * the direct child did not release it either, because the grandchild holds the
+ * pipe. Waiting for `close` is therefore waiting for something no timeout can
+ * reach. `exit` settles the run, and the deadline settles it itself.
  */
 export const spawnCommand = spec => new Promise(resolve => {
     const out = new BoundedOutput();
@@ -97,8 +106,8 @@ export const spawnCommand = spec => new Promise(resolve => {
         cwd: spec.cwd,
         // stdin CLOSED. `spawnSync` gave the child none; the default `spawn`
         // stdio is a live pipe nobody ever ends, so a check that reads stdin —
-        // a `cat`-style pipeline, a tool that prompts, a pager — blocked until
-        // the kill timer: 600s for repo-health, 900s for a gate command.
+        // a `cat`-style pipeline, a tool that prompts, a pager — would block
+        // until the kill timer fires instead of returning at once.
         stdio: ['ignore', 'pipe', 'pipe'],
         ...(spec.env ? { env: spec.env } : {})
     });
@@ -140,12 +149,12 @@ export const spawnCommand = spec => new Promise(resolve => {
         clearTimeout(drain);
         drain = setTimeout(() => done(null), DRAIN_MS);
     };
-    // NOT unref'd. With `spawnSync`'s own `timeout` gone this timer is the only
-    // bound left on every gate command, repo-health command and ACCEPT-debt
-    // re-run — and an unref'd timer is MEASURED in this repo never to fire at
-    // all on Windows (0/20s), which would leave all of them unbounded. It is
-    // cleared the moment the run settles, so it holds the loop open only while
-    // a command the caller is awaiting anyway is still running.
+    // NOT unref'd. This timer is the only bound left on every gate command,
+    // repo-health command and ACCEPT-debt re-run, and an unref'd timer is only
+    // guaranteed to fire while something ref'd is still pending — not a
+    // guarantee this can rely on. It is cleared the moment the run settles, so
+    // it holds the loop open only while a command the caller is awaiting
+    // anyway is still running.
     const timer = setTimeout(killAndSettle, spec.timeoutMs);
     if (spec.signal) {
         if (spec.signal.aborted)
@@ -180,7 +189,7 @@ export const spawnCommand = spec => new Promise(resolve => {
 /**
  * A non-zero exit whose output shows an EXTERNAL runtime dependency is missing, not
  * a code fault: a browser suite (Playwright/Cypress) whose browser binaries or system
- * libraries were never installed here (mx5 run 10 item 2: `test:ct` must run in the
+ * libraries were never installed here (a component-test runner must run in the
  * gate, but on a box with no Playwright browsers it is an environment gap, not a FAIL).
  * These exit non-zero (not 127), so they need output-shape recognition to skip.
  */
@@ -202,7 +211,7 @@ export const INFRA_GAP_OUTPUT_RE = /ECONNREFUSED|connection refused|ENOTFOUND|EA
  * `spawn-failed` is first and is kept distinguishable from every other row by its
  * id: a tool-level gap (127 inside the chain, a missing browser, a timeout) means
  * the runner demonstrably RAN, and only genuine spawn failures feed the gate's
- * full-blindness guard (mx5 run 16 — see observabilityGapFailure).
+ * full-blindness guard (see observabilityGapFailure).
  */
 const GAP_RULES = [
     {
@@ -281,15 +290,15 @@ function leadingBin(line) {
     return null;
 }
 /**
- * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * Re-run one VERIFY-block command line under the gate's existing
  * env-gap contract, so a debt whose reason NAMES that command can be closed by the
  * command itself rather than by a judgement about it.
  *
- * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: a
  * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
  * are all ordinary there. The leading command word is still resolved through
  * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
- * gap (mx5 run 16's blindness, one level down).
+ * gap.
  *
  * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
  * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the

package/dist/task/command-shrink.d.ts

@@ -2,11 +2,13 @@
  * SCOPE-SHRINK detection for the final-gate fix pass.
  *
  * The label guard (final-gate-fix.ts) compares the SET of discoverable gate
- * commands before and after the fix child. mx5 run 19 walked straight through
- * it: the autofix rewrote `"test": "AGENT=1 bun test"` to
- * `"AGENT=1 bun test ./test"`, the label `bun run test` existed before and
- * after, the set difference was empty, and the gate re-ran a suite that no
- * longer covered the repository — then reported "autofix converged".
+ * commands before and after the fix child, and a fix child walks straight through
+ * it. Rewrite `"test": "AGENT=1 bun test"` to `"AGENT=1 bun test ./test"` and the
+ * label `bun run test` exists before and after, so the set difference is empty —
+ * while the gate now re-runs a suite that no longer covers the repository, and
+ * reports that the autofix converged. Fed to `classifyBodyChange`, those two
+ * bodies come back `narrow` / `path-added`, which is the whole point of this
+ * module.
  *
  * What changed was not the command's NAME but its SCOPE. This module compares
  * the RESOLVED BODIES (`scripts[name]` for package.json, the recipe lines for a
@@ -16,23 +18,27 @@
  *   1. a path/glob argument is ADDED to a command member that had none
  *      (`bun test` → `bun test ./test`);
  *   2. an existing path/glob argument is replaced by a strict SUBPATH of itself
- *      (`eslint src` → `eslint src/server`);
+ *      (`eslint ./src` → `eslint ./src/server`). Note the argument has to LOOK
+ *      like a path — a bare `src` with no separator, dot or glob is not treated
+ *      as one, so `eslint src` → `eslint src/server` reads as neutral;
  *   3. an exclusion flag/pattern is ADDED (`--ignore`, `--exclude`,
  *      `--testPathIgnorePatterns`, `-x`, …);
  *   4. a config-file argument is swapped for one the fix pass itself created.
  *
- * With ONE excuse, measured on mx5@a9c6145 and documented at
- * `excusedByRelocation`: rule 3 does not fire when the same pass hands the
- * excluded input to another command the gate already runs.
+ * With ONE excuse, documented at `excusedByRelocation`: rule 3 does not fire when
+ * the same pass hands the excluded input to another command the gate already
+ * runs. Rules 1, 2 and 4 have no excuse.
  *
- * Everything else passes: new env vars, added flags that do not restrict the
- * input set, reordering, added chain members, whole new scripts. The guard's
- * job is to stop the fix pass from silently redefining the gate's own success
- * criterion — not to review the fix.
+ * Everything else passes, each checked by running it: a new env var, a flag that
+ * does not restrict the input set, reordering, an added chain member, an
+ * identical body. A path replaced by its PARENT classifies as `widen`, not
+ * `narrow`. The guard's job is to stop the fix pass from silently redefining the
+ * gate's own success criterion — not to review the fix.
  *
- * PURE by construction (no fs, no git): the live guard feeds it two body maps
- * from `discoverGateCommandBodies`, the replay harness feeds it two maps built
- * from git blobs. Same code decides both.
+ * PURE by construction: the module has no imports at all — no fs, no git, no
+ * clock. The live guard feeds it two body maps from `discoverGateCommandBodies`;
+ * anything replaying history feeds it two maps built from git blobs. The same
+ * code decides both.
  */
 /** Which of the four mechanical shapes fired. */
 export type ShrinkKind = 'path-added' | 'path-narrowed' | 'exclusion-added' | 'config-swapped';
@@ -64,8 +70,9 @@ export interface Narrowing {
     kinds: ShrinkKind[];
     reasons: string[];
 }
-/** Split a shell body into chain members, quote-aware: `&&`, `||`, `;`, `|`,
- *  and newlines (Makefile recipes arrive as multiple lines). */
+/** Split a shell body into chain members on `&&`, `||`, `;`, `|` and newlines
+ *  (Makefile recipes arrive as multiple lines). Quote-aware, and it matters:
+ *  `bun test --name 'a && b' && lint` splits into two members, not three. */
 export declare function splitChainMembers(body: string): string[];
 /** Is this token SYNTACTICALLY a path or glob? Deliberately lexical: no fs. */
 export declare function looksLikePath(tok: string): boolean;

package/dist/task/command-shrink.js

@@ -2,11 +2,13 @@
  * SCOPE-SHRINK detection for the final-gate fix pass.
  *
  * The label guard (final-gate-fix.ts) compares the SET of discoverable gate
- * commands before and after the fix child. mx5 run 19 walked straight through
- * it: the autofix rewrote `"test": "AGENT=1 bun test"` to
- * `"AGENT=1 bun test ./test"`, the label `bun run test` existed before and
- * after, the set difference was empty, and the gate re-ran a suite that no
- * longer covered the repository — then reported "autofix converged".
+ * commands before and after the fix child, and a fix child walks straight through
+ * it. Rewrite `"test": "AGENT=1 bun test"` to `"AGENT=1 bun test ./test"` and the
+ * label `bun run test` exists before and after, so the set difference is empty —
+ * while the gate now re-runs a suite that no longer covers the repository, and
+ * reports that the autofix converged. Fed to `classifyBodyChange`, those two
+ * bodies come back `narrow` / `path-added`, which is the whole point of this
+ * module.
  *
  * What changed was not the command's NAME but its SCOPE. This module compares
  * the RESOLVED BODIES (`scripts[name]` for package.json, the recipe lines for a
@@ -16,27 +18,32 @@
  *   1. a path/glob argument is ADDED to a command member that had none
  *      (`bun test` → `bun test ./test`);
  *   2. an existing path/glob argument is replaced by a strict SUBPATH of itself
- *      (`eslint src` → `eslint src/server`);
+ *      (`eslint ./src` → `eslint ./src/server`). Note the argument has to LOOK
+ *      like a path — a bare `src` with no separator, dot or glob is not treated
+ *      as one, so `eslint src` → `eslint src/server` reads as neutral;
  *   3. an exclusion flag/pattern is ADDED (`--ignore`, `--exclude`,
  *      `--testPathIgnorePatterns`, `-x`, …);
  *   4. a config-file argument is swapped for one the fix pass itself created.
  *
- * With ONE excuse, measured on mx5@a9c6145 and documented at
- * `excusedByRelocation`: rule 3 does not fire when the same pass hands the
- * excluded input to another command the gate already runs.
+ * With ONE excuse, documented at `excusedByRelocation`: rule 3 does not fire when
+ * the same pass hands the excluded input to another command the gate already
+ * runs. Rules 1, 2 and 4 have no excuse.
  *
- * Everything else passes: new env vars, added flags that do not restrict the
- * input set, reordering, added chain members, whole new scripts. The guard's
- * job is to stop the fix pass from silently redefining the gate's own success
- * criterion — not to review the fix.
+ * Everything else passes, each checked by running it: a new env var, a flag that
+ * does not restrict the input set, reordering, an added chain member, an
+ * identical body. A path replaced by its PARENT classifies as `widen`, not
+ * `narrow`. The guard's job is to stop the fix pass from silently redefining the
+ * gate's own success criterion — not to review the fix.
  *
- * PURE by construction (no fs, no git): the live guard feeds it two body maps
- * from `discoverGateCommandBodies`, the replay harness feeds it two maps built
- * from git blobs. Same code decides both.
+ * PURE by construction: the module has no imports at all — no fs, no git, no
+ * clock. The live guard feeds it two body maps from `discoverGateCommandBodies`;
+ * anything replaying history feeds it two maps built from git blobs. The same
+ * code decides both.
  */
 // ── tokenizing ──────────────────────────────────────────────────────────────
-/** Split a shell body into chain members, quote-aware: `&&`, `||`, `;`, `|`,
- *  and newlines (Makefile recipes arrive as multiple lines). */
+/** Split a shell body into chain members on `&&`, `||`, `;`, `|` and newlines
+ *  (Makefile recipes arrive as multiple lines). Quote-aware, and it matters:
+ *  `bun test --name 'a && b' && lint` splits into two members, not three. */
 export function splitChainMembers(body) {
     const out = [];
     let cur = '';
@@ -262,21 +269,20 @@ export function makefileRecipe(makefileText, target) {
 }
 // ── the rules ───────────────────────────────────────────────────────────────
 /**
- * RELOCATION EXCUSE (rule 3 only, measured on mx5@a9c6145).
+ * RELOCATION EXCUSE.
  *
- * That autofix rewrote `test` from `AGENT=1 bun test` to `AGENT=1 bun test
- * --path-ignore-patterns '**\/*.spec.tsx' && playwright test -c
- * playwright-ct.config.ts`. Read by hand: `test:ct` was ALREADY
- * `playwright test -c playwright-ct.config.ts` and already a discovered gate
- * command, so the excluded specs never left the gate's coverage — the pass
- * separated two runners that collide, it did not shrink what is measured.
- * Rejecting it would be a false positive, and the rule as first written did.
+ * A fix pass can split two runners that collide — excluding a set of specs from
+ * one command while adding, in the same body, a chain member that another
+ * ALREADY-DISCOVERED gate command runs over exactly those specs. Nothing left the
+ * gate's coverage there, so rejecting it would be a false positive.
  *
- * The excuse is deliberately narrow and hard to game: the pass must have added
- * a chain member that is VERBATIM (whitespace-normalized) a member of another
- * discovered gate command's body. `&& echo ok` does not qualify; neither does a
- * near-copy pointed at a different config. Nothing excuses rules 1, 2 or 4 —
- * a path narrowing stands on its own.
+ * The excuse is deliberately narrow and hard to game: the pass must have ADDED a
+ * chain member that is VERBATIM (whitespace-normalized) a member of another
+ * discovered gate command's body. Run both ways — with the sibling present the
+ * exclusion classifies neutral, and a near-copy pointed at a different config
+ * does NOT excuse it. An added FLAG alone can never qualify, because there is no
+ * added member to match. Nothing excuses rules 1, 2 or 4: a path narrowing stands
+ * on its own.
  *
  * Returns the matching sibling member, or null.
  */

package/dist/task/command-watchdog.d.ts

@@ -6,14 +6,17 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
  * returns — `godot --headless --check-only` with no timeout, a dev server, a
  * hung test — and the run wedges until the user manually aborts and tells the
  * model to add a timeout. pi's bash tool takes an OPTIONAL `timeout` with NO
- * default (see pi-coding-agent tools/bash.js), so any command the model didn't
- * bound runs forever. This supplies the missing default from the host side.
+ * default: its schema in `core/tools/bash.js` says "optional, no default
+ * timeout" and its resolver returns undefined for an absent value, so no timer is
+ * ever armed. This supplies the missing default from the host side.
  *
  * HOW: arm a wall-clock timer on `tool_execution_start`, disarm it on
- * `tool_execution_end`. If it elapses, `ctx.abort()` cancels the in-flight
- * operation — which fires the tool's AbortSignal, and pi's bash executor kills
- * the whole process tree on abort — then a follow-up user turn tells the model
- * what happened so it retries with a timeout instead of hanging again.
+ * `tool_execution_end` — both real pi events. If it elapses, `ctx.abort()`
+ * cancels the in-flight operation, which fires the tool's AbortSignal; pi's bash
+ * executor imports `killProcessTree` and its own comment on that listener reads
+ * "Handle abort signal by killing the entire process tree". A follow-up user turn
+ * then tells the model what happened so it retries with a timeout instead of
+ * hanging again.
  *
  * Tool-agnostic by default: it arms on every tool except exact names listed in
  * `commandTimeoutExemptTools`, which /task-config fills from the live tool list

package/dist/task/command-watchdog.js

@@ -7,14 +7,17 @@ import { CommandWatchdog, realTimerDeps, reminderMessage } from '../shared/comma
  * returns — `godot --headless --check-only` with no timeout, a dev server, a
  * hung test — and the run wedges until the user manually aborts and tells the
  * model to add a timeout. pi's bash tool takes an OPTIONAL `timeout` with NO
- * default (see pi-coding-agent tools/bash.js), so any command the model didn't
- * bound runs forever. This supplies the missing default from the host side.
+ * default: its schema in `core/tools/bash.js` says "optional, no default
+ * timeout" and its resolver returns undefined for an absent value, so no timer is
+ * ever armed. This supplies the missing default from the host side.
  *
  * HOW: arm a wall-clock timer on `tool_execution_start`, disarm it on
- * `tool_execution_end`. If it elapses, `ctx.abort()` cancels the in-flight
- * operation — which fires the tool's AbortSignal, and pi's bash executor kills
- * the whole process tree on abort — then a follow-up user turn tells the model
- * what happened so it retries with a timeout instead of hanging again.
+ * `tool_execution_end` — both real pi events. If it elapses, `ctx.abort()`
+ * cancels the in-flight operation, which fires the tool's AbortSignal; pi's bash
+ * executor imports `killProcessTree` and its own comment on that listener reads
+ * "Handle abort signal by killing the entire process tree". A follow-up user turn
+ * then tells the model what happened so it retries with a timeout instead of
+ * hanging again.
  *
  * Tool-agnostic by default: it arms on every tool except exact names listed in
  * `commandTimeoutExemptTools`, which /task-config fills from the live tool list
@@ -33,16 +36,19 @@ import { CommandWatchdog, realTimerDeps, reminderMessage } from '../shared/comma
 export { CommandWatchdog, commandTimeoutHint, realTimerDeps, reminderMessage, WATCHDOG_CANCEL_MARKER } from '../shared/command-watchdog.js';
 /**
  * One-shot marker: the most recent turn abort was issued BY THE WATCHDOG, not by
- * a human ESC. Both end the assistant turn with stopReason 'aborted' — the only
- * signal steerUntilDone's classifyTurnEnd() can read — so without this flag the
- * steer loop can win the race against the watchdog's queued follow-up turn and
- * show a steering prompt to an empty room (wedging an unattended run).
+ * a human ESC. Both end the assistant turn the same way, and `classifyTurnEnd`
+ * has nothing else to go on — it decides with `last?.stopReason === 'aborted'`.
+ * Without this flag the steer loop can win the race against the watchdog's queued
+ * follow-up turn and show a steering prompt to an empty room, wedging an
+ * unattended run.
  *
- * Set synchronously in onFire BEFORE ctx.abort(), so it is observable by the
- * time any waitForIdle resolves; consumed (cleared) by the first reader. A stale
- * flag (the aborted turn wasn't one the steer loop was watching) only costs the
- * consumer a bounded wait before it falls back to prompting — it can never
- * permanently suppress a human's steer prompt.
+ * Set synchronously in onFire BEFORE ctx.abort(), so it is observable by the time
+ * any waitForIdle resolves; consumed by the first reader. Run: it reads false
+ * before any abort, true once after a note, false again immediately after — and
+ * two notes still yield exactly one true. A stale flag (the aborted turn was not
+ * one the steer loop was watching) only costs the consumer a bounded wait before
+ * it falls back to prompting; it can never permanently suppress a human's steer
+ * prompt.
  */
 let watchdogAbortPending = false;
 /** @internal Set by onFire when it aborts a turn. Exported for the adapter and tests. */