@astrosheep/pi-context 0.19.0 → 0.21.0

package/dist/test/coherence.test.js

@@ -0,0 +1,375 @@
+/**
+ * OWNER: pi-context (adopted).
+ * STATUS: tracked acceptance spec for the history and notes read/search tools. No skip.
+ * CLAIM: following the cursors these tools return must reconstruct the original text exactly,
+ *   or the result must name the skipped range. Both read tools are one character window over two
+ *   stores (notes_read and history_read share the cursor walk below). In v2 this failed
+ *   at 13 sites; the rows that demanded an over-budget line in a single call are rebuilt as
+ *   cursor-walking rows below (the CLAIM explicitly licenses that: reconstruct exactly by
+ *   following cursors, or name the skipped range).
+ * HERMETIC: this file reads only its own in-memory session. Corpus replays of real sessions
+ *   are NOT hermetic, must be single-pass, and belong in a dev script, not npm test.
+ */
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import piContext, { historyFromSession } from "../src/index.js";
+import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
+import { stripLeadingFrontmatter } from "../src/notes/frontmatter.js";
+process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pc-coherence-agent-"));
+process.env.PI_NOTES_HOME = mkdtempSync(join(tmpdir(), "pc-coherence-notes-"));
+function makeExtension(sessionManager) {
+    const captured = { tools: new Map() };
+    const api = {
+        registerFlag() { },
+        registerTool(tool) { captured.tools.set(tool.name, tool); },
+        registerCommand() { },
+        on() { },
+        appendEntry(customType, data) { sessionManager.appendCustomEntry(customType, data); },
+        sendMessage(message) {
+            sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
+        },
+    };
+    piContext(api);
+    return captured;
+}
+function context(sessionManager) {
+    const fake = {
+        sessionManager,
+        getContextUsage: () => undefined,
+        compact: () => { },
+        isIdle: () => true,
+        hasPendingMessages: () => false,
+        cwd: "/private/tmp/pi-context-test",
+        isProjectTrusted: () => true,
+        ui: { notify: () => { } },
+    };
+    return fake;
+}
+async function call(captured, name, params, ctx) {
+    const tool = captured.tools.get(name);
+    assert.ok(tool, `registered ${name}`);
+    if ((name === "notes_write" || name === "notes_read") && "path" in params && !("address" in params)) {
+        const { path, ...rest } = params;
+        return tool.execute("call-1", { ...rest, address: path }, new AbortController().signal, () => { }, ctx);
+    }
+    return tool.execute("call-1", params, new AbortController().signal, () => { }, ctx);
+}
+function resultJson(result) {
+    const text = result.content[0];
+    assert.ok(text && text.type === "text");
+    return JSON.parse(text.text);
+}
+function assertWithinBudget(result, label) {
+    const bytes = Buffer.byteLength(result.content[0] && result.content[0].type === "text" ? result.content[0].text : "", "utf8");
+    if (bytes > TOOL_OUTPUT_MAX_BYTES)
+        failures.push(`${label}: response is ${bytes} bytes, over the ${TOOL_OUTPUT_MAX_BYTES}-byte budget`);
+}
+function appendText(sessionManager, text) {
+    return sessionManager.appendMessage({ role: "user", content: [{ type: "text", text }], timestamp: Date.now() });
+}
+/**
+ * Decode a raw read (notes_read / history_read): a one-line bracketed header, then
+ * the payload verbatim (which may itself contain newlines), so split on the first newline only.
+ */
+function resultRead(result) {
+    const text = result.content[0];
+    assert.ok(text && text.type === "text", "read result carries text");
+    const newline = text.text.indexOf("\n");
+    assert.ok(newline !== -1, "raw read carries a header line and a payload");
+    const header = text.text.slice(0, newline);
+    const content = text.text.slice(newline + 1);
+    assert.match(header, /^\[/, "the header is bracketed");
+    assert.match(header, /\]$/, "the header closes its bracket");
+    const match = header.match(/ · chars (\d+)-(\d+) of (\d+) · (end|continue at offset_chars=(\d+))/);
+    assert.ok(match, `read header names the char range and resume cursor: ${header}`);
+    const offset_chars = Number(match[1]);
+    const total_chars = Number(match[3]);
+    const next_offset_chars = match[4] === "end" ? null : Number(match[5]);
+    assert.equal([...content].length, Number(match[2]) - offset_chars, "the header range matches the delivered payload");
+    return { header, content, offset_chars, total_chars, next_offset_chars };
+}
+const PROFILES = [
+    { name: "cjk", unit: "历" },
+    { name: "emoji", unit: "🕷" },
+    { name: "ascii", unit: "x" },
+];
+const failures = [];
+const report = [];
+const codePoints = (text) => [...text].length;
+const codePointSlice = (text, start, end) => [...text].slice(start, end).join("");
+/**
+ * Follow either read tool's cursor exactly as the protocol tells the model to, asserting the
+ * cursor law on every page. Both tools are the same character window over two stores, so one
+ * walker serves both; `address` carries the tool's own identity parameters, and `options.start`
+ * lets a walk begin at a resolved address (a search hit's offset, or a negative tail read).
+ */
+async function walkWindow(captured, ctx, tool, address, label, options = {}) {
+    const parts = [];
+    let offset = options.start ?? 0;
+    let next = 0;
+    let calls = 0;
+    let total = 0;
+    while (next !== null && calls < 400) {
+        const params = { ...address, offset_chars: offset };
+        if (options.limitChars !== undefined)
+            params.limit_chars = options.limitChars;
+        const result = await call(captured, tool, params, ctx);
+        assertWithinBudget(result, `${label} offset=${offset}`);
+        const page = resultRead(result);
+        total = page.total_chars;
+        const delivered = codePoints(page.content);
+        if (page.offset_chars !== offset)
+            failures.push(`cursor law: ${label} echoed offset_chars=${page.offset_chars} for request offset ${offset}`);
+        if (page.next_offset_chars !== null && page.next_offset_chars !== offset + delivered) {
+            failures.push(`cursor law: ${label} next_offset_chars=${page.next_offset_chars} but offset ${offset} + delivered ${delivered}`);
+        }
+        if (page.next_offset_chars === null && offset + delivered !== page.total_chars) {
+            failures.push(`false exhaustion: ${label} returned next_offset_chars=null with ${page.total_chars - (offset + delivered)} characters undelivered`);
+        }
+        if (page.content.includes("…") || page.content.includes("[truncated"))
+            failures.push(`honest payload: ${label} appended a marker at offset ${offset}`);
+        parts.push(page.content);
+        next = page.next_offset_chars;
+        if (next !== null)
+            offset = next;
+        calls++;
+    }
+    if (offset !== total && calls >= 400)
+        failures.push(`${label} never terminated`);
+    return parts.join("");
+}
+const walkHistory = (captured, ctx, windowId, itemId, limitChars) => walkWindow(captured, ctx, "history_read", { window_id: windowId, item_id: itemId }, `history_read ${itemId}`, { limitChars });
+const walkNote = (captured, ctx, path, start = 0) => walkWindow(captured, ctx, "notes_read", { path }, `notes_read ${path}`, { start });
+test("coherence: following the returned cursors reconstructs the original text exactly", async () => {
+    const session = SessionManager.inMemory("/private/tmp/pi-context-test");
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const windowId = historyFromSession(ctx)[0].windowId;
+    // --- history_read: every profile x length reconstructs; cursor law holds per page ---
+    for (const profile of PROFILES) {
+        for (const length of [12_000, 12_001, 20_000, 30_000]) {
+            const original = profile.unit.repeat(length);
+            const itemId = appendText(session, original);
+            const reconstructed = await walkHistory(captured, ctx, windowId, itemId);
+            const missing = codePoints(original) - codePoints(reconstructed);
+            const line = `history_read default: ${profile.name} ${length} chars (${Buffer.byteLength(original, "utf8")} bytes) -> delivered ${codePoints(reconstructed)} chars, missing ${missing}, marker=${reconstructed.includes("[truncated")}`;
+            report.push(line);
+            if (reconstructed !== original)
+                failures.push(line);
+            session.appendMessage({ role: "assistant", content: [{ type: "text", text: `ack ${length}` }], timestamp: Date.now() });
+        }
+    }
+    // --- notes_read: a 40,000-code-point single line plus a tail, three profiles ---
+    for (const profile of PROFILES) {
+        const hugeLine = profile.unit.repeat(40_000);
+        const text = `${hugeLine}\ntail line`;
+        const path = `huge-${profile.name}.md`;
+        await call(captured, "notes_write", { path, content: text }, ctx);
+        const reconstructed = stripLeadingFrontmatter(await walkNote(captured, ctx, path));
+        const missing = codePoints(text) - codePoints(reconstructed);
+        const line = `notes_read: ${profile.name} single line ${codePoints(hugeLine)} chars (${Buffer.byteLength(hugeLine, "utf8")} bytes) -> delivered ${codePoints(reconstructed)} chars, missing ${missing}, marker=${reconstructed.includes("[truncated")}`;
+        report.push(line);
+        if (reconstructed !== text)
+            failures.push(line);
+    }
+    // --- The terminator itself can lie. A single line with no trailing newline is exactly what
+    // notes_write { content } produces; the returned cursor must not be null while text remains.
+    for (const profile of PROFILES) {
+        const hugeLine = profile.unit.repeat(40_000);
+        const path = `solo-${profile.name}.md`;
+        await call(captured, "notes_write", { path, content: hugeLine }, ctx);
+        const first = resultRead(await call(captured, "notes_read", { path }, ctx));
+        const deliveredBody = first.content.startsWith("---\n") ? stripLeadingFrontmatter(first.content) : first.content;
+        const undelivered = codePoints(hugeLine) - codePoints(deliveredBody);
+        report.push(`notes_read no trailing newline: ${profile.name} ${codePoints(hugeLine)} chars -> first page delivered ${codePoints(deliveredBody)} body chars, undelivered ${undelivered}, offset_chars=${first.offset_chars}, next_offset_chars=${String(first.next_offset_chars)}, marker=${first.content.includes("[truncated")}`);
+        if (first.offset_chars !== 0)
+            failures.push(`window echo: ${profile.name} first page echoed offset_chars=${first.offset_chars}, expected 0`);
+        if (first.total_chars < codePoints(hugeLine))
+            failures.push(`window total: ${profile.name} total_chars=${first.total_chars}, expected at least the body length`);
+        if (!first.content.startsWith("---\n"))
+            failures.push(`frontmatter first: ${profile.name} first page does not open with frontmatter`);
+        if (first.next_offset_chars === null && undelivered > 0)
+            failures.push(`false exhaustion: ${profile.name} returns next_offset_chars=null while ${undelivered} characters were never delivered`);
+        if (!hugeLine.startsWith(deliveredBody))
+            failures.push(`prefix law: ${profile.name} first page body is not a prefix of the line`);
+        const reconstructed = stripLeadingFrontmatter(await walkNote(captured, ctx, path));
+        if (reconstructed !== hugeLine)
+            failures.push(`notes_read single line is not reconstructible: ${profile.name}, ${codePoints(hugeLine) - codePoints(reconstructed)} chars missing`);
+    }
+    // --- The empty note must terminate: no self-feeding cursor, and a frontmatter-only window from 0.
+    await call(captured, "notes_write", { path: "empty.md", content: "" }, ctx);
+    const empty = resultRead(await call(captured, "notes_read", { path: "empty.md" }, ctx));
+    report.push(`notes_read empty note: offset_chars=${empty.offset_chars} total_chars=${empty.total_chars} next_offset_chars=${String(empty.next_offset_chars)} content=${JSON.stringify(empty.content)}`);
+    if (empty.offset_chars !== 0 || !empty.content.startsWith("---\n") || !empty.content.endsWith("---\n\n"))
+        failures.push("the empty note is not a frontmatter-only window from 0");
+    if (empty.next_offset_chars !== null)
+        failures.push("pagination hole: the empty note is never exhausted");
+    // --- notes_search: an over-budget matched line is named, then read back with cursors ---
+    const hugeCjkLine = "历".repeat(40_000);
+    const searched = resultJson(await call(captured, "notes_search", { query: "历", pattern: "huge-cjk.md" }, ctx));
+    const matchedFile = searched.files[0];
+    const matched = matchedFile?.matches[0];
+    report.push(`notes_search: matches_total=${String(matchedFile?.matches_total)} returned=${String(matchedFile?.matches.length)} first match delivered ${codePoints(matched?.text ?? "")} of ${String(matched?.total_chars)} chars, truncated=${String(matched?.truncated)}`);
+    if (!matched)
+        failures.push("notes_search dropped the over-budget matched line entirely");
+    else {
+        if (matched.truncated !== true)
+            failures.push("notes_search does not flag the over-budget matched line as truncated");
+        if (matched.total_chars !== codePoints(hugeCjkLine))
+            failures.push(`notes_search match total_chars=${matched.total_chars}, expected ${codePoints(hugeCjkLine)}`);
+        if (!hugeCjkLine.startsWith(matched.text))
+            failures.push("notes_search delivered a non-prefix of the matched line");
+        if (codePoints(matched.text) >= matched.total_chars)
+            failures.push("notes_search claims the over-budget line fits in one response");
+        const walked = stripLeadingFrontmatter(await walkNote(captured, ctx, "huge-cjk.md"));
+        if (walked !== `${hugeCjkLine}\ntail line`)
+            failures.push(`notes_search match line is not reconstructible from the note read: missing ${codePoints(`${hugeCjkLine}\ntail line`) - codePoints(walked)} chars`);
+    }
+    // --- history_search: a hit's visible text may be cut, but the offset it carries
+    // must resolve to the query through history_read (addresses-only mode).
+    const searchItemContent = `${"padding ".repeat(400)}历史内容${" trailing".repeat(400)}`;
+    const searchItemId = appendText(session, searchItemContent);
+    const hit = resultJson(await call(captured, "history_search", { query: "历史内容", max_chars_per_item: 400, window_id: windowId }, ctx));
+    const first = hit.items.find((item) => item.item_id === searchItemId);
+    report.push(`history_search: hit present=${Boolean(first)}, fields=${JSON.stringify(Object.keys(first ?? {}))}, match_offset_chars=${String(first?.match_offset_chars)}, truncated=${String(first?.truncated)}`);
+    if (!first)
+        failures.push("history_search did not return the matching item");
+    else {
+        if (first.truncated !== true)
+            failures.push("history_search does not flag the capped item as truncated");
+        if (first.total_chars !== codePoints(searchItemContent))
+            failures.push(`history_search total_chars=${first.total_chars}, expected ${codePoints(searchItemContent)}`);
+        if (!searchItemContent.startsWith(first.truncated_content))
+            failures.push("history_search delivered a non-prefix of the item");
+        if (first.truncated_content.includes("…"))
+            failures.push("history_search appended a marker to the payload");
+        if (!Number.isInteger(first.match_offset_chars))
+            failures.push("history_search carries no match_offset_chars");
+        else {
+            const at = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: searchItemId, offset_chars: first.match_offset_chars, limit_chars: 8 }, ctx));
+            if (!at.content.includes("历史内容"))
+                failures.push(`history_read at match_offset_chars=${first.match_offset_chars} does not show the query`);
+        }
+    }
+    // max_chars_per_item: 1 is a real address page for both history tools.
+    const addresses = resultJson(await call(captured, "history_search", { query: "历史内容", max_chars_per_item: 1, window_id: windowId }, ctx));
+    const address = addresses.items.find((item) => item.item_id === searchItemId);
+    report.push(`history_search max_chars_per_item=1: address=${JSON.stringify(address)}`);
+    if (!address)
+        failures.push("history_search max_chars_per_item=1 dropped the hit");
+    else {
+        if (codePoints(address.truncated_content) !== 1)
+            failures.push(`max_chars_per_item=1 delivered ${codePoints(address.truncated_content)} code points`);
+        if (address.truncated !== true || address.total_chars !== codePoints(searchItemContent))
+            failures.push("max_chars_per_item=1 does not name the full length");
+        if (!Number.isInteger(address.match_offset_chars))
+            failures.push("max_chars_per_item=1 carries no address");
+    }
+    const listed = resultJson(await call(captured, "history_list", { window_id: windowId, max_chars_per_item: 1, recent_first: false, limit: 500 }, ctx));
+    const listedAddress = listed.items.find((item) => item.item_id === searchItemId);
+    report.push(`history_list max_chars_per_item=1: ${JSON.stringify(listedAddress)}`);
+    if (!listedAddress)
+        failures.push("history_list max_chars_per_item=1 dropped the item");
+    else if (codePoints(listedAddress.truncated_content) !== 1 || listedAddress.truncated !== true || listedAddress.total_chars !== codePoints(searchItemContent)) {
+        failures.push("history_list max_chars_per_item=1 is not an honest address page");
+    }
+    // --- brain-04: capping a file's matches to fit the wire budget must be named, never silent.
+    const manyLines = Array.from({ length: 8_000 }, (_, index) => `needle ${index}`);
+    await call(captured, "notes_write", { path: "many.md", content: manyLines.join("\n") }, ctx);
+    const many = resultJson(await call(captured, "notes_search", { query: "needle", pattern: "many.md" }, ctx));
+    const manyEntry = many.files[0];
+    report.push(`brain-04: matches_total=${String(manyEntry?.matches_total)} returned=${String(manyEntry?.matches.length)}, next_cursor=${String(many.next_cursor)}`);
+    if (!manyEntry)
+        failures.push("brain-04: the many-match file is absent from the search result");
+    else {
+        if (manyEntry.matches_total !== manyLines.length)
+            failures.push(`brain-04: matches_total=${manyEntry.matches_total}, expected ${manyLines.length}`);
+        if (!(manyEntry.matches_total > manyEntry.matches.length))
+            failures.push("brain-04: budget-capped matches were silently dropped (matches_total === matches.length)");
+        if (manyEntry.matches_total - manyEntry.matches.length <= 0)
+            failures.push("brain-04: the response names no dropped matches");
+    }
+    // A file whose first match alone is over budget with more matches behind it: dropping trailing
+    // matches and cutting the kept line must still leave the whole response inside the wire budget.
+    const manyHugeLines = Array.from({ length: 4 }, (_, index) => `needle ${index} ${"w".repeat(45_000)}`);
+    await call(captured, "notes_write", { path: "huge-many.md", content: manyHugeLines.join("\n") }, ctx);
+    const hugeManyResult = await call(captured, "notes_search", { query: "needle", pattern: "huge-many.md" }, ctx);
+    assertWithinBudget(hugeManyResult, "notes_search huge-many");
+    const hugeEntry = resultJson(hugeManyResult).files[0];
+    report.push(`huge-many: matches_total=${String(hugeEntry?.matches_total)} returned=${String(hugeEntry?.matches.length)} truncated=${String(hugeEntry?.matches[0]?.truncated)}`);
+    if (!hugeEntry)
+        failures.push("huge-many: the many-huge-match file is absent from the search result");
+    else {
+        if (!(hugeEntry.matches_total > hugeEntry.matches.length))
+            failures.push("huge-many: dropped matches are not named");
+        if (hugeEntry.matches[0]?.truncated !== true)
+            failures.push("huge-many: the kept match is not flagged as a prefix");
+    }
+    // --- notes_search addresses: a match's offset_chars is the body-absolute code-point
+    // position of the earliest query occurrence in its line, so search → read composes exactly like
+    // history's match_offset_chars two-stage.
+    const addressLine1 = "pad ".repeat(50);
+    const addressLine3 = `${"历".repeat(20)}needle-address here`;
+    const addressLine4 = "zeta 历 needle-address";
+    await call(captured, "notes_write", { path: "address.md", content: `${addressLine1}\nsecond\n${addressLine3}\n${addressLine4}` }, ctx);
+    const expectedAddress = codePoints(addressLine1) + 1 + codePoints("second") + 1 + 20;
+    const addressHit = resultJson(await call(captured, "notes_search", { query: "needle-address", pattern: "address.md" }, ctx)).files[0]?.matches.find((match) => match.line === 3);
+    report.push(`notes_search address: line=${String(addressHit?.line)} offset_chars=${String(addressHit?.offset_chars)} expected=${expectedAddress}`);
+    const addressOffset = addressHit?.offset_chars;
+    if (typeof addressOffset !== "number")
+        failures.push("notes_search carries no offset_chars");
+    else if (addressOffset !== expectedAddress)
+        failures.push(`notes_search offset_chars=${addressOffset}, expected ${expectedAddress} (body-absolute, at the query)`);
+    // Multi-query OR: a line's address is the earliest occurrence of any query inside that line.
+    const line4Base = expectedAddress - 20 + codePoints(addressLine3) + 1;
+    const orLine4 = resultJson(await call(captured, "notes_search", { query: ["needle-address", "zeta"], pattern: "address.md" }, ctx)).files[0]?.matches.find((match) => match.line === 4);
+    report.push(`notes_search OR address: offset_chars=${String(orLine4?.offset_chars)} expected=${line4Base}`);
+    if (orLine4?.offset_chars !== line4Base)
+        failures.push(`notes_search OR offset_chars=${String(orLine4?.offset_chars)}, expected ${line4Base} (earliest of any query)`);
+    // --- Negative offsets on both stores: a tail read reaches the end in one call, the response
+    // echoes the resolved absolute offset, N >= total_chars reads from the start, and the cursor
+    // law still holds when a negative-start page is cut short.
+    for (const profile of PROFILES) {
+        const tailText = `head${profile.unit.repeat(20)}TAIL${profile.unit.repeat(20)}`;
+        const path = `tail-${profile.name}.md`;
+        await call(captured, "notes_write", { path, content: tailText }, ctx);
+        const full = resultRead(await call(captured, "notes_read", { path }, ctx));
+        const total = full.total_chars;
+        const bodyChars = codePoints(tailText);
+        const tail = resultRead(await call(captured, "notes_read", { path, offset_chars: -10 }, ctx));
+        report.push(`notes_read negative offset: ${profile.name} total=${total} -> offset_chars=${tail.offset_chars} next=${String(tail.next_offset_chars)} content=${JSON.stringify(tail.content)}`);
+        if (tail.offset_chars !== total - 10)
+            failures.push(`negative offset: notes_read ${profile.name} echoed ${tail.offset_chars}, expected ${total - 10}`);
+        if (tail.content !== codePointSlice(tailText, bodyChars - 10))
+            failures.push(`negative offset: notes_read ${profile.name} did not reach the body tail in one call`);
+        if (tail.next_offset_chars !== null)
+            failures.push(`negative offset: notes_read ${profile.name} tail read is not exhausted`);
+        const fromStart = resultRead(await call(captured, "notes_read", { path, offset_chars: -(total + 5), limit_chars: 8 }, ctx));
+        if (fromStart.offset_chars !== 0)
+            failures.push(`negative offset: notes_read ${profile.name} with N >= total_chars echoed ${fromStart.offset_chars}, expected 0`);
+        if (fromStart.content !== codePointSlice(full.content, 0, 8))
+            failures.push(`negative offset: notes_read ${profile.name} with N >= total_chars did not read from the start`);
+        const cut = resultRead(await call(captured, "notes_read", { path, offset_chars: -15, limit_chars: 4 }, ctx));
+        if (cut.next_offset_chars !== cut.offset_chars + codePoints(cut.content))
+            failures.push(`negative offset: notes_read ${profile.name} cut a negative-start read off the cursor law`);
+        const resumed = resultRead(await call(captured, "notes_read", { path, offset_chars: cut.next_offset_chars }, ctx));
+        if (resumed.offset_chars !== cut.next_offset_chars)
+            failures.push(`negative offset: notes_read ${profile.name} resume echoed ${resumed.offset_chars}, expected ${String(cut.next_offset_chars)}`);
+    }
+    // history_read gains the identical sugar over a durable item.
+    const historyTailText = `${"h".repeat(50)}END`;
+    const historyTailId = appendText(session, historyTailText);
+    const historyTail = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: historyTailId, offset_chars: -3 }, ctx));
+    report.push(`history_read negative offset: offset_chars=${historyTail.offset_chars} next=${String(historyTail.next_offset_chars)} content=${JSON.stringify(historyTail.content)}`);
+    if (historyTail.offset_chars !== 50 || historyTail.content !== "END" || historyTail.next_offset_chars !== null)
+        failures.push(`negative offset: history_read returned ${JSON.stringify(historyTail)}`);
+    const historyFromStart = resultRead(await call(captured, "history_read", { window_id: windowId, item_id: historyTailId, offset_chars: -500, limit_chars: 4 }, ctx));
+    if (historyFromStart.offset_chars !== 0 || historyFromStart.content !== "hhhh")
+        failures.push(`negative offset: history_read with N >= total_chars returned ${JSON.stringify(historyFromStart)}`);
+    console.log(report.map((line) => `  ${line}`).join("\n"));
+    assert.deepEqual(failures, [], `cursor-following lost text at ${failures.length} site(s)`);
+});

