@mjasnikovs/pi-task 0.38.10 → 0.38.12

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).

package/dist/task/env-notes.js

@@ -32,9 +32,7 @@
  * exactly that scrutiny, and forbids treating a grep of a generated artifact as
  * evidence of absence. Provenance is mechanical; re-validation is prompt-level.
  */
-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 ENV_NOTES_FILE = 'env-notes.md';
 /** Cap kept notes so a chatty run cannot grow the prompt block unboundedly. */
 const MAX_NOTES = 40;
@@ -46,18 +44,6 @@ const MAX_NOTE_LENGTH = 240;
  * stray tab in an emitted fact is normalised to a space before storage.
  */
 const ORIGIN_SEP = '\t';
-export function envNotesFile(cwd) {
-    return path.join(tasksDir(cwd), ENV_NOTES_FILE);
-}
-/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
-export async function readEnvNotes(cwd) {
-    try {
-        return (await fsp.readFile(envNotesFile(cwd), 'utf8')).trim();
-    }
-    catch {
-        return '';
-    }
-}
 /**
  * Parse the stored file into fact+origin records. Legacy lines written before
  * provenance (no separator) parse with an empty origin, so old caches still read.
@@ -79,6 +65,22 @@ export function parseEnvNotes(raw) {
 function serializeNote(n) {
     return n.origin ? `${n.fact}${ORIGIN_SEP}${n.origin}` : n.fact;
 }
+/** Keyed on the fact alone (case-insensitive): a fact already present keeps its
+ *  ORIGINAL origin — provenance traces to who first established it. */
+const ledger = makeLedger({
+    file: ENV_NOTES_FILE,
+    max: MAX_NOTES,
+    key: n => n.fact.toLowerCase(),
+    serialize: serializeNote,
+    parse: parseEnvNotes
+});
+export function envNotesFile(cwd) {
+    return ledger.path(cwd);
+}
+/** The raw stored file ('' when none were recorded yet). Parse with parseEnvNotes. */
+export async function readEnvNotes(cwd) {
+    return ledger.readRaw(cwd);
+}
 /**
  * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
  * length-capped; verdict markers can never match (different prefix).
@@ -134,27 +136,14 @@ export function isExcuseNote(fact) {
  * blocker.
  */
 export async function appendEnvNotes(cwd, notes, origin = '') {
-    if (notes.length === 0)
-        return;
-    try {
-        const existing = parseEnvNotes(await readEnvNotes(cwd));
-        const seen = new Set(existing.map(n => n.fact.toLowerCase()));
-        const merged = [...existing];
-        for (const note of notes) {
-            const fact = note.trim().replace(/\t/g, ' ');
-            const key = fact.toLowerCase();
-            if (key.length === 0 || seen.has(key))
-                continue;
-            seen.add(key);
-            merged.push({ fact, origin: origin.trim() });
-        }
-        const kept = merged.slice(-MAX_NOTES);
-        await fsp.mkdir(tasksDir(cwd), { recursive: true });
-        await fsp.writeFile(envNotesFile(cwd), kept.map(serializeNote).join('\n') + '\n', 'utf8');
-    }
-    catch {
-        // best-effort cache
+    const fresh = [];
+    for (const note of notes) {
+        const fact = note.trim().replace(/\t/g, ' ');
+        if (fact.length === 0)
+            continue;
+        fresh.push({ fact, origin: origin.trim() });
     }
+    await ledger.append(cwd, fresh);
 }
 /**
  * The prompt block a gate child receives when notes exist. Two things are

package/dist/task/final-gate-fix.d.ts

@@ -38,7 +38,7 @@ export declare function classifyFinalGateAnswer(answer: string | undefined): Fin
  * Extract it for reporting; the shrink guard itself compares the FULL
  * discovered-command sets, so a reason this cannot parse still guards.
  */
-export declare function extractFailingCommand(reason: string): string | null;
+export declare function exitedCommandFromReason(reason: string): string | null;
 /**
  * Build the fix child's prompt. Generic by construction: the only project facts
  * in it are the gate's own failure text — the command comes from the project's

package/dist/task/final-gate-fix.js

@@ -90,7 +90,7 @@ export function classifyFinalGateAnswer(answer) {
  * Extract it for reporting; the shrink guard itself compares the FULL
  * discovered-command sets, so a reason this cannot parse still guards.
  */
-export function extractFailingCommand(reason) {
+export function exitedCommandFromReason(reason) {
     const m = /`([^`]+)`\s+exited\b/.exec(reason);
     return m ? m[1] : null;
 }