@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/root-cause-repair.js

@@ -1,21 +1,12 @@
 /**
  * root-cause-repair — turn a verify-FAIL that was CAUSED by another task's file
- * into a scoped repair task in the running plan (mx5 run 14, PROMPT item 5).
+ * into a scoped repair task in the running plan.
  *
- * The failure class this closes, observed end-to-end in run 14: TASK_0007 shipped
- * `test/teardown.ts` with parameterized table names in its TRUNCATE statements.
- * That bug then FAILED two later, unrelated tasks —
- *
- *   TASK_0013  "test/teardown.ts has a pre-existing bug (parameterized table names
- *               in TRUNCATE statements) … despite all 10 actual tests passing"
- *   TASK_0019  "… due to a pre-existing teardown bug in `test/teardown.ts`
- *               (created by TASK_0007) … this task did not modify the teardown"
- *
- * — and BOTH ended in an enforce-revert, so the enforce pass's edits were destroyed
- * over a defect the current task did not create. The ledger recorded the root cause
- * twice and NOTHING ever scheduled a fix: the bug survived ~24h, until the final
- * gate's fix child happened to patch it, and it also generated the "2 pre-existing
- * failures / state pollution" excuse notes repeated across TASK_0033…0038.
+ * The failure class this closes: one task ships a broken shared file — a test
+ * teardown, say — and that file then FAILS later, unrelated tasks. Each of those
+ * FAILs is recorded as a debt naming the same root cause, and nothing schedules a
+ * fix: every later task keeps hitting it, and each one's enforce pass can be
+ * reverted over a defect it did not create.
  *
  * The channel here is deliberately narrow, because a false positive costs a whole
  * task slot and mutates a running plan. Three independent conditions must ALL hold:
@@ -23,25 +14,22 @@
  *   1. TEXT — the FAIL reason (or the resolution research's rationale) carries an
  *      explicit blame cue ("pre-existing", "created by TASK_nnnn", "bug in", "this
  *      task did not modify") and a path token near it. Merely MENTIONING a path is
- *      not blame: run 14's TASK_0010 FAIL lists `src/server/db.ts` inside the
- *      spec's own "Preserve all existing files on disk" quote, and must not spawn
- *      a repair task for it.
+ *      not blame: a FAIL that quotes the spec's own "Preserve all existing files
+ *      on disk" alongside a path must not spawn a repair task for that path.
  *   2. PROVENANCE — the blamed file was introduced by a DIFFERENT task's commit
  *      (task-provenance.ts). Unknown provenance is never evidence.
  *   3. AUTHORSHIP — the current task's own work does not touch the blamed file. If
  *      this task edited it, the defect may well be its own and the ordinary
  *      autofix/revert path is right.
  *
- * Environment-attributed failures are vetoed outright (run 14's TASK_0006: "no
- * PostgreSQL database server is available in this environment"). No file edit can
- * repair a missing daemon, so a repair task would be a guaranteed non-converging
- * yolo-FAIL.
+ * Environment-attributed failures are vetoed outright ("no PostgreSQL database
+ * server is available in this environment"). No file edit repairs a missing
+ * daemon, so a repair task there would be a guaranteed non-converging FAIL.
  *
- * Everything downstream is deduplicated by FILE: N debts naming one root file yield
- * exactly ONE repair task per run (run 14 would otherwise have spawned two for
- * `test/teardown.ts`). The repair task itself is just an ordinary plan entry — if it
- * fails, it lands in the ledger like any other task and is never re-spawned, which
- * is what keeps this from looping.
+ * Everything downstream is deduplicated by FILE: N debts naming one root file
+ * yield exactly ONE repair task per run. The repair task itself is just an
+ * ordinary plan entry — if it fails, it lands in the ledger like any other task
+ * and is never re-spawned, which is what keeps this from looping.
  */
 import { makeLedger } from './ledger.js';
 /** A path-like token: at least one directory separator, ending in a file name. */
