@mjasnikovs/pi-task 0.15.0 → 0.15.2

package/dist/config/register.js

@@ -18,15 +18,15 @@ const ITEMS = [
         label: 'orientation',
         description: 'Pre-supply the project core (manifest, types, schema…) to the read-heavy research workers'
     },
-    {
-        id: 'enforceGuidelines',
-        label: 'enforce guidelines',
-        description: 'Before each /task-auto commit, re-check the work against AGENTS.md/CLAUDE.md and fix drift'
-    },
     {
         id: 'verifyWork',
         label: 'verify work',
-        description: "After each /task-auto task, RUN its spec's VERIFY block in the workspace and report a PASS/FAIL verdict"
+        description: "After each /task-auto task, RUN its spec's VERIFY block in the workspace and report a PASS/FAIL verdict (also the signal that lets 'enforce guidelines' fix safely)"
+    },
+    {
+        id: 'enforceGuidelines',
+        label: 'enforce guidelines',
+        description: "Check each /task-auto commit against AGENTS.md/CLAUDE.md. Needs 'verify work' to FIX drift (fixes are reverted if they regress verification); without it, only reports violations"
     }
 ];
 function makeTheme(theme) {

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

@@ -60,13 +60,34 @@ export type { PhaseDeps };
  */
 export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string): Promise<string>;
 export declare function formatLoopHint(hit: LoopHit): string;
+/**
+ * Terminal hint for the degrade attempt: the model has thrashed through the whole
+ * strike budget re-reading files without converging, so we strip its tools and
+ * order it to emit the deliverable NOW from what it already has. Used only by
+ * read-only analysis phases (refine) whose output is a text rewrite that never
+ * strictly required a successful read — far better to ship a best-effort spec
+ * than to hard-fail the whole /task-auto run. See countRevisits / LoopExhausted.
+ */
+export declare function formatDegradeHint(hit: LoopHit): string;
 export declare function prependHint(hint: string | null, prompt: string): string;
 /**
  * Run a phase child with loop detection. On a detected loop, kill and re-spawn
  * with a hint that names the offending call. Cap at MAX_LOOP_RESTARTS restarts;
  * the (MAX_LOOP_RESTARTS+1)th loop throws LoopExhaustedError.
  */
-export declare function runPhaseWithLoopGuard(deps: PhaseDeps, name: string, tools: string, buildPrompt: (loopHint: string | null) => string): Promise<string>;
+export interface LoopGuardOptions {
+    /**
+     * When the strike budget is exhausted by loops, do NOT fail the phase. Run
+     * ONE final attempt with NO tools and a terminal hint ordering the model to
+     * emit its output from what it already has. Only safe for phases whose
+     * deliverable is a pure text rewrite that never strictly required a read
+     * (refine) — a hard-fail there kills the whole /task-auto run for a model
+     * that simply over-explored. Research/location phases must NOT enable this:
+     * their output depends on real reads, so a no-tools fallback would fabricate.
+     */
+    degradeOnExhaustion?: boolean;
+}
+export declare function runPhaseWithLoopGuard(deps: PhaseDeps, name: string, tools: string, buildPrompt: (loopHint: string | null) => string, opts?: LoopGuardOptions): Promise<string>;
 /**
  * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
  * the prompt. On success, return the validator's value; on two failures, throw

package/dist/task/child-runner.js

@@ -160,6 +160,22 @@ export function formatLoopHint(hit) {
         + `stuck in a loop. Avoid repeating that exact call; if you've already seen its result, `
         + `work from memory or pick a different angle.]`);
 }
+/**
+ * Terminal hint for the degrade attempt: the model has thrashed through the whole
+ * strike budget re-reading files without converging, so we strip its tools and
+ * order it to emit the deliverable NOW from what it already has. Used only by
+ * read-only analysis phases (refine) whose output is a text rewrite that never
+ * strictly required a successful read — far better to ship a best-effort spec
+ * than to hard-fail the whole /task-auto run. See countRevisits / LoopExhausted.
+ */
+export function formatDegradeHint(hit) {
+    return (`[SYSTEM NOTE: You called ${hit.call.name}(${JSON.stringify(hit.call.args)}) `
+        + `repeatedly and made no forward progress — you are stuck re-reading the same files. `
+        + `You now have NO tools: you cannot read, grep, list, or open anything further. `
+        + `STOP exploring. Produce the COMPLETE required output IMMEDIATELY, using only the task `
+        + `description and what you have already seen. Emit the full structured result now — do not `
+        + `ask to read more, do not explain, just output the final answer.]`);
+}
 export function prependHint(hint, prompt) {
     return hint === null ? prompt : `${hint}\n\n${prompt}`;
 }
