@mjasnikovs/pi-task 0.38.28 → 0.38.30

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. */

package/dist/task/context-attribution.d.ts

@@ -1,25 +1,25 @@
 /**
- * Deterministic detector for the F-1 laundering shape: a CONTEXT bullet that asserts
+ * Deterministic detector for the laundering shape: a CONTEXT bullet that asserts
  * external API USAGE SEMANTICS under an attribution cue that no EXTERNAL CONTEXT block
  * can actually support.
  *
- * THE SHAPE, from mx5 run 15 (TASK_0027.md, verbatim):
+ * THE SHAPE:
  *
  *   - The `hono` dependency is pinned at `^4.12.31` in package.json, and the external
  *     context confirms `hc<AppType>` pattern with base URL `/api` for same-origin
  *     relative paths works correctly (per Hono RPC docs LIVE data).
  *
- * worker:context has tools `read,grep` only (phases.ts:623) — it cannot consult any
- * documentation — so the base-URL claim was necessarily from model memory. It shipped
- * into TASK_0027's CONSTRAINTS and ACCEPTANCE, the implementation obeyed it exactly
- * (`hc<AppType>('/api')` plus `api.api.auth.login.$post()`), and every request went to
- * `/api/api/...` ⇒ 404 ⇒ the product's entire API surface was dead.
+ * The `worker:context` row in phases.ts gives that worker `tools: 'read,grep'` and
+ * nothing else — no fetch, no docs channel — so a base-URL claim like that one is
+ * necessarily from model memory. It then ships into a task's CONSTRAINTS and
+ * ACCEPTANCE, the implementation obeys it exactly, and every request goes to the
+ * wrong path.
  *
  * WHY THE OBVIOUS TEST DOES NOT WORK. "Flag a bullet whose package has no EXTERNAL
  * CONTEXT block" misses this case: EXTERNAL CONTEXT *did* carry a `### npm: hono` block.
  * That block contains version numbers and nothing else, so it cannot support a claim
  * about what a base URL MEANS — yet it lends the sentence an air of having been checked.
- * That is the whole mechanism (F-1e): one citable fact, the pinned version, fused in a
+ * That is the whole mechanism: one citable fact, the pinned version, fused in a
  * single sentence with an uncitable one under a shared attribution. The true half
  * launders the false half.
  *
@@ -30,27 +30,35 @@
  *   ### url:      fetched page content            -> CAN source a semantics claim
  *   ### service:  3 search-result SNIPPETS        -> cannot source a semantics claim
  *
- * The `service` exclusion is not a judgement call — it is the LIVE-DATA RULE's own scope.
- * That rule makes a service block authoritative for "current API surface, deprecation
- * status, and replacement systems", i.e. versions/status/names. A service block is a
- * title + URL + one-line description per result (service-blocks.ts:10); it cannot carry
- * what a parameter MEANS. This matters concretely: TASK_0027's enrichment produced
- * exactly one service block, `### service: Hono RPC client` (extractEnrichTargets on the
- * verbatim refined task yields services=[Hono RPC client], urls=[], packages=[any,api,hc]).
- * Were `service` treated as source-capable for semantics, the subject string "Hono RPC
- * client" would match the package `hono` and the fatal bullet would pass unflagged — the
- * detector would be unable to catch the very defect it exists for.
+ * The `service` exclusion is not a judgement call — it is the LIVE-DATA RULE's own
+ * scope. That rule (prompts.ts) makes a service block authoritative for "current
+ * API surface, deprecation status, and replacement systems", i.e. versions, status
+ * and names. And a service block is only ever a title, a URL and a one-line
+ * description per result — see `formatServiceBlock` — so it cannot carry what a
+ * parameter MEANS.
+ *
+ * This matters concretely, and was checked: with a single
+ * `### service: Hono RPC client` block as the only external context, the fatal
+ * bullet IS flagged. Were `service` treated as source-capable, that subject would
+ * match the package `hono` and the bullet would pass — leaving the detector unable
+ * to catch the one defect it exists for.
  *
  * A bullet is FLAGGED iff all three hold:
- *   1. it carries an attribution cue ("per ... LIVE data", "the external context
- *      confirms", "docs confirm", "per the official docs", ...);
- *   2. it asserts API usage semantics — how something is called, what a parameter means,
- *      what a default is, what behaviour results — as opposed to a version or a status;
+ *   1. it carries an attribution cue ("per... LIVE data", "the external context
+ *      confirms", "docs confirm", "per the official docs",...);
+ *   2. it asserts API usage semantics — how something is called, what a parameter
+ *      means, what a default is, what behaviour results — as opposed to a version
+ *      or a status;
  *   3. no `### url:` or `### docs:` block exists for any package the bullet names.
  *
- * Pure and side-effect free; unit-tested in context-attribution.test.ts against the real
- * run-15 bullets, including the three legitimate attributed bullets (TASK_0007, _0012,
- * _0031) that must NOT be flagged.
+ * All six branches were run against the laundering bullet above. It is FLAGGED with
+ * an npm-only block, with a service-only block, and with no external context at
+ * all; it is NOT flagged once a `### docs:` or `### url:` block for that package
+ * exists. And the same context leaves alone a version claim made under an
+ * attribution cue, a semantics claim made with NO cue, and a plain "is pinned at"
+ * statement of fact.
+ *
+ * Pure and side-effect free; also unit-tested in context-attribution.test.ts.
  */
 /** A block that actually appears in an EXTERNAL CONTEXT header. */
 export interface ContextBlock {
@@ -81,7 +89,7 @@ export interface BulletSpan {
 /**
  * Split a CONTEXT section into bullets WITH their line ranges. Continuation lines are
  * folded into the bullet above so a hard-wrapped claim is judged as one sentence — which
- * is exactly how the fatal run-15 bullet was written.
+ * is exactly how the fatal bullet was written.
  */
 export declare function splitBulletSpans(context: string): BulletSpan[];
 /** Split a CONTEXT section into its bullets, joining hard-wrapped continuation lines. */