@mjasnikovs/pi-task 0.38.11 → 0.38.13

package/dist/task/child-status.js

@@ -0,0 +1,99 @@
+/**
+ * ChildStatus — the live status of the child pi currently running under a
+ * status loader: its latest output line and its context usage.
+ *
+ * Four sites used to keep this state by hand — `let lastLine; let contextUsage;`
+ * plus two callbacks (`onChildOutput` writes the line, `onContextUsage` folds a
+ * snapshot through `resolveContextUsage` with the parent window), a reset before
+ * every child, and a loader whose every tick read both — in `/task-auto`'s
+ * planning `runChild`, `/task-plan`'s `child`, `buildGateDeps` (an accessor box
+ * handed to `makeGateChild`), and the single-task `TaskRunner`. The first three
+ * are one ritual and are now this class; the fourth stays where it is (see
+ * `orchestrator.ts`: its state is the whole-run `WidgetState`, shared by
+ * reference with `PhaseContext` and written by the phases themselves).
+ *
+ * `track` is the loader ritual: reset, raise the loader reading this status on
+ * every tick, run, always stop. The status OUTLIVES a track — `buildGateDeps`
+ * shares one across every gate child, and the verify gate raises its own
+ * gate-wide loader over a child that renders none (`frame: null`), so both must
+ * see the same object.
+ */
+import { runPhaseChild } from './child-runner.js';
+import { resolveContextUsage } from './context-usage.js';
+import { startAutoLoader } from './widget.js';
+export class ChildStatus {
+    _lastLine;
+    _contextUsage;
+    _parentContextWindow;
+    _startLoader;
+    constructor(deps) {
+        this._parentContextWindow = deps.parentContextWindow;
+        this._startLoader = deps.startLoader ?? startAutoLoader;
+    }
+    /** The child's latest stream line. Bind as `onChildOutput` / `onLine`. */
+    onLine(line) {
+        this._lastLine = line;
+    }
+    /**
+     * Fold a raw context_usage snapshot into the gauge: the child's own window,
+     * else the last known one, else the parent's (`resolveContextUsage`).
+     */
+    onContextUsage(snapshot) {
+        this._contextUsage = resolveContextUsage(snapshot, this._contextUsage, this._parentContextWindow);
+    }
+    /** Forget the previous child, so its trailer never sits under the next one's block. */
+    reset() {
+        this._lastLine = undefined;
+        this._contextUsage = undefined;
+    }
+    /** The two live fields, as a loader frame reads them. */
+    snapshot() {
+        return { lastLine: this._lastLine, contextUsage: this._contextUsage };
+    }
+    /**
+     * Run `run` under the loader: reset, raise a loader whose every tick is
+     * `frame()` plus the live line and gauge, and stop it in a `finally` — a
+     * throwing child must not leave the widget up. `frame` wins on a clash, which
+     * is how the verify gate shows its deterministic-stage label until the child
+     * has a line of its own. `frame: null` renders NO loader (the caller already
+     * has one reading this status) but still resets, so the previous child's
+     * trailer is cleared either way.
+     */
+    async track(ctx, frame, run) {
+        this.reset();
+        const stop = frame === null ?
+            () => { }
+            : this._startLoader(ctx, () => ({ ...this.snapshot(), ...frame() }));
+        try {
+            return await run();
+        }
+        finally {
+            stop();
+        }
+    }
+}
+/**
+ * Run one planning child — a phase child (`runPhaseChild`, with its Error-triage
+ * ladder) whose only UI is the shared status loader. Both `/task-auto`'s
+ * planning `runChild` and `/task-plan`'s `child` are adapters over this: what
+ * they disagree on is the phase deps (task id, read-once extension, debug log),
+ * the tool set, and the loader's labelling — all parameters here. What
+ * `/task-plan` adds around it (the read-only tree diff) stays its own.
+ */
+export async function runPlanningChild(opts) {
+    const { ctx, status, phaseDeps, name, tools, prompt, loader } = opts;
+    const startedAt = Date.now();
+    return status.track(ctx, () => ({
+        ...(loader.command === undefined ? {} : { command: loader.command }),
+        title: loader.title,
+        ...loader.step(name),
+        startedAt
+    }), () => runPhaseChild(phaseDeps, name, tools, prompt));
+}
+/** Wire a `ChildStatus` as a phase child's stream callbacks. */
+export function statusCallbacks(status) {
+    return {
+        onChildOutput: line => status.onLine(line),
+        onContextUsage: snapshot => status.onContextUsage(snapshot)
+    };
+}

