@mjasnikovs/pi-task 0.15.1 → 0.16.0

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/impl-widget.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Implementation-turn status widget.
+ *
+ * The phase widget (widget.ts) is disposed at spec-handoff, so the host agent's
+ * implementation turn — the longest, most visible part of a run — otherwise shows
+ * only pi's bare "⠸ Working…" indicator. This module keeps the SAME rich status
+ * block alive across that turn (task id · implementing/elapsed/context bar · ↳ last
+ * tool), driven by the host's own live `ctx.getContextUsage()`.
+ *
+ * It is event-driven rather than poll-wrapped because the two delivery paths differ:
+ *
+ *   • /task (fire-and-forget): the command returns right after `sendUserMessage`,
+ *     so the host runs the impl turn AFTER our code is gone — only an `agent_start`
+ *     handler can pick it up. Armed one-shot: `agent_end` disarms it.
+ *   • /task-auto (awaited): the caller blocks across `waitForIdle` plus any
+ *     compaction-resume / steer turns. Armed sticky: each `agent_start` re-shows the
+ *     widget, `agent_end` only hides it between turns, and the caller disarms once
+ *     the whole implementation phase has settled.
+ *
+ * Only one task runs at a time (single active task), so a single module-level slot
+ * is sufficient.
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export interface ImplWidgetMeta {
+    taskId: string;
+    title: string;
+    label?: string;
+}
+/**
+ * Arm the implementation widget just before the spec is handed off. `oneShot`
+ * true (fire-and-forget /task) lets `agent_end` disarm it after the single turn;
+ * false (awaited /task-auto) keeps it armed until `disarmImplWidget` is called.
+ */
+export declare function armImplWidget(meta: ImplWidgetMeta, opts: {
+    oneShot: boolean;
+}): void;
+/** Tear down the widget and clear the armed slot (sticky/awaited path). */
+export declare function disarmImplWidget(): void;
+/** Wire the agent-lifecycle handlers that drive the widget. Call once at setup. */
+export declare function setupImplWidget(pi: ExtensionAPI): void;

package/dist/task/impl-widget.js

