@mjasnikovs/pi-task 0.38.9 → 0.38.11

package/dist/task/child-runner.d.ts

@@ -112,6 +112,23 @@ interface PhaseDeps {
     /** Injectable delay for connection-error backoff; defaults to a real timer.
      *  Tests override it with a no-op so retries don't actually sleep. */
     sleepFor?: (ms: number) => Promise<void>;
+    /**
+     * Run ONE named Child pi and return its assistant text — the seam every phase
+     * child goes through. Absent (production) → the real wrappers run, with the
+     * loop detector, the wall-clock budget and the Error-triage ladder. Present →
+     * the substitute answers directly and NONE of those guards run.
+     *
+     * The child's NAME is the first parameter because the name is what a caller
+     * branches on and what a test wants to assert. It used to be discarded before
+     * reaching the only injectable boundary (`spawn`), so a phase test had to
+     * reconstruct it by matching prompt PROSE against prompts.ts — which made
+     * prompt copy load-bearing test infrastructure in a codebase whose practice is
+     * rewording prompts and A/B-ing them.
+     *
+     * `spawn` stays: the ladder's OWN tests must drive a real process to exercise
+     * the rungs. This seam is for callers to whom the child is a premise.
+     */
+    runChild?: (name: string, tools: string, prompt: string) => Promise<string>;
 }
 export type { PhaseDeps };
 /**

package/dist/task/child-runner.js

@@ -288,6 +288,8 @@ async function triageChildResult(deps, name, r, attempt, budget, verb) {
  * status describes our SIGTERM and says nothing about its verdict.
  */
 export async function runPhaseChild(deps, name, tools, prompt) {
+    if (deps.runChild)
+        return await deps.runChild(name, tools, prompt);
     let hint = null;
     const loopHistory = [];
     const budgetMs = deps.timeoutMs ?? PHASE_CHILD_TIMEOUT_MS;
@@ -366,6 +368,10 @@ async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
     await setTaskSection(cwd, taskId, 'loop events', next);
 }
 export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts = {}) {
+    // The substitute stands in for the whole guarded run, so it is handed the
+    // prompt the first strike would have used (no loop hint in flight yet).
+    if (deps.runChild)
+        return await deps.runChild(name, tools, buildPrompt(null));
     const loopHistory = [];
     // Carries the correction hint (loop OR leaked-tool-call) into the next strike.
     let nextHint = null;

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

@@ -1,9 +1,9 @@
 import { type HealthCommand } from './repo-health-check.js';
 import { type AcceptDebt, type VerifyRerunResult } from './accept-debt.js';
-import { type RenderOutcome } from './render-check.js';
-import { type DeepRenderOutcome } from './deep-render-check.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';
 export interface FinalGateOutcome {
     /** true → statics and every runnable integration command passed (or nothing to run). */
     ok: boolean;
@@ -106,236 +106,6 @@ export declare function discoverIntegrationCommands(cwd: string): {
 };
 /** Every lockfile consistency check that applies to this tree (possibly none). */
 export declare function discoverLockfileChecks(cwd: string): HealthCommand[];
-/**
- * Why this script is NOT a launch of the shipped app, or null when it plausibly
- * is one (mx5 run 18, validated).
- *
- * Run 18's boot command resolved to `bun run dev`, whose body is
- * `docker compose -f docker-compose.dev.yml up -d && until docker compose … pg_isready
- * … && concurrently "bun run dev:css" "bun run dev:js" "bun run --watch
- * src/server/index.ts"`. The gate sandbox has no docker, so the chain died at 127 and
- * the boot SKIPPED as an environment gap — while the shipped app had no HTTP listener
- * at all. A script whose first act is `docker compose up` cannot distinguish "the app
- * is broken" from "this box has no docker", so it is not evidence either way: better
- * to discover NO boot command — reported as "nothing to boot" — and let the static
- * serve-entry check (serve-entry.ts) carry the signal, than to spend the grace window
- * producing an unfalsifiable skip.
- *
- * CONSERVATIVE AND LEXICAL BY CONSTRUCTION. Only two shapes are rejected, both
- * decidable from the script text alone:
- *   1. the chain OPENS with container orchestration (docker/podman/nerdctl … up|start|run);
- *   2. the whole body is a multiplexer (concurrently/npm-run-all/run-p/run-s/turbo)
- *      whose every child is an ASSET watcher in watch mode (tailwind/tsc/esbuild/…),
- *      i.e. nothing in it can ever listen.
- * Anything else — `vite`, `next dev`, `node dist/index.js`, `nodemon`, `bun --watch
- * src/index.ts`, and any multiplexer with one non-asset child — is accepted
- * unchanged. Deciding whether a watcher actually SERVES is not attempted here; that
- * is exactly what the static serve-entry check is for.
- */
-export declare function nonLaunchScriptReason(body: string, scripts?: Record<string, string>): string | null;
-/**
- * The project's OWN launch command, if it declares one (package.json `start`,
- * else `dev`; Makefile `run`). null means the project has nothing to boot —
- * the boot check degrades to nothing-to-run.
- *
- * A script that is not a LAUNCH at all (nonLaunchScriptReason — mx5 run 18's
- * `docker compose up` orchestrator) is rejected here and falls through to the
- * next candidate, then to null. Discovering nothing is strictly better than
- * discovering something unfalsifiable: an env-gap skip of an orchestration script
- * says nothing about the app, and null is reported as "nothing to boot".
- */
-export declare function discoverBootCommand(cwd: string): HealthCommand | null;
-/**
- * The launch script that EXISTS but was rejected as not-a-launch, if any. Without
- * this the rejection would trade run 18's unfalsifiable skip for pure silence: no
- * boot command means bootSkipVerdict has no label to name, and a project whose test
- * suite ran still reports `observed > 0`, so unobservedVerdict stays quiet too. A
- * served app whose only declared launch script cannot start it was not observed to
- * run, and must say so.
- */
-export declare function rejectedLaunchScript(cwd: string): {
-    name: string;
-    reason: string;
-} | null;
-type BootOutcome = {
-    outcome: 'skip' | 'pass';
-    /** Set when the render check could not OBSERVE the served page (no browser,
-     *  undeterminable port) or its AUTHENTICATED half (no declared credentials,
-     *  an undrivable sign-in form, credentials the server rejected) — surfaced
-     *  by the gate as an UNOBSERVED warning. */
-    renderNote?: string;
-    /** skip only: the boot command never spawned (ENOENT) — feeds the
-     *  full-blindness guard (mx5 run 16), unlike a 127 where the runner ran. */
-    spawnFailed?: boolean;
-} | {
-    outcome: 'fail';
-    detail: string;
-} | {
-    outcome: 'orphan-port';
-    detail: string;
-    port: number | null;
-};
-/** Injectable environment probes for the boot check's orphan-port recovery, so the
- *  reap-and-retry path is deterministically testable without a real listener. */
-export interface BootDeps {
-    /** The pid + command line holding `port` in LISTEN, or null if none/unknown. */
-    findPortHolder?: (port: number) => {
-        pid: number;
-        command: string;
-    } | null;
-    /** Terminate a pid we attribute to ourselves; returns whether it was signalled. */
-    reap?: (pid: number) => boolean;
-    /**
-     * Does process group `pgid` currently own a LISTENing TCP socket? Drives the
-     * served-app boot check (mx5 run 10): a watcher (`dev` = tailwind/bundler
-     * --watch) stays alive forever without ever listening, so "still alive after the
-     * grace window = PASS" blessed a project that cannot serve a single request.
-     * Injected so the listener requirement is deterministically testable without a
-     * real socket; the default probes ss/lsof + pgid.
-     */
-    groupHasListener?: (pgid: number) => boolean;
-    /**
-     * The (lowest) TCP port a listener owned by process group `pgid` is bound to,
-     * or null when it cannot be determined. Feeds the render check's URL; injected
-     * for tests, default probes ss/lsof + pgid.
-     */
-    groupListeningPort?: (pgid: number) => number | null;
-    /**
-     * Load the served page once in a headless browser and judge the RENDERED DOM
-     * (mx5 runs 8/11: curl cannot execute JS, so a blank-mount app passed every
-     * gate). Runs only for a served app, against the live listener, before the
-     * boot child is killed. Absent → the boot check behaves exactly as before;
-     * the gate wires runRenderCheck by default for served apps.
-     */
-    renderProbe?: (url: string) => RenderOutcome;
-    /**
-     * SIGN IN on the served page and judge the AUTHENTICATED half of the app (mx5
-     * run 17). Runs only after `renderProbe` PASSED — the shallow blank-page rule
-     * keeps its own RED/GREEN-proven verdict and is never shadowed by this one.
-     * Absent → the boot check behaves exactly as before; the gate wires
-     * runDeepRenderCheck by default for served apps. May only FAIL when the SERVER
-     * itself authenticated the session (see deep-render-check.judgeDeepSession);
-     * anything else — no browser, no declared credentials, an undrivable form,
-     * rejected credentials — is an env gap and skips with an UNOBSERVED note.
-     */
-    deepRenderProbe?: (url: string) => DeepRenderOutcome | Promise<DeepRenderOutcome>;
-    /**
-     * Can this box enumerate listeners with pids AT ALL (ss/netstat/lsof)? False
-     * means the served-app requirement is UNOBSERVABLE here and must degrade to the
-     * survival rule rather than fail — see canEnumerateListeners.
-     */
-    enumerationCapable?: () => boolean;
-    /**
-     * Reserve a free port to hand the boot child as PORT, so an HTTP answer on it is
-     * ownership evidence. null → no port could be reserved (the check then relies on
-     * pgid attribution alone). Injected for tests.
-     */
-    pickPort?: () => Promise<number | null>;
-    /**
-     * The port the project's own client was BUILT to call, when it declares one and
-     * nothing is holding it — preferred over a freshly reserved port so the served
-     * origin and the origin the client calls are the same one (see pinnedLocalPort).
-     * null → use the reserved private port exactly as before.
-     */
-    preferredPort?: () => Promise<number | null>;
-    /** Does anything answer HTTP on 127.0.0.1:`port`? Injected for tests. */
-    httpProbe?: (port: number) => boolean;
-}
-/**
- * Does the finished run stand up a listening HTTP server? Deterministic, from the
- * built manifest (a server-framework dependency is the plan's own artifact) OR, when
- * available, the plan/spec text. Used to decide whether the boot check must observe a
- * LISTENER (served app) or may pass on mere survival / quick exit (CLI project).
- */
-export declare function detectsServedApp(cwd: string, planText?: string): boolean;
-/** `ss -tlnpH` rows → {pid, port}. Column 4 (0-based 3) is the local address; the
- *  port is its last `:`-suffixed number ("0.0.0.0:3000", "[::]:3000"). */
-export declare function parseSsListeners(stdout: string): Array<{
-    pid: number;
-    port: number;
-}>;
-/**
- * `netstat -tlnp` rows → {pid, port} (mx5 run 14, validated: the agent-sandbox
- * image ships NEITHER ss NOR lsof — only ps and netstat — so the served-app boot
- * check could never observe a listener and failed unfalsifiably). The pid rides
- * in the trailing "PID/Program name" column ("1234/bun"); rows the kernel will
- * not attribute to us print "-" there and are skipped.
- */
-export declare function parseNetstatListeners(stdout: string): Array<{
-    pid: number;
-    port: number;
-}>;
-/** `lsof -iTCP -sTCP:LISTEN -n -P` rows → {pid, port}. */
-export declare function parseLsofListeners(stdout: string): Array<{
-    pid: number;
-    port: number;
-}>;
-export declare function canEnumerateListeners(): boolean;
-/** Test seam: forget the memoised capability answer. */
-export declare function resetListenerToolCapability(): void;
-/**
- * A free TCP port on the loopback interface, or null if one cannot be reserved.
- * The boot check hands this to the child as PORT so that a successful HTTP
- * request to it is OWNERSHIP evidence: nobody else knows the number (mx5 runs
- * 8/10/11 — orphaned servers from earlier checks answered curl on the
- * conventional :3000 and passed checks the app had not earned).
- */
-export declare function pickFreePort(): Promise<number | null>;
-/** Can we bind 127.0.0.1:`port` right now? (Free ⇒ the boot child can have it.) */
-export declare function isPortFree(port: number): Promise<boolean>;
-/**
- * The project's own declared local port, but only if nothing is holding it — the
- * default `preferredPort` for the gate. A declared port that is BUSY falls back to
- * a reserved one rather than colliding: a stranger's server on :3000 must never be
- * mistaken for the app we just booted.
- */
-export declare function preferredDeclaredPort(cwd: string): Promise<number | null>;
-/**
- * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
- * command's own fate within the grace window decides:
- *
- *   - non-zero exit (or signal death) before the window closes → FAIL, output tail;
- *   - exit 0 before the window closes → PASS (a CLI-style "run" that finished);
- *   - still alive when the window closes → PASS, then the whole process group is
- *     killed (detached spawn = own group; SIGTERM, escalating to SIGKILL).
- *
- * For a SERVED app (`expectServer` true — the spec/plan promised an HTTP server) mere
- * survival is not enough: a watcher (`dev` = tailwind/bundler --watch) stays alive
- * forever without ever listening, and a type-only entrypoint exits 0 in <1s having
- * served nothing (mx5 run 10 — both were blessed by the survival rule). The boot then
- * PASSes only once a LISTENing socket owned by our process group is observed; if the
- * command exits, or the grace window closes, with no listener ever seen → FAIL naming
- * that a listening server was expected.
- *
- * OBSERVABILITY is a precondition of that FAIL (mx5 run 14, validated). The listener
- * requirement needs pgid-attributed socket enumeration; win32 has none, and neither
- * does a Linux image shipping no ss/netstat/lsof — run 14's sandbox was exactly that,
- * so the check emitted "never opened a listening socket" against an app that
- * demonstrably served, three autofix passes could not falsify it, and the run was
- * recorded failed. Two defences, in order:
- *
- *   - the child is spawned with a freshly reserved, otherwise-unused PORT, and an
- *     HTTP answer on THAT port proves a listener regardless of tooling. The private
- *     port is what makes the HTTP probe trustworthy: an orphaned server from an
- *     earlier check answers on :3000, but nobody else knows this number.
- *   - if nothing can enumerate listeners AND the assigned port never answered, the
- *     served-app requirement is unobservable here, so `expectServer` collapses to
- *     the survival rule and the PASS is stamped UNOBSERVED. An app that ignores PORT
- *     is indistinguishable from one that never listened — an observer limitation,
- *     not an app defect, and it may not be reported as one.
- *
- * A child that EXITS non-zero still FAILs in every environment: "the process died"
- * needs no socket probe, so run 14's original true positive (a `--hot` runtime
- * pinning a crashed app) stays reportable wherever the tooling exists.
- *
- * Env-gap contract as everywhere: spawn error (ENOENT) or a command-not-found
- * inside the chain (exit 127, or the runner's own wording where the platform
- * reports it that way — see isCommandNotFound) → skip.
- */
-export declare function runBootCheck(cwd: string, [bin, args]: HealthCommand, graceMs?: number, opts?: {
-    expectServer?: boolean;
-    deps?: BootDeps;
-}): Promise<BootOutcome>;
 /**
  * Labels (`bin args…`) of every command the gate CAN currently discover — the
  * static half (repo-health) plus the integration half. Pure discovery, nothing
@@ -463,55 +233,9 @@ export declare function unobservedVerdict(args: {
     /** Of those, how many actually RAN (a real pass or a real fail). */
     observed: number;
 }): string | null;