package/dist/task/command-run.d.ts

@@ -102,3 +102,39 @@ export declare function outputTail(stdout: string, stderr: string, limit?: numbe
  * an environment gap (see INFRA_GAP_OUTPUT_RE). Empty for an ordinary check.
  */
 export declare function classifyCommandRun(run: CommandRun, gapPatterns?: readonly RegExp[]): CommandVerdict;
+/**
+ * How a re-run of ONE recorded VERIFY command line ended.
+ *   pass — it ran and exited 0. The ONLY outcome that may close a debt.
+ *   fail — it ran and exited non-zero for a real reason. Debt stays open.
+ *   gap  — nothing was observed: the shell/runner never spawned, 127 inside the
+ *          chain, a timeout, a missing browser, or absent external infrastructure.
+ *          INCONCLUSIVE, so the debt stays open (surface, never re-hide).
+ */
+export type VerifyRerunOutcome = {
+    outcome: 'pass';
+} | {
+    outcome: 'fail';
+    status: number;
+    tail: string;
+} | {
+    outcome: 'gap';
+    detail: string;
+};
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export declare function runVerifyCommandLine(cwd: string, line: string, timeoutMs: number, extraGapRe?: RegExp, 
+/** The spawner. Injected so a re-run's outcome can be tested without one. */
+run?: CommandRunner): VerifyRerunOutcome;

package/dist/task/command-run.js

@@ -28,7 +28,7 @@
  * had none.
  */
 import { spawnSync } from 'node:child_process';
-import { isCommandNotFound } from './runner-resolve.js';
+import { isCommandNotFound, resolveRunner, runnerEnv } from './runner-resolve.js';
 /** The real runner. */
 export const spawnCommand = spec => {
     const r = spawnSync(spec.bin, spec.args, {
@@ -136,3 +136,50 @@ export function classifyCommandRun(run, gapPatterns = []) {
         tail: outputTail(run.stdout, run.stderr)
     };
 }
+/** The command word of a shell line, past any leading `VAR=value` assignments. */
+function leadingBin(line) {
+    for (const tok of line.trim().split(/\s+/)) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tok))
+            continue;
+        return tok;
+    }
+    return null;
+}
+/**
+ * Re-run one VERIFY-block command line (nexttask 5) under the gate's existing
+ * env-gap contract, so a debt whose reason NAMES that command can be closed by the
+ * command itself rather than by a judgement about it.
+ *
+ * Runs through `sh -c` because a VERIFY line is a shell line, not an argv: run 19's
+ * is `AGENT=1 bun test test/listings.test.ts`, and env prefixes, `&&` and redirects
+ * are all ordinary there. The leading command word is still resolved through
+ * runner-resolve so a login-shell-stripped PATH cannot make every re-run look like a
+ * gap (mx5 run 16's blindness, one level down).
+ *
+ * The asymmetry is the point: only exit 0 is conclusive. Every other ending — real
+ * failure, missing tool, unreachable database, timeout, no POSIX shell — leaves the
+ * debt exactly as open as it was.
+ */
+export function runVerifyCommandLine(cwd, line, timeoutMs, extraGapRe, 
+/** The spawner. Injected so a re-run's outcome can be tested without one. */
+run = spawnCommand) {
+    const bin = leadingBin(line);
+    const runner = bin === null ? null : resolveRunner(bin);
+    // A VERIFY line is a SHELL line, not an argv — env prefixes, `&&` and
+    // redirects are all ordinary there — so the runner spawns `sh -c`.
+    const verdict = classifyCommandRun(run({
+        cwd,
+        bin: 'sh',
+        args: ['-c', line],
+        timeoutMs,
+        env: runner ? runnerEnv(runner) : { ...process.env }
+    }), 
+    // Infrastructure counts as a gap on EVERY debt re-run, not only on
+    // request: an unreachable database cannot tell us whether the code is
+    // fixed, and the asymmetry below means an inconclusive re-run simply
+    // leaves the debt as open as it was.
+    extraGapRe ? [INFRA_GAP_OUTPUT_RE, extraGapRe] : [INFRA_GAP_OUTPUT_RE]);
+    if (verdict.outcome === 'gap')
+        return { outcome: 'gap', detail: verdict.detail };
+    return verdict;
+}

