@mjasnikovs/pi-task 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgars Mjasnikovs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+<div align="center">
+
+# 🧩 pi-task
+
+**Deterministic spec-orchestration for local models — with bundled web, docs, fetch, and worker sub-agent tools.**
+
+[![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-326%20passing-3fb950)](#development)
+[![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
+
+</div>
+
+---
+
+## What it does
+
+Local models drift. Ask one to plan a non-trivial change and it skips context, hallucinates APIs, and forgets what you actually asked. `pi-task` fixes this by **not trusting a single prompt** — it drives your request through a fixed, persisted pipeline of small, verifiable steps, then hands the main session a clean spec to execute.
+
+```
+/task add rate-limiting to the public API
+        │
+        ▼
+  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
+  │  refine  │──▶│ research │──▶│  grill   │──▶│ compose  │──▶│ critique │
+  └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
+   sharpen the    parallel        clarifying     assemble        triage +
+   raw prompt     sub-agents:     questions      the spec        rewrite if
+                  files · APIs ·  (auto- or                      the draft
+                  context ·       you answer)                    isn't clean
+                  tooling
+        │
+        ▼
+  final spec ──▶ main pi session   (you keep working in the same chat)
+```
+
+Every phase boundary is written to `.pi-tasks/TASK_NNNN.md`, so a task survives a crash, a restart, or a `/task-cancel` — pick it back up with `/task-resume`.
+
+## Why it's different
+
+- **Deterministic by construction.** The phase order is fixed code, not a model's free choice. The orchestrator loops over a config table; each phase has one job and one output section.
+- **Parallel research, focused output.** The research phase fans out to isolated child agents — one indexing project files, others digging into APIs, context, and tooling — and **verifies tooling claims** before they reach the spec.
+- **Context stays clean.** Noisy file/code spelunking, page fetches, and docs lookups run in throwaway child sessions. The parent only ever sees the distilled answer, never the raw page or the 4k-line file.
+- **Built for local LLMs.** A loop detector and failure classifier catch the stalls, repetitions, and malformed output that smaller models produce, and retry with sharper emphasis instead of giving up.
+- **Crash-safe.** State is a plain Markdown file you can read, diff, and edit by hand.
+
+## Install
+
+```sh
+pi install npm:@mjasnikovs/pi-task
+```
+
+> Requires [`pi`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (the Earendil coding agent) ≥ 0.75.
+
+## Slash commands
+
+| Command | What it does |
+| --- | --- |
+| `/task <prompt>` | Start a new task and run it through the full pipeline. |
+| `/task-list` | Open the task list in an editor dialog. |
+| `/task-resume [id]` | Resume the most recent (or named) unfinished task. |
+| `/task-cancel` | Cancel the running task (soft-terminal — still resumable). |
+
+## The pipeline
+
+| Phase | Output section | What happens |
+| --- | --- | --- |
+| **refine** | `refined prompt` | Sharpens your raw ask into an unambiguous, self-contained statement. |
+| **research** | `research` | Fans out to parallel sub-agents (project files · APIs · domain context · tooling), enriches any referenced packages/URLs/external services with fresh docs, then **verifies tooling claims**. |
+| **grill** | `grill Q&A` | Generates the clarifying questions the spec can't be written without — auto-answered from context where possible, surfaced to you where not. |
+| **compose** | `spec` | Assembles refined prompt + research + Q&A into a single implementation spec. |
+| **critique** | `spec` | Triages the draft; if it isn't already clean, rewrites it. The triage pass skips the expensive rewrite when the draft already holds up. |
+
+The finished spec is delivered to your main `pi` conversation via `sendUserMessage`, so you keep working in the same chat — no context handoff, no copy-paste.
+
+## Bundled tools
+
+`pi-task` also registers four MCP-style worker tools (formerly `@mjasnikovs/pi-worker`). All are parallel-execution-capable, so the parent session can issue several calls in one turn.
+
+### `pi-worker`
+Spawns an isolated child `pi --print` session with read + bash tools. Use it for noisy file/code work that would otherwise flood the main context.
+
+### `pi-worker-search`
+Runs a Brave Search query and returns a compact markdown list (title · URL · snippet). Use it to discover candidate URLs before fetching.
+
+> **Requires** `BRAVE_SEARCH_API_KEY` (also accepted as `BRAVE_API_KEY`). Grab a free key at [api.search.brave.com/app/keys](https://api.search.brave.com/app/keys).
+
+### `pi-worker-fetch`
+Fetches a URL, cleans the HTML to markdown ([Readability](https://github.com/mozilla/readability) + [Turndown](https://github.com/mixmark-io/turndown)), then hands it to an isolated child that extracts **only** the content answering your `query`. The parent never sees the raw page.
+
+- Only `text/html` responses — PDFs, JSON, etc. return a clear error.
+- Bodies over 2 MB are rejected.
+- The extraction child runs with `--no-tools` to mitigate visible-text prompt injection.
+
+### `pi-worker-docs`
+Resolves an installed npm package, indexes its `.d.ts` files and README into a local SQLite cache, retrieves the most relevant chunks for your `query`, and passes them to an isolated child that extracts the focused answer. Version-pinned to whatever is in your `node_modules`.
+
+- The package must be installed in the project's `node_modules`; otherwise a one-time auto-install into a dedicated cache dir is attempted.
+- 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.
+
+## Configuration
+
+| Variable | Used by | Notes |
+| --- | --- | --- |
+| `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required for web search. |
+| `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
+
+Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your `.gitignore` if you don't want them checked in.
+
+## Development
+
+```sh
+bun install
+bun test src/      # 326 tests across 28 files
+bun run lint       # prettier + eslint + tsc --noEmit
+bun run build      # tsc → dist/
+```
+
+Built with [Bun](https://bun.sh), TypeScript (strict), and [TypeBox](https://github.com/sinclairzx81/typebox) for tool schemas. Design docs and plans live in [`docs/`](./docs).
+
+## License
+
+[MIT](./LICENSE) © Edgars Mjasnikovs

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export default function (pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,6 @@
+import { registerTask } from './task/orchestrator.js';
+import { registerWorkers } from './workers/index.js';
+export default function (pi) {
+    registerTask(pi);
+    registerWorkers(pi);
+}

package/dist/shared/child-output.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared utilities for parsing and formatting child pi output.
+ *
+ * Used by both fetch-core (web page extraction) and docs-core (npm package
+ * docs extraction). The child pi outputs <answer> and <excerpt> XML tags;
+ * these functions parse, verify, and format the result.
+ */
+export declare function parseChildOutput(stdout: string): {
+    answer: string;
+    excerpt?: string;
+};
+export declare function normaliseWhitespace(s: string): string;
+/** Check whether an excerpt appears verbatim in the source content
+ *  (whitespace-normalised). Returns false for empty excerpts. */
+export declare function isExcerptInContent(excerpt: string, content: string): boolean;
+/** Format the child's parsed output with a header and optional excerpt block.
+ *  When `verified === false` a warning is prepended. */
+export declare function formatResultText(header: string, parsed: {
+    answer: string;
+    excerpt?: string;
+}, verified: boolean | undefined): string;

package/dist/shared/child-output.js

@@ -0,0 +1,40 @@
+/**
+ * Shared utilities for parsing and formatting child pi output.
+ *
+ * Used by both fetch-core (web page extraction) and docs-core (npm package
+ * docs extraction). The child pi outputs <answer> and <excerpt> XML tags;
+ * these functions parse, verify, and format the result.
+ */
+export function parseChildOutput(stdout) {
+    const trimmed = stdout.trim();
+    const answerMatch = /<answer>([\s\S]*?)<\/answer>/i.exec(trimmed);
+    const excerptMatch = /<excerpt>([\s\S]*?)<\/excerpt>/i.exec(trimmed);
+    if (!answerMatch)
+        return { answer: trimmed };
+    return {
+        answer: answerMatch[1].trim(),
+        excerpt: excerptMatch?.[1].trim() || undefined
+    };
+}
+export function normaliseWhitespace(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+/** Check whether an excerpt appears verbatim in the source content
+ *  (whitespace-normalised). Returns false for empty excerpts. */
+export function isExcerptInContent(excerpt, content) {
+    if (!excerpt)
+        return false;
+    return normaliseWhitespace(content).includes(normaliseWhitespace(excerpt));
+}
+/** Format the child's parsed output with a header and optional excerpt block.
+ *  When `verified === false` a warning is prepended. */
+export function formatResultText(header, parsed, verified) {
+    if (!parsed.excerpt) {
+        return header ? `${header}\n\n${parsed.answer}` : parsed.answer;
+    }
+    const quote = parsed.excerpt.replace(/\n/g, '\n> ');
+    const warning = verified === false ?
+        'WARNING: cited excerpt not found verbatim in source content — the child pi may have paraphrased or hallucinated.\n\n'
+        : '';
+    return `${warning}${header}\n\n${parsed.answer}\n\nSource excerpt:\n> ${quote}`;
+}

package/dist/shared/child-process.d.ts

@@ -0,0 +1,71 @@
+import type { EventEmitter } from 'node:events';
+/** Grace period between SIGTERM and SIGKILL (ms). */
+export declare const KILL_GRACE_MS = 5000;
+/** Base flags shared by all child pi invocations. */
+export declare const CHILD_BASE_ARGS: readonly ["--print", "--no-skills", "--no-extensions", "--no-prompt-templates", "--no-context-files", "--no-session"];
+export interface ProcLike extends EventEmitter {
+    stdout: EventEmitter | null;
+    stderr: EventEmitter | null;
+    killed: boolean;
+    kill(signal: string): boolean | void;
+}
+export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
+    cwd: string;
+    shell: boolean;
+    stdio: ['ignore', 'pipe', 'pipe'];
+}) => ProcLike;
+export interface ChildResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    aborted: boolean;
+    /** Extracted assistant text (only populated in json-events mode). */
+    text?: string;
+}
+export interface ToolCall {
+    name: string;
+    args: unknown;
+}
+export interface LoopHit {
+    call: ToolCall;
+    count: number;
+    windowSize: number;
+}
+export interface ContextSnapshot {
+    tokens: number;
+    contextWindow: number;
+    percent: number;
+}
+export interface RunChildTextOptions {
+    mode: 'text';
+    /**
+     * Drop stdout chunks instead of buffering them into the result. Use for
+     * pipe-through tools (npm install, build commands) where we only need the
+     * exit code and stderr — verbose stdout can exceed V8's max string length.
+     */
+    discardStdout?: boolean;
+    /**
+     * Fires exactly once on the first stdout data chunk. Lets callers split
+     * total elapsed into wait-for-first-byte vs generation time — useful when
+     * concurrent children may queue on an upstream slot (e.g. model API
+     * concurrency caps) before producing output.
+     */
+    onFirstByte?: () => void;
+}
+export interface RunChildJsonEventsOptions {
+    mode: 'json-events';
+    onLine?: (line: string) => void;
+    onContextUsage?: (snapshot: ContextSnapshot) => void;
+    onToolCall?: (call: ToolCall) => LoopHit | null;
+    onFirstByte?: () => void;
+}
+export type RunChildOptions = RunChildTextOptions | RunChildJsonEventsOptions;
+export declare function runChild(spawn: SpawnFn, invocation: {
+    command: string;
+    args: ReadonlyArray<string>;
+}, cwd: string, signal: AbortSignal | undefined, opts?: RunChildOptions): Promise<ChildResult>;
+export declare function runChildDefault(invocation: {
+    command: string;
+    args: ReadonlyArray<string>;
+}, cwd: string, signal: AbortSignal | undefined, opts?: RunChildOptions, spawnFn?: SpawnFn): Promise<ChildResult>;
+export declare function summarizeToolArgs(toolName: string, args: unknown): string;

package/dist/shared/child-process.js

@@ -0,0 +1,190 @@
+import { spawn as defaultSpawn } from 'node:child_process';
+/** Grace period between SIGTERM and SIGKILL (ms). */
+export const KILL_GRACE_MS = 5000;
+/** Base flags shared by all child pi invocations. */
+export const CHILD_BASE_ARGS = [
+    '--print',
+    '--no-skills',
+    '--no-extensions',
+    '--no-prompt-templates',
+    '--no-context-files',
+    '--no-session'
+];
+// ─── Unified runChild ────────────────────────────────────────────────────────
+export function runChild(spawn, invocation, cwd, signal, opts) {
+    return new Promise(resolve => {
+        let stdout = '';
+        let stderr = '';
+        let aborted = false;
+        const isJsonEvents = opts?.mode === 'json-events';
+        const discardStdout = opts?.mode === 'text' && opts.discardStdout === true;
+        // State for json-events mode
+        let finalText = '';
+        let textDeltaAccum = '';
+        const proc = spawn(invocation.command, invocation.args, {
+            cwd,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let firstByteFired = false;
+        proc.stdout?.on('data', (d) => {
+            if (!firstByteFired) {
+                firstByteFired = true;
+                opts?.onFirstByte?.();
+            }
+            if (discardStdout)
+                return;
+            const chunk = d.toString();
+            stdout += chunk;
+            if (isJsonEvents) {
+                drainJsonEvents(chunk, opts);
+            }
+        });
+        proc.stderr?.on('data', (d) => {
+            stderr += d.toString();
+        });
+        proc.on('close', (code) => {
+            const text = isJsonEvents ? (finalText || textDeltaAccum).trim() : undefined;
+            resolve({ stdout, stderr, exitCode: code ?? 0, aborted, text });
+        });
+        proc.on('error', () => {
+            resolve({ stdout, stderr, exitCode: 1, aborted });
+        });
+        if (signal) {
+            const kill = () => {
+                aborted = true;
+                proc.kill('SIGTERM');
+                setTimeout(() => {
+                    if (!proc.killed)
+                        proc.kill('SIGKILL');
+                }, KILL_GRACE_MS);
+            };
+            if (signal.aborted)
+                kill();
+            else
+                signal.addEventListener('abort', kill, { once: true });
+        }
+        // ─── JSON event-stream processing ──────────────────────────────────
+        function drainJsonEvents(chunk, jsonOpts) {
+            let buf = chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) !== -1) {
+                const line = buf.slice(0, nl).trim();
+                buf = buf.slice(nl + 1);
+                if (line.length === 0)
+                    continue;
+                try {
+                    const evt = JSON.parse(line);
+                    if (evt && typeof evt === 'object') {
+                        handleEvent(evt, jsonOpts);
+                    }
+                }
+                catch {
+                    // Non-JSON line (startup banner, etc.) — ignore.
+                }
+            }
+        }
+        function handleEvent(evt, jsonOpts) {
+            const t = typeof evt.type === 'string' ? evt.type : '';
+            if (t === 'context_usage' && jsonOpts.onContextUsage) {
+                const tokens = Number(evt.tokens ?? 0);
+                const contextWindow = Number(evt.contextWindow ?? 0);
+                const percent = Number(evt.percent ?? 0);
+                if (tokens > 0 || contextWindow > 0) {
+                    jsonOpts.onContextUsage({ tokens, contextWindow, percent });
+                }
+                return;
+            }
+            if (t === 'message_end' && jsonOpts.onContextUsage) {
+                const msg = evt.message;
+                if (msg?.role === 'assistant') {
+                    const usage = msg.usage;
+                    if (usage) {
+                        const tokens = Number(usage.input ?? 0)
+                            + Number(usage.cacheRead ?? 0)
+                            + Number(usage.cacheWrite ?? 0)
+                            + Number(usage.output ?? 0);
+                        if (tokens > 0) {
+                            jsonOpts.onContextUsage({ tokens, contextWindow: 0, percent: 0 });
+                        }
+                    }
+                }
+                return;
+            }
+            if (t === 'agent_end' && Array.isArray(evt.messages)) {
+                for (let i = evt.messages.length - 1; i >= 0; i--) {
+                    const m = evt.messages[i];
+                    if (m && m.role === 'assistant' && Array.isArray(m.content)) {
+                        const texts = [];
+                        for (const c of m.content) {
+                            if (c?.type === 'text' && typeof c.text === 'string') {
+                                texts.push(c.text);
+                            }
+                        }
+                        if (texts.length > 0) {
+                            finalText = texts.join('');
+                            break;
+                        }
+                    }
+                }
+                return;
+            }
+            if (t === 'message_update') {
+                const ame = evt.assistantMessageEvent;
+                const ameType = ame && typeof ame.type === 'string' ? ame.type : '';
+                if (ameType === 'text_start') {
+                    textDeltaAccum = '';
+                    if (jsonOpts.onLine)
+                        jsonOpts.onLine('writing answer…');
+                }
+                else if (ameType === 'text_delta' && typeof ame.delta === 'string') {
+                    textDeltaAccum += ame.delta;
+                }
+                else if (ameType === 'thinking_start' && jsonOpts.onLine) {
+                    jsonOpts.onLine('thinking…');
+                }
+                return;
+            }
+            if (t === 'tool_execution_start') {
+                const tn = typeof evt.toolName === 'string' ? evt.toolName : 'tool';
+                if (jsonOpts.onLine) {
+                    const detail = summarizeToolArgs(tn, evt.args);
+                    jsonOpts.onLine(detail ? `${tn}: ${detail}` : tn);
+                }
+                if (jsonOpts.onToolCall) {
+                    const hit = jsonOpts.onToolCall({ name: tn, args: evt.args });
+                    if (hit) {
+                        aborted = true;
+                        proc.kill('SIGTERM');
+                        setTimeout(() => {
+                            if (!proc.killed)
+                                proc.kill('SIGKILL');
+                        }, KILL_GRACE_MS);
+                    }
+                }
+            }
+        }
+    });
+}
+// ─── Convenience: spawn with default node child_process ──────────────────────
+export function runChildDefault(invocation, cwd, signal, opts, spawnFn) {
+    return runChild(spawnFn ?? defaultSpawn, invocation, cwd, signal, opts);
+}
+// ─── Shared helpers ──────────────────────────────────────────────────────────
+export function summarizeToolArgs(toolName, args) {
+    if (!args || typeof args !== 'object')
+        return '';
+    const a = args;
+    if (toolName === 'bash' && typeof a.command === 'string') {
+        return a.command.replace(/\s+/g, ' ').trim();
+    }
+    if (typeof a.file_path === 'string')
+        return a.file_path;
+    if (typeof a.path === 'string')
+        return a.path;
+    if (typeof a.filePath === 'string')
+        return a.filePath;
+    if (typeof a.pattern === 'string')
+        return a.pattern;
+    return '';
+}

package/dist/shared/pi-invocation.d.ts

@@ -0,0 +1,7 @@
+/** Pick the right way to re-invoke pi: prefer the current pi script under the
+ *  current node/bun runtime; fall back to the `pi` shim on PATH. Mirrors the
+ *  pattern from pi-coding-agent's official subagent example. */
+export declare function getPiInvocation(args: string[]): {
+    command: string;
+    args: string[];
+};

package/dist/shared/pi-invocation.js

@@ -0,0 +1,24 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** Pick the right way to re-invoke pi: prefer the current pi script under the
+ *  current node/bun runtime; fall back to the `pi` shim on PATH. Mirrors the
+ *  pattern from pi-coding-agent's official subagent example. */
+export function getPiInvocation(args) {
+    // Test/dev override: point at a specific pi binary directly. Bypasses the
+    // re-invoke-current-script heuristic, which goes wrong under `bun test`
+    // (currentScript is the .test.ts file, not a pi entrypoint).
+    if (process.env.PI_BIN) {
+        return { command: process.env.PI_BIN, args };
+    }
+    const currentScript = process.argv[1];
+    const isBunVirtualScript = currentScript?.startsWith('/$bunfs/root/');
+    if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+        return { command: process.execPath, args: [currentScript, ...args] };
+    }
+    const execName = path.basename(process.execPath).toLowerCase();
+    const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+    if (!isGenericRuntime) {
+        return { command: process.execPath, args };
+    }
+    return { command: 'pi', args };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Child process runner for the pi-task orchestrator.
+ *
+ * Thin wrapper layer over the unified `runChild` in `shared/child-process.ts`.
+ * Provides JSON event-stream parsing, loop detection, and context-usage tracking
+ * for phase-level child pi invocations.
+ */
+import { type SpawnFn, type ContextSnapshot, type ToolCall, type LoopHit } from '../shared/child-process.js';
+export declare const LOOP_WINDOW = 20;
+export declare const LOOP_THRESHOLD = 5;
+export declare const MAX_LOOP_RESTARTS = 2;
+export interface PhaseRunResult {
+    text: string;
+    exitCode: number;
+    stderr: string;
+    loopHit?: LoopHit;
+}
+export declare function childArgs(tools: string, prompt: string): string[];
+export declare const USER_CANCELLED = "__user_cancelled__";
+/**
+ * Run a child pi process with JSON event-stream output, loop detection, and
+ * context-usage tracking. This is the typed convenience wrapper used by
+ * phase-level code.
+ */
+export declare function runChild(cwd: string, tools: string, prompt: string, signal: AbortSignal, onLine?: (line: string) => void, onContextUsage?: (snapshot: ContextSnapshot) => void, onToolCall?: (call: ToolCall) => LoopHit | null, spawnFn?: SpawnFn): Promise<PhaseRunResult>;
+interface PhaseDeps {
+    cwd: string;
+    taskId: string;
+    signal: AbortSignal;
+    onChildOutput?: (line: string) => void;
+    onContextUsage?: (snapshot: ContextSnapshot) => void;
+    /**
+     * Record a sub-step duration under the currently running top-level phase.
+     * The orchestrator rebinds this between phases so each call lands in the
+     * right phase's children array. Phases that don't care can ignore it.
+     */
+    recordSubStep?: (label: string, ms: number) => void;
+    spawn?: SpawnFn;
+}
+export type { PhaseDeps };
+/** Run a child pi and return its assistant text. Throws if exit code != 0. */
+export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string): Promise<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
+ * with a hint that names the offending call. Cap at MAX_LOOP_RESTARTS restarts;
+ * the (MAX_LOOP_RESTARTS+1)th loop throws LoopExhaustedError.
+ */
+export declare function runPhaseWithLoopGuard(deps: PhaseDeps, name: string, tools: string, buildPrompt: (loopHint: string | null) => string): Promise<string>;
+/**
+ * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
+ * the prompt. On success, return the validator's value; on two failures, throw
+ * the caller-supplied error built from the last problem string.
+ */
+export declare function runWithEmphasisRetry<T>(deps: PhaseDeps, name: string, tools: string, build: (retryProblem: string | null) => string, validate: (text: string) => {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    problem: string;
+}, onFail: (problem: string) => Error): Promise<T>;
+export declare class LoopExhaustedError extends Error {
+    readonly phase: string;
+    readonly history: LoopHit[];
+    constructor(phase: string, history: LoopHit[]);
+}