-/**
- * The SAME third verdict, at the door unobservedVerdict cannot reach: the boot
- * check specifically (mx5 run 18, validated).
- *
- * Run 18 shipped an app with no HTTP server behind a converged final gate. Its
- * `src/server/index.ts` ends at `export {app}` — no `Bun.serve`, no
- * `export default app`, no `start` script — so `bun run src/server/index.ts` exits
- * 0 immediately and the product cannot be started at all. The gate's boot command
- * resolved to `bun run dev`, whose body begins `docker compose … up -d`; the gate
- * sandbox had no docker, so the boot SKIPPED as an environment gap. Skips
- * contribute nothing to `dynObserved`, and `bun run test`, `test:ct`, `build`,
- * `lint`, `seed` and `migrate` all ran — so `dynObserved > 0`, the full-skip
- * blindness guard (observabilityGapFailure) stayed correctly quiet, and the trail
- * read `final-gate: autofix converged — statics + … passed` with 24/24 tasks green.
- *
- * The defect is that "the app was never observed to boot" and "the app booted
- * fine" produced BYTE-IDENTICAL gate output. That is the class scripts/ab-verdict.ts
- * exists to kill one layer up: absence of evidence rendered in the shape of
- * evidence. So a discovered-but-skipped boot now names itself, and — unlike every
- * other skip — it CANNOT be cancelled by observations from other commands.
- * Component tests are the trap here, not the alibi: run 18 had 51 green Playwright
- * CT tests, and CT mounts components in a browser without ever assembling or
- * starting the server.
- *
- * DECIDED, do not silently re-open:
- *  - NOT a FAIL. A boot skip on a docker-less box is a genuine environment gap, and
- *    failing it re-creates run 16's unfalsifiable-FAIL mistake pointing the other
- *    way. UNOBSERVED blocks nothing while being loud and durable (the caller records
- *    it as final-gate debt the next run re-surfaces), and it keeps "boot never ran"
- *    out of the autofix child's seed — a child cannot fix a missing docker, so the
- *    highest-probability response would be to FABRICATE a bootable command, the
- *    class that refuted the `## verified tooling` harvest.
- *  - BOTH skip flavours count. Run 18's skip carried `spawnFailed: false` (127 inside
- *    the script chain, not an ENOENT on the runner), so keying off spawnFailed would
- *    have missed the actual defect.
- *  - SERVED APPS ONLY. `expectServer === false` (a CLI/library project) is fenced off
- *    deliberately: a CLI whose `dev` script needs an absent tool has no server to be
- *    unobserved, and widening the lever there buys warnings nobody can act on.
- */
-export declare function bootSkipVerdict(args: {
-    /** `bin args…` of the DISCOVERED boot command; null ⇒ nothing to boot, which is
-     *  not the same thing as a boot that was not observed. */
-    label: string | null;
-    /** Did the boot check end in `skip` (either flavour)? */
-    skipped: boolean;
-    /** Does this project stand up an HTTP server (detectsServedApp)? */
-    expectServer: boolean;
-}): string | null;
 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