@@ -50,14 +38,14 @@ const PATH_TOKEN_RE = /(?:[\w.@-]+\/)+[\w.@-]+\.\w+/g;
  * Phrases that ATTRIBUTE a failure to something that predates the current task.
  * Each is a blame cue: the path token nearest a cue is the accused file. Kept
  * deliberately specific — a bare "existing" matches the spec boilerplate
- * "Preserve all existing files on disk" that run 14's TASK_0010 FAIL quotes.
+ * "Preserve all existing files on disk" that a task FAIL quotes.
  */
 const BLAME_CUE_RE = /pre-?\s?existing|existing (?:bug|defect|failure|issue|fault)|(?:created|introduced|added|written) (?:by|in) TASK_\d+|(?:bug|defect|fault|error) in\b|already (?:broken|failing|red)|(?:this task )?did not (?:modify|touch|create|change)|not (?:modified|touched|created|introduced) by this task|unrelated to this task/gi;
 /**
  * Failures the environment causes, not a file. No edit to any file repairs a
- * missing database server, so these must never open the repair channel — run 14's
- * TASK_0006 ("no PostgreSQL database server is available in this environment (no
- * binary, no Docker, no listener on port 5432)") is the canonical shape.
+ * missing database server, so these must never open the repair channel. The
+ * canonical shape is "no PostgreSQL database server is available in this
+ * environment (no binary, no Docker, no listener on port 5432)".
  */
 const ENVIRONMENT_BLAME_RE = /no (?:postgres|postgresql|mysql|database|redis|docker|network|internet|display)\b|not (?:installed|available|running|present) (?:in|on|for) (?:this |the )?(?:env|environment|sandbox|container|machine|image|system)|(?:environment|env|sandbox|container) (?:gap|limitation|lacks|has no|does not (?:have|provide))|no (?:binary|listener|daemon|server) (?:on|for|available)|missing (?:binary|executable|system (?:tool|package)|runtime)|is not installed|command not found/i;
 /** How far from a blame cue a path token may sit and still be the accused file. */