@@ -172,12 +188,7 @@ async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
     const next = existing ? `${existing}\n${line}` : line;
     await setTaskSection(cwd, taskId, 'loop events', next);
 }
-/**
- * Run a phase child with loop detection. On a detected loop, kill and re-spawn
- * with a hint that names the offending call. Cap at MAX_LOOP_RESTARTS restarts;
- * the (MAX_LOOP_RESTARTS+1)th loop throws LoopExhaustedError.
- */
-export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt) {
+export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt, opts = {}) {
     const loopHistory = [];
     // Carries the correction hint (loop OR leaked-tool-call) into the next strike.
     let nextHint = null;
@@ -192,9 +203,14 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt) {
         if (r.loopHit) {
             const isLastStrike = strike === MAX_LOOP_RESTARTS;
             loopHistory.push(r.loopHit);
-            await appendLoopEvent(deps.cwd, deps.taskId, name, r.loopHit, strike + 1, isLastStrike ? 'phase failed' : 'restarted with hint');
-            if (isLastStrike)
+            const lastOutcome = opts.degradeOnExhaustion ? 'degraded — no-tools final attempt' : 'phase failed';
+            await appendLoopEvent(deps.cwd, deps.taskId, name, r.loopHit, strike + 1, isLastStrike ? lastOutcome : 'restarted with hint');
+            if (isLastStrike) {
+                if (opts.degradeOnExhaustion) {
+                    return await runDegradedFinalAttempt(deps, name, buildPrompt, r.loopHit, loopHistory);
+                }
                 throw new LoopExhaustedError(name, loopHistory);
+            }
             nextHint = formatLoopHint(r.loopHit);
             continue;
         }
@@ -236,6 +252,24 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt) {
     }
     throw new LoopExhaustedError(name, loopHistory);
 }
+/**
+ * Final degrade attempt after the loop budget is spent: re-spawn the child with
+ * NO tools and a terminal hint, so a model that thrashed re-reading files is
+ * forced to emit its deliverable from what it already has. With no tools there
+ * are no tool calls, so no loop can recur — the only failure modes left are a
+ * dead turn (non-zero exit, model error) or empty output, any of which fall back
+ * to the original LoopExhaustedError so the phase still fails honestly when even
+ * the degrade produces nothing.
+ */
+async function runDegradedFinalAttempt(deps, name, buildPrompt, hit, loopHistory) {
+    deps.logDebug?.(`${name}: loop budget exhausted — degrading to a no-tools final attempt`);
+    const r = await runChild(deps.cwd, '', // --no-tools: the model cannot read/grep/list, only answer
+    buildPrompt(formatDegradeHint(hit)), deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn);
+    if (r.exitCode !== 0 || r.modelError || r.text.trim().length === 0) {
+        throw new LoopExhaustedError(name, loopHistory);
+    }
+    return r.text;
+}
 /**
  * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
  * the prompt. On success, return the validator's value; on two failures, throw

package/dist/task/phases.js

@@ -62,7 +62,15 @@ export function replaceToolingWithVerified(research, verifiedCommands) {
     return replaced;
 }
 // ─── Phase functions ─────────────────────────────────────────────────────────
-export const phaseRefine = (deps, raw, planContext) => runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext))));
+export const phaseRefine = (deps, raw, planContext) => runPhaseWithLoopGuard(deps, 'refine', 'read', hint => prependHint(hint, appendNoThink(REFINE_PROMPT(raw, planContext))), 
+// refine's deliverable is a 4-section text rewrite that never strictly
+// needs a successful read — on a test-writing task against a large
+// existing codebase the model over-explores (re-reads source hunting for
+// the impl) and burns the loop budget. Degrade to a no-tools final
+// attempt instead of hard-failing the whole run. See TASK_0016 (mx5):
+// refine looped 3×/resume forever; the deliverable was always producible
+// from the title + design doc alone.
+{ degradeOnExhaustion: true });
 export async function phaseVerifyTooling(deps, research) {
     const commands = extractToolingCommands(research);
     if (!commands || commands.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.15.0",
+    "version": "0.15.2",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",