@mjasnikovs/pi-task 0.13.15 → 0.13.17

package/dist/task/auto-orchestrator.d.ts

@@ -26,6 +26,24 @@ export interface AutoDeps {
  * is returned verbatim when nothing readable is referenced.
  */
 export declare function expandFeatureMentions(cwd: string, feature: string): Promise<string>;
+/**
+ * The @file references in the feature that point at a readable file on disk —
+ * the bare path tokens, deduped, in first-seen order. Unreadable mentions
+ * (typos, non-file @tokens) are dropped so we never advertise a missing file as
+ * an authoritative spec.
+ */
+export declare function readableMentions(cwd: string, feature: string): Promise<string[]>;
+/**
+ * Thread the feature's spec references into every decomposed task title.
+ * Decompose emits titles only, and a title is ALL a per-task pipeline ever sees
+ * — so without this the design doc the feature pointed at is invisible
+ * downstream and each task drifts to a generic reading of its one-line title
+ * (this is how an "Implement @design.md" run built a generic `posts` table the
+ * spec never mentioned). Appending the @refs makes the per-task refine/research
+ * read the real spec and treat it as authoritative over the title. No readable
+ * refs → titles unchanged, so a doc-less /task-auto behaves exactly as before.
+ */
+export declare function attachSpecRefs(titles: string[], refs: string[]): string[];
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export declare function planAuto(ctx: ExtensionCommandContext, cwd: string, feature: string, deps: AutoDeps): Promise<string | null>;
 export declare function requestAutoCancel(): void;

package/dist/task/auto-orchestrator.js

@@ -51,6 +51,47 @@ export async function expandFeatureMentions(cwd, feature) {
     }
     return blocks.length === 0 ? feature : `${feature.trim()}\n\n${blocks.join('\n\n')}`;
 }
+/**
+ * The @file references in the feature that point at a readable file on disk —
+ * the bare path tokens, deduped, in first-seen order. Unreadable mentions
+ * (typos, non-file @tokens) are dropped so we never advertise a missing file as
+ * an authoritative spec.
+ */
+export async function readableMentions(cwd, feature) {
+    const out = [];
+    const seen = new Set();
+    for (const m of feature.matchAll(MENTION_RE)) {
+        const rel = m[1];
+        if (seen.has(rel))
+            continue;
+        seen.add(rel);
+        try {
+            await fsp.access(path.resolve(cwd, rel));
+            out.push(rel);
+        }
+        catch {
+            // not a readable file — don't thread it into task titles
+        }
+    }
+    return out;
+}
+/**
+ * Thread the feature's spec references into every decomposed task title.
+ * Decompose emits titles only, and a title is ALL a per-task pipeline ever sees
+ * — so without this the design doc the feature pointed at is invisible
+ * downstream and each task drifts to a generic reading of its one-line title
+ * (this is how an "Implement @design.md" run built a generic `posts` table the
+ * spec never mentioned). Appending the @refs makes the per-task refine/research
+ * read the real spec and treat it as authoritative over the title. No readable
+ * refs → titles unchanged, so a doc-less /task-auto behaves exactly as before.
+ */
+export function attachSpecRefs(titles, refs) {
+    if (refs.length === 0)
+        return titles;
+    const list = refs.map(r => '@' + r).join(' ');
+    const suffix = ` | spec: ${list} — authoritative; read it and follow it over this title wherever they differ`;
+    return titles.map(t => (t.includes('| spec:') ? t : t + suffix));
+}
 /** Plan phase: clarify → decompose → write AUTO file. Returns the new id, or null. */
 export async function planAuto(ctx, cwd, feature, deps) {
     // clarify — sequential & adaptive: ask one question at a time, feeding every
@@ -138,7 +179,11 @@ export async function planAuto(ctx, cwd, feature, deps) {
     const clarifications = answers.join('\n');
     // decompose
     const listRaw = await deps.runChild('auto-decompose', 'read', AUTO_DECOMPOSE_PROMPT(featureForModel, clarifications));
-    const titles = parseDecomposeList(listRaw);
+    // Thread the feature's spec doc(s) into every title so each per-task
+    // pipeline — which only ever sees its title — reads the real spec instead of
+    // a lossy one-line paraphrase of it.
+    const refs = await readableMentions(cwd, feature);
+    const titles = attachSpecRefs(parseDecomposeList(listRaw), refs);
     if (titles.length === 0) {
         announceDone(ctx, '/task-auto: no tasks produced from the feature.', 'warning');
         return null;
@@ -304,7 +349,11 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             }
             if (!res.ok) {
                 await updateTaskFrontMatter(cwd, id, { state: 'failed' });
-                announceDone(active, `${id} stopped at "${next.title}" — fix and run /task-auto-resume.`, 'error');
+                // res.reason is set when the implementation turn itself died
+                // (e.g. a context-overflow 400) — surface it so the real cause
+                // isn't lost behind the generic "stopped" message.
+                const why = res.reason ? ` — ${res.reason.slice(0, 160)}` : '';
+                announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
                 return;
             }
             // res.ok === true means runner.run() completed, so res.taskId is the

package/dist/task/auto-prompts.js

@@ -33,6 +33,7 @@ fork the breakdown). Account for the answers so far:
   time (file/blob storage, client/rendering strategy, auth and session model,
   real-time vs polling transport, search, deployment).
 - Skip anything /task will naturally resolve per-task during its own research.
+- Stay grounded in the referenced spec. If a design/spec doc is included above, do NOT propose a new subsystem, dependency, or requirement it does not call for, and do NOT re-ask a choice the spec already settles. Ask only about genuine forks the spec leaves open.
 
 YOU MUST propose a default answer for the question — every question you emit
 carries exactly one SUGGESTED line. Never omit it, never leave it blank, never

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

@@ -52,6 +52,7 @@ export type { PhaseDeps };
  * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
  */
 export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string): Promise<string>;