package/dist/test/dream.test.js

@@ -0,0 +1,142 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, linkSync, mkdirSync, readFileSync, statSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { acquireLock, failLock } from "../src/dream/lock.js";
+import { materialGate, timeGate } from "../src/dream/gates.js";
+import { defaultDreamerSessionFactory, dreamerWriteToolDefinitions, runDreamer, DREAMER_TOOLS } from "../src/dream/runner.js";
+import { gitCommit } from "../src/dream/git.js";
+import { execFileSync } from "node:child_process";
+import { contentText } from "../src/history.js";
+function fixture() { return mkdtempSync(join(tmpdir(), "dream-")); }
+function old(path) { const d = new Date(Date.now() - 48 * 3600_000); utimesSync(path, d, d); }
+test("time and material gates preserve skip decisions and reasons", () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    writeFileSync(lock, "999999");
+    const fresh = timeGate(lock, 24);
+    assert.equal(fresh.ok, false);
+    assert.equal(fresh.reason, "time gate: lock is too fresh");
+    old(lock);
+    assert.deepEqual(timeGate(lock, 24).ok, true);
+    mkdirSync(join(home, "pi/session/one"), { recursive: true });
+    writeFileSync(join(home, "pi/session/one/a.md"), "a");
+    const material = materialGate(home, statSync(lock).mtimeMs, 1);
+    assert.equal(material.ok, true);
+    assert.match(material.reason, /material gate: 1 changed sessions/);
+    assert.equal(materialGate(home, Date.now(), 2).ok, false);
+});
+test("live lock is excluded, dead lock is reclaimed, and failures restore mtime", () => {
+    const home = fixture();
+    const lock = join(home, ".dream.lock");
+    writeFileSync(lock, String(process.pid));
+    const live = acquireLock(lock);
+    assert.equal(live.held, false);
+    assert.equal(live.reason, "lock gate: live process holds the lock");
+    writeFileSync(lock, "999999");
+    old(lock);
+    const prior = statSync(lock).mtimeMs;
+    const reclaimed = acquireLock(lock);
+    assert.equal(reclaimed.held, true);
+    utimesSync(lock, new Date(), new Date());
+    failLock(reclaimed);
+    assert.ok(Math.abs(statSync(lock).mtimeMs - prior) < 2000);
+});
+test("dreamer write jail accepts home files and refuses escapes", async () => {
+    const home = fixture();
+    const tools = new Map(dreamerWriteToolDefinitions(home).map((tool) => [tool.name, tool]));
+    const ctx = { cwd: home };
+    await tools.get("write").execute("write", { path: "global/x.md", content: "one" }, undefined, undefined, ctx);
+    assert.equal(readFileSync(join(home, "global/x.md"), "utf8"), "one");
+    const rejectsOutsideHome = async (tool, path) => {
+        const params = tool === "write" ? { path, content: "outside" } : { path, edits: [{ oldText: "one", newText: "outside" }] };
+        await assert.rejects(() => tools.get(tool).execute("escape", params, undefined, undefined, ctx), (error) => error.message.includes(home));
+    };
+    for (const tool of ["write", "edit"]) {
+        await rejectsOutsideHome(tool, "/tmp/dream-jail-outside.md");
+        await rejectsOutsideHome(tool, "../dream-jail-outside.md");
+    }
+    const outside = fixture();
+    symlinkSync(outside, join(home, "escape"));
+    await rejectsOutsideHome("write", "escape/outside.md");
+    await rejectsOutsideHome("edit", "escape/outside.md");
+    assert.equal(existsSync(join(outside, "outside.md")), false, "the jail does not write through an in-home symlink");
+    const outsideFile = join(outside, "outside.md");
+    writeFileSync(outsideFile, "outside");
+    symlinkSync(outsideFile, join(home, "global/outside-link.md"));
+    await rejectsOutsideHome("write", "global/outside-link.md");
+    assert.equal(readFileSync(outsideFile, "utf8"), "outside", "the jail does not write through a symlinked file outside home");
+    linkSync(outsideFile, join(home, "global/hardlink.md"));
+    await rejectsOutsideHome("write", "global/hardlink.md");
+    assert.equal(readFileSync(outsideFile, "utf8"), "outside", "the jail does not write through a hardlinked file outside home");
+    const insideFile = join(home, "global/inside.md");
+    writeFileSync(insideFile, "inside");
+    symlinkSync(insideFile, join(home, "global/inside-link.md"));
+    await tools.get("write").execute("write", { path: "global/inside-link.md", content: "updated" }, undefined, undefined, ctx);
+    assert.equal(readFileSync(insideFile, "utf8"), "updated", "the jail permits a symlinked file that resolves inside home");
+});
+test("dreamer allowlist contains only the file tools and reports their writes", async () => {
+    let configured = [];
+    const session = {
+        subscribe(handler) { this.handler = handler; return () => { }; },
+        handler: (_event) => { },
+        async prompt(_text) { this.handler({ type: "tool_execution_start", toolName: "write", args: { path: "global/a.md", content: "a" } }); this.handler({ type: "tool_execution_start", toolName: "edit", args: { path: "project/p.md", edits: [] } }); this.handler({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "done" }, { type: "text", text: "again" }] } }); },
+        dispose() { },
+    };
+    const result = await runDreamer("playbook", "/tmp/notes", { sessionFactory: async (options) => { configured = options.tools; return session; } });
+    assert.deepEqual(configured, DREAMER_TOOLS);
+    assert.deepEqual(configured, ["read", "grep", "find", "ls", "write", "edit"]);
+    assert.equal(configured.some((tool) => tool.startsWith("notes_")), false);
+    assert.deepEqual(result.writes, [{ tool: "write", path: "global/a.md" }, { tool: "edit", path: "project/p.md" }]);
+    assert.equal(result.report, "done\nagain");
+    assert.equal(result.report, contentText([{ type: "text", text: "done" }, { type: "text", text: "again" }]), "dream and history share the text projection");
+});
+test("dreamer session has exactly the jailed file-tool allowlist", async () => {
+    const session = await defaultDreamerSessionFactory({ cwd: fixture(), tools: DREAMER_TOOLS });
+    try {
+        assert.deepEqual(session.agent.state.tools.map((tool) => tool.name).sort(), [...DREAMER_TOOLS].sort());
+    }
+    finally {
+        session.dispose();
+    }
+});
+test("playbook describes plain files and the retained frontmatter", () => {
+    const playbook = readFileSync(join(process.cwd(), "playbook.md"), "utf8");
+    assert.equal(playbook.includes("notes_"), false);
+    for (const field of ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count"])
+        assert.match(playbook, new RegExp(`^${field}:`, "m"));
+    assert.equal(/^scope:/m.test(playbook), false, "scope is derived from the address rather than persisted");
+    assert.match(playbook, /Nothing is physically deleted/);
+});
+test("provider errors propagate without parsing a response", async () => {
+    const session = {
+        subscribe(handler) { this.handler = handler; return () => { }; },
+        handler: (_event) => { },
+        async prompt(_text) { this.handler({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "Insufficient Balance" } }); },
+        dispose() { },
+    };
+    await assert.rejects(() => runDreamer("playbook", "/tmp/notes", { sessionFactory: async () => session }), /Insufficient Balance/);
+});
+test("default dreamer rejects an unresolvable model pattern", async () => {
+    await assert.rejects(() => defaultDreamerSessionFactory({ cwd: "/tmp/notes", modelPattern: "definitely-not-a-real-model", tools: DREAMER_TOOLS }), /definitely-not-a-real-model/);
+});
+test("git audit layer commits baseline and dream, stays silent when clean, keeps file content", () => {
+    const home = fixture();
+    writeFileSync(join(home, "a.md"), "one");
+    gitCommit(home, "baseline t");
+    gitCommit(home, "dream t"); // clean tree — no empty commit
+    const log1 = execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim();
+    assert.equal(log1, "baseline t");
+    writeFileSync(join(home, "a.md"), "two");
+    gitCommit(home, "dream t2");
+    const log2 = execFileSync("git", ["log", "--format=%s"], { cwd: home, encoding: "utf8" }).trim();
+    assert.equal(log2, "dream t2\nbaseline t");
+    assert.equal(readFileSync(join(home, "a.md"), "utf8"), "two"); // notes themselves untouched by the layer
+    const before = execFileSync("git", ["show", "HEAD~1:a.md"], { cwd: home, encoding: "utf8" }).trim();
+    assert.equal(before, "one"); // rollback information actually recorded
+});
+test("git audit layer never breaks the run when git itself fails", () => {
+    gitCommit(join(fixture(), "missing", "home"), "x"); // init on a missing cwd throws inside — swallowed
+});

