@mjasnikovs/pi-task 0.38.11 → 0.38.13

package/dist/task/env-notes.js

@@ -32,9 +32,7 @@
  * exactly that scrutiny, and forbids treating a grep of a generated artifact as
  * evidence of absence. Provenance is mechanical; re-validation is prompt-level.
  */
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
-import { tasksDir } from './task-io.js';
+import { makeLedger } from './ledger.js';
 const ENV_NOTES_FILE = 'env-notes.md';
 /** Cap kept notes so a chatty run cannot grow the prompt block unboundedly. */
 const MAX_NOTES = 40;
@@ -46,18 +44,6 @@ const MAX_NOTE_LENGTH = 240;
  * stray tab in an emitted fact is normalised to a space before storage.
  */
 const ORIGIN_SEP = '\t';
-export function envNotesFile(cwd) {
-    return path.join(tasksDir(cwd), ENV_NOTES_FILE);
-}
-/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
-export async function readEnvNotes(cwd) {
-    try {
-        return (await fsp.readFile(envNotesFile(cwd), 'utf8')).trim();
-    }
-    catch {
-        return '';
-    }
-}
 /**
  * Parse the stored file into fact+origin records. Legacy lines written before
  * provenance (no separator) parse with an empty origin, so old caches still read.
@@ -79,6 +65,22 @@ export function parseEnvNotes(raw) {
 function serializeNote(n) {
     return n.origin ? `${n.fact}${ORIGIN_SEP}${n.origin}` : n.fact;
 }
+/** Keyed on the fact alone (case-insensitive): a fact already present keeps its
+ *  ORIGINAL origin — provenance traces to who first established it. */
+const ledger = makeLedger({
+    file: ENV_NOTES_FILE,
+    max: MAX_NOTES,
+    key: n => n.fact.toLowerCase(),
+    serialize: serializeNote,
+    parse: parseEnvNotes
+});
+export function envNotesFile(cwd) {
+    return ledger.path(cwd);
+}
+/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
+export async function readEnvNotes(cwd) {
+    return ledger.readRaw(cwd);
+}
 /**
  * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
  * length-capped; verdict markers can never match (different prefix).
@@ -134,27 +136,14 @@ export function isExcuseNote(fact) {
  * blocker.
  */
 export async function appendEnvNotes(cwd, notes, origin = '') {
-    if (notes.length === 0)
-        return;
-    try {
-        const existing = parseEnvNotes(await readEnvNotes(cwd));
-        const seen = new Set(existing.map(n => n.fact.toLowerCase()));
-        const merged = [...existing];
-        for (const note of notes) {
-            const fact = note.trim().replace(/\t/g, ' ');
-            const key = fact.toLowerCase();
-            if (key.length === 0 || seen.has(key))
-                continue;
-            seen.add(key);
-            merged.push({ fact, origin: origin.trim() });
-        }
-        const kept = merged.slice(-MAX_NOTES);
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(envNotesFile(cwd), kept.map(serializeNote).join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort cache
+    const fresh = [];
+    for (const note of notes) {
+        const fact = note.trim().replace(/\t/g, ' ');
+        if (fact.length === 0)
+            continue;
+        fresh.push({ fact, origin: origin.trim() });
     }
+    await ledger.append(cwd, fresh);
 }
 /**
  * The prompt block a gate child receives when notes exist. Two things are

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

@@ -38,7 +38,7 @@ export declare function classifyFinalGateAnswer(answer: string | undefined): Fin
  * Extract it for reporting; the shrink guard itself compares the FULL
  * discovered-command sets, so a reason this cannot parse still guards.
  */
-export declare function extractFailingCommand(reason: string): string | null;
+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

package/dist/task/final-gate-fix.js

@@ -90,7 +90,7 @@ export function classifyFinalGateAnswer(answer) {
  * Extract it for reporting; the shrink guard itself compares the FULL
  * discovered-command sets, so a reason this cannot parse still guards.
  */
-export function extractFailingCommand(reason) {
+export function exitedCommandFromReason(reason) {
     const m = /`([^`]+)`\s+exited\b/.exec(reason);
     return m ? m[1] : null;
 }

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

@@ -1,9 +1,10 @@
 import { type HealthCommand } from './repo-health-check.js';
-import { type AcceptDebt, type VerifyRerunResult } from './accept-debt.js';
+import { deriveOpenDebts, rerunDebtVerifyCommand, type AcceptDebt } from './accept-debt.js';
 import { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners, type BootDeps } from './boot-probe.js';
 import { type CommandRunner } from './command-run.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { type EnvClosure } from './env-template-closure.js';
+import { observabilityGapFailure, unobservedVerdict } from './gate-tally.js';
 export interface FinalGateOutcome {
     /** true → statics and every runnable integration command passed (or nothing to run). */
     ok: boolean;
@@ -129,159 +130,12 @@ export declare function discoverGateCommandLabels(cwd: string): string[];
  * guard already owns.
  */
 export declare function discoverGateCommandBodies(cwd: string): Record<string, string>;
-/**
- * How a re-run of ONE recorded VERIFY command line ended.
- *   pass — it ran and exited 0. The ONLY outcome that may close a debt.
- *   fail — it ran and exited non-zero for a real reason. Debt stays open.
- *   gap  — nothing was observed: the shell/runner never spawned, 127 inside the
- *          chain, a timeout, a missing browser, or absent external infrastructure.
- *          INCONCLUSIVE, so the debt stays open (surface, never re-hide).
- */
-export type VerifyRerunOutcome = {
-    outcome: 'pass';
-} | {
-    outcome: 'fail';
-    status: number;
-    tail: string;
-} | {
-    outcome: 'gap';
-    detail: string;
-};
-/**
- * Re-run one VERIFY-block command line (nexttask 5) 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
- * 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).
- *
- * 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
- * debt exactly as open as it was.
- */
-export declare function runVerifyCommandLine(cwd: string, line: string, timeoutMs: number, extraGapRe?: RegExp, 
-/** The spawner. Injected so a re-run's outcome can be tested without one. */
-run?: CommandRunner): VerifyRerunOutcome;
-/**
- * The full-skip blindness guard (mx5 run 16, validated): dynamic commands were
- * DISCOVERED but every single one skipped as an environment gap, so the gate
- * decided on statics alone and stamped a permanently blank app green. Per-command
- * env-gap skips stay legitimate (a missing browser must not fail a suite); what
- * may never happen again is ALL of them skipping while the gate still reports
- * PASS — a gate that observed nothing dynamic has no basis to vouch for the
- * assembled app. Pure so the semantics are unit-tested; the caller feeds it the
- * attempt/observation counters and runner resolvability.
- */
-export declare function observabilityGapFailure(args: {
-    /** Dynamic commands the gate discovered and tried to run. */
-    attempted: number;
-    /** Of those, how many it actually OBSERVED (a real pass OR a real fail —
-     *  either proves the command ran; only skips observe nothing). */
-    observed: number;
-    /** Of the skips, how many were SPAWN failures (runner never ran, ENOENT).
-     *  Tool-level gaps (missing browser, 127 inside the chain, timeout) prove
-     *  the runner itself works and keep the classic env-gap contract — the
-     *  blindness class fires only when EVERY attempt failed to even spawn. */
-    spawnFailures: number;
-    /** Distinct runner bins across the attempted commands. */
-    runnerBins: string[];
-    /** Is this runner spawnable (bare or via a known install location)? */
-    runnerResolvable: (bin: string) => boolean;
-}): string | null;
-/**
- * The THIRD verdict. observabilityGapFailure above covers "commands were DISCOVERED
- * but every one failed to spawn" — a rank-0 FAIL. It deliberately returns null for
- * `attempted === 0`, and until now that silence fell straight through to
- * `PASS — no integration command found (statics passed)`: the run-16 blindness class
- * entering through a different door, where "we never checked" reads exactly like "we
- * checked and it was fine". Measured 2026-07-27: IAR1 (C++/CMake, no package.json)
- * shipped that verdict TWICE while carrying 2 and 3 open verify-FAIL debts, and
- * godot-engine (package.json whose only script is `verify`) reproduces it live today.
- *
- * So: observed anything dynamic ⇒ PASS; discovered-but-all-spawn-failed ⇒ the
- * existing FAIL; observed NOTHING ⇒ this note, carried on an `ok: true` outcome.
- *
- * WHY NON-BLOCKING (decided, not deferred — the evidence cuts both ways and this is
- * the resolution):
- *  - Blocking's case: both real occurrences also carried open verify-FAIL debt, so
- *    the runs with no dynamic evidence were exactly the runs already known to be
- *    carrying defects.
- *  - Against, and decisive: (1) that debt is ALREADY surfaced unconditionally at the
- *    gate moment, on PASS as on FAIL — the IAR1 records literally read "PASS — no
- *    integration command found … UNRESOLVED VERIFY-FAIL DEBT still open (2)". The
- *    missing signal was never the debt, it was the word PASS endorsing the run, and
- *    that is what this fixes. (2) `ok: false` routes into the autofix picker, whose
- *    seed is `reason`; "no integration command is discoverable" is not fixable by
- *    editing code, so the highest-probability child response is to FABRICATE a
- *    runnable command to satisfy the gate — the same fabrication class that refuted
- *    the `## verified tooling` harvest (see discoverIntegrationCommands) and that had
- *    run 11's fix child `rm` a sibling's deliverable. (3) That harvest being refuted
- *    means IAR1 and godot-engine can NEVER discover a command, so blocking would end
- *    every non-npm run in `failed` permanently, with no remedy — the task's own I3
- *    ("show blocking does not block IAR1/godot post-Task-1") is unsatisfiable, and
- *    its stated consequence is to downgrade to a warning and say so. This is that.
- * The teeth are elsewhere and are real: the verdict word changes, the gate trail says
- * UNOBSERVED, and the caller records a durable final-gate debt that the NEXT run's
- * gate re-surfaces (it can never auto-close — it is not static-class).
- */
-export declare function unobservedVerdict(args: {
-    /** Dynamic commands the gate discovered and tried to run (0 ⇒ nothing existed). */
-    discovered: number;
-    /** Of those, how many actually RAN (a real pass or a real fail). */
-    observed: number;
-}): string | null;
+export { runVerifyCommandLine, type VerifyRerunOutcome } from './command-run.js';
+export { observabilityGapFailure, unobservedVerdict };
 export { taskThatIntroduced };
 export { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
 export type { BootDeps };
-/**
- * ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
- * the user accepted despite a verify-FAIL and re-check each against the CURRENT
- * tree. A static-class debt whose statics now pass is provably RESOLVED (a later
- * task fixed it) and pruned from the ledger; every other debt cannot be proven
- * resolved deterministically, so it stays OPEN and is surfaced — a run may not
- * complete silently carrying an accepted defect. FP-safe by construction (see
- * accept-debt.ts). Best-effort: a ledger read/write failure must never break the
- * caller.
- *
- * FACTORED OUT of runFinalIntegrationGate (nexttask 6): the derivation has to be
- * runnable at a SECOND moment — after a converged final-gate autofix, where the
- * orchestrator used to rebuild its gate outcome as a bare `{ok, reason}` and drop
- * `openDebts` entirely. The report a run ends on has to be derived from the tree
- * the run ends with, not from the tree as it was before the fix pass.
- *
- * `staticOk` is the caller's claim about the CURRENT statics, and it is the only
- * thing that can auto-close a static-class debt — so a caller that does not know
- * must pass `false` (unprovable ⇒ stays open), never a guess.
- */
-export declare function deriveOpenDebts(cwd: string, staticOk: boolean): Promise<{
-    openDebts: AcceptDebt[];
-    debtNote?: string;
-    trail?: string[];
-}>;
-/**
- * Re-run ONE debt's stored VERIFY command for the re-check, with the no-write guard
- * (`inv-no-write`) wrapped around it.
- *
- * A VERIFY command is the project's own command and may legitimately write (a build
- * emits `dist/`, a suite writes a snapshot). What it may NOT do is turn the tree into
- * a passing tree and have that count as the debt being fixed — the run would then be
- * certifying its own side effect. So tracked state is captured before and after, and
- * a pass that came with a tracked change is downgraded to INCONCLUSIVE with the
- * change named. Untracked output is left alone: it is what a build legitimately
- * produces, and `git status --porcelain` in a repo with the usual ignores does not
- * see it.
- *
- * A repository the guard cannot read (no git, git absent) is not a licence to skip
- * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
- * assumption rather than an observation.
- */
-export declare function rerunDebtVerifyCommand(cwd: string, command: string, 
-/** The spawner, for BOTH the command and the tracked-state reads. Injected so
- *  the guard's four outcomes are testable without a repo or a real command. */
-run?: CommandRunner): VerifyRerunResult;
+export { deriveOpenDebts, rerunDebtVerifyCommand };
 /**
  * Where in the gate a closure scan runs. The two stages are NOT interchangeable
  * and neither is a scheduling preference: