@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/lint-fix.js

@@ -261,6 +261,7 @@ export async function runBoundedLintFix(deps) {
         deps.log?.(`lint-fix REVERT-GUARD — discarded ${violations.length} work file(s)`);
         return {
             ok: false,
+            class: 'not-applied',
             reason: `revert-guard: fix pass discarded work (${violations.slice(0, 3).join(', ')}`
                 + `${violations.length > 3 ? ', …' : ''}) — fix ${snapshot ? 'rolled back' : 'REJECTED but no snapshot to restore'}`
         };
@@ -288,6 +289,7 @@ export async function runBoundedLintFix(deps) {
                 deps.log?.(`lint-fix CROSS-TASK-DELETION GUARD — ${named[0]}`);
                 return {
                     ok: false,
+                    class: 'not-applied',
                     reason: `cross-task-deletion: fix child DELETED sibling task deliverable(s) `
                         + `(${named.slice(0, 3).join('; ')}${crossDeletions.length > 3 ? '; …' : ''}) `
                         + `— restored from HEAD; deleting another task's committed work is not a fix`
@@ -311,6 +313,8 @@ export async function runBoundedLintFix(deps) {
                 deps.log?.(`lint-fix FROZEN-PATH GUARD — ${frozenViolations.slice(0, 3).join(', ')}`);
                 return {
                     ok: false,
+                    class: 'frozen-path',
+                    contradiction: { criterion: deps.failReason, frozenPath: frozenViolations[0] },
                     reason: `frozen-path: fix child modified spec-frozen path(s) `
                         + `(${frozenViolations.slice(0, 3).join(', ')}`
                         + `${frozenViolations.length > 3 ? ', …' : ''}) — `
@@ -322,7 +326,7 @@ export async function runBoundedLintFix(deps) {
     }
     if (end.kind === 'error') {
         deps.log?.(`lint-fix child failed — ${end.msg}`);
-        return { ok: false, reason: `fix child failed: ${end.msg}` };
+        return { ok: false, class: 'not-applied', reason: `fix child failed: ${end.msg}` };
     }
     if (end.kind === 'blocked')
         deps.log?.(`lint-fix BLOCKED — ${end.note}`);
@@ -344,28 +348,30 @@ export async function runBoundedLintFix(deps) {
     const health = await deps.repoHealth();
     if (!health.ok) {
         if (end.kind === 'blocked') {
-            return { ok: false, reason: `fix child blocked: ${end.note}` };
+            return { ok: false, class: 'not-applied', reason: `fix child blocked: ${end.note}` };
         }
         // FROZEN-PATH TRACE on non-convergence: when the child was honest — it did
         // NOT touch the frozen path, so the guard above never tripped — but the
         // check is still red and its own output NAMES a frozen path (the typed
         // ESLint message quoted in this file's header), the findings can only be
-        // fixed by an edit this task's spec forbids. Report it under the same
-        // `frozen-path:` prefix as the guard trip, so the gate loop can route
-        // straight to the human picker instead of burning unattended AUTOFIX
-        // rounds an impl re-run under the same freeze cannot converge out of.
+        // fixed by an edit this task's spec forbids. Report the same
+        // `frozen-path` class as the guard trip, so the gate's decision table
+        // exits on round one instead of burning unattended AUTOFIX rounds an impl
+        // re-run under the same freeze cannot converge out of.
         const implicated = frozen.filter(p => pathNamedIn(`${health.reason}\n${health.output ?? ''}`, p));
         if (implicated.length > 0) {
             deps.log?.(`lint-fix FROZEN-PATH TRACE — ${implicated.slice(0, 3).join(', ')}`);
             return {
                 ok: false,
+                class: 'frozen-path',
+                contradiction: { criterion: health.reason, frozenPath: implicated[0] },
                 reason: `frozen-path: static findings implicate spec-frozen path(s) `
                     + `(${implicated.slice(0, 3).join(', ')}`
                     + `${implicated.length > 3 ? ', …' : ''}) — did not converge `
                     + `(${health.reason}); a fix under this task's constraints cannot converge`
             };
         }
-        return { ok: false, reason: `did not converge: ${health.reason}` };
+        return { ok: false, class: 'not-applied', reason: `did not converge: ${health.reason}` };
     }
-    return { ok: true, reason: guardNote };
+    return { ok: true, class: 'converged', ...(guardNote === undefined ? {} : { reason: guardNote }) };
 }

package/dist/task/loop-detector.d.ts

@@ -30,7 +30,15 @@ export interface ToolCall {
 export interface LoopHit {
     call: ToolCall;
     count: number;
-    windowSize: number;
+    /**
+     * How many recent calls `count` was counted over.
+     *
+     * OPTIONAL because a stall hit counts a streak or a byte total, not a window
+     * — it used to carry 0 there, which every renderer printed as "in the last 0
+     * calls". Absent means "this hit has no window"; a renderer must say what the
+     * hit actually measured instead.
+     */
+    windowSize?: number;
     /**
      * Set when the kill came from the whole-run StallDetector rather than this
      * short-window detector, naming which of its two rules tripped
@@ -63,11 +71,25 @@ export declare class LoopDetector {
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     private readonly pathThreshold;
     private readonly buf;
+    /**
+     * Every path the attempt has targeted, with the span it covered — the WHOLE
+     * attempt, not the window `buf` holds. It is the only record of what a killed
+     * attempt actually read: the kill fires from the tool-call hook, before a byte
+     * of answer text streams, so text carry-forward is empty by construction and
+     * the re-spawn would otherwise start blind.
+     */
+    private readonly visits;
     constructor(window?: number, threshold?: number, 
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     pathThreshold?: number);
     /** Record a tool call. Returns LoopHit if either threshold is breached, else null. */
     record(call: ToolCall): LoopHit | null;
+    /**
+     * The attempt's READ-SET, in first-seen order: every path it opened, with the
+     * line span when the call named one. This is what a restart carries instead of
+     * answer text — see {@link visits}.
+     */
+    visited(): string[];
     /**
      * Count same-path calls in the window that are "revisits" — accesses that end
      * no further into the file than the furthest line already covered for that
@@ -84,5 +106,32 @@ export declare class LoopDetector {
      */
     private countRevisits;
 }
-/** The restart hint a re-spawned child gets after a loop kill: names the call. */
-export declare function formatLoopHint(hit: LoopHit): string;
+/**
+ * What killed the attempt, as prose a human reads in a degraded section or a
+ * `loop events` line.
+ *
+ * ONE renderer because each rule measures something different — calls in a
+ * window, a consecutive streak, bytes against a context window — and a shared
+ * "×N in the last M calls" template printed the streak's absent window as
+ * "in the last 0 calls".
+ */
+export declare function describeLoopHit(hit: LoopHit): string;
+/**
+ * The read-set clause a restart hint carries, or '' when the killed attempt
+ * opened nothing.
+ *
+ * It is the only thing a loop restart CAN carry: the kill fires from the
+ * tool-call hook, so there is no partial answer to hand forward (which is why
+ * `loop` is absent from CARRY_FORWARD_REASONS in pi-worker-core.ts). Without it
+ * "do not re-read what you have already read" names no files and the re-spawn
+ * re-reads the same ones.
+ *
+ * Bounded so a rotation over hundreds of files cannot outgrow the prompt it is
+ * prepended to; the count keeps the elision honest.
+ */
+export declare function formatReadSet(visited: readonly string[]): string;
+/**
+ * The restart hint a re-spawned child gets after a loop kill: names the call, and
+ * the read-set the killed attempt built up.
+ */
+export declare function formatLoopHint(hit: LoopHit, visited?: readonly string[]): string;

package/dist/task/loop-detector.js

@@ -96,6 +96,14 @@ export class LoopDetector {
     threshold;
     pathThreshold;
     buf = [];
+    /**
+     * Every path the attempt has targeted, with the span it covered — the WHOLE
+     * attempt, not the window `buf` holds. It is the only record of what a killed
+     * attempt actually read: the kill fires from the tool-call hook, before a byte
+     * of answer text streams, so text carry-forward is empty by construction and
+     * the re-spawn would otherwise start blind.
+     */
+    visits = new Map();
     constructor(window = LOOP_WINDOW, threshold = LOOP_THRESHOLD, 
     /** Revisits of one path needed to trip; defaults to the exact threshold. */
     pathThreshold = threshold) {
@@ -107,9 +115,17 @@ export class LoopDetector {
     record(call) {
         const key = loopKey(call);
         const offset = readOffset(call.args);
-        this.buf.push({ key, path: primaryPath(call.args), offset, end: readEnd(call.args, offset) });
+        const path = primaryPath(call.args);
+        const end = readEnd(call.args, offset);
+        this.buf.push({ key, path, offset, end });
         if (this.buf.length > this.window)
             this.buf.shift();
+        if (path !== null) {
+            const seen = this.visits.get(path);
+            this.visits.set(path, seen ?
+                { from: Math.min(seen.from, offset), to: Math.max(seen.to, end) }
+                : { from: offset, to: end });
+        }
         // 1. Exact-match loop: identical (name, args) repeated past threshold.
         let exact = 0;
         for (const e of this.buf)
@@ -120,7 +136,6 @@ export class LoopDetector {
         // 2. Path-aware loop: the same file re-targeted without forward progress.
         // Caught here precisely because varied offset/limit change the exact key on
         // every call, so pattern 1 above can never see it.
-        const path = this.buf[this.buf.length - 1].path;
         if (path !== null) {
             const revisits = this.countRevisits(path);
             if (revisits >= this.pathThreshold) {
@@ -129,6 +144,14 @@ export class LoopDetector {
         }
         return null;
     }
+    /**
+     * The attempt's READ-SET, in first-seen order: every path it opened, with the
+     * line span when the call named one. This is what a restart carries instead of
+     * answer text — see {@link visits}.
+     */
+    visited() {
+        return [...this.visits].map(([path, span]) => span.to === Infinity ? path : `${path} (lines ${span.from}-${span.to})`);
+    }
     /**
      * Count same-path calls in the window that are "revisits" — accesses that end
      * no further into the file than the furthest line already covered for that
@@ -157,11 +180,64 @@ export class LoopDetector {
         return revisits;
     }
 }
-/** The restart hint a re-spawned child gets after a loop kill: names the call. */
-export function formatLoopHint(hit) {
+/**
+ * What killed the attempt, as prose a human reads in a degraded section or a
+ * `loop events` line.
+ *
+ * ONE renderer because each rule measures something different — calls in a
+ * window, a consecutive streak, bytes against a context window — and a shared
+ * "×N in the last M calls" template printed the streak's absent window as
+ * "in the last 0 calls".
+ */
+export function describeLoopHit(hit) {
+    const call = `${hit.call.name}(${JSON.stringify(hit.call.args)})`;
+    if (hit.stall === 'context-churn') {
+        return (`pulled in about ${hit.count} tokens of tool output, more than its `
+            + `${hit.windowSize}-token context window holds (last call ${call})`);
+    }
+    if (hit.stall === 'no-new-ground') {
+        return (`stopped covering new ground — ${hit.count} consecutive tool calls returned `
+            + `nothing it had not already seen (last call ${call})`);
+    }
+    return `stuck in a loop — called ${call} ×${hit.count} in the last ${hit.windowSize} calls`;
+}
+/**
+ * The read-set clause a restart hint carries, or '' when the killed attempt
+ * opened nothing.
+ *
+ * It is the only thing a loop restart CAN carry: the kill fires from the
+ * tool-call hook, so there is no partial answer to hand forward (which is why
+ * `loop` is absent from CARRY_FORWARD_REASONS in pi-worker-core.ts). Without it
+ * "do not re-read what you have already read" names no files and the re-spawn
+ * re-reads the same ones.
+ *
+ * Bounded so a rotation over hundreds of files cannot outgrow the prompt it is
+ * prepended to; the count keeps the elision honest.
+ */
+export function formatReadSet(visited) {
+    if (visited.length === 0)
+        return '';
+    const shown = visited.slice(0, MAX_READ_SET_ENTRIES);
+    const rest = visited.length - shown.length;
+    return (` You have already read, do not re-open: ${shown.join(', ')}`
+        + (rest > 0 ? `, and ${rest} more` : '')
+        + '.');
+}
+/**
+ * How many paths a restart hint lists. The read-set is a reminder, not an
+ * inventory: past a screenful the tail stops being read and only costs prefill,
+ * and the elision line still tells the child there was more.
+ */
+const MAX_READ_SET_ENTRIES = 40;
+/**
+ * The restart hint a re-spawned child gets after a loop kill: names the call, and
+ * the read-set the killed attempt built up.
+ */
+export function formatLoopHint(hit, visited = []) {
     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 `
         + `stuck in a loop. Avoid repeating that exact call; if you've already seen its result, `
-        + `work from memory or pick a different angle.]`);
+        + `work from memory or pick a different angle.`
+        + `${formatReadSet(visited)}]`);
 }

package/dist/task/mentions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Expand any @file references in the feature text by appending each referenced
+ * file's contents, so the planning children (clarify, decompose) always see the
+ * real spec inline instead of relying on the model to open the file itself.
+ * Without this, clarify on a one-line "Implement @spec.md" tends to bail with
+ * NONE because, to the model, the request looks small and unambiguous.
+ * Unreadable mentions (typos, non-file @tokens) are left untouched; the feature
+ * 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[]>;

package/dist/task/mentions.js

@@ -0,0 +1,86 @@
+/**
+ * `@file` references in a prompt, and the two things done with them: inlining the
+ * file's contents for the planning children, and naming the files themselves.
+ *
+ * Its own module because both the PLANNING side (auto-orchestrator, which threads
+ * the spec doc into every task title) and the PHASE side (research, which lets the
+ * orientation core select a cited doc) need the same answer, and the phase side
+ * cannot import the orchestrator that imports it.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { readTextFile } from '../shared/fs-text.js';
+const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
+// Trailing punctuation a user naturally types AFTER an @-mention when it sits in
+// prose — "Implement @design.md, reuse…" or "see @spec.md." — which the greedy
+// [^\s]+ above would otherwise swallow into the path. Left unstripped, the
+// resulting "design.md," resolves to no file, expansion is silently skipped, and
+// the planner reasons over a one-line "Implement @design.md" with NO spec inline
+// → it fabricates generic questions and tasks the spec never called for.
+//
+// Measured against a real file: the greedy token from "Implement @design.md,
+// reuse the parser" is `design.md,`, which does not exist; stripped, `design.md`
+// does. None of these chars are legitimate trailing characters of a doc path.
+const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
+/** The cleaned path token of an @-mention: greedy match minus trailing prose punctuation. */
+function mentionPath(token) {
+    return token.replace(MENTION_TRAILING_PUNCT, '');
+}
+/** Every distinct @-mention path in `text`, in first-seen order. */
+function mentionPaths(text) {
+    const out = [];
+    const seen = new Set();
+    for (const m of text.matchAll(MENTION_RE)) {
+        const rel = mentionPath(m[1]);
+        if (rel === '' || seen.has(rel))
+            continue;
+        seen.add(rel);
+        out.push(rel);
+    }
+    return out;
+}
+/**
+ * Expand any @file references in the feature text by appending each referenced
+ * file's contents, so the planning children (clarify, decompose) always see the
+ * real spec inline instead of relying on the model to open the file itself.
+ * Without this, clarify on a one-line "Implement @spec.md" tends to bail with
+ * NONE because, to the model, the request looks small and unambiguous.
+ * Unreadable mentions (typos, non-file @tokens) are left untouched; the feature
+ * is returned verbatim when nothing readable is referenced.
+ */
+export async function expandFeatureMentions(cwd, feature) {
+    const blocks = [];
+    for (const rel of mentionPaths(feature)) {
+        try {
+            // Normalize CRLF/CR so an @-mentioned design doc saved on Windows
+            // inlines with LF endings the downstream phase parsers expect.
+            const body = await readTextFile(path.resolve(cwd, rel));
+            if (body.trim().length > 0) {
+                blocks.push(`--- contents of ${rel} ---\n${body.trim()}`);
+            }
+        }
+        catch {
+            // not a readable file — leave the @token in place, skip expansion
+        }
+    }
+    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 = [];
+    for (const rel of mentionPaths(feature)) {
+        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;
+}

package/dist/task/orchestrator.d.ts

@@ -19,6 +19,8 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type WidgetState } from './widget.js';
 import { type RunTaskFn } from './gate-deps.js';
+import { type HealthBaseline } from './health-baseline.js';
+import { type FixContext } from './fix-context.js';
 import { type GateDeps } from './task-gates.js';
 import { type PhaseSeams } from './child-runner.js';
 import type { PiModel } from '../shared/model-resolve.js';
@@ -68,14 +70,34 @@ export interface TaskRunnerOptions {
      */
     planContext?: string;
     /**
-     * Marks this run as a verify-FAIL re-attempt. When set (only by /task-auto's
-     * autofix path, with `resumeId` pointing at the already-composed task), the
-     * text — the verify gate's failure reason plus any guidance the user typed —
-     * is prepended to the delivered spec as a RE-ATTEMPT banner, so the
-     * implementer fixes the specific failure and re-satisfies the VERIFY block
-     * rather than blindly redoing the task. Empty/undefined on a first attempt.
+     * The /task-auto plan entry this run implements (`TaskEntry.key`). Recorded in
+     * the task file's front matter, which is where every phase reads it back —
+     * this option only exists to carry it in on a fresh start. Undefined for a
+     * bare /task, which belongs to no plan.
      */
-    fixInstruction?: string;
+    planKey?: string;
+    /**
+     * Marks this run as a verify-FAIL re-attempt (set only by the gate loop's
+     * autofix path, with `resumeId` pointing at the already-composed task):
+     * everything the gate knows about the failure — its class, the attempt
+     * number, what the deterministic probes found, any spec contradiction —
+     * rendered ahead of the delivered spec by `formatFixBanner`. Undefined on a
+     * first attempt.
+     */
+    fixContext?: FixContext;
+    /**
+     * The repo-health baseline for the tree this task starts from
+     * (health-baseline.ts), written to `## health baseline` once the task file
+     * exists. A thunk because only the runner knows whether the file already
+     * carries one — a resumed or auto-fixed task must keep the ORIGINAL baseline,
+     * and re-running the project's statics to discard the result is the cost this
+     * saves. Absent → no section, and the verify gate establishes one lazily.
+     *
+     * It is handed the RUNNER'S ctx, not the caller's: `runSingleTask` replaces the
+     * session before the runner starts, so the ctx a call site closed over is torn
+     * down by the time this fires and its status loader would throw on it.
+     */
+    healthBaseline?: (ctx: ExtensionCommandContext) => Promise<HealthBaseline | null>;
     /** 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
@@ -91,7 +113,9 @@ export declare class TaskRunner {
     private readonly _sendSpec;
     private readonly _onStart;
     private readonly _planContext;
-    private readonly _fixInstruction;
+    private readonly _planKey;
+    private readonly _fixContext;
+    private readonly _healthBaseline;
     /** See {@link TaskRunnerOptions.implAwaited}. */
     private readonly _implAwaited;
     private readonly _abort;
@@ -109,6 +133,12 @@ export declare class TaskRunner {
      */
     private readonly _timings;
     private _currentPhaseChildren;
+    /**
+     * Whether this run has already appended its timings block. The success path
+     * writes, and a cancel raised AFTER it still lands in the catch — which would
+     * otherwise append a second block for the same attempt.
+     */
+    private _timingsWritten;
     constructor(opts: TaskRunnerOptions);
     get taskId(): string;
     get signal(): AbortSignal;
@@ -127,12 +157,26 @@ export declare class TaskRunner {
      * `runSingleTask` path on its own.
      */
     run(): Promise<RunEnd>;
+    /**
+     * Store the task's repo-health baseline, ONCE. A re-entry — a resume, an
+     * autofix re-run — must keep the original: the baseline answers "what was
+     * already broken when this task started", and re-taking it on a tree the task
+     * has since edited answers a different question with the same name.
+     */
+    private _writeHealthBaseline;
     private _run;
     /** Stop the phase widget — clearing both the terminal and remote surfaces —
      *  exactly once. Nulling the disposer makes repeat calls no-ops, so the
      *  failure flash that handleFailure sets after the catch isn't wiped by the
      *  finally block's call. */
     private _disposeWidget;
+    private _writeTimings;
+    /**
+     * Append this delivery to the `## handoff` ledger. The attempt number is the
+     * count of deliveries already recorded rather than anything this process
+     * carries: a re-entry is a FRESH runner and knows nothing of the one before it.
+     */
+    private _recordHandoff;
     private _deliverSpec;
     /**
      * The spec as the implementer should receive it (Layer B). Layer A strips phantom
@@ -145,7 +189,7 @@ export declare class TaskRunner {
      */
     private _specForDelivery;
 }
-export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId' | 'seams' | 'onStart' | 'planContext' | 'fixInstruction'> {
+export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId' | 'seams' | 'onStart' | 'planContext' | 'planKey' | 'fixContext' | 'healthBaseline'> {
     /** Await the session going idle after the spec is delivered, so the caller
      *  blocks until the agent has implemented it. Default false. */
     waitForImplementation?: boolean;