@mjasnikovs/pi-task 0.13.26 → 0.13.28

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-559%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-731%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -49,7 +49,8 @@ pi install npm:@mjasnikovs/pi-task
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume` | Resume the active `/task-auto` run at the next unfinished task. |
 | `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
-| `/remote` | Show the QR code & URLs for the always-on web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
+| `/task-config` | Toggle pi-task settings in an editor dialog: remote server, compress reasoning, auto-commit, and orientation. |
+| `/remote` | Show the QR code & URLs for the web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
 ## The pipeline
 
@@ -77,10 +78,11 @@ A real feature is usually several tasks, not one. `/task-auto` is a thin planner
 - **Clarify first.** It asks the few clarifying questions whose answers change how the feature splits, then decomposes the answers into an ordered list of task titles written to `.pi-tasks/TASK_AUTO_NNNN.md`.
 - **Sequential, blocking.** Each title runs through `/task` to a spec, the spec is implemented, and the loop waits for that to finish before starting the next title. No overlap.
 - **Crash- and cancel-safe.** Progress is the markdown checkboxes in the AUTO file. `/task-auto-resume` (no id) automatically picks up the active run at the first unchecked title. If a title's `/task` run fails, the loop stops and leaves the run resumable.
+- **One commit per task.** When **auto-commit** is on (the default) and you're in a git repo, the working tree is snapshotted into a single commit after each title passes, so the run produces a clean per-task history. It's best-effort: outside a repo, with nothing to commit, or on any git error, the loop reports the reason and keeps going. Toggle it in `/task-config`.
 
 ## Remote — drive a task from your phone
 
-The remote server is **always on** — it starts automatically with each session, with nothing taking up screen space. Run `/remote` any time to pop a QR code and the connection URLs: a **Tailscale** line and a **LAN** line when both are available (the QR encodes the Tailscale-preferred one). Open the URL on any device that can reach the host and you get a live view of the session: streaming output, tool calls, and the `/task` status block (phase, elapsed, context). It's bidirectional — the browser can:
+The remote server is **on by default** — it starts automatically with each session, with nothing taking up screen space (disable it in `/task-config`). Run `/remote` any time to pop a QR code and the connection URLs: a **Tailscale** line and a **LAN** line when both are available (the QR encodes the Tailscale-preferred one). Open the URL on any device that can reach the host and you get a live view of the session: streaming output, tool calls, and the `/task` status block (phase, elapsed, context). It's bidirectional — the browser can:
 
 - **Answer grill / `/task-auto` clarify questions.** Each question appears as a card with the recommended default pre-filled (Accept), a free-text box (Submit), Skip, or Cancel task.
 - **Start and control tasks.** Type `/task …`, `/task-auto …`, `/task-cancel`, `/task-resume`, etc. — they run on the host.
@@ -136,6 +138,17 @@ Resolves an installed npm package, indexes its `.d.ts` files and README into a l
 - The first call for a `(package, version)` pair pays a one-time ingestion cost; later calls are FTS-only.
 - Cache lives at `${XDG_CACHE_HOME:-~/.cache}/pi-worker/docs.sqlite` — delete it to reset.
 
+## Settings — `/task-config`
+
+Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings persist to `~/.config/pi-task/config.json` and all default to **on**:
+
+| Setting | What it does |
+| --- | --- |
+| **remote** | The remote UI server (QR code, phone access). Turn off to never start it. |
+| **compress reasoning** | After each message, compresses the model's `<think>` blocks down to the decisions/constraints/facts that matter later — keeping long local-model runs from drowning their own context in self-talk. |
+| **auto-commit** | Snapshots the working tree into one git commit per `/task-auto` sub-task (see above). |
+| **orientation** | Pre-reads the project's core files (manifest, config, domain types, schema, entrypoints, API surface) once and hands the contents to the read-heavy research workers, so they skip re-discovering the same files cold. Bounded by a hard byte budget; applied only where it helps (FILES/APIS workers). |
+
 ## Configuration
 
 | Variable | Used by | Notes |