@@ -0,0 +1,131 @@
+/**
+ * Implementation-turn status widget.
+ *
+ * The phase widget (widget.ts) is disposed at spec-handoff, so the host agent's
+ * implementation turn — the longest, most visible part of a run — otherwise shows
+ * only pi's bare "⠸ Working…" indicator. This module keeps the SAME rich status
+ * block alive across that turn (task id · implementing/elapsed/context bar · ↳ last
+ * tool), driven by the host's own live `ctx.getContextUsage()`.
+ *
+ * It is event-driven rather than poll-wrapped because the two delivery paths differ:
+ *
+ *   • /task (fire-and-forget): the command returns right after `sendUserMessage`,
+ *     so the host runs the impl turn AFTER our code is gone — only an `agent_start`
+ *     handler can pick it up. Armed one-shot: `agent_end` disarms it.
+ *   • /task-auto (awaited): the caller blocks across `waitForIdle` plus any
+ *     compaction-resume / steer turns. Armed sticky: each `agent_start` re-shows the
+ *     widget, `agent_end` only hides it between turns, and the caller disarms once
+ *     the whole implementation phase has settled.
+ *
+ * Only one task runs at a time (single active task), so a single module-level slot
+ * is sufficient.
+ */
+import { WIDGET_KEY, WIDGET_REFRESH_MS, buildImplLines } from './widget.js';
+import { setTaskWidget } from '../remote/session-state.js';
+let armed = null;
+let lastLine;
+let timer = null;
+let activeCtx = null;
+/** Map the host's live context usage to the widget snapshot, or undefined when the
+ *  token count is unknown (e.g. right after compaction, before the next response). */
+function snapshot(ctx) {
+    const u = ctx.getContextUsage?.();
+    if (!u || u.tokens == null)
+        return undefined;
+    return { tokens: u.tokens, contextWindow: u.contextWindow, percent: u.percent ?? 0 };
+}
+function render() {
+    if (!armed || !activeCtx)
+        return;
+    const ctx = activeCtx;
+    const state = {
+        taskId: armed.meta.taskId,
+        title: armed.meta.title,
+        label: armed.meta.label,
+        startedAt: armed.startedAt,
+        lastLine,
+        contextUsage: snapshot(ctx)
+    };
+    try {
+        ctx.ui.setWidget(WIDGET_KEY, buildImplLines(state, ctx.ui.theme));
+    }
+    catch {
+        /* stale ctx */
+    }
+    setTaskWidget(buildImplLines(state, undefined)); // un-themed for the wire
+}
+function startTimer() {
+    if (timer)
+        return;
+    render();
+    timer = setInterval(render, WIDGET_REFRESH_MS);
+    timer.unref?.();
+}
+function stopTimer() {
+    if (timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+}
+function clearWidget() {
+    try {
+        activeCtx?.ui.setWidget(WIDGET_KEY, undefined);
+    }
+    catch {
+        /* stale ctx */
+    }
+    setTaskWidget(undefined);
+}
+/** One-line summary of a host tool call for the `↳` trailer (best-effort). */
+function formatToolLine(toolName, args) {
+    const a = (args ?? {});
+    const field = a.path ?? a.file_path ?? a.command ?? a.pattern ?? a.prompt ?? a.query ?? a.url;
+    const detail = typeof field === 'string' ? ' ' + field.replace(/\s+/g, ' ').trim() : '';
+    return `${toolName}${detail}`;
+}
+/**
+ * Arm the implementation widget just before the spec is handed off. `oneShot`
+ * true (fire-and-forget /task) lets `agent_end` disarm it after the single turn;
+ * false (awaited /task-auto) keeps it armed until `disarmImplWidget` is called.
+ */
+export function armImplWidget(meta, opts) {
+    armed = { meta, oneShot: opts.oneShot, startedAt: Date.now() };
+    lastLine = undefined;
+}
+/** Tear down the widget and clear the armed slot (sticky/awaited path). */
+export function disarmImplWidget() {
+    stopTimer();
+    clearWidget();
+    armed = null;
+    activeCtx = null;
+    lastLine = undefined;
+}
+/** Wire the agent-lifecycle handlers that drive the widget. Call once at setup. */
+export function setupImplWidget(pi) {
+    pi.on('agent_start', (_event, ctx) => {
+        if (!armed)
+            return;
+        activeCtx = ctx;
+        lastLine = undefined;
+        startTimer();
+    });
+    pi.on('tool_execution_start', (event, _ctx) => {
+        if (!armed)
+            return;
+        lastLine = formatToolLine(event.toolName, event.args);
+    });
+    pi.on('agent_end', (_event, _ctx) => {
+        if (!armed)
+            return;
+        stopTimer();
+        clearWidget();
+        // Fire-and-forget /task: the single impl turn is over, so disarm. Awaited
+        // /task-auto leaves the slot armed so the next compaction-resume / steer
+        // turn re-shows it; the caller disarms when the phase truly settles.
+        if (armed.oneShot) {
+            armed = null;
+            activeCtx = null;
+            lastLine = undefined;
+        }
+    });
+}

package/dist/task/orchestrator.d.ts

@@ -28,6 +28,11 @@ export declare class TaskRunner {
     private readonly _onStart;
     private readonly _planContext;
     private readonly _fixInstruction;
+    /** True when the caller awaits the implementation turn (waitForImplementation):
+     *  the impl widget stays armed across the whole impl phase (incl. compaction /
+     *  steer turns) and is disarmed here. False for fire-and-forget /task, where the
+     *  widget is armed one-shot and its own agent_end disarms it. */
+    private readonly _implAwaited;
     private readonly _abort;
     private readonly _startedAt;
     private readonly _widgetState;
@@ -43,7 +48,7 @@ export declare class TaskRunner {
      */
     private readonly _timings;
     private _currentPhaseChildren;
-    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn, onStart?: (taskId: string) => void | Promise<void>, planContext?: string, fixInstruction?: string);
+    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn, onStart?: (taskId: string) => void | Promise<void>, planContext?: string, fixInstruction?: string, implAwaited?: boolean);
     get taskId(): string;
     get signal(): AbortSignal;
     /** Return the current widget state, or null if not started. */

package/dist/task/orchestrator.js

@@ -23,6 +23,7 @@ import { PHASE_INDEX, PHASE_ORDER, RESUMABLE_STATES } from './task-types.js';
 import { normaliseTaskId, parseFrontMatter, extractSection } from './task-parsers.js';
 import { allocateTaskId, ensureTasksDir, readSection, readTaskFile, setTaskSection, taskFilePath, tasksDir, updateTaskFrontMatter, writeTaskFile } from './task-io.js';
 import { startWidget } from './widget.js';
+import { armImplWidget, disarmImplWidget, setupImplWidget } from './impl-widget.js';
 import { publishViewer, publishNotify, registerBridgeCommand, getBridge } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { parseVerifyBlock } from './spec-validation.js';
@@ -54,6 +55,11 @@ export class TaskRunner {
     _onStart;
     _planContext;
     _fixInstruction;
+    /** True when the caller awaits the implementation turn (waitForImplementation):
+     *  the impl widget stays armed across the whole impl phase (incl. compaction /
+     *  steer turns) and is disarmed here. False for fire-and-forget /task, where the
+     *  widget is armed one-shot and its own agent_end disarms it. */
+    _implAwaited;
     _abort = new AbortController();
     _startedAt;
     _widgetState;
@@ -69,7 +75,7 @@ export class TaskRunner {
      */
     _timings = [];
     _currentPhaseChildren = null;
-    constructor(ctx, cwd, rawPrompt, resumeId, sendSpec, spawnFn, onStart, planContext, fixInstruction) {
+    constructor(ctx, cwd, rawPrompt, resumeId, sendSpec, spawnFn, onStart, planContext, fixInstruction, implAwaited) {
         this._ctx = ctx;
         this._cwd = cwd;
         this._rawPrompt = rawPrompt;
@@ -78,6 +84,7 @@ export class TaskRunner {
         this._onStart = onStart;
         this._planContext = planContext;
         this._fixInstruction = fixInstruction;
+        this._implAwaited = implAwaited ?? false;
         this._startedAt = Date.now();
         // We'll populate id/title/phase lazily in run().
         // Placeholder — real values set in run().
@@ -265,13 +272,30 @@ export class TaskRunner {
     }
     async _deliverSpec(ctx) {
         const spec = this._specForDelivery();
+        // Keep the rich status block alive across the implementation turn (the phase
+        // widget was disposed at handoff). Awaited (/task-auto) stays armed across all
+        // sub-turns and is disarmed here; fire-and-forget (/task) arms one-shot and its
+        // own agent_end disarms it after the single turn.
+        const meta = {
+            taskId: this._widgetState.taskId,
+            title: this._widgetState.title,
+            label: this._widgetState.label
+        };
         if (this._sendSpec) {
-            await this._sendSpec(spec);
+            armImplWidget(meta, { oneShot: !this._implAwaited });
+            try {
+                await this._sendSpec(spec);
+            }
+            finally {
+                if (this._implAwaited)
+                    disarmImplWidget();
+            }
             return;
         }
         if (!piApi) {
             throw new Error('extension not initialised (no ExtensionAPI captured)');
         }
+        armImplWidget(meta, { oneShot: true });
         if (ctx.isIdle()) {
             piApi.sendUserMessage(spec);
         }
@@ -494,7 +518,7 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                     if (!interrupted)
                         implError = implementationError(newCtx);
                 }
-            }, opts.spawnFn, opts.onStart, opts.planContext, opts.fixInstruction);
+            }, opts.spawnFn, opts.onStart, opts.planContext, opts.fixInstruction, opts.waitForImplementation);
             await runner.run();
             taskId = runner.taskId;
         }
@@ -643,6 +667,7 @@ async function handleTaskCancel(_args, ctx) {
 // ─── Entry point ─────────────────────────────────────────────────────────────
 export function registerTask(pi) {
     piApi = pi;
+    setupImplWidget(pi);
     registerBridgeCommand(pi, 'task', {
         description: 'Start a new task. Usage: /task <prompt>',
         handler: handleTask

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

@@ -63,4 +63,14 @@ export declare function buildAutoLoaderLines(s: AutoLoaderState, theme?: WidgetT
  * (returns a no-op disposer) when there's no UI.
  */
 export declare function startAutoLoader(ctx: ExtensionCommandContext, getState: () => AutoLoaderState | null): () => void;
+export interface ImplState {
+    taskId: string;
+    title: string;
+    /** Short display label compressed from `title`; falls back to a truncation when absent. */
+    label?: string;
+    startedAt: number;
+    lastLine?: string;
+    contextUsage?: ContextSnapshot;
+}
+export declare function buildImplLines(s: ImplState, theme?: WidgetTheme): string[];
 export declare function flashTerminalWidget(ctx: ExtensionCommandContext, state: Exclude<TaskState, 'pending' | 'in_progress' | 'completed'>, taskId: string, reason: string | undefined): void;

package/dist/task/widget.js

@@ -170,6 +170,21 @@ export function startAutoLoader(ctx, getState) {
         setTaskWidget(undefined);
     };
 }
+export function buildImplLines(s, theme) {
+    const elapsed = formatDuration(Date.now() - s.startedAt);
+    const head = `${s.taskId} · ${titleForDisplay(s)}`;
+    let detail = `implementing · ${elapsed}`;
+    if (s.contextUsage) {
+        const ctxDetail = formatContextDetail(s.contextUsage, theme);
+        if (ctxDetail)
+            detail += ` · ${ctxDetail}`;
+    }
+    const lines = [head, detail];
+    const trailer = lastLineTrailer(s.lastLine, theme);
+    if (trailer)
+        lines.push(trailer);
+    return lines;
+}
 export function flashTerminalWidget(ctx, state, taskId, reason) {
     if (!ctx.hasUI)
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.15.1",
+    "version": "0.16.0",
     "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",