@@ -654,4 +378,32 @@ export type { ClosureScan, ClosureScanInput, ClosureScanStage };
  * it, and autofix converges only when the whole list is empty. Per-section
  * env-gap/INFRA_GAP skip semantics and orphan-port recovery are unchanged.
  */
-export declare function runFinalIntegrationGate(cwd: string, timeoutMs?: number, bootGraceMs?: number, bootDeps?: BootDeps, planText?: string): Promise<FinalGateOutcome>;
+/**
+ * Everything the run-end gate needs beyond the tree it is judging.
+ *
+ * An options object rather than a positional tail: the production call site read
+ * `runFinalIntegrationGate(cwd, undefined, undefined, undefined, planText)`, and
+ * `bootGraceMs`/`timeoutMs` are adjacent numbers that swap without a type error.
+ *
+ * `run`, `envClosure` and `trackedFiles` are SEAMS, by the same test GateDeps
+ * states: a scenario needs to substitute them. `runGateCommand`,
+ * `runVerifyCommandLine` and `rerunDebtVerifyCommand` each already take a
+ * `CommandRunner`; this is the fourth and last driver in the file, and without it
+ * the config-gap branch below is unreachable in test — not by oversight, but
+ * because reaching it needs a git-tracked env template, so every launch-contract
+ * test (bare `makeDir`, no `git init`) misses it by construction.
+ */
+export interface FinalGateOptions {
+    timeoutMs?: number;
+    bootGraceMs?: number;
+    bootDeps?: BootDeps;
+    planText?: string;
+    /** Spawner for the lockfile / integration / launch-script sections. Boot
+     *  spawns through `bootDeps`, which has its own probes. */
+    run?: CommandRunner;
+    /** The tracked env-template closure. Default reads git, degrading to inert. */
+    envClosure?: (cwd: string) => EnvClosure;
+    /** The repo's tracked file list, or null when it cannot be determined. */
+    trackedFiles?: (cwd: string) => string[] | null;
+}
+export declare function runFinalIntegrationGate(cwd: string, opts?: FinalGateOptions): Promise<FinalGateOutcome>;