@@ -280,10 +268,11 @@ export async function drainRepairQueue(cwd) {
     return parsed;
 }
 /**
- * Collapse candidates by file — MANDATORY dedup: run 14's two teardown.ts debts
- * (TASK_0013, TASK_0019) must yield exactly ONE repair task naming both. First
- * record wins for defect/command (they describe the same fault); blamed tasks
- * accumulate in first-seen order.
+ * Collapse candidates by file — MANDATORY dedup: two debts naming the same file
+ * must yield exactly ONE repair task naming both blamed tasks. Keyed on the
+ * NORMALISED path, so `./x.ts` and `x.ts` are one entry. First record wins for
+ * defect and command (they describe the same fault); blamed tasks accumulate in
+ * first-seen order.
  */
 export function mergeRepairCandidates(candidates) {
     const byFile = new Map();
@@ -339,11 +328,10 @@ export function planHasRepairFor(titles, file) {
     });
 }
 /**
- * The extra scope fence a repair entry carries into refine. Without it, refine
- * re-expands "repair test/teardown.ts: parameterized table names in TRUNCATE"
- * into "overhaul the test infrastructure" — the /task-auto drift lesson. The
- * fence pins the single editable file and pins the VERIFY to the exact command
- * the debt failed on.
+ * The extra scope fence a repair entry carries into refine. A repair title names
+ * one file and one narrow defect, which refine will otherwise re-expand into
+ * "overhaul the test infrastructure". The fence pins the single editable file and
+ * pins the VERIFY to the exact command the debt failed on.
  */
 export function buildRepairScopeFence(file, verifyCommand) {
     return [

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

@@ -13,23 +13,20 @@
  *   2. the raw-stdin interception that makes the terminal behave like the
  *      browser is ARMED (`cancel-input.ts`: `armCancelListener`/`disarm…`).
  *
- * Before this module the pair — begin, arm, … finally disarm, end, report the
- * dropped lines — was written out at four sites in two files, and the `finally`
- * halves disagreed on order (the orchestrator disarmed first; `/task-auto` ended
- * first). The order is not observable — both halves are synchronous, the
+ * The teardown order is not observable — both halves are synchronous, the
  * listener only consults `isRunActive()` on a keystroke, and no keystroke can
  * land between two statements of one tick — so there is ONE order here, not an
  * option: stop listening, then release the hold and report what it dropped.
  *
- * The two refcounts stay two, deliberately. `runDepth` is read by the remote
- * bridge (`isRunActive`) with no ctx in hand and by the listener itself;
- * `armed.depth` guards a live stdin subscription that is re-pointed on every
- * session replacement (`rearmCancelListener`) and is armed on its own by the
- * cancel-latency harness and cancel-points tests. Collapsing them means one
- * module's counter driving the other's lifecycle, or a third counter with both
- * modules demoted to flags — a wider change than the drift it prevents. What
- * prevents drift now is that this bracket is the ONLY production caller of
- * either pair.
+ * The two refcounts stay two, deliberately. `runDepth` (mid-run-input.ts) is read
+ * by the remote bridge through `isRunActive` with no ctx in hand, and by the
+ * listener itself; `armed.depth` (cancel-input.ts) guards a live stdin
+ * subscription that is re-pointed on every session replacement
+ * (`rearmCancelListener`, called from orchestrator.ts) and that
+ * cancel-input.test.ts arms directly. Collapsing them means one module's counter
+ * driving the other's lifecycle, or a third counter with both modules demoted to
+ * flags — a wider change than the drift it prevents. What prevents drift now is
+ * that this bracket is the ONLY production caller of either pair.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 export interface RunBracketOptions {

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

@@ -1,22 +1,14 @@
 /**
  * run-end — how a single /task run ENDED, named once.
  *
- * `TaskRunner.run` returned `void` and never threw, so `runSingleTask` learned
- * what it had just done by RE-READING the task file's front matter, narrowing
- * that to `ok: boolean`, and smuggling the rest out of the `withSession` closure
- * through three mutable captures. Both commands then re-derived a cause the
- * runner already had: `classifyFailure` names the ending exactly, and
- * `handleFailure` threw the name away.
+ * `TaskRunner.run` returns this, so a caller never has to re-derive the ending by
+ * re-reading the task file's front matter and narrowing it to a boolean. Reading
+ * the file back cannot tell a user cancel from a fault: `/task-cancel` writes
+ * `cancelled`, and anything that only asks "is the state completed?" then treats
+ * that stop as a failure and overwrites it.
  *
- * The live consequence was a wrong report. `/task-cancel` during a gated run
- * writes `cancelled` to the file; `ok` is `state === 'completed'`, so it is
- * false; `!res.ok` calls `markResumable`, which overwrites `cancelled` with
- * `failed`, and announces a red *"stopped — fix and run /task-resume"*.
- * `/task-auto` hits the same arm for the same input, because its cancel branch
- * only consults a module global that `/task-cancel` never sets.
- *
- * The file is still written — it is what a RESUME reads. What changed is that it
- * is no longer the channel this process uses to talk to itself.
+ * The file is still written — it is what a RESUME reads. It is just not the
+ * channel this process uses to talk to itself.
  */
 /** Why a run stopped. Exactly one of these is true of any finished run. */
 export type RunEnd = 
@@ -45,14 +37,12 @@ export type RunEndKind = RunEnd['kind'];
 /**
  * What a command does about each ending.
  *
- * `resumable` and `announce` are the two facts the two hand-written ladders
- * disagreed about, and the disagreement is where the cancel bug lived: a
- * `cancelled` run was falling into the `failed` arm and being marked resumable.
- * The WORDING stays per-command — `/task` says "resume with /task-resume" where
- * `/task-auto` says "/task-auto-resume" — so only the policy is shared.
+ * The POLICY is shared by /task's loop (orchestrator.ts) and /task-auto's
+ * (auto-orchestrator.ts). The WORDING stays per-command — /task says "resume with
+ * /task-resume" where /task-auto says "/task-auto-resume".
  */
 export interface RunEndPolicy {
-    /** Mark the task resumable (overwrites its state with `failed`). */
+    /** Mark the task resumable — `markResumable` writes `state: failed`. */
     resumable: boolean;
     /**
      * Does this ending FAIL the plan that contains the task?
@@ -73,5 +63,5 @@ export interface RunEndPolicy {
  * fault.
  */
 export declare const RUN_END_POLICY: Record<RunEndKind, RunEndPolicy>;
-/** Did the run deliver a spec? The single question the old `ok` boolean answered. */
+/** Did the run deliver a spec? True for `completed` and nothing else. */
 export declare function runSucceeded(end: RunEnd): boolean;

package/dist/task/run-end.js

@@ -1,22 +1,14 @@
 /**
  * run-end — how a single /task run ENDED, named once.
  *
- * `TaskRunner.run` returned `void` and never threw, so `runSingleTask` learned
- * what it had just done by RE-READING the task file's front matter, narrowing
- * that to `ok: boolean`, and smuggling the rest out of the `withSession` closure
- * through three mutable captures. Both commands then re-derived a cause the
- * runner already had: `classifyFailure` names the ending exactly, and
- * `handleFailure` threw the name away.
+ * `TaskRunner.run` returns this, so a caller never has to re-derive the ending by
+ * re-reading the task file's front matter and narrowing it to a boolean. Reading
+ * the file back cannot tell a user cancel from a fault: `/task-cancel` writes
+ * `cancelled`, and anything that only asks "is the state completed?" then treats
+ * that stop as a failure and overwrites it.
  *
- * The live consequence was a wrong report. `/task-cancel` during a gated run
- * writes `cancelled` to the file; `ok` is `state === 'completed'`, so it is
- * false; `!res.ok` calls `markResumable`, which overwrites `cancelled` with
- * `failed`, and announces a red *"stopped — fix and run /task-resume"*.
- * `/task-auto` hits the same arm for the same input, because its cancel branch
- * only consults a module global that `/task-cancel` never sets.
- *
- * The file is still written — it is what a RESUME reads. What changed is that it
- * is no longer the channel this process uses to talk to itself.
+ * The file is still written — it is what a RESUME reads. It is just not the
+ * channel this process uses to talk to itself.
  */
 /**
  * The one table. A run that the USER stopped is not resumable-as-failed: its
@@ -31,7 +23,7 @@ export const RUN_END_POLICY = {
     failed: { resumable: true, failsRun: true, level: 'error' },
     'no-session': { resumable: false, failsRun: false, level: 'warning' }
 };
-/** Did the run deliver a spec? The single question the old `ok` boolean answered. */
+/** Did the run deliver a spec? True for `completed` and nothing else. */
 export function runSucceeded(end) {
     return end.kind === 'completed';
 }

package/dist/task/run-final-gate.d.ts

@@ -3,14 +3,14 @@
  *
  * task-gates.ts gates ONE task against its own spec. This gates the WHOLE REPO once,
  * when every task in a /task-auto run is checked off and BEFORE the run is declared
- * complete: every task passed its own per-slice gates, but per-slice green has shipped
- * a dead app twice (mx5 runs 3 & 5 — statics clean, every protected route 500ing). So
- * the project's OWN whole-repo commands run once here, unaided.
+ * complete. Every task passing its own per-slice gate does not prove the assembled
+ * whole works, so the project's OWN whole-repo commands run once here, unaided.
  *
  * The stage owns four things the per-task gate has no equivalent of:
  *
  *   1. THREE verdicts, not two — PASS / FAIL / UNOBSERVED. A gate that observed
- *      nothing dynamic is never announced as a pass (final-gate.ts unobservedVerdict).
+ *      nothing dynamic is never announced as a pass (gate-tally.ts
+ *      `unobservedVerdict`).
  *   2. The run-end ACCEPT-debt report — every defect a task was allowed to ship with,
  *      surfaced at the last moment anyone will look, and RE-DERIVED against the final
  *      tree after a converged autofix so the last word is about the tree that shipped.
@@ -19,7 +19,7 @@
  *      after MAX_FINAL_GATE_AUTOFIX so a non-converging fix pass cannot loop forever.
  *   4. The stranded sub-fixes a non-converging fix pass leaves in the working tree —
  *      committed on EVERY terminal outcome, because both of them end the run and the
- *      next `git checkout` would destroy real repairs (mx5 run 14: 13 of them).
+ *      next `git checkout` would destroy real repairs.
  *
  * Every terminal outcome is RETURNED, never announced here — same contract as
  * {@link runGatesForTask}'s GateResult: the caller owns the parent task file's state
@@ -54,21 +54,19 @@ export interface FinalGateStageDeps {
     finalGateFix?: FinalGateFixFn;
     /**
      * Paths currently uncommitted in the working tree (`git status` shape), used to
-     * detect SUB-FIXES a non-converging fix pass left behind (mx5 run 13 PROMPT 4 item
-     * 3). Every task is committed by the time this stage runs, so anything dirty here
-     * is the fix pass's own work. Absent → the stranded-fix handling is skipped
+     * detect SUB-FIXES a non-converging fix pass left behind (item 4 in the header).
+     * Every task is committed by the time this stage runs, so anything dirty here is
+     * the fix pass's own work. Absent → the stranded-fix handling is skipped
      * entirely (prior behavior).
      */
     pendingChanges?: (cwd: string) => Promise<string[]>;
     /**
      * Re-derive the still-open ACCEPT-debt ledger against the tree AS IT IS NOW
-     * (final-gate.ts `deriveOpenDebts`). Needed because the run's "N recorded
-     * verify-FAIL defect(s) are STILL unresolved" report used to be built from the
-     * FIRST gate result and the converged-autofix path then rebuilt the gate outcome
-     * as a bare `{ok, reason}` — so `openDebts` was not merely un-actioned, it was GONE
-     * from the value, and no code path could ever clear, re-check or act on it (mx5 run
-     * 18: four defects reported STILL OPEN at 14:58, one of them fixed by the autofix
-     * that converged at 15:03, and the report never moved).
+     * (`deriveOpenDebts`, defined in accept-debt.ts and re-exported by
+     * final-gate.ts). Needed because the run's "N recorded verify-FAIL defect(s) are
+     * STILL unresolved" report is built from the FIRST gate result: without this, an
+     * autofix that converged after that report would leave the run's last word about
+     * a tree that no longer exists.
      *
      * `staticOk` is the caller's PROOF about the current statics, never a guess: it is
      * passed true only where the gate itself just passed them. Absent (tests) → the
@@ -108,8 +106,9 @@ export interface FinalGateStageParams {
     /** The parent /task-auto id: trail target, notify prefix, commit-message tag. */
     runId: string;
     /** The parent plan (the task list), handed to the gate so it can tell a served app
-     *  from a CLI — the boot check requires a listener only for the former (mx5 run 10:
-     *  a CSS watcher satisfied "still alive"). */
+     *  from a CLI — the boot check requires a listener only for the former. Without
+     *  that distinction any long-lived process, a file watcher included, satisfies
+     *  "still alive". */
     planText: string;
     /** How many tasks the run completed — for the completion announcement only. */
     taskCount: number;
@@ -134,9 +133,8 @@ export type FinalGateStageResult = {
 /**
  * Run the whole-repo gate and resolve its verdict with the user.
  *
- * Lifted verbatim out of /task-auto's run loop, which it never shared state with:
- * the stage reads no per-task variable and writes none. Never throws for a gate
- * outcome — only a user cancel inside a gate child propagates (the caller's
- * USER_CANCELLED path handles it).
+ * Shares no state with /task-auto's run loop: the stage reads no per-task variable
+ * and writes none. Never throws for a gate outcome — only a user cancel inside a
+ * gate child propagates (the caller's USER_CANCELLED path handles it).
  */
 export declare function runFinalGateStage(active: ExtensionCommandContext, deps: FinalGateStageDeps, p: FinalGateStageParams): Promise<FinalGateStageResult>;