@mjasnikovs/pi-task 0.13.16 → 0.13.18

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

@@ -26,6 +26,30 @@ 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 AND any per-task decisions into every
+ * decomposed task title. A title is ALL a per-task pipeline ever sees, so both
+ * the design doc the feature pointed at and the user's clarification choices have
+ * to ride along or they're invisible downstream — this is how an "Implement
+ * @design.md" run built a generic `posts` table the spec never mentioned, and how
+ * a "do not use vite" clarification got silently overridden by the doc's own
+ * vite.config.ts.
+ *
+ * Precedence is the crux: a clarification is a CORRECTION to a (possibly stale)
+ * spec doc, so the decisions clause is marked as overriding the doc, while the doc
+ * stays authoritative for everything the decisions don't touch. Decompose scopes
+ * each decision to the task(s) it governs, so most titles carry none. No readable
+ * refs and no decisions → title 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,66 @@ 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;
+}
+/** A trailing "[decisions: …]" clause decompose may attach to a task line. */
+const DECISIONS_RE = /\s*\[decisions:\s*(.+?)\]\s*$/i;
+/**
+ * Thread the feature's spec references AND any per-task decisions into every
+ * decomposed task title. A title is ALL a per-task pipeline ever sees, so both
+ * the design doc the feature pointed at and the user's clarification choices have
+ * to ride along or they're invisible downstream — this is how an "Implement
+ * @design.md" run built a generic `posts` table the spec never mentioned, and how
+ * a "do not use vite" clarification got silently overridden by the doc's own
+ * vite.config.ts.
+ *
+ * Precedence is the crux: a clarification is a CORRECTION to a (possibly stale)
+ * spec doc, so the decisions clause is marked as overriding the doc, while the doc
+ * stays authoritative for everything the decisions don't touch. Decompose scopes
+ * each decision to the task(s) it governs, so most titles carry none. No readable
+ * refs and no decisions → title unchanged, so a doc-less /task-auto behaves
+ * exactly as before.
+ */
+export function attachSpecRefs(titles, refs) {
+    const list = refs.map(r => '@' + r).join(' ');
+    return titles.map(t => {
+        if (t.includes('| spec:') || t.includes('| decisions'))
+            return t; // already threaded
+        const dm = DECISIONS_RE.exec(t);
+        const base = dm ? t.slice(0, dm.index).trimEnd() : t;
+        const decisions = dm ? dm[1].trim() : '';
+        let out = base;
+        if (decisions) {
+            out += ` | decisions (explicit user choices — these OVERRIDE the spec doc wherever they conflict; follow them exactly): ${decisions}`;
+        }
+        if (refs.length > 0) {
+            out += ` | spec: ${list} — otherwise authoritative; read it and follow it over this title wherever they differ`;
+        }
+        return out;
+    });
+}
 /** 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 +198,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;

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
@@ -81,4 +82,10 @@ RULES:
 - Order tasks so earlier ones unblock later ones (foundations first).
 - Each task should be independently implementable as a single /task run.
 - Prefer a handful of substantial tasks over many trivial ones.
+- When a CLARIFICATION decision governs a task, append it to that task's line as
+  "[decisions: <directive>]" — include ONLY the decisions that bear on that task,
+  and attach a cross-cutting decision to EACH task it governs. Most tasks carry
+  none. These are explicit user choices that may contradict the referenced spec
+  doc; phrase them as imperative directives (e.g. "use Bun's built-in bundler, do
+  not add vite"). Do NOT invent decisions — only restate ones from CLARIFICATIONS.
 - Output the checkbox list and NOTHING else (no preamble, no numbering).`;

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/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.16",
+    "version": "0.13.18",
     "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",