@mjasnikovs/pi-task 0.40.50 → 0.41.0

package/dist/task/orchestrator.js

@@ -23,15 +23,18 @@ import { handleFailure } from './failure-classifier.js';
 import { PHASE_INDEX, PHASE_ORDER, RESUMABLE_STATES } from './task-types.js';
 import { normaliseTaskId, parseFrontMatter, extractSection } from './task-parsers.js';
 import { readTextFile } from '../shared/fs-text.js';
-import { allocateTaskId, ensureTasksDir, readSection, readTaskFile, setTaskSection, taskFilePath, tasksDir, updateTaskFrontMatter, writeTaskFile } from './task-io.js';
+import { allocateTaskId, ensureTasksDir, mergeTaskSection, readSection, readTaskFile, setTaskSection, taskFilePath, tasksDir, updateTaskFrontMatter, writeTaskFile } from './task-io.js';
 import { startWidget } from './widget.js';
 import { setupImplWidget } from './impl-widget.js';
 import { enterImplementationTurn } from './implementation-scope.js';
 import { SessionUI, publishNotify, registerBridgeCommand, getBridge, notifyBoth, isRemoteOrigin } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
-import { gateDebugWriter } from './debug-log.js';
+import { appendDebugLine, gateDebugWriter } from './debug-log.js';
+import { runLogPath } from './state-dir.js';
 import { buildGateDeps } from './gate-deps.js';
+import { formatHealthBaseline, HEALTH_BASELINE_SECTION } from './health-baseline.js';
+import { formatFixBanner } from './fix-context.js';
 import { runGatesForTask } from './task-gates.js';
 import { parseVerifyBlock } from './spec-validation.js';
 import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phantom-imports.js';
@@ -42,8 +45,10 @@ import { holdImplementation, liveModelControl } from './implementation-hold.js';
 import { rearmCancelListener } from './cancel-input.js';
 import { takeHeldInput, isRunActive } from './mid-run-input.js';
 import { withRun, announceTerminal } from './run-bracket.js';
+import { currentRunContext } from './run-context.js';
 import { RUN_END_POLICY, runSucceeded } from './run-end.js';
-import { formatTimings } from './timings.js';
+import { mergeTimings } from './timings.js';
+import { appendHandoff, parseHandoff, specHash, summariseFixContext } from './handoff.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
 import { superviseImplementation } from './implementation-turn.js';
 import { TERMINAL_OUTCOMES, formatAt, formatWhy } from './terminal-outcome.js';