package/dist/task/command-watchdog.js

@@ -34,7 +34,7 @@ export { CommandWatchdog, commandTimeoutHint, realTimerDeps, reminderMessage, WA
 /**
  * One-shot marker: the most recent turn abort was issued BY THE WATCHDOG, not by
  * a human ESC. Both end the assistant turn with stopReason 'aborted' — the only
- * signal steerUntilDone's wasInterrupted() can read — so without this flag the
+ * signal steerUntilDone's classifyTurnEnd() can read — so without this flag the
  * steer loop can win the race against the watchdog's queued follow-up turn and
  * show a steering prompt to an empty room (wedging an unattended run).
  *

package/dist/task/context-usage.d.ts

@@ -1,7 +1,8 @@
 /**
- * Context-usage resolution — shared by the single-task widget (TaskRunner) and
- * the /task-auto planning loader (defaultDeps), which both mirror a child's
- * context_usage events into a display snapshot with identical math.
+ * Context-usage resolution — the one piece of math every child-status mirror
+ * shares. `ChildStatus` (child-status.ts) folds it into its `onContextUsage` for
+ * the planning and gate children; the single-task widget (TaskRunner) calls it
+ * directly, because its state is the whole-run `WidgetState`, not one child's.
  */
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import type { ContextSnapshot } from '../shared/child-process.js';

package/dist/task/context-usage.js

@@ -1,7 +1,8 @@
 /**
- * Context-usage resolution — shared by the single-task widget (TaskRunner) and
- * the /task-auto planning loader (defaultDeps), which both mirror a child's
- * context_usage events into a display snapshot with identical math.
+ * Context-usage resolution — the one piece of math every child-status mirror
+ * shares. `ChildStatus` (child-status.ts) folds it into its `onContextUsage` for
+ * the planning and gate children; the single-task widget (TaskRunner) calls it
+ * directly, because its state is the whole-run `WidgetState`, not one child's.
  */
 /** The parent session's context window, or 0 when the model doesn't expose it. */
 export function getParentContextWindow(ctx) {

package/dist/task/contracts.js

@@ -27,9 +27,7 @@
  * Stack-agnostic: an "interface fact" is any pinned boundary string; the guard is
  * pure substring matching over the source text, with no assumption about its shape.
  */
-import * as fsp from 'node:fs/promises';
-import * as path from 'node:path';
-import { tasksDir } from './task-io.js';
+import { makeLedger } from './ledger.js';
 const CONTRACTS_FILE = 'contracts.md';
 /** Cap kept entries so the injected block stays bounded on a large design. */
 const MAX_CONTRACTS = 40;
@@ -37,17 +35,26 @@ const MAX_CONTRACTS = 40;
 const MAX_CONTRACT_LENGTH = 300;
 /** A quote shorter than this is too generic to anchor a contract (and to match). */
 const MIN_QUOTE_LENGTH = 6;
+function lineKey(line) {
+    const q = /"([^"]+)"/.exec(line);
+    return normalise(q ? q[1] : line);
+}
+const ledger = makeLedger({
+    file: CONTRACTS_FILE,
+    max: MAX_CONTRACTS,
+    key: c => c.key,
+    serialize: c => c.line,
+    parse: raw => raw
+        .split('\n')
+        .filter(l => l.trim().length > 0)
+        .map(line => ({ line, key: lineKey(line) }))
+});
 export function contractsFile(cwd) {
-    return path.join(tasksDir(cwd), CONTRACTS_FILE);
+    return ledger.path(cwd);
 }
 /** The stored registry text ('' when none recorded yet). */
 export async function readContracts(cwd) {
-    try {
-        return (await fsp.readFile(contractsFile(cwd), 'utf8')).trim();
-    }
-    catch {
-        return '';
-    }
+    return ledger.readRaw(cwd);
 }
 /**
  * Normalise for substring matching: collapse all whitespace runs to one space and
@@ -114,31 +121,7 @@ function formatEntry(e) {
  * are swallowed — the registry is a sharpener, never a blocker.
  */
 export async function appendContracts(cwd, entries) {
-    if (entries.length === 0)
-        return;
-    try {
-        const existingLines = (await readContracts(cwd))
-            .split('\n')
-            .filter(l => l.trim().length > 0);
-        const seen = new Set(existingLines.map(l => {
-            const q = /"([^"]+)"/.exec(l);
-            return normalise(q ? q[1] : l);
-        }));
-        const merged = [...existingLines];
-        for (const e of entries) {
-            const key = normalise(e.quote);
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            merged.push(formatEntry(e));
-        }
-        const kept = merged.slice(-MAX_CONTRACTS);
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(contractsFile(cwd), kept.join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort registry
-    }
+    await ledger.append(cwd, entries.map(e => ({ line: formatEntry(e), key: normalise(e.quote) })));
 }
 /**
  * The read-only prompt block a downstream slice (refine/compose) receives when the

package/dist/task/deep-render-check.d.ts

@@ -177,3 +177,50 @@ export declare function runDeepRenderCheck(url: string, cwd: string, opts?: {
      *  is the whole runtime of a driver test. The gate never passes it. */
     quietMs?: number;
 }): Promise<DeepRenderOutcome>;