package/dist/test/history.test.js

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { contentText, resetV2WindowId, rootWindowId, visibleItem } from "../src/history.js";
+test("visibleItem reports a plain fitting prefix and names the full length", () => {
+    const item = visibleItem({ windowId: "w", itemId: "i", role: "user", content: "abcdef", createdAt: undefined }, 4);
+    assert.equal(Array.from(item.truncated_content).length, 4);
+    assert.equal(item.truncated_content, "abcd");
+    assert.equal(item.truncated_content.includes("…"), false, "no marker is appended to the payload");
+    assert.equal(item.truncated, true);
+    assert.equal(item.total_chars, 6);
+    const whole = visibleItem({ windowId: "w", itemId: "i", role: "user", content: "abcdef", createdAt: undefined }, 6);
+    assert.equal(whole.truncated, false);
+    assert.equal(whole.total_chars, 6);
+    assert.equal(whole.truncated_content, "abcdef");
+});
+test("persisted reset IDs are opaque within the supported protocol version", () => {
+    assert.equal(resetV2WindowId({ piContext: "reset-v2", windowId: "opaque-window-id" }), "opaque-window-id");
+    assert.equal(resetV2WindowId({ piContext: "reset-v1", windowId: "opaque-window-id" }), undefined);
+    assert.equal(resetV2WindowId({ piContext: "reset-v2", windowId: 123 }), undefined);
+    assert.equal(resetV2WindowId(null), undefined);
+});
+test("text content projection and root window IDs have stable shared forms", () => {
+    const content = [{ type: "text", text: "first" }, { type: "toolCall", name: "ignored" }, { type: "text", text: "second" }];
+    assert.equal(contentText(content), "first\nsecond");
+    assert.equal(rootWindowId("12345678-abcd"), "pcw:12345678:root");
+});