@mjasnikovs/pi-task 0.23.1 → 0.24.1

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/task/requirements.d.ts

@@ -31,7 +31,18 @@ export declare function keepGroundedRequirements(entries: RequirementEntry[], so
  * never the model-authored anchor text. Without `sourceDoc` (or for quotes that
  * cannot be located) the fill degrades to the old given-order behavior.
  */
-export declare function capRequirements(entries: RequirementEntry[], passages: string[], sourceDoc?: string): RequirementEntry[];
+export declare function capRequirements(entries: RequirementEntry[], passages: string[], sourceDoc?: string, 
+/** A/B seam: `false` reproduces the pre-budget rule, so an offline harness can
+ *  score the shipped rule against the one it replaced without transcribing
+ *  sectionFairFill and letting the copy drift. Production never passes it. */
+deprioritiseLowValue?: boolean): RequirementEntry[];
+/**
+ * Quotes that pass the grounding guard (verbatim substring of the doc) but state
+ * no obligation. There is no obligation test anywhere else in the pipeline —
+ * `keepGroundedRequirements` only checks the quote really appears in the source,
+ * so any sentence at all survives it and precision rests entirely on the model.
+ */
+export declare function isLowValueQuote(quote: string): boolean;
 /**
  * DETERMINISTIC RECALL FLOOR (same medicine as the launch-contract checklist):
  * paragraphs carrying an obligation marker (word-bounded "required"/"must").

package/dist/task/requirements.js

@@ -98,7 +98,11 @@ export function keepGroundedRequirements(entries, sourceDoc) {
  * never the model-authored anchor text. Without `sourceDoc` (or for quotes that
  * cannot be located) the fill degrades to the old given-order behavior.
  */
-export function capRequirements(entries, passages, sourceDoc) {
+export function capRequirements(entries, passages, sourceDoc, 
+/** A/B seam: `false` reproduces the pre-budget rule, so an offline harness can
+ *  score the shipped rule against the one it replaced without transcribing
+ *  sectionFairFill and letting the copy drift. Production never passes it. */
+deprioritiseLowValue = true) {
     if (entries.length <= MAX_REQUIREMENTS)
         return entries;
     const norms = passages.map(normalise);
@@ -109,7 +113,114 @@ export function capRequirements(entries, passages, sourceDoc) {
     const marked = entries.filter(covers);
     const rest = entries.filter(e => !covers(e));
     const budget = MAX_REQUIREMENTS - Math.min(marked.length, MAX_REQUIREMENTS);
-    return [...marked.slice(0, MAX_REQUIREMENTS), ...sectionFairFill(rest, budget, sourceDoc)];
+    // The low-value filter applies to the UNMARKED remainder only. Quoting an
+    // obligation-marked passage is the pipeline's existing, validated evidence
+    // that a quote states an obligation, and it outranks any lexical heuristic:
+    // "MUST log every request" is 22 characters and every length-based rule reads
+    // it as a fragment. Filtering ahead of the marked/rest split deleted it.
+    //
+    // INSURANCE, not a measured win on mx5: across both 30-run pools exactly one
+    // distinct quote per pool is low-value AND marked, and it is a genuinely
+    // truncated one. The layering matters for specs whose obligations are SHORT,
+    // which mx5's are not. Do not cite it as the reason tail coverage holds —
+    // tail coverage is identical with the filter applied before the split.
+    const pool = deprioritiseLowValue ? budgetedByObligation(rest, budget, sourceDoc) : rest;
+    return [...marked.slice(0, MAX_REQUIREMENTS), ...sectionFairFill(pool, budget, sourceDoc)];
+}
+/** Longest a dependency-pin row can be before it is presumed to carry an
+ *  obligation after the pin. Real pins in the measured corpus run 32..48 chars;
+ *  the pin-prefixed lines that DO obligate ("TypeScript `6.0.3` — one strict
+ *  `tsconfig.json`: `strict`, `noUncheckedIndexedAccess`, …") run 130..260. */
+const MAX_PIN_LENGTH = 80;
+/** Cut mid-expression: an unbalanced fence or bracket, or a trailing separator.
+ *  NOT `;` — a complete clause legitimately ends with one, and dropping on `;`
+ *  discarded a runnable `lint` = `prettier … && eslint … && tsc --noEmit` line. */
+function isTruncatedQuote(q) {
+    if ((q.match(/`/g) ?? []).length % 2 === 1)
+        return true;
+    for (const [open, close] of [
+        ['(', ')'],
+        ['[', ']'],
+        ['{', '}']
+    ]) {
+        const o = (q.match(new RegExp(`\\${open}`, 'g')) ?? []).length;
+        const c = (q.match(new RegExp(`\\${close}`, 'g')) ?? []).length;
+        if (o > c)
+            return true;
+    }
+    return /[,:([{]\s*$/.test(q.trim());
+}
+/** A bare version row — data, not an obligation. Length-gated, see MAX_PIN_LENGTH. */
+function isDependencyPin(q) {
+    const t = q.trim().replace(/^\*\*|\*\*$/g, '');
+    if (t.length > MAX_PIN_LENGTH)
+        return false;
+    return /^\**[`*]?[\w@/-]+[`*]?\**\s*[`']?\d+\.\d+/.test(t);
+}
+/** A DDL/schema row: `col type …`. */
+function isSchemaRow(q) {
+    return /^\s*[\w_]+\s+(?:uuid|text|int|integer|bigint|boolean|timestamptz|bytea|jsonb|numeric|smallint)\b/i.test(q);
+}
+/** Too short to state an obligation. MIN_QUOTE_LENGTH (6) admits "Contact
+ *  seller"; a clause needs a subject and a predicate. */
+function isQuoteFragment(q) {
+    const t = q.trim();
+    return t.length < 25 || t.split(/\s+/).length < 4;
+}
+/**
+ * Quotes that pass the grounding guard (verbatim substring of the doc) but state
+ * no obligation. There is no obligation test anywhere else in the pipeline —
+ * `keepGroundedRequirements` only checks the quote really appears in the source,
+ * so any sentence at all survives it and precision rests entirely on the model.
+ */
+export function isLowValueQuote(quote) {
+    return (isTruncatedQuote(quote)
+        || isDependencyPin(quote)
+        || isSchemaRow(quote)
+        || isQuoteFragment(quote));
+}
+/**
+ * Deprioritise obligation-free quotes, but only as far as the BUDGET requires.
+ *
+ * Measured (mx5, 20402-char spec, two independent 30-run extraction pools): the
+ * extractor's single-pass yield swings 20..160 for byte-identical input, and the
+ * padding crowds real obligations out of the 40 that ship — high-yield runs land
+ * FEWER critical obligations than low-yield ones. Critical obligations reaching
+ * the shipped list go 8.50 → 9.37 of 16 on the design pool (10 runs better, 0
+ * worse, p=0.0020) and 7.70 → 8.43 on the confirmation pool (12 / 0, p=0.0005).
+ *
+ * BUDGETED, not absolute. Below the cap no slot is contested, so dropping there
+ * destroys information and buys nothing; a run that filtered 55 quotes down to 20
+ * lost its only carrier of the Argon2id obligation — a DDL row that was correctly
+ * classified as one — while 20 slots sat empty. So the low-value entries come back
+ * in source-doc order until the list reaches the cap.
+ *
+ * Absolute filtering scored marginally higher on raw count (24 gains vs 22 across
+ * both pools) and was rejected anyway: its extra gains are one more obligation in
+ * an already-populated list, while its one loss is an obligation vanishing from a
+ * run outright. Those are not the same size of mistake.
+ *
+ * Doc order for the restore is the neutral choice: which entries return only
+ * matters when more were dropped than there are free slots, and ordering by
+ * anything fitted to an observed loss would be tuning the rule to one pool.
+ */
+function budgetedByObligation(entries, budget, sourceDoc) {
+    const keep = entries.filter(e => !isLowValueQuote(e.quote));
+    if (keep.length >= budget)
+        return keep;
+    const at = (e) => {
+        if (!sourceDoc)
+            return Number.MAX_SAFE_INTEGER;
+        const i = sourceDoc.indexOf(e.quote.trim());
+        return i < 0 ? Number.MAX_SAFE_INTEGER : i;
+    };
+    const restored = entries
+        .filter(e => isLowValueQuote(e.quote))
+        .map((e, given) => ({ e, at: at(e), given }))
+        .sort((x, y) => x.at - y.at || x.given - y.given)
+        .slice(0, budget - keep.length)
+        .map(x => x.e);
+    return [...keep, ...restored];
 }
 /** The doc split into heading-delimited sections, each pre-normalised for
  *  containment tests. Text before the first heading is its own section. */

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

@@ -92,6 +92,30 @@ export interface RunWorkerResult {
     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

@@ -331,7 +331,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.23.1",
+    "version": "0.24.1",
     "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",