@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/task/file-inventory.js

@@ -1,20 +1,24 @@
 /**
- * Project file inventory — runs `git ls-files` once per /task run so research
- * workers can skip their own discovery loops and jump straight to targeted
- * read/grep on known paths. Returns '' on failure (non-git repo, git missing,
- * timeout) so callers can fall back to the pre-inventory behavior.
+ * Project file inventory — `git ls-files`, capped, with the task directory
+ * stripped. `phaseResearch` computes it once and puts it in the header every
+ * research worker gets; `refineExistingFilesBlock` also uses it to pick the
+ * paths orientation pre-reads.
+ *
+ * Returns '' on failure: a non-git tree exits 128, and a missing binary reaches
+ * `runChildDefault`'s `error` handler as exit 1. Both callers treat '' as "no
+ * inventory" and carry on.
  */
 import { makeGit } from '../shared/git-runner.js';
 import { TASKS_DIR_NAME } from './task-types.js';
 const DEFAULT_MAX_LINES = 2000;
 /**
- * Drop the committed task directory from the inventory. `git ls-files` lists
- * tracked files regardless of `.ignore`, so once tasks are committed they would
- * otherwise be handed to every research worker (and feed orientation). The user
- * wants tasks committable but invisible to workers and the local model, so we
- * strip `.pi-tasks/` here — the inventory's single chokepoint. (`git ls-files`
- * always emits posix-style paths, so the forward-slash prefix is correct on all
- * platforms.)
+ * Drop the committed task directory from the inventory. `git ls-files` lists a
+ * TRACKED file even when `.gitignore` matches it — confirmed against a real
+ * repo where `.pi-tasks/` is both ignored and committed — so once tasks are
+ * committed they reach every research worker and feed orientation unless they
+ * are stripped here. This is the only filter on the inventory path.
+ *
+ * `git ls-files` prints forward slashes, so the prefix matches as written.
  */
 export function stripTasksDir(raw) {
     const prefix = `${TASKS_DIR_NAME}/`;
@@ -24,19 +28,18 @@ export function stripTasksDir(raw) {
         .join('\n');
 }
 /**
- * `git ls-files`, or '' on ANY failure — non-git tree, missing git, cancelled run.
- * The empty string is the caller's fall-back-to-pre-inventory signal, so every
- * unhappy path has to collapse to it.
+ * `git ls-files`, or '' on ANY failure — non-git tree, missing git, cancelled
+ * run. '' is the signal both callers branch on, so every unhappy path has to
+ * collapse to it.
  *
- * Runs on the shared GitRunner (`shared/git-runner.ts`), which brings the abort
- * discipline this used to hand-roll: the listener is detached when the child
- * settles normally, so a run-long orchestrator signal does not accumulate one
- * retained child per invocation (GitHub issue #9).
+ * Runs on the shared GitRunner, whose child detaches its abort listener when it
+ * settles: one AbortController is shared across a whole run, so a listener left
+ * attached per call would retain each finished child.
  *
- * The `signal.aborted` check is what preserves this function's OWN contract on
- * cancellation. A killed child closes with a null exit code, which the runner
- * reports as 0 — so without it a cancelled run would hand back a truncated
- * inventory as if it were complete, where the hand-rolled version returned ''.
+ * The `signal.aborted` check is what holds the contract on cancellation. A
+ * killed child closes with a null exit code and `runChild` reports `code ?? 0`,
+ * so without the check a cancelled run would return partial stdout as if the
+ * listing were complete.
  */
 async function runGitLsFiles(cwd, signal) {
     const git = makeGit(cwd, signal);

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

@@ -5,13 +5,15 @@ import { type TreeChangeSummary, type IgnoredSnapshot } from './write-guard.js';
 export declare const FINAL_FIX_TOOLS = "read,edit,bash";
 /**
  * How many fix passes the user may launch from the picker before the option is
- * withdrawn (mirrors the per-task MAX_AUTO_AUTOFIX budget). Each attempt is a
- * full model child plus a full gate re-run — after this many that still FAIL,
- * only Leave-failed / Accept remain so a person breaks the loop.
+ * withdrawn. Same value as the per-task MAX_AUTO_AUTOFIX budget. Each attempt is
+ * a full model child plus a full gate re-run — after this many that still FAIL,
+ * `run-final-gate.ts` drops the Autofix card and only Leave-failed / Accept
+ * remain, so a person breaks the loop.
  */
 export declare const MAX_FINAL_GATE_AUTOFIX = 3;
-/** Picker labels/values. Classification accepts the value token, the label, or
- *  free text (→ autofix guidance), same contract as the per-task resolution. */
+/** Picker labels/values. Each label starts with its own value word, so
+ *  `classifyFinalGateAnswer` accepts the value token and the label alike;
+ *  anything else is free text and becomes autofix guidance. */
 export declare const FINAL_LEAVE_VALUE = "fail";
 export declare const FINAL_ACCEPT_VALUE = "accept";
 export declare const FINAL_AUTOFIX_VALUE = "autofix";
@@ -19,8 +21,8 @@ export declare const FINAL_LEAVE_LABEL = "Leave failed \u2014 I will fix and /ta
 export declare const FINAL_ACCEPT_LABEL = "Accept \u2014 complete the run anyway";
 export declare const FINAL_AUTOFIX_LABEL = "Autofix \u2014 run a bounded fix pass and re-run the gate";
 export interface FinalGateChoice {
-    /** What the user decided. 'leave' = leave the run failed (also the dismissal
-     *  default — identical to the pre-autofix behavior). */
+    /** What the user decided. 'leave' = leave the run failed, and also what a
+     *  dismissed picker means. */
     action: 'leave' | 'accept' | 'autofix';
     /** Free-text guidance typed instead of picking a card; folded into the fix
      *  child's failure seed. Only set with 'autofix'. */
@@ -28,63 +30,51 @@ export interface FinalGateChoice {
 }
 /**
  * Map a final-gate picker answer to an action. Dismissal (undefined/empty) and
- * an explicit leave stay "leave" — exactly what the two-option picker did.
- * Free text becomes autofix guidance, mirroring classifyResolutionAnswer; the
- * caller demotes autofix back to "leave" when the option was not offered.
+ * an explicit leave both stay "leave". Free text becomes autofix guidance; the
+ * caller's `choice.action === 'autofix' && canAutofix` test demotes autofix back
+ * to leave when the card was not offered.
  */
 export declare function classifyFinalGateAnswer(answer: string | undefined): FinalGateChoice;
 /**
- * The gate's fail reason always carries the failing command in backticks
- * (`` `bun run test` exited 1 — … `` / ``static checks: `make lint` exited 2``).
- * Extract it for reporting; the shrink guard itself compares the FULL
- * discovered-command sets, so a reason this cannot parse still guards.
+ * The gate's fail reason carries the failing command in backticks — final-gate
+ * mints `` `<label>` exited <status> — <tail> ``, with a `lockfile check: ` or
+ * `launch script: ` prefix on two of the sections. Extract it for reporting
+ * only; the shrink guard compares the FULL discovered-command sets, so a reason
+ * this cannot parse still guards.
  */
 export declare function exitedCommandFromReason(reason: string): string | null;
 /**
  * Build the fix child's prompt. Generic by construction: the only project facts
- * in it are the gate's own failure text — the command comes from the project's
- * discovered manifest, never from a hardcoded ecosystem. The seed may carry
- * SEVERAL failures (the gate aggregates every section since mx5 run 13, ranked
- * most load-bearing first); convergence means the WHOLE list is empty, so the
- * child is told to fix all of them.
+ * in it are the gate's own failure text, whose command labels come from the
+ * project's discovered manifest. The seed may carry SEVERAL failures — the gate
+ * runs every section and aggregates, emitting "N failures (ranked, most
+ * load-bearing first)" — and it reports `ok` only when that list is empty, so
+ * the child is told to fix all of them.
  */
 export declare function buildFinalFixPrompt(failReason: string): string;
-/**
- * Parse the child's final marker. Last match wins (the model reasons before
- * concluding and bash output can echo the words). No marker → treated as DONE:
- * the gate re-run is the arbiter either way, so a missing marker only skips the
- * early-out on a self-declared BLOCKED.
- */
+/** This pass's marker word, parsed by the shared `parseFixMarker` (last match
+ *  wins; no marker → DONE). */
 export declare function parseFinalFixMarker(text: string): {
     blocked: boolean;
     note?: string;
 };
 /**
- * STRANDED SUB-FIXES (mx5 run 13, PROMPT 4 item 3).
- *
- * A fix attempt that does not converge keeps its edits: they are NOT discarded
- * (only a guard trip discards), and `deps.commit` runs only on `fix.ok`. So a
- * partial fix that genuinely repaired something sits in the working tree, uncommitted,
- * and if the user then ACCEPTs the FAIL the run completes around it — leaving HEAD
- * broken while the repair is invisible unless someone runs `git status`.
+ * STRANDED SUB-FIXES.
  *
- * That is exactly what run 13 shipped: the fix child's bunfig.toml change made
- * `bun run test` pass 116/116, attempt 1 did not converge overall, the user accepted
- * the FAIL, and the tree still shows the file modified while HEAD's `bun run test` is
- * broken. The repair and the breakage were BOTH real; only the repair was discarded
- * by default.
+ * An attempt that does not converge KEEPS its edits — only a guard trip
+ * discards — and the caller commits only on `fix.ok`. So a partial fix that
+ * genuinely repaired something sits uncommitted in the working tree while HEAD
+ * still carries the defect, invisible unless someone runs `git status`.
  *
- * The rule: a partial fix is either committed (its own commit, named in the trail) or
- * explicitly surfaced — never silently stranded.
+ * The rule: a partial fix is either committed as its own named commit or
+ * explicitly surfaced — never silently stranded. `run-final-gate.ts` calls
+ * `commitStranded` on BOTH terminal outcomes, accept and leave-failed, so an
+ * unattended run that ends on LEAVE does not leave real repairs one `git
+ * checkout` from gone.
  *
- * mx5 run 14 proved the committing half only ever ran on the ACCEPT path. The run
- * ended on LEAVE (YOLO, budget spent) and 13 real repairs — the dev script, the
- * teardown bug, test serialization, the migrate script: the changes that make that
- * app work today — were left dirty in the tree, one `git checkout` from gone, after
- * an UNATTENDED run nobody was watching. So EVERY terminal non-converged outcome
- * commits them now, not just ACCEPT. Only guard-CLEAN edits qualify: an attempt a
- * write-guard rejected without discarding leaves REJECTED edits in the tree, and
- * those are never committed (the guard is not weakened to make committing easier).
+ * Only guard-CLEAN edits qualify. `AutofixLedger.mayCommitTree()` goes false
+ * once a guard has rejected an attempt whose edits could not be discarded, and
+ * never flips back: the guard is not weakened to make committing easier.
  */
 /** Commit subject for partial fixes committed alongside a terminal gate FAIL. */
 export declare const STRANDED_FIX_COMMIT: (runId: string, outcome?: "accepted" | "left-failed") => string;
@@ -99,38 +89,32 @@ export interface FinalFixResult {
     /** Human-readable outcome (converged gate reason, or why the attempt failed). */
     reason: string;
     /**
-     * The re-run gate's OUTCOME, whole — present whenever the gate actually ran
-     * (absent only when the fix child self-declared blocked and the re-run was
-     * skipped).
-     *
-     * This used to be four flattened `gate*` mirrors, and the flattening lost
-     * things. `openDebts` never crossed at all, so `runFinalGateStage` rebuilt
-     * `fin` as a literal three times and each literal dropped it — the recorded
-     * mx5 run-18 defect, fixed by RE-DERIVING the field (`reconcileDebts`) rather
-     * than by keeping the value. Then 19A had to push `observedFailures` across the
-     * same wall as a third parallel field and re-pair it downstream by
-     * `gateObservedFailures?.includes(detail)` — a membership test that exists only
-     * because the pairing was broken in transit.
+     * The re-run gate's OUTCOME, whole — present whenever the gate actually ran,
+     * absent only when the fix child self-declared BLOCKED and the re-run was
+     * skipped. The whole `FinalGateOutcome` crosses, not a hand-picked copy of
+     * some of its fields: a copy silently drops whatever it forgot, and the
+     * pairing between `failures` and `observedFailures` only holds inside it.
      */
     gate?: FinalGateOutcome;
     /** On a converged outcome: the UNOBSERVED note the CALLER should show. It is
      *  the gate's own note plus any downgrade this fix pass added (see the
      *  ignored-dependency probe below), so it is not simply `gate.unobserved`. */
     unobserved?: string;
-    /** Gitignored path(s) this fix pass wrote, exempt classes already removed (see
-     *  write-guard.ts). Present whether or not the gate converged — the caller
-     *  trails them either way; path names only, never contents. */
+    /** Gitignored path(s) this fix pass wrote, with the exempt classes already
+     *  removed (task dir, `.git`, node_modules, build output — write-guard.ts).
+     *  Present whether or not the gate converged; path names only, never
+     *  contents. */
     ignoredWrites?: string[];
     /** …and the mechanical dependency probe found the converged gate does NOT pass
      *  without them, so `unobserved` above carries the downgrade. Absent when the
-     *  probe could not answer (no probe wired, restore risk, too many paths). */
+     *  probe could not answer: no probe wired, a path that would not move, or more
+     *  paths than its bound allows. */
     ignoredDependent?: boolean;
     /** A write-guard rejected this attempt (deletion / shrink / probe-gaming). */
     guardTripped?: boolean;
-    /** …and its edits were discarded. When a guard tripped and this is false, the
-     *  working tree still holds REJECTED edits, so the caller must NOT commit what
-     *  it finds there (mx5 run 14 item 2b: commit surviving fix-pass edits — but
-     *  only guard-CLEAN ones; the cheat guard is never weakened to ease committing). */
+    /** …and its edits were discarded. False here with `guardTripped` true means
+     *  the tree still holds REJECTED edits, and the caller must not commit what it
+     *  finds: that is what `AutofixLedger.mayCommitTree()` latches off. */
     editsDiscarded?: boolean;
 }
 export interface FinalFixDeps {
@@ -143,34 +127,37 @@ export interface FinalFixDeps {
     runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
     /** Re-run the final integration gate — the only arbiter of convergence.
      *  Converges only when the gate's FULL aggregated failure list is empty
-     *  (ok=true); `failures` rides through so the caller sees every entry. */
-    /** Returns the gate's own outcome type, not a structural copy of five of its
-     *  fields — a re-declaration is how `openDebts` came to be silently absent. */
+     *  (ok=true); `failures` rides through so the caller sees every entry.
+     *  Typed as the gate's own outcome, not a structural copy of some fields. */
     gate: (cwd: string) => Promise<FinalGateOutcome>;
-    /** Labels of every currently-discoverable gate command (static + integration),
-     *  for the shrink guard. Pure discovery — nothing is executed. */
+    /** Labels of every currently-discoverable gate command — health, lockfile,
+     *  integration and boot — for the shrink guard. Pure discovery: nothing
+     *  runs. */
     discoverLabels: (cwd: string) => string[];
     /** The same commands' RESOLVED BODIES (`label → scripts[name]` / Makefile
      *  recipe), for the scope-shrink half of the guard. Absent → only the label
-     *  comparison runs, i.e. the pre-run-19 behaviour. */
+     *  comparison runs. */
     discoverBodies?: (cwd: string) => Record<string, string>;
     /** Discard the fix child's working-tree edits (guard trips only). Absent
      *  → the violation is still rejected, edits are left for inspection. */
     discard?: (cwd: string) => Promise<void>;
-    /** The fix child's tree changes (`git status --porcelain` shape) — diff capture
-     *  for the log and the deletion guard's input. The tree was clean before the
-     *  child ran (every task committed), so status IS the child's work. */
+    /** Tree changes in `git status --porcelain` shape — the deletion guard's input
+     *  and the "created by this fix" set the scope-shrink guard consults. Every
+     *  task is committed before this stage, so what status reports is fix-pass
+     *  work; on a second attempt that includes the first attempt's kept edits,
+     *  since a non-converged attempt is not discarded. */
     treeChanges?: () => Promise<TreeChangeSummary>;
     /** The union of every task spec's frozen (Do-NOT-modify) paths — the whole-run
      *  write-deny set, since this child works across all slices at once. */
     frozenPaths?: () => Promise<string[]>;
-    /** Restore the given frozen paths to HEAD; returns the files actually reverted
-     *  (same mechanical deny the enforce pass carries — see frozen-path-guard.ts). */
+    /** Restore the given frozen paths to HEAD; returns the files actually reverted.
+     *  `frozen-path-guard.ts`'s `revertFrozenPaths`, the same one the per-task
+     *  passes use. */
     revertFrozen?: (paths: string[]) => Promise<string[]>;
-    /** Deterministic probe scan over the child's ADDED lines (probe-gaming, F6):
-     *  a fix written to game a check rather than meet it rejects the attempt —
-     *  run 11's autofix replaced the typed client with a hand-written contract
-     *  copy to green the lint. Findings are verbatim offending lines. */
+    /** Deterministic probe scan over the child's ADDED lines: a fix whose own
+     *  added text says it is gaming a check rather than meeting it rejects the
+     *  attempt. There is no verify child downstream of this pass to judge such a
+     *  finding. Findings are the verbatim offending lines. */
     probeScan?: () => Promise<string[]>;
     /** Fingerprint of the ACTIONABLE ignored paths (build output and node_modules
      *  already exempt). Called before and after the child; the difference is what
@@ -189,9 +176,10 @@ export interface FinalFixDeps {
     log?: (msg: string) => void;
 }
 /**
- * Run one bounded final-gate fix attempt: snapshot discovery → child → write-guard
- * stack (diff capture → frozen-path revert → deletion guard → shrink guard → probe
- * scan) → gate re-run. Never throws for an outcome; only a user cancel inside
- * runChild propagates (the caller's USER_CANCELLED path handles it).
+ * Run one bounded final-gate fix attempt: snapshot discovery and ignored paths →
+ * child → frozen-path revert → deletion guard → shrink guard → scope-shrink
+ * guard → probe scan → gate re-run. Never throws for an outcome; only a user
+ * cancel inside runChild propagates, and the caller's USER_CANCELLED path
+ * handles that.
  */
 export declare function runFinalGateAutofix(deps: FinalFixDeps): Promise<FinalFixResult>;