+/** A launched, connected browser: the client to speak to it and the one way to
+ *  tear it down. `close` is idempotent and never throws. */
+export interface LaunchedBrowser {
+    cdp: Cdp;
+    close: () => Promise<void>;
+}
+/**
+ * Everything that touches a real process or the filesystem: spawn the Chrome-family
+ * binary at `bin` with a throwaway profile at `userDataDir`, read the DevTools ws
+ * URL off its output, connect. Rejects if the browser exits or errors before it
+ * listens, or the socket cannot open; whatever was started by then is torn down.
+ * `signal` is the caller's teardown: aborting it closes whatever exists, mid-launch
+ * or after, which is how a budget timeout reaches a browser that never listened.
+ * The caller owns `userDataDir` (creation and removal) — this only points Chrome
+ * at it.
+ *
+ * @internal Exported for `drive` and its own harness; the gate goes through
+ * `runDeepRenderCheck`.
+ */
+export declare function launchBrowser(bin: string, userDataDir: string, { signal }?: {
+    signal?: AbortSignal;
+}): Promise<LaunchedBrowser>;
+/** The subset of `Cdp` the session drives: request/response and event fan-out.
+ *  Defined from what `driveSession` calls, so a scripted fake is a dozen lines. */
+export interface CdpLike {
+    send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<Record<string, unknown>>;
+    on(method: string, cb: (params: Record<string, unknown>) => void): void;
+}
+export interface DriveSessionOptions {
+    url: string;
+    credentials: LoginCredentials | null;
+    /** Turns the facts the session gathered into the verdict. `drive` wraps
+     *  `judgeDeepSession` with the recorder hook here. */
+    judge: (f: DeepSessionFacts) => DeepRenderOutcome;
+    /** Settle quiet window; defaults to QUIET_MS. */
+    quietMs?: number;
+}
+/**
+ * The session over an already-connected browser: navigate, inspect, sign in if the
+ * landing is a wall and credentials exist, settle, phase the same-origin request
+ * log against the sign-in request, re-enter once the sign-in was accepted, and
+ * hand the facts to `judge`. Pure protocol logic — no process, no filesystem, no
+ * socket — so every branch is testable against a fake `CdpLike`.
+ *
+ * @internal Exported for its own tests.
+ */
+export declare function driveSession(cdp: CdpLike, { url, credentials, judge, quietMs }: DriveSessionOptions): Promise<DeepRenderOutcome>;

package/dist/task/deep-render-check.js

@@ -494,35 +494,11 @@ export async function runDeepRenderCheck(url, cwd, opts = {}) {
     }
     const budget = opts.timeoutMs ?? DEEP_RENDER_TIMEOUT_MS;
     const userDataDir = mkdtempSync(path.join(os.tmpdir(), 'pi-task-deep-render-'));
-    let child = null;
-    let socket = null;
-    const cleanup = () => {
-        try {
-            socket?.close();
-        }
-        catch {
-            // socket already gone
-        }
-        try {
-            if (child?.pid)
-                process.kill(-child.pid, 'SIGKILL');
-        }
-        catch {
-            // group already gone
-        }
-        try {
-            rmSync(userDataDir, { recursive: true, force: true });
-        }
-        catch {
-            // best-effort temp cleanup
-        }
-    };
+    // Aborted in `finally`, so a browser still mid-launch when the budget expires is
+    // torn down too — the launch owns the process, and this is how it hears about it.
+    const teardown = new AbortController();
     try {
-        return await withTimeout(drive(url, bin, userDataDir, credentials, c => {
-            child = c;
-        }, s => {
-            socket = s;
-        }, opts.onFacts, opts.quietMs), budget);
+        return await withTimeout(drive(url, bin, userDataDir, credentials, opts.onFacts, opts.quietMs, teardown.signal), budget);
     }
     catch (e) {
         const why = e instanceof Error ? e.message : String(e);
@@ -532,7 +508,13 @@ export async function runDeepRenderCheck(url, cwd, opts = {}) {
         };
     }
     finally {
-        cleanup();
+        teardown.abort();
+        try {
+            rmSync(userDataDir, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort temp cleanup
+        }
     }
 }
 function withTimeout(p, ms) {
@@ -548,48 +530,111 @@ function withTimeout(p, ms) {
         });
     });
 }
