@mjasnikovs/pi-task 0.24.0 → 0.24.2

package/dist/shared/child-process.d.ts

@@ -165,6 +165,16 @@ export declare class JsonEventSink {
      * model/provider failed (disconnect, fetch failed, socket hang up, 5xx)
      * after pi exhausted its internal retries. Holds the provider's errorMessage
      * so callers can report the real cause instead of an empty completion.
+     *
+     * CLEARED when a LATER agent_end delivers assistant text: pi retries a failed
+     * turn itself (`auto_retry_start`) and each attempt emits its own agent_end,
+     * so a recovered blip arrives as agent_end(stopReason "error", empty) followed
+     * by agent_end(text). Measured live against a proxy that drops the first
+     * connection: pi makes up to 4 attempts over ~15s, and on attempts 1–3 the
+     * child returns the real answer WITH the dead first attempt's errorMessage
+     * still in the stream. Latching that would report a failure for a run that
+     * succeeded. An error AFTER the last text-bearing turn still latches — that
+     * one really did lose the tail of the work.
      */
     modelError: string | undefined;
     private textDeltaAccum;

package/dist/shared/child-process.js

@@ -30,6 +30,16 @@ export class JsonEventSink {
      * model/provider failed (disconnect, fetch failed, socket hang up, 5xx)
      * after pi exhausted its internal retries. Holds the provider's errorMessage
      * so callers can report the real cause instead of an empty completion.
+     *
+     * CLEARED when a LATER agent_end delivers assistant text: pi retries a failed
+     * turn itself (`auto_retry_start`) and each attempt emits its own agent_end,
+     * so a recovered blip arrives as agent_end(stopReason "error", empty) followed
+     * by agent_end(text). Measured live against a proxy that drops the first
+     * connection: pi makes up to 4 attempts over ~15s, and on attempts 1–3 the
+     * child returns the real answer WITH the dead first attempt's errorMessage
+     * still in the stream. Latching that would report a failure for a run that
+     * succeeded. An error AFTER the last text-bearing turn still latches — that
+     * one really did lose the tail of the work.
      */
     modelError = undefined;
     textDeltaAccum = '';
@@ -103,6 +113,10 @@ export class JsonEventSink {
             return;
         }
         if (t === 'agent_end' && Array.isArray(evt.messages)) {
+            // Errors latched by THIS batch describe a turn that failed AFTER the
+            // text found below it (the scan runs backwards), so they survive; only
+            // an error from an earlier agent_end is cleared by a later answer.
+            let latchedHere = false;
             for (let i = evt.messages.length - 1; i >= 0; i--) {
                 const m = evt.messages[i];
                 if (!m || m.role !== 'assistant')
@@ -117,6 +131,7 @@ export class JsonEventSink {
                     && m.errorMessage.length > 0
                     && this.modelError === undefined) {
                     this.modelError = m.errorMessage;
+                    latchedHere = true;
                 }
                 if (Array.isArray(m.content)) {
                     const texts = [];
@@ -127,6 +142,10 @@ export class JsonEventSink {
                     }
                     if (texts.length > 0) {
                         this.finalText = texts.join('');
+                        // This turn answered, so an error latched by an EARLIER
+                        // agent_end was a blip pi retried past — drop it.
+                        if (!latchedHere)
+                            this.modelError = undefined;
                         break;
                     }
                 }

package/dist/task/phases.d.ts

@@ -108,6 +108,21 @@ export declare function scopedToolingGoal(refined: string): string;
  * partial text, so an empty degrade is never mistaken for a real finding.
  */
 export declare function degradedSectionBody(name: string, reason: string, partial: string): string;
+/**
+ * The body written for a research section the worker confirmed has no entries.
+ *
+ * Three states have to stay distinguishable to anyone — human or later phase —
+ * reading a research section, so each carries its own marker:
+ *   `(none — …)`     the worker RAN and answered "nothing applies" (this)
+ *   `(degraded: …)`  the worker was killed mid-answer, text may be partial
+ *                    (degradedSectionBody)
+ *   section absent   the worker never got that far — the phase threw
+ *
+ * Naming the worker inside the marker keeps it true after assembly, where the
+ * section headings are all that separate the four workers' output.
+ */
+export declare function emptySectionBody(name: string): string;
+export declare function isBareNoneAnswer(text: string): boolean;
 export declare function phaseResearch(deps: PhaseDeps, refined: string, researchDeps?: PhaseResearchDeps): Promise<string>;
 export interface PhaseAutoAnswerDeps {
     docsFocused?: typeof docsFocused;

package/dist/task/phases.js

@@ -55,6 +55,12 @@ export function extractToolingCommands(research) {
         const line = raw.trim();
         if (!line)
             continue;
+        // A section MARKER describes the worker, not a command. Without this the
+        // "(none — the TOOLING worker ran …)" / "(degraded: …)" line is handed to the
+        // verify child as a command to run, which can only be rejected — noise in the
+        // prompt and one more thing that reads like a real tool in the task file.
+        if (/^\((?:none —|degraded:)/.test(line))
+            continue;
         const match = line.match(/^\S.*?\s{2,}(.+)$/);
         if (match) {
             commands.push(match[1].trim());
@@ -300,11 +306,27 @@ export function scopedToolingGoal(refined) {
  *     (exit 143) OR a clean exit 0 with truncated text, so loopHit/timedOut — not
  *     exitCode — are the reliable signal and are checked first.
  *
- *   - 'fatal' (non-zero exit that isn't a loop-kill, empty output, or a leaked
- *     never-executed tool call): the output is untrustworthy in a way partial text
- *     can't paper over (broken env, model disconnect, wrong tool-call dialect).
- *     These still throw — degrading them would launder a real breakage into a
- *     plausible-looking section. Returns null when the result is trustworthy.
+ *   - 'fatal' (non-zero exit that isn't a loop-kill, a provider error behind an
+ *     empty answer, or a leaked never-executed tool call): the output is
+ *     untrustworthy in a way partial text can't paper over (broken env, model
+ *     disconnect, wrong tool-call dialect). These still throw — degrading them
+ *     would launder a real breakage into a plausible-looking section.
+ *
+ *   - 'empty' (clean exit 0, no provider error, no loop/timeout — the model simply
+ *     wrote nothing): NOT a failure. On an extremely simple task ("create a folder
+ *     with an index.html in it") three of the four workers have genuinely nothing
+ *     to report, and each worker prompt tells the model to emit ONLY what this task
+ *     touches and to drop everything else — so silence is the CORRECT answer and
+ *     was killing the whole task at research (issue #10). Measured live on the
+ *     issue's own prompt (30 reps/worker, local Qwen3.6-27B): every APIS answer was
+ *     semantically "there is nothing here", and 2/30 were literally zero bytes on a
+ *     clean exit — the other 28 survived only because the model happened to wrap the
+ *     same non-answer in a parenthetical, which is model style, not signal. The
+ *     caller retries once and then accepts an explicit empty section; what stays
+ *     fatal is silence WITH a reported cause, which is the masked-disconnect case
+ *     this branch was written for and which `modelError` now names outright.
+ *
+ * Returns null when the result is trustworthy.
  */
 function classifyResearchWorker(name, result) {
     if (result.loopHit) {
@@ -326,7 +348,33 @@ function classifyResearchWorker(name, result) {
         };
     }
     if (result.text.trim().length === 0) {
-        return { kind: 'fatal', error: new Error(`Research ${name} worker produced no output`) };
+        // NOTHING CAME BACK — two different events wear the same face, and the whole
+        // point of this branch is to tell them apart:
+        //
+        //   FAILED, cause reported: pi delivers a failed turn as an empty assistant
+        //     message with stopReason "error" and exit 0, so the real cause used to be
+        //     discarded and reported as the useless "produced no output". Name it.
+        //   FAILED, child never spoke: no stdout at all means the child died before it
+        //     could run (unresolvable provider, missing key, bad argv) — it never
+        //     answered, so it cannot have answered "nothing".
+        //   EMPTY: a child that streamed, exited 0, reported no error, and wrote no
+        //     answer. The worker ran and the model had nothing to say — a real answer
+        //     on a task that touches nothing, not a failure.
+        if (result.modelError) {
+            return {
+                kind: 'fatal',
+                error: new Error(`Research ${name} worker: model error — ${result.modelError.slice(0, 200)}`)
+            };
+        }
+        if (!result.sawOutput) {
+            return {
+                kind: 'fatal',
+                error: new Error(`Research ${name} worker produced no output — the child never wrote a `
+                    + 'single byte, so it died before it could answer'
+                    + (result.stderr ? `: ${result.stderr.slice(-300)}` : ''))
+            };
+        }
+        return { kind: 'empty' };
     }
     if (result.leakedToolCall) {
         return {
@@ -365,6 +413,67 @@ async function manifestDependencyNames(cwd) {
         return [];
     }
 }
+/**
+ * The body written for a research section the worker confirmed has no entries.
+ *
+ * Three states have to stay distinguishable to anyone — human or later phase —
+ * reading a research section, so each carries its own marker:
+ *   `(none — …)`     the worker RAN and answered "nothing applies" (this)
+ *   `(degraded: …)`  the worker was killed mid-answer, text may be partial
+ *                    (degradedSectionBody)
+ *   section absent   the worker never got that far — the phase threw
+ *
+ * Naming the worker inside the marker keeps it true after assembly, where the
+ * section headings are all that separate the four workers' output.
+ */
+export function emptySectionBody(name) {
+    return `(none — the ${name} worker ran and reported no entries for this task)`;
+}
+/**
+ * A worker answer that IS the word "nothing" and carries no other content:
+ * `(none)`, `N/A`, `- none`, `(no content)`, `(no entries)`. Live workers write
+ * these often on a task that touches nothing (measured on the issue's prompt:
+ * `(no content)`, `(no response)`, a bare `(none)` from the gate's own retry),
+ * and each one means exactly what an empty answer means — so they are recorded
+ * with the same marker rather than passed through in whatever shape the model
+ * happened to pick. Deliberately NARROW: it matches only a lone token, never
+ * prose like "(no APIs to list — this task creates a plain HTML file …)", which
+ * carries a reason worth keeping.
+ */
+const BARE_NONE_ANSWER = /^[-*\s]*\(?\s*(?:none|n\/?a|nothing|no (?:content|entries|response|items|results))\s*\.?\s*\)?\s*$/i;
+export function isBareNoneAnswer(text) {
+    return BARE_NONE_ANSWER.test(text.trim());
+}
+/**
+ * Prepended on the ONE retry the empty-section gate triggers. A zero-byte answer is
+ * ambiguous — a crashed worker looks exactly like a worker with nothing to say — so
+ * the retry's only job is to remove the ambiguity: answer properly, or say "(none)"
+ * in as many words.
+ *
+ * It must NOT turn into an invitation to skip the work: `(none)` is offered only
+ * behind an explicit "after you have looked" condition, because this retry also
+ * fires on a normal project where the first attempt died for an unrelated reason,
+ * and an easy opt-out there would silence real research.
+ *
+ * MEASUREMENT OPEN. The recovery path's QUALITY on a real repo is being measured
+ * (scripts live under /home/edgars/tmp/issue10: first FILES answer faulted to
+ * empty, every other child live, against an uninterrupted control). First rep on
+ * an earlier wording did NOT take the `(none)` exit but drifted into writing code
+ * instead of listing paths — the deliverable-not-inputs failure the base prompt
+ * already forbids below this preamble. Blast radius is bounded: the gate fires
+ * only on a run that would otherwise have FAILED outright, so a mediocre recovered
+ * section is strictly better than the dead task it replaces — but if the drift
+ * reproduces, this preamble must restate the section's output contract, not just
+ * demand an answer.
+ */
+const EMPTY_SECTION_PREAMBLE = 'STOP. Your previous attempt returned an EMPTY answer — zero characters. An empty '
+    + 'response cannot be accepted, because it is indistinguishable from a worker that '
+    + 'crashed before it wrote anything. Answer again now, and do the research properly '
+    + 'this time: look first, then write what you found, in the required format. Only if '
+    + 'you have looked and there is genuinely nothing to report — the task touches no '
+    + 'existing file, needs no external symbol, or the project has no such tooling — write '
+    + 'exactly `(none)` and nothing else. Do not answer `(none)` to avoid the work, and '
+    + 'never answer with silence.';
 /**
  * Prepended to worker:apis's prompt on the ONE retry the zero-retrieval gate triggers. It
  * names the exact failure (a section written with no retrieval) so the correction is concrete,
@@ -638,6 +747,35 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             }
         }));
         let r = await runOnce();
+        // EMPTY-SECTION GATE (issue #10). A worker that returns zero bytes on a clean run
+        // used to fail the whole task ("Research APIS worker produced no output"), which is
+        // exactly what an extremely simple task provokes: with nothing on disk to survey and
+        // no external symbol in play, silence is the correct answer and the run died on it.
+        // Retry ONCE — silence is genuinely ambiguous, and a worker that crashed before
+        // writing deserves a second attempt — then accept an explicitly empty section. A
+        // provider error behind the silence is classified fatal below and never reaches here.
+        let confirmedEmpty = false;
+        if (classifyResearchWorker(spec.section, r)?.kind === 'empty') {
+            deps.logDebug?.(`${spec.label}: EMPTY answer on a clean exit — retrying once before`
+                + ' accepting the section as having no entries');
+            deps.onChildOutput?.(`${spec.label}: empty — retrying`);
+            const retry = await runOnce(EMPTY_SECTION_PREAMBLE);
+            if (retry.text.trim().length > 0) {
+                deps.logDebug?.(`${spec.label}: retry answered (len=${retry.text.trim().length})`
+                    + ' — replacing the empty section');
+                r = retry;
+            }
+            else {
+                confirmedEmpty = classifyResearchWorker(spec.section, retry)?.kind === 'empty';
+                deps.logDebug?.(`${spec.label}: retry STILL empty — `
+                    + (confirmedEmpty ?
+                        'the worker ran twice and reported no entries; recording the'
+                            + ' section as empty (NOT a failure)'
+                        : 'and this attempt did not run cleanly — failing the phase'));
+                if (!confirmedEmpty)
+                    r = retry;
+            }
+        }
         // ZERO-RETRIEVAL GATE — a deterministic handle, not another instruction. A non-empty
         // section produced with no grounding-retrieval call was written from memory; retry ONCE
         // with a forced retrieval-first pass and keep the retry only if it actually retrieved.
@@ -675,7 +813,10 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
                 degradedSectionBody(spec.section, f.reason, res.text)
                 : res.text.trim();
         };
-        if (spec.retryIfSilent) {
+        // `confirmedEmpty` already spent a retry on exactly this ("you wrote nothing"), and
+        // the worker answered "nothing applies" a second time — re-asking here would just
+        // burn a third child for the same answer.
+        if (spec.retryIfSilent && !confirmedEmpty) {
             const body = silentBodyOf(r);
             const verdict = body === null ? null : classifyContextSilence(body);
             if (verdict?.silent && verdict.genuineLoss) {
@@ -703,12 +844,20 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         const failure = classifyResearchWorker(spec.section, r);
         if (failure?.kind === 'fatal')
             throw failure.error;
-        const rawText = failure?.kind === 'runaway' ?
-            degradedSectionBody(spec.section, failure.reason, r.text)
-            : r.text.trim();
+        // A worker that answers "nothing applies" is recorded the same way whether it
+        // said so with zero bytes (confirmedEmpty) or with a bare "(none)"/"N/A" — the
+        // two are the same answer, and only the marker makes either one distinguishable
+        // from a worker that never answered at all.
+        const rawText = failure?.kind === 'runaway' ? degradedSectionBody(spec.section, failure.reason, r.text)
+            : confirmedEmpty || isBareNoneAnswer(r.text) ? emptySectionBody(spec.section)
+                : r.text.trim();
         if (failure?.kind === 'runaway') {
             deps.logDebug?.(`${spec.label}: degraded — ${failure.reason}`);
         }
+        if (!confirmedEmpty && isBareNoneAnswer(r.text)) {
+            deps.logDebug?.(`${spec.label}: answered "${r.text.trim().slice(0, 40)}" — recording it as`
+                + ' an empty section (the worker ran and found nothing)');
+        }
         // Post-check the worker's own output before it is persisted, so the cache a
         // resume reads back is already gated. A degraded partial goes through it too —
         // a truncated section can still carry a laundered claim.

package/dist/workers/pi-worker-core.d.ts

@@ -86,12 +86,46 @@ export interface RunWorkerInput {
      * 0 / omitted = off.
      */
     streamInactivityMs?: number;
+    /** Backoff sleep, injectable so tests don't wait out the real delays. */
+    sleepFor?: (ms: number) => Promise<void>;
+    /**
+     * Connection-error restart budget. Defaults to MAX_LOOP_RESTARTS, and even
+     * then the SHARED `restarts` counter is what actually binds — a worker that
+     * already spent the budget looping does not get extra lives here. 0 turns the
+     * retry off, which is how scripts/connection-retry-ab.ts gets a baseline arm
+     * out of a build that already ships the retry.
+     */
+    connectionRetries?: number;
 }
 export interface RunWorkerResult {
     text: string;
     exitCode: number;
     stderr: string;
     aborted: boolean;
+    /**
+     * The provider-reported cause when the model turn itself failed (disconnect,
+     * fetch failed, 5xx after pi's own retries): pi delivers it as an assistant
+     * message with stopReason "error" and EMPTY text, exit code 0. Phase children
+     * have always surfaced this (child-runner.ts) — research workers did not, so a
+     * swallowed provider error reached the caller as an indistinguishable empty
+     * answer and was reported as the useless "produced no output" (issue #10).
+     * Only meaningful when `text` is empty: a turn that produced text after pi
+     * recovered is a success, and the first-error capture must not relabel it.
+     */
+    modelError?: string;
+    /**
+     * Whether the child ever produced a single byte of stdout. Under `--mode json`
+     * a live pi child streams protocol events long before any assistant text, so
+     * this separates the two ways a worker can come back with nothing:
+     *   sawOutput true  — the child ran and the MODEL chose to write nothing
+     *                     (a legitimately empty section on a trivial task)
+     *   sawOutput false — the child never spoke at all: it died at startup
+     *                     (unresolvable provider, missing key, bad argv). That is
+     *                     a FAILURE and must never be recorded as "no entries".
+     * Derived from the same first-byte timestamp `waitMs`/`workMs` use, so it
+     * cannot disagree with them.
+     */
+    sawOutput: boolean;
     /**
      * Milliseconds between spawn and the child's first stdout chunk. When
      * multiple workers run concurrently and the upstream model API queues at

package/dist/workers/pi-worker-core.js

@@ -3,7 +3,7 @@ import { runChildDefault } from '../shared/child-process.js';
 import { CommandWatchdog, commandTimeoutHint, realTimerDeps } from '../shared/command-watchdog.js';
 import { childBaseArgs } from '../shared/child-extensions.js';
 import { LoopDetector } from '../task/loop-detector.js';
-import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint } from '../task/child-runner.js';
+import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint, isConnectionError, connectionRetryBackoffMs } from '../task/child-runner.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { discoverModelEndpoints, probeModelEndpoints } from '../shared/model-endpoint.js';
 import { streamStallHint } from '../shared/stream-watchdog.js';
@@ -66,6 +66,7 @@ const STALL_AFTER_MS = 180_000;
 const WORKER_TIMEOUT_HINT = '[SYSTEM NOTE: Your previous attempt ran out of time before answering — you '
     + 'were exploring too long. Be decisive: do the minimum reads/greps needed, '
     + 'then write your answer now. Do not re-explore ground you have already covered.]';
+const defaultSleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 /**
  * Combine an external abort signal with an internal wall-clock timeout into one
  * signal, while keeping the two causes distinguishable: `timedOut()` is true
@@ -192,6 +193,9 @@ export async function runWorker(input) {
     // `restarts` (the shared budget) so a loop-caused restart doesn't shorten
     // the rope of a child that has never hung (see commandCeilingForAttempt).
     let hangKills = 0;
+    // Connection-error restarts specifically — drives the backoff schedule (and
+    // lets a harness set the budget to 0 without touching the shared counter).
+    let connRetries = 0;
     let leakRetries = 0;
     for (;;) {
         const prompt = hint === null ? input.prompt : `${hint}\n\n${input.prompt}`;
@@ -315,6 +319,36 @@ export async function runWorker(input) {
             restarts++;
             continue;
         }
+        // A connection-class model error is restartable on the same budget, exactly
+        // as runPhaseWithLoopGuard already treats it — a research worker had no such
+        // retry, so one dropped fetch failed the whole task at research while the
+        // identical blip in refine/compose was absorbed.
+        //
+        // What this can and cannot buy, measured (flaky proxy in front of the local
+        // llama-server, dropping every connection for a fixed outage window): pi
+        // retries a failed turn itself, 4 attempts over ~15s, and a run that
+        // recovers no longer reports modelError at all (see JsonEventSink). So a
+        // surfaced connection error means pi's own ~15s budget is already spent, and
+        // a re-spawn only helps when the outage outlasts it. It does: at a 20s
+        // outage the baseline never recovered and this policy always did, 0/8 → 8/8
+        // (Fisher p=0.00016), and the same at 35s. Below ~15s pi absorbs it alone —
+        // 8/8 both arms, so the retry neither helps nor costs there. Beyond ~46s
+        // (three spawns' combined budget) both arms fail. The price is paid only on
+        // a backend that is really gone: time-to-report goes ~15s → ~46s. Re-run:
+        // scripts/connection-retry-ab.ts.
+        //
+        // Connection class ONLY. Auth, bad request and context overflow still fail
+        // fast: re-issuing the same request cannot fix them, so spending the budget
+        // would only delay the report.
+        if (result.modelError
+            && isConnectionError(result.modelError)
+            && restarts < MAX_LOOP_RESTARTS
+            && connRetries < (input.connectionRetries ?? MAX_LOOP_RESTARTS)) {
+            await (input.sleepFor ?? defaultSleep)(connectionRetryBackoffMs(connRetries));
+            restarts++;
+            connRetries++;
+            continue;
+        }
         // Only treat output as a leak on a clean, complete run — a non-zero exit
         // or abort yields partial text the caller already handles, and detecting
         // there would just mislabel the real failure.
@@ -331,7 +365,9 @@ export async function runWorker(input) {
             aborted: result.aborted,
             waitMs,
             workMs,
+            sawOutput: tFirstByte !== null,
             groundingRetrievalCount,
+            ...(result.modelError ? { modelError: result.modelError } : {}),
             ...(leaked ? { leakedToolCall: leaked } : {}),
             ...(loopHit ? { loopHit } : {}),
             ...(timedOut ? { timedOut: true } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.24.0",
+    "version": "0.24.2",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",