@@ -153,7 +166,7 @@ Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your
 
 ```sh
 bun install
-bun test src/      # 559 tests across 46 files
+bun test src/      # 731 tests across 57 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/config/config.d.ts

@@ -2,6 +2,7 @@ export interface PiTaskConfig {
     remote: boolean;
     compressReasoning: boolean;
     autoCommit: boolean;
+    orientation: boolean;
 }
 export declare function getConfig(): PiTaskConfig;
 export declare function saveConfig(config: PiTaskConfig): Promise<void>;

package/dist/config/config.js

@@ -5,7 +5,8 @@ import * as os from 'node:os';
 const DEFAULTS = {
     remote: true,
     compressReasoning: true,
-    autoCommit: true
+    autoCommit: true,
+    orientation: true
 };
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'pi-task', 'config.json');
 const _g = globalThis;

package/dist/config/register.js

@@ -12,6 +12,11 @@ const ITEMS = [
         id: 'autoCommit',
         label: 'auto-commit',
         description: 'git commit around each /task-auto sub-task (checkpoint before, snapshot after)'
+    },
+    {
+        id: 'orientation',
+        label: 'orientation',
+        description: 'Pre-supply the project core (manifest, types, schema…) to the read-heavy research workers'
     }
 ];
 function makeTheme(theme) {
@@ -48,7 +53,7 @@ async function handleTaskConfig(_args, ctx) {
 }
 export function registerConfig(pi) {
     registerBridgeCommand(pi, 'task-config', {
-        description: 'Configure pi-task settings (remote, compress reasoning, auto-commit).',
+        description: 'Configure pi-task settings (remote, compress reasoning, auto-commit, orientation).',
         handler: handleTaskConfig
     });
 }

package/dist/task/_ab.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/task/_ab.js

@@ -0,0 +1,68 @@
+/* Live A/B: orientation OFF vs ON, real pi + local model, real mx5 repo. */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { runWorker } from '../workers/pi-worker-core.js';
+import { getFileInventory } from './file-inventory.js';
+import { buildOrientation } from './orientation.js';
+import { appendNoThink, RESEARCH_FILES_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_TOOLING_PROMPT } from './prompts.js';
+import { scopedToolingGoal } from './phases.js';
+const DOCS_EXT = new URL('../workers/docs-extension.js', import.meta.url).pathname;
+const SINGLE_READ_EXT = new URL('../workers/single-read-extension.js', import.meta.url).pathname;
+const CWD = '/home/edgars/hub/mx5';
+process.env.PI_BIN ??= '/home/edgars/.local/share/mise/installs/node/26.2.0/bin/pi';
+const refined = await readFile('/tmp/refined.txt', 'utf8');
+const inventoryRaw = await getFileInventory(CWD);
+const invPaths = inventoryRaw.split('\n').filter(l => l.trim());
+const inventoryHeader = `PROJECT FILE INVENTORY\n${inventoryRaw}\n\n`;
+const orientation = await buildOrientation(invPaths, async (p) => {
+    try {
+        return await readFile(resolve(CWD, p), 'utf8');
+    }
+    catch {
+        return null;
+    }
+});
+console.error(`orientation: ${orientation.supplied.size} files, ${(orientation.block.length / 1024).toFixed(1)}KB`);
+const suppliedRel = new Set([...orientation.supplied].map(p => resolve(CWD, p)));
+const workers = {
+    FILES: { build: RESEARCH_FILES_PROMPT, tools: undefined, ext: [] },
+    APIS: {
+        build: RESEARCH_APIS_PROMPT,
+        tools: 'read,grep,find,ls,pi-worker-docs',
+        ext: [DOCS_EXT]
+    },
+    CONTEXT: { build: RESEARCH_CONTEXT_PROMPT, tools: 'read,grep', ext: [] },
+    TOOLING: {
+        build: (r) => RESEARCH_TOOLING_PROMPT(scopedToolingGoal(r)),
+        tools: undefined,
+        ext: [SINGLE_READ_EXT]
+    }
+};
+async function run(worker, on) {
+    const header = (on ? orientation.block : '') + inventoryHeader;
+    const prompt = appendNoThink(header + workers[worker].build(refined));
+    const reads = [];
+    const r = await runWorker({
+        prompt,
+        cwd: CWD,
+        ...(workers[worker].tools ? { tools: workers[worker].tools } : {}),
+        ...(workers[worker].ext.length ? { extensions: workers[worker].ext } : {}),
+        onLine: line => {
+            const m = /read: (\S+)/.exec(line);
+            if (m)
+                reads.push(resolve(CWD, m[1]));
+        }
+    });
+    const reReadSupplied = reads.filter(p => suppliedRel.has(p)).length;
+    const label = `${worker} ${on ? 'ON ' : 'OFF'}`;
+    console.log(`${label}  exit=${r.exitCode} loop=${r.loopHit ? 'Y' : 'n'} time=${r.loopHit || r.timedOut ? '(runaway)' : ''}` +
+        ` workMs=${r.workMs} reads=${reads.length} reads_of_core=${reReadSupplied} answerChars=${r.text.trim().length}`);
+    return { reads: reads.length, reReadSupplied, workMs: r.workMs, exit: r.exitCode };
+}
+for (const w of ['FILES', 'APIS', 'CONTEXT', 'TOOLING']) {
+    const off = await run(w, false);
+    const on = await run(w, true);
+    const saved = off.reads - on.reads;
+    console.log(`  -> ${w}: reads ${off.reads}->${on.reads} (${saved >= 0 ? '-' : '+'}${Math.abs(saved)}), ` +
+        `workMs ${off.workMs}->${on.workMs}, core re-read while ON: ${on.reReadSupplied}\n`);
+}

package/dist/task/orientation.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Project orientation core — a bounded snapshot of the few files every research
+ * worker re-reads cold to learn "what is this project" (manifest, config, domain
+ * types, schema, entrypoints, API surface). The four workers run as separate
+ * child processes with no shared memory, so today each one independently
+ * `read()`s the same hot files: across the recorded mx5 run package.json was
+ * read 87×, src/types/index.ts 82×, and 55% of all worker reads were repeats of
+ * a file another worker in the same task had already read.
+ *
+ * This module picks that orientation core from the file inventory (repo-agnostic,
+ * by path convention), reads it ONCE in the parent, and the caller folds it into
+ * the shared prompt header — so every worker already has those files and skips
+ * the cold read. It is purely additive: nothing is blocked, so a worker can still
+ * read anything it wants; orientation only removes the need to.
+ *
+ * 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.
+ */
+/**
+ * Total bytes of file content the orientation block may contain (~10k tokens).
+ * 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. 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;
+/**
+ * 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.
+ * It is deliberately set high enough that the byte budget binds first on real
+ * repos (verified: mx5/aiz-server hit the budget at ~16 files; a 5000-file repo
+ * yields only ~6 orientation candidates because leaf source is filtered out). An
+ * earlier cap of 16 wrongly bound before the budget — e.g. it dropped 5 core
+ * files on a 165-file repo while leaving 17KB of budget unused.
+ */
+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.
+ */
+export declare function orientationTier(path: string): number | null;
+/**
+ * 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 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>;
+}
+/**
+ * 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.
+ */
+export declare function buildOrientation(inventoryPaths: string[], readFile: (path: string) => Promise<string | null>, opts?: {
+    byteBudget?: number;
+    perFileMax?: number;
+    maxFiles?: number;
+}): Promise<OrientationResult>;

package/dist/task/orientation.js

@@ -0,0 +1,198 @@
+/**
+ * Project orientation core — a bounded snapshot of the few files every research
+ * worker re-reads cold to learn "what is this project" (manifest, config, domain
+ * types, schema, entrypoints, API surface). The four workers run as separate
+ * child processes with no shared memory, so today each one independently
+ * `read()`s the same hot files: across the recorded mx5 run package.json was
+ * read 87×, src/types/index.ts 82×, and 55% of all worker reads were repeats of
+ * a file another worker in the same task had already read.
+ *
+ * This module picks that orientation core from the file inventory (repo-agnostic,
+ * by path convention), reads it ONCE in the parent, and the caller folds it into
+ * the shared prompt header — so every worker already has those files and skips
+ * the cold read. It is purely additive: nothing is blocked, so a worker can still
+ * read anything it wants; orientation only removes the need to.
+ *
+ * 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.
+ */
+/**
+ * Total bytes of file content the orientation block may contain (~10k tokens).
+ * 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. Selection stops as soon as adding a file would
+ * exceed it.
+ */
+export const ORIENTATION_BYTE_BUDGET = 40 * 1024;
+/** A single file larger than this is skipped (read by the worker as before). */
+export const ORIENTATION_PER_FILE_MAX = 12 * 1024;
+/**
+ * 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.
+ * It is deliberately set high enough that the byte budget binds first on real
+ * repos (verified: mx5/aiz-server hit the budget at ~16 files; a 5000-file repo
+ * yields only ~6 orientation candidates because leaf source is filtered out). An
+ * earlier cap of 16 wrongly bound before the budget — e.g. it dropped 5 core
+ * files on a 165-file repo while leaving 17KB of budget unused.
+ */
+export const ORIENTATION_MAX_FILES = 40;
+/** Code/config/doc extensions worth pre-reading; everything else is ignored. */
+const ORIENTATION_EXTENSIONS = new Set([
+    'ts',
+    'tsx',
+    'js',
+    'jsx',
+    'mjs',
+    'cjs',
+    'json',
+    'sql',
+    'prisma',
+    'go',
+    'rs',
+    'py',
+    'rb',
+    'java',
+    'kt',
+    'md',
+    'toml',
+    'graphql',
+    'gql'
+]);
+/** Root manifests — the single highest-signal "what is this project" file. */
+const MANIFEST_BASENAMES = new Set([
+    'package.json',
+    'go.mod',
+    'cargo.toml',
+    'pyproject.toml',
+    'requirements.txt',
+    'pom.xml',
+    'build.gradle',
+    'gemfile',
+    'composer.json',
+    'deno.json'
+]);
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i === -1 ? p : p.slice(i + 1);
+}
+function extension(p) {
+    const b = basename(p);
+    const i = b.lastIndexOf('.');
+    return i === -1 ? '' : b.slice(i + 1).toLowerCase();
+}
+function depth(p) {
+    let n = 0;
+    for (const c of p)
+        if (c === '/')
+            n++;
+    return n;
+}
+/**
+ * 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.
+ */
+export function orientationTier(path) {
+    const lower = path.toLowerCase();
+    // Never orient on vendored/build output or tests: a dependency's manifest or
+    // a big *.test.ts would otherwise outrank the project's own files and eat the
+    // budget (validated against the mx5 traces — node_modules/hono/package.json
+    // and zod-schemas.test.ts both crowded out genuinely hot project files). A
+    // git-ls-files inventory won't list these anyway; this is belt-and-braces.
+    if (/(^|\/)(node_modules|dist|build|out|vendor|\.git|coverage)\//.test(lower))
+        return null;
+    if (/\.(test|spec)\.[a-z]+$/.test(lower) || /(^|\/)(__tests__|e2e)\//.test(lower))
+        return null;
+    if (path.startsWith('/'))
+        return null; // absolute path escaped the repo root
+    const base = basename(lower);
+    const ext = extension(lower);
+    if (MANIFEST_BASENAMES.has(base))
+        return 0;
+    if (!ORIENTATION_EXTENSIONS.has(ext))
+        return null;
+    if (base === 'tsconfig.json' || /\.config\.(ts|js|mjs|cjs|json)$/.test(base))
+        return 1;
+    const segs = lower.split('/');
+    const stem = base.replace(/\.[^.]+$/, '');
+    if (ext === 'sql'
+        || ext === 'prisma'
+        || ext === 'graphql'
+        || ext === 'gql'
+        || base.endsWith('.d.ts')
+        || segs.includes('types')
+        || stem === 'types'
+        || /schema|zod/.test(lower))
+        return 2;
+    if (['index', 'main', 'app', 'server', 'mod'].includes(stem))
+        return 3;
+    if (/(^|\/)api(\/|s?\.|$)/.test(lower) || segs.includes('api'))
+        return 4;
+    if (stem === 'readme')
+        return 5;
+    return null;
+}
+/**
+ * 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 function selectOrientationFiles(inventoryPaths) {
+    return inventoryPaths
+        .map(p => ({ p, tier: orientationTier(p) }))
+        .filter((x) => x.tier !== null)
+        .sort((a, b) => a.tier - b.tier || depth(a.p) - depth(b.p) || (a.p < b.p ? -1 : 1))
+        .map(x => x.p);
+}
+/**
+ * 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.
+ */
+export async function buildOrientation(inventoryPaths, readFile, opts = {}) {
+    const byteBudget = opts.byteBudget ?? ORIENTATION_BYTE_BUDGET;
+    const perFileMax = opts.perFileMax ?? ORIENTATION_PER_FILE_MAX;
+    const maxFiles = opts.maxFiles ?? ORIENTATION_MAX_FILES;
+    const candidates = selectOrientationFiles(inventoryPaths).slice(0, maxFiles * 4);
+    const supplied = new Set();
+    const parts = [];
+    // Budget the *emitted* block, not just the raw content: the per-file fence
+    // (`--- path ---\n` + the `\n\n` join) and the fixed wrapper add up across
+    // many files and would otherwise let the block overrun the budget (a 27-file
+    // repo overran a content-only budget by >1KB). Seed `used` with the wrapper
+    // so the final block is guaranteed ≤ byteBudget.
+    const HEADER = `PROJECT ORIENTATION (full contents of the project's core files — `
+        + `already provided, do not re-read these)\n`;
+    const TRAILER = '\n\n';
+    let used = Buffer.byteLength(HEADER + TRAILER, 'utf8');
+    for (const path of candidates) {
+        if (supplied.size >= maxFiles)
+            break;
+        const text = await readFile(path);
+        if (text === null)
+            continue;
+        if (Buffer.byteLength(text, 'utf8') > perFileMax)
+            continue;
+        const piece = `--- ${path} ---\n${text.replace(/\n+$/, '')}`;
+        // Each piece after the first is preceded by the `\n\n` join separator.
+        const pieceBytes = Buffer.byteLength(piece, 'utf8') + (parts.length > 0 ? 2 : 0);
+        if (used + pieceBytes > byteBudget)
+            continue;
+        used += pieceBytes;
+        supplied.add(path);
+        parts.push(piece);
+    }
+    if (parts.length === 0)
+        return { block: '', supplied };
+    return { block: HEADER + parts.join('\n\n') + TRAILER, supplied };
+}

package/dist/task/phases.js

@@ -9,6 +9,10 @@ import { runWorker } from '../workers/pi-worker-core.js';
 import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
 import { getFileInventory } from './file-inventory.js';
+import { buildOrientation } from './orientation.js';
+import { getConfig } from '../config/config.js';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
 import { formatServiceBlock, formatFreshnessSkippedBlock } from './service-blocks.js';
 import { gatherExternalContext } from './external-context.js';
 import { REFINE_PROMPT, RESEARCH_FILES_PROMPT, RESEARCH_APIS_PROMPT, RESEARCH_CONTEXT_PROMPT, RESEARCH_TOOLING_PROMPT, GRILL_GEN_PROMPT, GRILL_AUTO_ANSWER_PROMPT, GRILL_AUTO_FORMAT_HINT, COMPOSE_PROMPT, CRITIQUE_PROMPT, CRITIQUE_TRIAGE_PROMPT, VERIFY_TOOLING_PROMPT, MAX_GRILL_QUESTIONS, appendNoThink } from './prompts.js';
@@ -194,6 +198,37 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     // behavior.
     const inventoryRaw = await fileInventoryFn(deps.cwd, deps.signal).catch(() => '');
     const inventoryHeader = inventoryRaw.length > 0 ? `PROJECT FILE INVENTORY\n${inventoryRaw}\n\n` : '';