-async function drive(url, bin, userDataDir, credentials, holdChild, holdSocket, onFacts, quietMs) {
-    const origin = new URL(url).origin;
+/** launch → session → close. The two halves are separately testable: the launch
+ *  against a fake browser on disk, the session against an in-process fake CDP. */
+async function drive(url, bin, userDataDir, credentials, onFacts, quietMs, signal) {
     /** Every verdict goes through here, so a recorder sees the same facts the judge
      *  does — the corpus is what the gate itself read, not a reconstruction. */
     const judge = (f) => {
         onFacts?.(f);
         return judgeDeepSession(f);
     };
-    const child = spawn(bin, [
-        '--headless',
-        '--disable-gpu',
-        '--no-sandbox',
-        '--disable-dev-shm-usage',
-        '--no-first-run',
-        '--no-default-browser-check',
-        '--disable-extensions',
-        `--user-data-dir=${userDataDir}`,
-        '--remote-debugging-port=0',
-        'about:blank'
-    ], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
-    holdChild(child);
-    child.unref();
-    const wsUrl = await new Promise((resolve, reject) => {
-        let buf = '';
-        const onData = (d) => {
-            buf += String(d);
-            const m = /DevTools listening on (ws:\/\/\S+)/.exec(buf);
-            if (m)
-                resolve(m[1]);
-        };
-        child.stderr?.on('data', onData);
-        child.stdout?.on('data', onData);
-        child.on('error', e => reject(e));
-        child.on('exit', code => reject(new Error(`browser exited ${code} before listening`)));
-    });
-    const socket = new WebSocket(wsUrl, { perMessageDeflate: false, maxPayload: 128 * 1024 * 1024 });
-    holdSocket(socket);
-    await new Promise((resolve, reject) => {
-        socket.once('open', () => resolve());
-        socket.once('error', e => reject(e instanceof Error ? e : new Error(String(e))));
-    });
-    const cdp = new Cdp(socket);
+    const browser = await launchBrowser(bin, userDataDir, { signal });
+    try {
+        return await driveSession(browser.cdp, { url, credentials, judge, quietMs });
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * Everything that touches a real process or the filesystem: spawn the Chrome-family
+ * binary at `bin` with a throwaway profile at `userDataDir`, read the DevTools ws
+ * URL off its output, connect. Rejects if the browser exits or errors before it
+ * listens, or the socket cannot open; whatever was started by then is torn down.
+ * `signal` is the caller's teardown: aborting it closes whatever exists, mid-launch
+ * or after, which is how a budget timeout reaches a browser that never listened.
+ * The caller owns `userDataDir` (creation and removal) — this only points Chrome
+ * at it.
+ *
+ * @internal Exported for `drive` and its own harness; the gate goes through
+ * `runDeepRenderCheck`.
+ */
+export async function launchBrowser(bin, userDataDir, { signal } = {}) {
+    let child = null;
+    let socket = null;
+    const close = () => {
+        try {
+            socket?.close();
+        }
+        catch {
+            // socket already gone
+        }
+        try {
+            if (child?.pid)
+                process.kill(-child.pid, 'SIGKILL');
+        }
+        catch {
+            // group already gone
+        }
+        return Promise.resolve();
+    };
+    signal?.addEventListener('abort', () => void close(), { once: true });
+    if (signal?.aborted) {
+        throw new Error('aborted before launch');
+    }
+    try {
+        child = spawn(bin, [
+            '--headless',
+            '--disable-gpu',
+            '--no-sandbox',
+            '--disable-dev-shm-usage',
+            '--no-first-run',
+            '--no-default-browser-check',
+            '--disable-extensions',
+            `--user-data-dir=${userDataDir}`,
+            '--remote-debugging-port=0',
+            'about:blank'
+        ], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        const proc = child;
+        proc.unref();
+        const wsUrl = await new Promise((resolve, reject) => {
+            let buf = '';
+            const onData = (d) => {
+                buf += String(d);
+                const m = /DevTools listening on (ws:\/\/\S+)/.exec(buf);
+                if (m)
+                    resolve(m[1]);
+            };
+            proc.stderr?.on('data', onData);
+            proc.stdout?.on('data', onData);
+            proc.on('error', e => reject(e));
+            proc.on('exit', code => reject(new Error(`browser exited ${code} before listening`)));
+        });
+        const ws = new WebSocket(wsUrl, { perMessageDeflate: false, maxPayload: 128 * 1024 * 1024 });
+        socket = ws;
+        await new Promise((resolve, reject) => {
+            ws.once('open', () => resolve());
+            ws.once('error', e => reject(e instanceof Error ? e : new Error(String(e))));
+        });
+        return { cdp: new Cdp(ws), close };
+    }
+    catch (e) {
+        await close();
+        throw e;
+    }
+}
+/**
+ * The session over an already-connected browser: navigate, inspect, sign in if the
+ * landing is a wall and credentials exist, settle, phase the same-origin request
+ * log against the sign-in request, re-enter once the sign-in was accepted, and
+ * hand the facts to `judge`. Pure protocol logic — no process, no filesystem, no
+ * socket — so every branch is testable against a fake `CdpLike`.
+ *
+ * @internal Exported for its own tests.
+ */
+export async function driveSession(cdp, { url, credentials, judge, quietMs }) {
+    const origin = new URL(url).origin;
     const requests = new Map();
     let lastActivity = Date.now();
     cdp.on('Network.requestWillBeSent', p => {

package/dist/task/env-notes.d.ts

@@ -1,6 +1,3 @@
-export declare function envNotesFile(cwd: string): string;
-/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
-export declare function readEnvNotes(cwd: string): Promise<string>;
 /** One recorded fact plus the origin task that established it (may be ''). */
 export interface EnvNote {
     fact: string;
@@ -11,6 +8,9 @@ export interface EnvNote {
  * provenance (no separator) parse with an empty origin, so old caches still read.
  */
 export declare function parseEnvNotes(raw: string): EnvNote[];
+export declare function envNotesFile(cwd: string): string;
+/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
+export declare function readEnvNotes(cwd: string): Promise<string>;
 /**
  * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
  * length-capped; verdict markers can never match (different prefix).