+export declare function formatLoopHint(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

package/dist/task/child-runner.js

@@ -119,7 +119,7 @@ export async function runPhaseChild(deps, name, tools, prompt) {
     // Unreachable: the loop returns clean text or throws on the final leak.
     throw new LeakedToolCallError(name, '(unknown)');
 }
-function formatLoopHint(hit) {
+export function formatLoopHint(hit) {
     const argsStr = JSON.stringify(hit.call.args);
     return (`[SYSTEM NOTE: Your prior attempt called ${hit.call.name}(${argsStr}) `
         + `${hit.count} times in the last ${hit.windowSize} tool calls — you appeared to be `

package/dist/task/orchestrator.d.ts

@@ -108,6 +108,14 @@ export interface RunSingleTaskResult {
      * uninterrupted.
      */
     interrupted?: boolean;
+    /**
+     * Why the run is not ok, when known. Set when a waitForImplementation turn
+     * ended with stopReason "error" (the model/provider died mid-implementation —
+     * e.g. a context-overflow 400 — after the task file was already marked
+     * `completed` at spec-handoff). The /task-auto loop surfaces this in its
+     * "stopped at …" message so the real cause isn't lost. Undefined otherwise.
+     */
+    reason?: string;
 }
 /**
  * Run one prompt through the full single-task pipeline in a fresh session and

package/dist/task/orchestrator.js

@@ -288,6 +288,29 @@ function wasInterrupted(ctx) {
     }
     return false;
 }
+/**
+ * The error cause when the most recent assistant turn ended with stopReason
+ * "error" — the model/provider failed mid-implementation (context overflow,
+ * disconnect, provider 5xx) after pi exhausted its own retries. Returns the
+ * provider's errorMessage, or undefined if the turn ended cleanly ("stop") or
+ * was user-aborted ("aborted", handled by wasInterrupted).
+ *
+ * The /task-auto loop reads this AFTER the implementation wait: a task's file is
+ * marked `completed` at spec-handoff (before implementation), so without this
+ * check an implementation turn that died — e.g. "400 ... exceeds the available
+ * context size" — would still read as ok and get checked off and committed.
+ */
+function implementationError(ctx) {
+    const entries = ctx.sessionManager.getEntries();
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if ('message' in e && 'role' in e.message && e.message.role === 'assistant') {
+            const m = e.message;
+            return m.stopReason === 'error' ? (m.errorMessage ?? 'model error') : undefined;
+        }
+    }
+    return undefined;
+}
 /**
  * After the implementation turn settles, honour a user ESC by letting them steer.
  *
@@ -326,6 +349,11 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
     // cancellation path (where no replacement occurs).
     let freshCtx = ctx;
     let interrupted = false;
+    // The implementation turn's failure cause, when it ended with stopReason
+    // "error" (only meaningful in the waitForImplementation path). The task file
+    // was already marked `completed` at spec-handoff, so this is the only signal
+    // that the implementation itself died and the task must not be checked off.
+    let implError;
     const result = await ctx.newSession({
         withSession: async (newCtx) => {
             freshCtx = newCtx;
@@ -335,6 +363,10 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                 if (opts.waitForImplementation) {
                     await newCtx.waitForIdle();
                     interrupted = await steerUntilDone(newCtx, opts.promptSteer);
+                    // A user-declined steer (interrupted) is its own paused
+                    // path; otherwise inspect how the turn actually ended.
+                    if (!interrupted)
+                        implError = implementationError(newCtx);
                 }
             }, opts.spawnFn, opts.onStart);
             await runner.run();
@@ -360,13 +392,18 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
             ok = false;
         }
     }
+    // The file reads `completed` from spec-handoff even when the implementation
+    // turn then died. Demote to a failure so /task-auto stops here (leaving the
+    // entry unchecked and resumable) instead of committing and advancing.
+    if (ok && implError)
+        ok = false;
     if (opts.notifyFinish) {
         // One push per top-level /task or /task-resume, on any terminal end. The
         // file state is the source of truth: 'completed' on success, 'failed' /
         // 'cancelled' otherwise; an unreadable/absent file falls back to 'ended'.
         void pushNotify('Task finished', `${taskId || 'Task'} ${state ?? 'ended'}.`, 'pi-end').catch(() => { });
     }
-    return { taskId, ok, sessionCancelled: false, ctx: freshCtx, interrupted };
+    return { taskId, ok, sessionCancelled: false, ctx: freshCtx, interrupted, reason: implError };
 }
 // ─── Command handlers ────────────────────────────────────────────────────────
 async function handleTask(args, ctx) {

package/dist/task/phases.js

@@ -179,6 +179,20 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // mirrors workerSpecs order — the loop above pushes in sequence).
     const sections = workerSpecs.map((spec, i) => ({ name: spec.section, result: workerResults[i] }));
     for (const { name, result } of sections) {
+        // Loop/timeout exhaustion is checked before the generic exit-code branch:
+        // a loop-kill arrives as a SIGTERM (exit 143) AND sometimes as a clean
+        // exit 0 with partial text, so keying off exitCode alone would either give
+        // a useless "exit 143" message or silently accept truncated output. The
+        // worker already burned its MAX_LOOP_RESTARTS restarts before setting these.
+        if (result.loopHit) {
+            const argsStr = JSON.stringify(result.loopHit.call.args);
+            throw new Error(`Research ${name} worker stuck in a loop — called `
+                + `${result.loopHit.call.name}(${argsStr}) ×${result.loopHit.count} in the last `
+                + `${result.loopHit.windowSize} calls and still looped after restarts`);
+        }
+        if (result.timedOut) {
+            throw new Error(`Research ${name} worker timed out after restarts`);
+        }
         if (result.exitCode !== 0) {
             throw new Error(`Research ${name} worker failed (exit ${result.exitCode}): ${result.stderr.slice(-500)}`);
         }

package/dist/task/prompts.js

@@ -54,6 +54,7 @@ Rules:
 - Fix spelling and grammar; output in English regardless of input language.
 - Preserve every concrete identifier verbatim (paths, function names, ports, env vars, file:line refs).
 - Do not invent requirements not implied by the input.
+- If the task references a design/spec document (an @-path or a named spec file), READ it and treat it as authoritative. Carry its concrete schema verbatim into GOAL/CONSTRAINTS — table and column names, types, endpoint methods and paths, enum values. The task title is only a pointer into that spec: where the title and the spec disagree, follow the spec, and never introduce a table, column, endpoint, or dependency the spec does not define.
 - Do not output any preamble, commentary, or markdown headings beyond the four sections above.
 
 Task: ${raw}`;
@@ -73,6 +74,8 @@ const RESEARCH_FILES_PROMPT = (refined) => `You are doing targeted research for
 
 FILES owns paths. APIS owns symbols. Do not omit a path because it "feels like config" — if the agent will touch or read it, list it here.
 
+If the task references a design/spec document (an @-path or a named spec file), OPEN it first and list it — it is the contract for this task, and the schema, names, and endpoints it defines are authoritative over any paraphrase in the task title.
+
 When a task operates across a whole directory tree (e.g. lint, typecheck, build, format, test-all), list the root directory entry (\`src/  one-line purpose\`) instead of enumerating every file under it. Enumerate individual files only when they need to be singled out — modified specifically, called out by name in the task, or distinct from their siblings in some material way.
 
 RELEVANCE — read carefully: list ONLY paths this specific task touches — the files the agent will read, edit, or must be aware of to complete THIS task. Do NOT inventory the whole repo or list files just because they exist. A file the agent will never open does not belong here. Aim for the smallest sufficient set: include every path the task genuinely reaches and nothing more. There is no fixed limit — a broad task may need many entries, a narrow one only a few. Right-size to the task, not to a number, and collapse directories to their root entry where the task spans a whole tree.

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

@@ -1,4 +1,5 @@
 import { type SpawnFn } from '../shared/child-process.js';
+import { type LoopHit } from '../task/loop-detector.js';
 export interface RunWorkerInput {
     prompt: string;
     cwd: string;
@@ -10,6 +11,8 @@ export interface RunWorkerInput {
     extensions?: string[];
     /** Called for each tool execution start and text-writing event inside the worker. */
     onLine?: (line: string) => void;
+    /** Per-worker wall-clock timeout in ms. Defaults to RESEARCH_WORKER_TIMEOUT_MS. */
+    timeoutMs?: number;
 }
 export interface RunWorkerResult {
     text: string;
@@ -34,5 +37,18 @@ export interface RunWorkerResult {
      * failure rather than trusting the returned text.
      */
     leakedToolCall?: string;
+    /**
+     * Set when the worker was killed for looping (the same tool call repeated
+     * past threshold) and still looped after exhausting MAX_LOOP_RESTARTS
+     * restarts. The returned text is truncated mid-stream — the caller must treat
+     * this as a failure, not trust it.
+     */
+    loopHit?: LoopHit;
+    /**
+     * Set when the worker's final attempt hit the per-worker wall-clock timeout
+     * after exhausting its restart budget. Like loopHit, the text is partial and
+     * the caller must treat it as a failure.
+     */
+    timedOut?: boolean;
 }
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;

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

@@ -1,6 +1,7 @@
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { CHILD_BASE_ARGS, runChildDefault } from '../shared/child-process.js';
 import { LoopDetector } from '../task/loop-detector.js';
+import { LOOP_WINDOW, LOOP_THRESHOLD, MAX_LOOP_RESTARTS, formatLoopHint } from '../task/child-runner.js';
 import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 // `--mode json` makes pi emit structured events as they happen instead of
 // buffering the assistant text and flushing on exit. That matters for the
@@ -10,33 +11,118 @@ import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../s
 // model starts producing — making waitMs the real queue/cold-start cost and
 // workMs the real generation+tool-call cost.
 const DEFAULT_TOOLS = 'read,grep,find,ls';
+/**
+ * Hard wall-clock bound on a single research worker run (one spawn). The
+ * exact-match LoopDetector only catches *identical* repeated tool calls; a model
+ * that thrashes with slightly-varied calls (different grep patterns each time)
+ * slips past it and would otherwise run unbounded. This is the backstop for that
+ * case: after this long with no clean exit, abort and restart with a hint. Sized
+ * well above a healthy worker's observed runtime (~25-130s on the local backend)
+ * so it never trips a legitimately slow run.
+ */
+const RESEARCH_WORKER_TIMEOUT_MS = 240_000;
+/** Restart hint after a wall-clock timeout — distinct from the loop hint. */
+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.]';
+/**
+ * Combine an external abort signal with an internal wall-clock timeout into one
+ * signal, while keeping the two causes distinguishable: `timedOut()` is true
+ * only when the timer fired (not when the external signal aborted), so the caller
+ * can restart on a timeout but not on a user cancel.
+ */
+function workerTimeout(external, ms) {
+    const ctrl = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        ctrl.abort();
+    }, ms);
+    const onExternal = () => ctrl.abort();
+    if (external) {
+        if (external.aborted)
+            ctrl.abort();
+        else
+            external.addEventListener('abort', onExternal, { once: true });
+    }
+    return {
+        signal: ctrl.signal,
+        timedOut: () => timedOut,
+        cleanup: () => {
+            clearTimeout(timer);
+            external?.removeEventListener('abort', onExternal);
+        }
+    };
+}
 export async function runWorker(input) {
     const tools = input.tools ?? DEFAULT_TOOLS;
     const extensionArgs = (input.extensions ?? []).flatMap(e => ['-e', e]);
     const baseArgs = [...extensionArgs, ...CHILD_BASE_ARGS, '--mode', 'json', '--tools', tools];
+    const timeoutMs = input.timeoutMs ?? RESEARCH_WORKER_TIMEOUT_MS;
     let hint = null;
-    for (let attempt = 0;; attempt++) {
+    // Loop-kill and timeout share one restart budget, mirroring
+    // runPhaseWithLoopGuard: a runaway worker gets re-spawned with a corrective
+    // hint up to MAX_LOOP_RESTARTS times before we give up. Leaked tool calls
+    // keep their own MAX_LEAK_RETRIES budget below — a different failure mode.
+    let restarts = 0;
+    let leakRetries = 0;
+    for (;;) {
         const prompt = hint === null ? input.prompt : `${hint}\n\n${input.prompt}`;
         const invocation = getPiInvocation([...baseArgs, prompt]);
         const tStart = Date.now();
         let tFirstByte = null;
-        const loopDetector = new LoopDetector(20, 5);
-        const result = await runChildDefault(invocation, input.cwd, input.signal, {
-            mode: 'json-events',
-            onFirstByte: () => (tFirstByte = Date.now()),
-            onToolCall: call => loopDetector.record(call),
-            onLine: input.onLine
-        }, input.spawn);
+        const loopDetector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
+        // Capture the hit the detector reports (it also returns it to the unified
+        // runner, which kills the child on a hit). Without capturing it here the
+        // SIGTERM that kill produces would surface as a bare non-zero exit the
+        // caller couldn't distinguish from a crash.
+        let loopHit;
+        const timeout = workerTimeout(input.signal, timeoutMs);
+        let result;
+        try {
+            result = await runChildDefault(invocation, input.cwd, timeout.signal, {
+                mode: 'json-events',
+                onFirstByte: () => (tFirstByte = Date.now()),
+                onToolCall: call => {
+                    const hit = loopDetector.record(call);
+                    if (hit && !loopHit)
+                        loopHit = hit;
+                    return hit;
+                },
+                onLine: input.onLine
+            }, input.spawn);
+        }
+        finally {
+            timeout.cleanup();
+        }
         const tEnd = Date.now();
         const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;
         const workMs = tFirstByte === null ? 0 : tEnd - tFirstByte;
         const text = result.text ?? '';
+        const timedOut = timeout.timedOut();
+        // A loop-kill gets the same restart-with-hint treatment every other phase
+        // already gets (runPhaseWithLoopGuard) — name the offending call so the
+        // re-spawn avoids it. Bounded by the shared restart budget.
+        if (loopHit && restarts < MAX_LOOP_RESTARTS) {
+            hint = formatLoopHint(loopHit);
+            restarts++;
+            continue;
+        }
+        // A wall-clock timeout (the backstop for varied thrash the exact-match
+        // detector misses) is also restartable, sharing the same budget. Skip when
+        // a loop also tripped — the loop hint above is more specific.
+        if (timedOut && !loopHit && restarts < MAX_LOOP_RESTARTS) {
+            hint = WORKER_TIMEOUT_HINT;
+            restarts++;
+            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.
         const leaked = result.exitCode === 0 && !result.aborted ? detectLeakedToolCall(text) : null;
-        if (leaked && attempt < MAX_LEAK_RETRIES) {
+        if (leaked && leakRetries < MAX_LEAK_RETRIES) {
             hint = leakedToolCallHint(leaked);
+            leakRetries++;
             continue;
         }
         return {
@@ -46,7 +132,9 @@ export async function runWorker(input) {
             aborted: result.aborted,
             waitMs,
             workMs,
-            ...(leaked ? { leakedToolCall: leaked } : {})
+            ...(leaked ? { leakedToolCall: leaked } : {}),
+            ...(loopHit ? { loopHit } : {}),
+            ...(timedOut ? { timedOut: true } : {})
         };
     }
 }

package/package.json

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