+    // Pre-read the project's orientation core (manifest, config, domain types,
+    // schema, entrypoints, API surface) ONCE and hand the full contents to the
+    // READ-HEAVY workers in their header. The workers run as separate child
+    // processes, so without this each one that explores re-reads the same hot
+    // files cold. Bounded by a hard byte budget so it can't overflow on a large
+    // repo; purely additive (nothing is blocked) so it can only remove a
+    // redundant read, never hide a file.
+    //
+    // Applied to FILES and APIS only — NOT CONTEXT/TOOLING. Verified with a live
+    // A/B on the local model (real pi, real repo): FILES and APIS are bimodal —
+    // they sometimes answer from the inventory but sometimes spiral into heavy
+    // reads (APIS hit 37 reads / 221s, a near-runaway), and pre-supplying the core
+    // collapses that to 0 reads / ~3.5s with the model honoring "do not re-read"
+    // (0 core re-reads in every ON run). CONTEXT works from inventory+grep and
+    // reads ~0 files regardless, so the block was pure prefill and made it slower
+    // in 5/5 reps; TOOLING is already scoped + single-read-guarded and saw no
+    // benefit. So orientation only goes where reads actually happen.
+    const orientationPaths = getConfig().orientation && inventoryRaw.length > 0 ?
+        inventoryRaw.split('\n').filter(l => l.trim().length > 0)
+        : [];
+    const orientation = await buildOrientation(orientationPaths, async (path) => {
+        try {
+            return await readFile(resolve(deps.cwd, path), 'utf8');
+        }
+        catch {
+            return null;
+        }
+    }).catch(() => ({ block: '', supplied: new Set() }));
+    if (orientation.supplied.size > 0) {
+        deps.logDebug?.(`orientation: pre-supplied ${orientation.supplied.size} core files`);
+    }
     const promptHeader = externalContext + inventoryHeader;
     let doneCount = 0;
     const updateProgress = () => {
@@ -235,12 +270,14 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         {
             section: 'FILES',
             label: 'worker:files',
-            prompt: appendNoThink(promptHeader + RESEARCH_FILES_PROMPT(refined))
+            // Read-heavy: gets the orientation core (see note above).
+            prompt: appendNoThink(orientation.block + promptHeader + RESEARCH_FILES_PROMPT(refined))
         },
         {
             section: 'APIS',
             label: 'worker:apis',
-            prompt: appendNoThink(promptHeader + RESEARCH_APIS_PROMPT(refined)),
+            // Read-heavy: gets the orientation core (see note above).
+            prompt: appendNoThink(orientation.block + promptHeader + RESEARCH_APIS_PROMPT(refined)),
             tools: 'read,grep,find,ls,pi-worker-docs',
             extensions: [DOCS_EXTENSION_PATH]
         },

package/package.json

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