@@ -102,7 +107,9 @@ export class TaskRunner {
     _sendSpec;
     _onStart;
     _planContext;
-    _fixInstruction;
+    _planKey;
+    _fixContext;
+    _healthBaseline;
     /** See {@link TaskRunnerOptions.implAwaited}. */
     _implAwaited;
     _abort = new AbortController();
@@ -120,6 +127,12 @@ export class TaskRunner {
      */
     _timings = [];
     _currentPhaseChildren = null;
+    /**
+     * 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.
+     */
+    _timingsWritten = false;
     constructor(opts) {
         const { ctx, cwd, rawPrompt } = opts;
         this._ctx = ctx;
@@ -129,7 +142,9 @@ export class TaskRunner {
         this._sendSpec = opts.sendSpec;
         this._onStart = opts.onStart;
         this._planContext = opts.planContext;
-        this._fixInstruction = opts.fixInstruction;
+        this._planKey = opts.planKey;
+        this._fixContext = opts.fixContext;
+        this._healthBaseline = opts.healthBaseline;
         this._implAwaited = opts.implAwaited ?? false;
         this._startedAt = Date.now();
         // Placeholder: id/title/phase are only known once run() has allocated or
@@ -207,9 +222,34 @@ export class TaskRunner {
     async run() {
         return withRun(this._ctx, {}, () => this._run());
     }
+    /**
+     * 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.
+     */
+    async _writeHealthBaseline(cwd, id) {
+        if (!this._healthBaseline)
+            return;
+        try {
+            if ((await readSection(cwd, id, HEALTH_BASELINE_SECTION)) !== null)
+                return;
+            const baseline = await this._healthBaseline(this._ctx);
+            if (!baseline)
+                return;
+            await setTaskSection(cwd, id, HEALTH_BASELINE_SECTION, formatHealthBaseline(baseline));
+        }
+        catch {
+            // The gate establishes one lazily; never fail a run over the baseline.
+        }
+    }
     async _run() {
         const cwd = this._cwd;
         const ctx = this._ctx;
+        // Resolved HERE, not in the constructor: the run bracket that owns the
+        // per-run facts is opened by `run()`, one statement before this. A
+        // caller-supplied seam wins, like `logDebug` below.
+        this._deps.runContext ??= currentRunContext(cwd);
         // Initialise or resume the TASK file.
         let id;
         let title;
@@ -221,7 +261,13 @@ export class TaskRunner {
             title = frontMatter.title;
             label = frontMatter.label;
             resumePhase = frontMatter.phase;
-            await updateTaskFrontMatter(cwd, id, { state: 'in_progress' });
+            // A re-entry backfills the plan key onto a file written before this
+            // run knew one (an older task, or a resume that reaches a task the
+            // plan has since keyed); it never clears one already on disk.
+            await updateTaskFrontMatter(cwd, id, {
+                state: 'in_progress',
+                ...(this._planKey !== undefined && { plan_key: this._planKey })
+            });
         }
         else {
             id = await allocateTaskId(cwd);
@@ -233,7 +279,8 @@ export class TaskRunner {
                 phase: 'refine',
                 created_at: now,
                 updated_at: now,
-                title
+                title,
+                ...(this._planKey !== undefined && { plan_key: this._planKey })
             };
             await writeTaskFile(cwd, fm, `\n## raw prompt\n\n${this._rawPrompt.trim() || '(none)'}\n`);
         }
@@ -242,8 +289,9 @@ export class TaskRunner {
         // any phase work — and recover it if the session dies mid-pipeline.
         if (this._onStart)
             await this._onStart(id);
-        // Wire up per-task debug log (<cwd>/.pi-tasks/TASK_XXXX-debug.log).
-        const debugLogPath = path.join(tasksDir(cwd), `${id}-debug.log`);
+        await this._writeHealthBaseline(cwd, id);
+        // Wire up the per-task debug log in this run's state dir (state-dir.ts).
+        const debugLogPath = runLogPath(cwd, `${id}-debug.log`);
         // `gateDebugWriter` returns undefined at level `off`, so every
         // `logDebug?.(…)` site downstream short-circuits before it formats a string
         // and the file is never created. A caller-supplied `logDebug` seam WINS
@@ -251,10 +299,7 @@ export class TaskRunner {
         // runner-driven test, and production never sets one, so the file writer is
         // unaffected.
         this._deps.logDebug ??= gateDebugWriter((msg) => {
-            const line = `${new Date().toISOString()} ${msg}\n`;
-            fsp.appendFile(debugLogPath, line).catch(() => {
-                /* ignore */
-            });
+            appendDebugLine(debugLogPath, msg);
         });
         this._deps.logDebug?.(`run: start phase=${resumePhase}`);
         // Register as active.
@@ -331,9 +376,10 @@ export class TaskRunner {
                 throw new Error('no_verify_block');
             await updateTaskFrontMatter(cwd, id, { state: 'completed', phase: 'done' });
             this._disposeWidget();
-            await setTaskSection(cwd, id, 'phase timings', formatTimings(this._timings));
-            await setTaskSection(cwd, id, 'handoff', `handoff_at: ${new Date().toISOString()}`);
-            await this._deliverSpec(ctx);
+            await this._writeTimings(cwd, id);
+            const spec = await this._specForDelivery();
+            await this._recordHandoff(cwd, id, spec);
+            await this._deliverSpec(spec);
             // SAFE CHECKPOINT (post implementation turn): every phase section is
             // on disk and the turn has ENDED. Its edits are uncommitted, so a
             // resume re-delivers the spec onto the partly-edited tree — the same
@@ -367,7 +413,7 @@ export class TaskRunner {
             // useful for analysis. Best-effort — never mask the original error.
             if (this._timings.length > 0) {
                 try {
-                    await setTaskSection(cwd, id, 'phase timings', formatTimings(this._timings));
+                    await this._writeTimings(cwd, id);
                 }
                 catch {
                     /* ignore — preserve original failure */
@@ -393,8 +439,30 @@ export class TaskRunner {
         this._stopWidget?.();
         this._stopWidget = null;
     }
-    async _deliverSpec(_ctx) {
-        const spec = await this._specForDelivery();
+    async _writeTimings(cwd, id) {
+        if (this._timingsWritten)
+            return;
+        this._timingsWritten = true;
+        await mergeTaskSection(cwd, id, 'phase timings', prev => mergeTimings(prev, this._timings));
+    }
+    /**
+     * 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.
+     */
+    async _recordHandoff(cwd, id, spec) {
+        const fix = this._fixContext;
+        await mergeTaskSection(cwd, id, 'handoff', prev => {
+            const record = {
+                attempt: parseHandoff(prev).length + 1,
+                specHash: specHash(spec),
+                delivered: fix ? 'reattempt' : 'fresh',
+                ...(fix ? { fixContext: summariseFixContext(fix) } : {})
+            };
+            return appendHandoff(prev, record);
+        });
+    }
+    async _deliverSpec(spec) {
         // 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
@@ -463,13 +531,9 @@ export class TaskRunner {
         // specific failure and re-satisfies the VERIFY block, rather than redoing
         // the task from scratch (or repeating the same mistake).
         let fixBanner = '';
-        if (this._fixInstruction && this._fixInstruction.trim().length > 0) {
+        if (this._fixContext) {
             this._deps.logDebug?.('impl-handoff RE-ATTEMPT banner prepended (verify FAIL fix)');
-            fixBanner =
-                'RE-ATTEMPT — your previous implementation of this task FAILED verification.\n'
-                    + "Fix the cause below, then make the spec's VERIFY block pass. Do NOT start over;\n"
-                    + 'change only what is needed to resolve the failure.\n\n'
-                    + `VERIFICATION FAILURE:\n${this._fixInstruction.trim()}`;
+            fixBanner = formatFixBanner(this._fixContext);
         }
         const banners = [fixBanner, apiBanner].filter(b => b && b.length > 0).join('\n\n');
         return banners ? `${banners}\n\n${this._pc.spec}` : this._pc.spec;
@@ -547,7 +611,9 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                 seams: opts.seams,
                 onStart: opts.onStart,
                 planContext: opts.planContext,
-                fixInstruction: opts.fixInstruction,
+                planKey: opts.planKey,
+                fixContext: opts.fixContext,
+                healthBaseline: opts.healthBaseline,
                 implAwaited: opts.waitForImplementation
             });
             runEnd = await runner.run();
@@ -593,7 +659,9 @@ export const gateRunTask = (c, cwd, t, opts) => runSingleTask(c, cwd, t, {
     resumeId: opts?.resumeId,
     onStart: opts?.onStart,
     planContext: opts?.planContext,
-    fixInstruction: opts?.fixInstruction
+    planKey: opts?.planKey,
+    fixContext: opts?.fixContext,
+    healthBaseline: opts?.healthBaseline
     // NO `seams` here, deliberately. Threading them would need a field on
     // `GateParams` and another on `GateDeps`, and nothing — production or
     // test — would set either: the gate is reached through two orchestrators
@@ -650,8 +718,16 @@ async function runGatedTaskInner(ctx, cwd, raw, opts = {}) {
     // notifyFinish push the fire-and-forget path emits via runSingleTask).
     // Bound late to `active`: a gate autofix can replace the live session.
     const announce = (msg, level) => announceTerminal(active, msg, level);
+    // The health baseline is taken at /task's OWN start, this task's equivalent of
+    // /task-auto's pre-task checkpoint: the last moment the tree is the one the
+    // task inherited. Lazy — a resumed task file already carries its original and
+    // never pays for the run. There is no composed title yet, so the loader is
+    // labelled with what the user typed, or the id being resumed.
+    const label = opts.resumeId ?? raw;
+    const capture = deps.captureHealthBaseline;
+    const healthBaseline = capture ? { healthBaseline: (c) => capture(c, cwd, label) } : {};
     // First implementation run (blocking).
-    const res = await deps.runTask(active, cwd, raw, { resumeId: opts.resumeId });
+    const res = await deps.runTask(active, cwd, raw, { resumeId: opts.resumeId, ...healthBaseline });
     active = res.ctx ?? active;
     const tag = res.taskId || 'Task';
     // One dispatch over the named ending, so a cancel can never be reported as a

package/dist/task/orientation.d.ts

@@ -1,32 +1,48 @@
 /**
  * Project orientation core — a bounded snapshot of the few files a research worker
- * re-reads cold to learn "what is this project" (manifest, config, domain types,
- * schema, entrypoints, API surface). The four research workers are separate child
- * processes with no shared memory, so without this each one reads the same hot
- * files for itself.
+ * re-reads cold to learn "what is this project" (the doc the task cites, manifest,
+ * config, project rules, domain types, schema, entrypoints, API surface). The four
+ * research workers are separate child processes with no shared memory, so without
+ * this each one reads the same hot files for itself.
  *
  * This module picks that core from the file inventory (repo-agnostic, by path
  * convention) and reads it ONCE in the parent. The caller folds the block into a
- * prompt: refine gets a tier-0/1 subset, and phases.ts prepends the full block to
- * the two READ-HEAVY research workers (`worker:files`, `worker:apis`) — not to all
- * four. It is purely additive: nothing is blocked, so a worker can still read
- * anything it wants; orientation only removes the need to.
+ * prompt: refine gets the manifest/config tiers, and phases.ts prepends the full
+ * block to the three EXPLORING research workers — not to TOOLING. It is purely
+ * additive: nothing is blocked, so a worker can still read anything it wants;
+ * orientation only removes the need to.
+ *
+ * ELIGIBILITY IS A REGISTRY, not a ladder of regexes: {@link ORIENTATION_RULES} is
+ * an ordered list of `{id, tier, match}` rows over an {@link OrientationCandidate},
+ * so "does this file orient" and "how fundamental is it" are one row each, and the
+ * two facts a path cannot carry on its own — whether the task CITES it, and whether
+ * it is VENDORED — are fields on the candidate rather than more pattern-matching.
  *
  * Bounded by design — the snapshot can never overflow the prompt regardless of
- * repo size: a hard total byte budget, a per-file cap (one huge file can't eat
- * the budget), and a candidate cap. Files that don't fit are simply not
- * pre-supplied; the worker reads them as before. Selection is the pure, tested
- * core; reading takes an injectable reader so it can be exercised without a repo.
+ * repo size: a hard total byte budget, a per-file cap so one huge file can't eat
+ * it, a candidate cap, and a second budget of the same size that only cited
+ * documents may draw on. Files that don't fit are simply not pre-supplied; the worker reads
+ * them as before. Selection is the pure, tested core; reading takes an injectable
+ * reader so it can be exercised without a repo.
  */
 /**
  * Total bytes the emitted orientation block may occupy. This is the real overflow
  * guard: it bounds the block regardless of repo size, and because the snapshot is
- * prepended to each read-heavy worker it also caps the prefill those workers pay.
+ * prepended to each exploring worker it also caps the prefill those workers pay.
  * Selection stops as soon as adding a file would exceed it.
  */
 export declare const ORIENTATION_BYTE_BUDGET: number;
 /** A single file larger than this is skipped (read by the worker as before). */
 export declare const ORIENTATION_PER_FILE_MAX: number;
+/**
+ * A SECOND purse, spent only on cited documents.
+ *
+ * A design doc is routinely most of the core budget on its own — the recorded mx5
+ * run's is 29 KB of 40 KB — so charging it to the shared purse buys the one file
+ * the task cites by dropping five files every task needs. Equal to the core
+ * budget, so the block can at most double and the bound stays a stated one.
+ */
+export declare const ORIENTATION_CITED_BYTE_BUDGET: number;
 /**
  * Backstop file-count cap — a guard against a pathological repo with hundreds of
  * tiny core files packing the byte budget into noise, NOT a normal-case limit. Set
@@ -35,37 +51,127 @@ export declare const ORIENTATION_PER_FILE_MAX: number;
  */
 export declare const ORIENTATION_MAX_FILES = 40;
 /**
- * Priority tier for an orientation candidate — lower is more fundamental. The
- * tiers mirror the questions a worker re-derives on every task: what is this
- * project (manifest) → how is it built (config) → what is its domain model
- * (types/schema) → where does it start (entrypoints) → what is its surface (api)
- * → what does it say about itself (docs). Returns null for paths that aren't
- * orientation material, so they're dropped entirely.
+ * The priority ladder, lowest first. The tiers mirror the questions a worker
+ * re-derives on every task: what am I being asked about (the cited doc) → what is
+ * this project (manifest) → how is it built (config) → what rules does it set for
+ * itself (guidelines) → what is its domain model (types/schema) → where does it
+ * start (entrypoints) → what is its surface (api) → what does it say about itself
+ * (docs).
+ *
+ * Named rather than numbered at the call sites: refine asks for "manifest and
+ * config", not for "0 and 1", and a tier inserted in the middle must not silently
+ * change what refine gets.
+ */
+export declare const ORIENTATION_TIERS: {
+    readonly cited: 0;
+    readonly manifest: 1;
+    readonly config: 2;
+    readonly guidelines: 3;
+    readonly domain: 4;
+    readonly entrypoint: 5;
+    readonly api: 6;
+    readonly docs: 7;
+};
+/**
+ * Directories whose contents are never this project's own source: vendored
+ * dependencies, build output, and the agent's own scaffolding. A dependency's
+ * `package.json` is a manifest by basename and `.pi/skills/**` is a wall of
+ * markdown — either would outrank the project's real files and eat the budget.
+ *
+ * A registry rather than one regex so a project can be given more through
+ * `.gitignore` and `orientationExclude` (config.ts) without editing a pattern.
+ */
+export declare const VENDORED_DIRS: readonly string[];
+/** What a rule decides on, beyond the path itself. */
+export interface OrientationCandidate {
+    path: string;
+    /** The task prompt names this file (a readable @-mention): its spec document. */
+    cited: boolean;
+    /** Not this project's own source — see {@link VENDORED_DIRS}. */
+    vendored: boolean;
+}
+/** One eligibility rule: the tier a matching candidate lands in. */
+export interface OrientationRule {
+    id: string;
+    tier: number;
+    match: (c: OrientationCandidate) => boolean;
+    /**
+     * This row identifies a file by its exact name (or because the task cites
+     * it), so {@link ORIENTATION_EXTENSIONS} does not apply. That filter exists to
+     * stop a row from GUESSING at a `.png` or a `.lock`; `Gemfile` and
+     * `requirements.txt` are not guesses.
+     */
+    byName?: true;
+}
+/**
+ * Eligibility, in priority order — FIRST MATCH WINS, and a candidate no row
+ * matches is not orientation material and is dropped entirely.
+ *
+ * The three rejecting rows come first and carry no tier of their own: a vendored
+ * file, a test and an absolute path are excluded whatever else they look like.
+ * They are rows rather than early returns so the whole policy is one list.
+ */
+export declare const ORIENTATION_RULES: ReadonlyArray<OrientationRule>;
+/**
+ * Priority tier for an orientation candidate — lower is more fundamental, null
+ * for a path that is not orientation material.
  */
-export declare function orientationTier(path: string): number | null;
+export declare function orientationTier(path: string, opts?: {
+    cited?: boolean;
+    vendored?: boolean;
+}): number | null;
+/**
+ * Is this path outside the project's own source? `VENDORED_DIRS` plus whatever
+ * `.gitignore` and `orientationExclude` add (see {@link parseIgnorePatterns}).
+ */
+export declare function isVendored(path: string, patterns?: readonly string[]): boolean;
+/**
+ * The usable patterns in a `.gitignore`.
+ *
+ * Negations (`!kept.md`) are DROPPED rather than honoured: un-ignoring is a
+ * whole-file-order semantics this does not implement, and the inventory a real
+ * run orients over is `git ls-files`, which has already applied the real rules.
+ * What is left here only has to keep bulk out.
+ */
+export declare function parseIgnorePatterns(gitignore: string): string[];
+/** One selected file and the tier it was selected at. */
+export interface OrientationPick {
+    path: string;
+    tier: number;
+}
+export interface OrientationSelectOptions {
+    /** Paths the task prompt cites — its spec documents. */
+    cited?: readonly string[];
+    /** `.gitignore` lines plus `orientationExclude`, on top of `VENDORED_DIRS`. */
+    excludePatterns?: readonly string[];
+}
 /**
  * Rank inventory paths into orientation priority order: by tier, then shallower
  * paths first (a root entrypoint beats a deeply-nested one), then alphabetical
  * for a fully deterministic order. Non-orientation paths are dropped. The result
  * is the *candidate* order; the byte budget is applied later when reading.
  */
-export declare function selectOrientationFiles(inventoryPaths: string[]): string[];
+export declare function selectOrientationFiles(inventoryPaths: string[], opts?: OrientationSelectOptions): OrientationPick[];
 export interface OrientationResult {
     /** Formatted PROJECT ORIENTATION block to prepend to the worker header, or ''. */
     block: string;
     /** Resolved-relative paths whose full content was pre-supplied in the block. */
     supplied: Set<string>;
 }
+export interface OrientationBuildOptions extends OrientationSelectOptions {
+    byteBudget?: number;
+    /** The separate purse cited documents are charged to — see
+     *  {@link ORIENTATION_CITED_BYTE_BUDGET}. */
+    citedByteBudget?: number;
+    perFileMax?: number;
+    maxFiles?: number;
+}
 /**
  * Read the orientation core within the byte budget and format it as a header
  * block. `readFile` returns a file's text or null (missing/unreadable/binary) —
  * a null or over-cap file is skipped, not fatal. Greedy in priority order: take
- * each file whose content fits the per-file cap and the remaining total budget;
- * skip the rest. Returns an empty block (and empty set) when nothing qualifies,
- * so the caller falls back to today's behavior.
+ * each file whose content fits its tier's per-file cap and the remaining total
+ * budget; skip the rest. Returns an empty block (and empty set) when nothing
+ * qualifies, so the caller falls back to today's behavior.
  */
-export declare function buildOrientation(inventoryPaths: string[], readFile: (path: string) => Promise<string | null>, opts?: {
-    byteBudget?: number;
-    perFileMax?: number;
-    maxFiles?: number;
-}): Promise<OrientationResult>;
+export declare function buildOrientation(inventoryPaths: string[], readFile: (path: string) => Promise<string | null>, opts?: OrientationBuildOptions): Promise<OrientationResult>;