@mjasnikovs/pi-task 0.38.14 → 0.38.16

package/dist/task/command-run.js

@@ -27,24 +27,156 @@
  * carried nine injectable probes for the gate's boot half while its command half
  * had none.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { isCommandNotFound, resolveRunner, runnerEnv } from './runner-resolve.js';
-/** The real runner. */
-export const spawnCommand = spec => {
-    const r = spawnSync(spec.bin, spec.args, {
+/**
+ * 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.
+ *
+ * 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.
+ */
+const OUTPUT_HEAD_CAP = 256 * 1024;
+const OUTPUT_TAIL_CAP = 768 * 1024;
+/** One stream, bounded, keeping its head and its tail with the middle elided. */
+class BoundedOutput {
+    head = '';
+    tail = '';
+    total = 0;
+    push(chunk) {
+        this.total += chunk.length;
+        let rest = chunk;
+        if (this.head.length < OUTPUT_HEAD_CAP) {
+            const room = OUTPUT_HEAD_CAP - this.head.length;
+            this.head += rest.slice(0, room);
+            rest = rest.slice(room);
+        }
+        if (rest.length === 0)
+            return;
+        this.tail = (this.tail + rest).slice(-OUTPUT_TAIL_CAP);
+    }
+    toString() {
+        const elided = this.total - this.head.length - this.tail.length;
+        return elided > 0 ?
+            `${this.head}\n…[${elided} characters elided]…\n${this.tail}`
+            : this.head + this.tail;
+    }
+}
+/**
+ * After the child EXITS, how long its pipes may still deliver buffered data
+ * before the run is reported. Not a wait for the pipes to CLOSE — that is the
+ * bug below — just the turn or two the reader needs to hand over what it has.
+ */
+const DRAIN_MS = 50;
+/**
+ * The real runner: one bounded child, output collected, never rejects.
+ *
+ * A kill — by the wall clock or by the caller's cancel — reads as `status: null`,
+ * which the gap ladder already treats as "nothing was observed".
+ *
+ * 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.
+ */
+export const spawnCommand = spec => new Promise(resolve => {
+    const out = new BoundedOutput();
+    const err = new BoundedOutput();
+    let settled = false;
+    let exitStatus = null;
+    let exited = false;
+    let endedStreams = 0;
+    let drain;
+    const child = spawn(spec.bin, spec.args, {
         cwd: spec.cwd,
-        encoding: 'utf8',
-        timeout: spec.timeoutMs,
+        // 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.
+        stdio: ['ignore', 'pipe', 'pipe'],
         ...(spec.env ? { env: spec.env } : {})
     });
-    return {
-        failedToStart: r.error !== undefined && r.error !== null,
-        ...(r.error ? { failureMessage: r.error.message } : {}),
-        status: r.status,
-        stdout: r.stdout ?? '',
-        stderr: r.stderr ?? ''
+    const done = (status, failure) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        clearTimeout(drain);
+        spec.signal?.removeEventListener('abort', killAndSettle);
+        resolve({
+            failedToStart: failure !== undefined,
+            ...(failure === undefined ? {} : { failureMessage: failure }),
+            status,
+            stdout: out.toString(),
+            stderr: err.toString()
+        });
+    };
+    const expectedStreams = (child.stdout ? 1 : 0) + (child.stderr ? 1 : 0);
+    const settleIfDrained = () => {
+        if (exited && endedStreams >= expectedStreams)
+            done(exitStatus);
+    };
+    const kill = () => {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    };
+    /**
+     * The deadline and the cancel both END the run. The kill only reaches the
+     * direct child, so this cannot wait to observe its effect — it kills, gives
+     * the pipes one drain, and reports `status: null` regardless.
+     */
+    const killAndSettle = () => {
+        kill();
+        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.
+    const timer = setTimeout(killAndSettle, spec.timeoutMs);
+    if (spec.signal) {
+        if (spec.signal.aborted)
+            killAndSettle();
+        else
+            spec.signal.addEventListener('abort', killAndSettle, { once: true });
+    }
+    child.stdout?.on('data', (d) => out.push(d.toString()));
+    child.stderr?.on('data', (d) => err.push(d.toString()));
+    child.stdout?.on('end', () => {
+        endedStreams++;
+        settleIfDrained();
+    });
+    child.stderr?.on('end', () => {
+        endedStreams++;
+        settleIfDrained();
+    });
+    child.on('error', (e) => done(null, e.message));
+    child.on('exit', (code) => {
+        exited = true;
+        exitStatus = code;
+        // Both ends of the same question: settle now if the pipes are already
+        // at EOF, otherwise settle after one short drain rather than waiting on
+        // whoever else is holding them.
+        settleIfDrained();
+        if (!settled) {
+            clearTimeout(drain);
+            drain = setTimeout(() => done(exitStatus), DRAIN_MS);
+        }
+    });
+});
 /**
  * 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
@@ -116,14 +248,17 @@ export function outputTail(stdout, stderr, limit = 400) {
  * `gapPatterns` are the EXTRA output shapes this particular command may treat as
  * an environment gap (see INFRA_GAP_OUTPUT_RE). Empty for an ordinary check.
  */
-export function classifyCommandRun(run, gapPatterns = []) {
+export function classifyCommandRun(run, gapPatterns = [], opts = {}) {
     // A clean exit is a pass before any gap shape is consulted: gap patterns
     // describe output, and passing output can legitimately mention a database or
     // a browser.
     if (!run.failedToStart && run.status === 0)
         return { outcome: 'pass' };
     const output = `${run.stdout}\n${run.stderr}`;
+    const runtimeGap = opts.runtimeGap ?? true;
     for (const rule of GAP_RULES) {
+        if (rule.id === 'missing-runtime' && !runtimeGap)
+            continue;
         if (rule.applies(run, output, gapPatterns)) {
             return { outcome: 'gap', gap: rule.id, detail: rule.detail(run) };
         }
@@ -160,19 +295,20 @@ function leadingBin(line) {
  * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
  * debt exactly as open as it was.
  */
-export function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe, 
+export async function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe, 
 /** The spawner. Injected so a re-run's outcome can be tested without one. */
-run = spawnCommand) {
+run = spawnCommand, signal) {
     const bin = leadingBin(line);
     const runner = bin === null ? null : resolveRunner(bin);
     // A VERIFY line is a SHELL line, not an argv — env prefixes, `&&` and
     // redirects are all ordinary there — so the runner spawns `sh -c`.
-    const verdict = classifyCommandRun(run({
+    const verdict = classifyCommandRun(await run({
         cwd,
         bin: 'sh',
         args: ['-c', line],
         timeoutMs,
-        env: runner ? runnerEnv(runner) : { ...process.env }
+        env: runner ? runnerEnv(runner) : { ...process.env },
+        ...(signal === undefined ? {} : { signal })
     }), 
     // Infrastructure counts as a gap on EVERY debt re-run, not only on
     // request: an unreachable database cannot tell us whether the code is

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

@@ -19,12 +19,16 @@
  * {@link ExternalContextLookups} — an adapter, expressible only since the
  * focused-extractor seam landed.
  */
-import { docsRaw } from '../workers/docs-core.js';
-import { fetchRaw } from '../workers/fetch-core.js';
-import { npmVersionLookup, type NpmVersionInfo } from '../workers/npm-version.js';
+import { type NpmVersionInfo } from '../workers/npm-version.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
 import type { PhaseDeps } from './child-runner.js';
-type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep'>;
+/**
+ * What assembling the block needs off the phase's deps: where it runs, when to
+ * stop, where to trail a sub-step — and, for the research binding, the four
+ * lookup seams. They are fields on `PhaseDeps` (not a second bag) because the
+ * bag was a trailing parameter no production caller could reach.
+ */
+type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep' | 'docsRaw' | 'fetchRaw' | 'npmVersionLookup' | 'searchFn'>;
 /** What a target lookup contributes to the block. */
 export interface ExternalTargetResult {
     /** Emitted as an `### npm:` block ahead of every body. Absent for url targets. */
@@ -89,13 +93,6 @@ export interface ExternalContextPolicy {
  * is nothing to enrich (no targets, or every lookup failed).
  */
 export declare function buildExternalContext(source: string, deps: GatherDeps, lookups: ExternalContextLookups, policy?: ExternalContextPolicy): Promise<string>;
-/** Injectable workers so enrichment is testable without spawning real lookups. */
-export interface ExternalContextDeps {
-    docsRaw?: typeof docsRaw;
-    fetchRaw?: typeof fetchRaw;
-    searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
-    npmVersionLookup?: typeof npmVersionLookup;
-}
 /**
  * The RESEARCH-phase binding: raw workers, no caps, live versions for every
  * named dep, truncated bodies, timed, and short-circuited when there is nothing
@@ -103,5 +100,5 @@ export interface ExternalContextDeps {
  *
  * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''`.
  */
-export declare function gatherExternalContext(refined: string, deps: GatherDeps, researchDeps?: ExternalContextDeps): Promise<string>;
+export declare function gatherExternalContext(refined: string, deps: GatherDeps): Promise<string>;
 export {};

package/dist/task/external-context.js

@@ -108,10 +108,10 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
  *
  * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''`.
  */
-export async function gatherExternalContext(refined, deps, researchDeps = {}) {
-    const docsRawFn = researchDeps.docsRaw ?? docsRaw;
-    const fetchRawFn = researchDeps.fetchRaw ?? fetchRaw;
-    const npmVersionFn = researchDeps.npmVersionLookup ?? npmVersionLookup;
+export async function gatherExternalContext(refined, deps) {
+    const docsRawFn = deps.docsRaw ?? docsRaw;
+    const fetchRawFn = deps.fetchRaw ?? fetchRaw;
+    const npmVersionFn = deps.npmVersionLookup ?? npmVersionLookup;
     const docsQuery = refined.split('\n').find(l => l.trim()) ?? refined;
     return buildExternalContext(refined, deps, {
         docs: async (pkg) => {
@@ -135,7 +135,7 @@ export async function gatherExternalContext(refined, deps, researchDeps = {}) {
             const r = await fetchRawFn({ url, signal: deps.signal });
             return { body: r.markdown.slice(0, RAW_BODY_LIMIT) };
         },
-        search: researchDeps.searchFn
+        search: deps.searchFn
     }, {
         versionLookup: pkg => npmVersionFn(pkg, { signal: deps.signal }),
         subStepLabel: 'enrichment',

package/dist/task/failure-classifier.d.ts

@@ -12,4 +12,12 @@ export interface FailureClass {
     level: NotifyLevel;
 }
 export declare function classifyFailure(err: unknown, aborted: boolean): FailureClass;
-export declare function handleFailure(err: unknown, ctx: ExtensionCommandContext, cwd: string, id: string, aborted: boolean): Promise<void>;
+/**
+ * Persist, flash and announce a failure — and RETURN the classification.
+ *
+ * It used to return `void`, so the name it had just computed died here and the
+ * caller learned how the run ended by re-reading the task file's front matter and
+ * narrowing it to a boolean. Handing the value back is what lets `TaskRunner.run`
+ * say `RunEnd` instead.
+ */
+export declare function handleFailure(err: unknown, ctx: ExtensionCommandContext, cwd: string, id: string, aborted: boolean): Promise<FailureClass>;

package/dist/task/failure-classifier.js

@@ -74,6 +74,14 @@ export function classifyFailure(err, aborted) {
         level: 'error'
     };
 }
+/**
+ * Persist, flash and announce a failure — and RETURN the classification.
+ *
+ * It used to return `void`, so the name it had just computed died here and the
+ * caller learned how the run ended by re-reading the task file's front matter and
+ * narrowing it to a boolean. Handing the value back is what lets `TaskRunner.run`
+ * say `RunEnd` instead.
+ */
 export async function handleFailure(err, ctx, cwd, id, aborted) {
     const c = classifyFailure(err, aborted);
     await updateTaskFrontMatter(cwd, id, { state: c.state, reason: c.reason });
@@ -82,4 +90,5 @@ export async function handleFailure(err, ctx, cwd, id, aborted) {
     // Mirror to remote viewers — ctx.ui.notify is terminal-only, so without this
     // the remote view shows nothing when a task fails.
     publishLifecycleNotice(`${id} ${c.notify}`, c.level);
+    return c;
 }

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

@@ -1,3 +1,4 @@
+import type { FinalGateOutcome } from './final-gate.js';
 import { type TreeChangeSummary, type IgnoredSnapshot } from './write-guard.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
  *  failing command (and the project's own tooling), not to mutate git state. */
@@ -97,22 +98,24 @@ export interface FinalFixResult {
     ok: boolean;
     /** Human-readable outcome (converged gate reason, or why the attempt failed). */
     reason: string;
-    /** On a did-not-converge outcome: the FRESH gate failure, so the caller's next
-     *  picker (and next fix attempt) works from the current state, not the stale one. */
-    gateReason?: string;
-    /** The fresh gate's individual ranked failures (see FinalGateOutcome.failures),
-     *  so the caller can trail each entry — never just the first. */
-    gateFailures?: string[];
-    /** …and which of them a PROBE returned after OBSERVING (see
-     *  FinalGateOutcome.observedFailures). Carried so the caller's non-progress
-     *  classifier can ask the probe's own verdict instead of guessing from the
-     *  failure text — a check that was observed to FAIL is never demote-eligible
-     *  (nexttask 19A). */
-    gateObservedFailures?: string[];
-    /** On a converged outcome: the re-run gate's UNOBSERVED note, if it observed
-     *  nothing dynamic (see FinalGateOutcome.unobserved). Carried so the caller
-     *  labels a converge-on-statics-alone the same way it labels a first-pass one —
-     *  "converged" must never quietly mean "we stopped being able to check". */
+    /**
+     * 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.
+     */
+    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
@@ -141,16 +144,9 @@ export interface FinalFixDeps {
     /** 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. */
-    gate: (cwd: string) => Promise<{
-        ok: boolean;
-        reason: string;
-        failures?: string[];
-        /** Which of them a probe returned after OBSERVING (nexttask 19A) — carried
-         *  through so the caller's demote decision can ask the probe's own verdict
-         *  instead of re-deriving observability from the failure string. */
-        observedFailures?: string[];
-        unobserved?: string;
-    }>;
+    /** 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. */
+    gate: (cwd: string) => Promise<FinalGateOutcome>;
     /** Labels of every currently-discoverable gate command (static + integration),
      *  for the shrink guard. Pure discovery — nothing is executed. */
     discoverLabels: (cwd: string) => string[];

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

@@ -334,13 +334,7 @@ export async function runFinalGateAutofix(deps) {
     }
     const fin = await deps.gate(deps.cwd);
     if (!fin.ok) {
-        return withIgnored({
-            ok: false,
-            reason: `did not converge: ${fin.reason}`,
-            gateReason: fin.reason,
-            gateFailures: fin.failures,
-            ...(fin.observedFailures ? { gateObservedFailures: fin.observedFailures } : {})
-        });
+        return withIgnored({ ok: false, reason: `did not converge: ${fin.reason}`, gate: fin });
     }
     // IGNORED-DEPENDENCY DOWNGRADE (mx5 run 19). The gate says PASS; the question
     // this answers is whether that PASS belongs to the REPOSITORY or only to this
@@ -368,6 +362,7 @@ export async function runFinalGateAutofix(deps) {
     return withIgnored({
         ok: true,
         reason: fin.reason,
+        gate: fin,
         ...(notes.length > 0 ? { unobserved: notes.join(' ') } : {}),
         ...(ignoredDependent !== undefined ? { ignoredDependent } : {})
     });

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

@@ -1,6 +1,6 @@
 import { type HealthCommand } from './repo-health-check.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 { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, 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';
@@ -133,8 +133,9 @@ export declare function discoverGateCommandBodies(cwd: string): Record<string, s
 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 { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
 export type { BootDeps };
+export type { BootSectionVerdict } from './boot-probe.js';
 export { deriveOpenDebts, rerunDebtVerifyCommand };
 /**
  * Where in the gate a closure scan runs. The two stages are NOT interchangeable
@@ -259,5 +260,12 @@ export interface FinalGateOptions {
     envClosure?: (cwd: string) => EnvClosure;
     /** The repo's tracked file list, or null when it cannot be determined. */
     trackedFiles?: (cwd: string) => string[] | null;
+    /**
+     * The run's cancel. Reaches every command the gate spawns — repo-health, the
+     * lockfile/integration/launch sections and the ACCEPT-debt re-runs. Nothing
+     * could be cancelled while `CommandRunner` was synchronous: the event loop
+     * never got a turn in which to notice.
+     */
+    signal?: AbortSignal;
 }
 export declare function runFinalIntegrationGate(cwd: string, opts?: FinalGateOptions): Promise<FinalGateOutcome>;