@astrosheep/pi-context 0.22.1 → 0.23.1

package/dist/test/pagination.property.test.js

@@ -292,21 +292,21 @@ function assertTruncatedIdentity(expectedPath, actual, label) {
     assert.ok(headChars.length + tailChars.length < expectedChars.length, `${label}: truncation actually removes characters`);
 }
 /**
- * Map a notes page entry's path back to the expected store path. A non-truncated path must
- * equal it; a flagged path must be a visible middle-truncation of a legacy path that the
- * write cap could never have produced. The expected path is returned either way so the
+ * Map a notes page entry's address back to the expected address. A non-truncated address must
+ * equal it; a flagged address must be a visible middle-truncation of a legacy address that the
+ * write cap could never have produced. The expected address is returned either way so the
  * pagination invariants compare like with like.
  */
 function notePathIdentity(expectedPaths, cursor, label, page, key) {
     return page[key].map((file, index) => {
         const expectedPath = expectedPaths[cursor + index];
         assert.ok(expectedPath !== undefined, `${label} cursor=${cursor}: page returned more entries than the store holds`);
-        if (file.path_truncated) {
-            assert.ok(Buffer.byteLength(expectedPath, "utf8") > MAX_NOTE_PATH_BYTES, `${label} cursor=${cursor}: only a legacy path beyond the write cap may be truncated, got ${file.path}`);
-            assertTruncatedIdentity(expectedPath, file.path, `${label} cursor=${cursor}`);
+        if (file.address_truncated) {
+            assert.ok(Buffer.byteLength(expectedPath, "utf8") > MAX_NOTE_PATH_BYTES, `${label} cursor=${cursor}: only a legacy address beyond the write cap may be truncated, got ${file.address}`);
+            assertTruncatedIdentity(expectedPath, file.address, `${label} cursor=${cursor}`);
         }
         else {
-            assert.equal(file.path, expectedPath, `${label} cursor=${cursor}: path is returned intact when its entry fits`);
+            assert.equal(file.address, expectedPath, `${label} cursor=${cursor}: address is returned intact when its entry fits`);
         }
         return expectedPath;
     });
@@ -398,10 +398,10 @@ test("notes_list enumerates every note file across seeded mixes", async () => {
         const captured = makeExtension(session);
         const ctx = context(session);
         await materializeNotes(plan, captured, ctx);
-        const all = new Map(listNotes(ctx, {}).map((row) => [row.path, row]));
+        const all = new Map(listNotes(ctx, {}).map((row) => [row.address, row]));
         for (const variant of plan.list) {
             const params = { pattern: variant.pattern, max_results: variant.maxResults };
-            const expected = expectedListRows(ctx, variant).map((row) => row.path);
+            const expected = expectedListRows(ctx, variant).map((row) => row.address);
             const label = `notes_list seed=${seed} ${variant.label} pattern=${JSON.stringify(variant.pattern)} max_results=${variant.maxResults}`;
             const pages = await walkPages({
                 captured, ctx, tool: "notes_list", params,
@@ -413,13 +413,12 @@ test("notes_list enumerates every note file across seeded mixes", async () => {
             let flat = 0;
             for (const page of pages) {
                 for (const file of page.files) {
-                    const storePath = expected[flat++];
-                    const row = all.get(storePath);
-                    assert.ok(row, `${label}: listed ${storePath} is not in the note store`);
-                    assert.equal(file.size_bytes, row.sizeBytes, `${label}: size_bytes for ${storePath}`);
-                    assert.equal(file.stale, row.meta.stale, `${label}: stale for ${storePath}`);
-                    assert.equal(Date.parse(file.created_at), row.meta.created_at, `${label}: created_at for ${storePath}`);
-                    assert.equal(Date.parse(file.updated_at), row.meta.updated_at, `${label}: updated_at for ${storePath}`);
+                    const address = expected[flat++];
+                    const row = all.get(address);
+                    assert.ok(row, `${label}: listed ${address} is not in the note store`);
+                    assert.deepEqual(Object.keys(file).sort(), file.address_truncated ? ["address", "address_truncated", "stale", "updated_at"] : ["address", "stale", "updated_at"]);
+                    assert.equal(file.stale, row.meta.stale, `${label}: stale for ${address}`);
+                    assert.equal(Date.parse(file.updated_at), row.meta.updated_at, `${label}: updated_at for ${address}`);
                 }
             }
         }
@@ -435,7 +434,9 @@ test("notes_search enumerates every matching file across seeded mixes", async ()
         const bodies = new Map(plan.writes.map((write) => [write.path, write.body]));
         for (const variant of plan.search) {
             const params = { query: variant.query, pattern: variant.pattern, max_files: variant.maxFiles, max_matches_per_file: variant.maxMatchesPerFile };
-            const expected = expectedSearchRows(ctx, variant).map((row) => row.path);
+            const expectedRows = expectedSearchRows(ctx, variant);
+            const expected = expectedRows.map((row) => row.address);
+            const expectedByAddress = new Map(expectedRows.map((row) => [row.address, row]));
             const label = `notes_search seed=${seed} ${variant.label} query=${JSON.stringify(variant.query)} pattern=${JSON.stringify(variant.pattern)} max_files=${variant.maxFiles} max_matches_per_file=${variant.maxMatchesPerFile}`;
             const pages = await walkPages({
                 captured, ctx, tool: "notes_search", params,
@@ -447,7 +448,8 @@ test("notes_search enumerates every matching file across seeded mixes", async ()
             let flat = 0;
             for (const page of pages) {
                 for (const file of page.files) {
-                    const storePath = expected[flat++];
+                    const address = expected[flat++];
+                    const storePath = address;
                     const body = bodies.get(storePath);
                     assert.ok(body !== undefined, `${label}: reported ${storePath} was never written`);
                     const lines = body.split("\n");
@@ -455,19 +457,12 @@ test("notes_search enumerates every matching file across seeded mixes", async ()
                     assert.ok(file.matches.length >= 1, `${label}: ${storePath} reports no matches but appears in the result`);
                     assert.ok(file.matches.length <= Math.min(matchingLines.length, variant.maxMatchesPerFile), `${label}: ${storePath} reports ${file.matches.length} matches beyond its cap`);
                     assert.deepEqual(file.matches.map((match) => match.line), matchingLines.slice(0, file.matches.length), `${label}: ${storePath} match lines are not the first matching lines`);
-                    const lineBase = [];
-                    let lineOffset = 0;
-                    for (const text of lines) {
-                        lineBase.push(lineOffset);
-                        lineOffset += Array.from(text).length + 1;
-                    }
-                    for (const match of file.matches) {
+                    const expectedMatches = expectedByAddress.get(address)?.matches;
+                    assert.ok(expectedMatches, `${label}: ${address} is absent from the store search`);
+                    for (const [index, match] of file.matches.entries()) {
                         const line = lines[match.line - 1];
                         assert.ok(line.includes(variant.query), `${label}: ${storePath}:${match.line} does not contain the query`);
-                        // The documented address: body-absolute code points up to the line, plus the query's
-                        // earliest occurrence inside it.
-                        const earliest = line.indexOf(variant.query);
-                        assert.equal(match.offset_chars, lineBase[match.line - 1] + Array.from(line.slice(0, earliest)).length, `${label}: ${storePath}:${match.line} offset_chars does not address the query`);
+                        assert.equal(match.offset_chars, expectedMatches[index]?.offsetChars, `${label}: ${storePath}:${match.line} offset_chars does not address the serialized read stream`);
                     }
                 }
             }

package/dist/test/reset-lifecycle.test.js

@@ -42,7 +42,10 @@ function harness() {
         disable: () => { enabled = false; lifecycle.clear(); },
         enable: () => { enabled = true; },
         before: (reason = "threshold") => emit("session_before_compact", { reason, signal: new AbortController().signal }),
-        settle: () => { emit("agent_end"); idle = true; emit("agent_settled"); },
+        // Do not await this result until after the manually driven compact callbacks:
+        // real Pi awaits the originating handler while the continuation can emit its
+        // own nested agent_settled event.
+        settle: () => { emit("agent_end"); idle = true; return emit("agent_settled"); },
         success: (id = "reset", willRetry = false) => {
             currentReset = id;
             emit("session_compact", { compactionEntry: { id }, willRetry });
@@ -50,150 +53,144 @@ function harness() {
         complete: (index = 0) => requests[index].onComplete({}),
     };
 }
-test("reset completion, duplicate callbacks, and duplicate tools cannot launch duplicate runs", () => {
+test("the originating settled handler waits for its continuation's nested settlement", async () => {
     const h = harness();
     assert.equal(h.lifecycle.request(), "rollover_requested");
     assert.equal(h.lifecycle.request(), "rollover_already_pending");
-    h.settle();
-    h.emit("agent_settled");
+    const outer = h.settle();
     assert.equal(h.requests.length, 1);
     h.success();
     h.success();
-    assert.deepEqual(h.messages, [], "nothing starts inside session_compact");
     h.complete();
     h.complete();
-    h.emit("agent_settled");
-    assert.deepEqual(h.messages, ["continue"]);
-    assert.equal(h.requests.length, 1);
-});
-test("automatic threshold compactions reset on the spot, with no steer and no model turn", () => {
-    const h = harness();
-    assert.ok(h.before().compaction, "the native attempt becomes our reset immediately");
-    assert.deepEqual(h.messages, [], "nothing is sent to the model");
+    assert.deepEqual(h.messages, ["continue"], "one continuation starts after compaction completion");
+    let released = false;
+    void Promise.resolve(outer).then(() => { released = true; });
+    await Promise.resolve();
+    assert.equal(released, false, "sending the continuation does not release the original handler");
+    await h.settle();
+    await outer;
+    assert.equal(released, true, "only the continuation's settled event releases its owner");
+    assert.equal(h.requests.length, 1, "duplicate compact and settled callbacks do not restart reset work");
 });
-test("a native compaction failure is not treated as failure of an explicit reset", () => {
+test("a reset requested by a continuation completes before its predecessor releases", async () => {
     const h = harness();
-    h.emit("session_compact_failed", { reason: "threshold", aborted: true });
     h.lifecycle.request();
-    h.settle();
-    h.success();
+    const first = h.settle();
+    h.success("first");
     h.complete();
     assert.deepEqual(h.messages, ["continue"]);
-});
-test("failed resets release the request, retain history, and do not retry", () => {
-    const h = harness();
-    h.lifecycle.request();
-    h.settle();
-    h.emit("session_compact_failed", { reason: "manual", aborted: false });
-    h.requests[0].onError(new Error("Nothing to compact"));
-    h.requests[0].onError(new Error("duplicate callback"));
-    h.complete();
-    h.emit("agent_settled");
-    assert.equal(h.requests.length, 1);
-    assert.equal(h.notices.length, 1);
-    assert.deepEqual(h.messages, []);
-    h.setIdle(false);
-    assert.ok(h.before().compaction, "the next native attempt resets directly");
-    assert.equal(h.lifecycle.request(), "rollover_requested", "explicit retry is possible");
-    h.settle();
-    assert.equal(h.requests.length, 2);
-    h.success();
+    // This models new_context being called during the first continuation run.
+    assert.equal(h.lifecycle.request(), "rollover_requested");
+    const second = h.settle();
+    assert.equal(h.requests.length, 2, "the continuation's settled handler starts its requested reset");
+    h.success("second");
     h.complete(1);
-    assert.deepEqual(h.messages, ["continue"]);
+    assert.deepEqual(h.messages, ["continue", "continue"]);
+    let firstReleased = false;
+    void Promise.resolve(first).then(() => { firstReleased = true; });
+    await Promise.resolve();
+    assert.equal(firstReleased, false, "the predecessor remains owned while the second continuation runs");
+    await h.settle();
+    await second;
+    await first;
+    assert.equal(firstReleased, true);
+    assert.equal(h.lifecycle.request(), "rollover_requested", "a later window can request another reset");
 });
-test("synchronous compact errors cannot leave a permanent in-flight request", () => {
+test("automatic compactions reset on the spot, with no continuation", () => {
     const h = harness();
-    h.setThrow();
-    h.lifecycle.request();
-    h.settle();
-    h.emit("agent_settled");
-    assert.equal(h.notices.length, 1);
-    assert.equal(h.lifecycle.request(), "rollover_requested");
+    assert.ok(h.before().compaction, "the native attempt becomes our reset immediately");
+    assert.deepEqual(h.messages, []);
 });
-test("user abort ends explicit work without resurrecting the run", () => {
-    const h = harness();
-    h.lifecycle.request();
-    h.setSignal(AbortSignal.abort());
-    h.settle();
-    assert.equal(h.requests.length, 0);
-    assert.equal(h.messages.includes("continue"), false);
+test("failure, synchronous scheduling errors, and cancellation release their owners without retry", async () => {
+    const failed = harness();
+    failed.lifecycle.request();
+    const outer = failed.settle();
+    failed.requests[0].onError(new Error("Nothing to compact"));
+    failed.requests[0].onError(new Error("duplicate callback"));
+    failed.complete();
+    await outer;
+    assert.equal(failed.notices.length, 1);
+    assert.deepEqual(failed.messages, []);
+    assert.equal(failed.lifecycle.request(), "rollover_requested", "a later explicit request is possible");
+    const synchronous = harness();
+    synchronous.setThrow();
+    synchronous.lifecycle.request();
+    await synchronous.settle();
+    assert.equal(synchronous.notices.length, 1);
+    assert.equal(synchronous.lifecycle.request(), "rollover_requested");
+    const aborted = harness();
+    aborted.lifecycle.request();
+    aborted.setSignal(AbortSignal.abort());
+    await aborted.settle();
+    assert.equal(aborted.requests.length, 0);
+    assert.deepEqual(aborted.messages, []);
 });
-test("shutdown, restart, tree navigation and toggling off invalidate late callbacks", () => {
-    for (const boundary of ["session_shutdown", "session_start", "session_tree", "off"]) {
+test("shutdown, tree invalidation, toggling off, and stale sessions release waiters safely", async () => {
+    for (const boundary of ["session_shutdown", "session_start", "session_tree", "off", "session-change"]) {
         const h = harness();
         h.lifecycle.request();
-        h.settle();
+        const outer = h.settle();
         h.success();
+        h.complete();
         if (boundary === "off") {
             h.disable();
             h.enable();
         }
+        else if (boundary === "session-change") {
+            h.setSession("second");
+            h.complete();
+            h.emit("session_tree");
+        }
         else
             h.emit(boundary);
         h.complete();
         h.requests[0].onError(new Error("late error"));
-        assert.deepEqual(h.messages, [], boundary);
+        await outer;
         assert.deepEqual(h.notices, [], boundary);
+        assert.deepEqual(h.messages, ["continue"], boundary);
         if (boundary === "session_shutdown")
             h.emit("session_start");
-        h.lifecycle.request();
-        h.settle();
-        assert.equal(h.requests.length, 2, `${boundary}: a fresh request still works`);
-    }
-});
-test("callback identity keeps an earlier failure from cancelling a newer request", () => {
-    const h = harness();
-    h.lifecycle.request();
-    h.settle();
-    h.requests[0].onError(new Error("first failure"));
-    h.lifecycle.request();
-    h.settle();
-    h.requests[0].onError(new Error("late first failure"));
-    h.success();
-    h.complete(1);
-    assert.deepEqual(h.messages, ["continue"]);
-    assert.equal(h.notices.length, 1);
-});
-test("native compaction satisfies a pending request without duplicating Pi's continuation", () => {
-    for (const willRetry of [false, true]) {
-        const h = harness();
-        h.lifecycle.request();
-        h.success("native", willRetry);
-        h.settle();
-        assert.equal(h.requests.length, 0);
-        assert.deepEqual(h.messages, []);
+        if (boundary === "session-change")
+            h.emit("session_tree");
+        assert.equal(h.lifecycle.request(), "rollover_requested", `${boundary}: a fresh request still works`);
     }
 });
-test("do not interrupt another active run or duplicate a queued user prompt", () => {
-    const h = harness();
-    h.lifecycle.request();
-    h.setIdle(false);
-    h.emit("agent_settled");
-    assert.equal(h.requests.length, 0, "another extension already started work");
-    h.settle();
-    h.success();
-    h.setIdle(false);
-    h.complete();
-    assert.deepEqual(h.messages, [], "the active prompt owns continuation");
+test("queued or competing work is not duplicated and releases an unneeded continuation owner", async () => {
+    const competing = harness();
+    competing.lifecycle.request();
+    competing.setIdle(false);
+    assert.equal(competing.emit("agent_settled"), undefined, "another run owns the first settled event");
+    competing.setIdle(true);
+    const outer = competing.settle();
+    competing.success();
+    competing.setIdle(false);
+    competing.complete();
+    await outer;
+    assert.deepEqual(competing.messages, [], "an active prompt owns continuation");
     const queued = harness();
     queued.lifecycle.request();
-    queued.settle();
+    const queuedOuter = queued.settle();
     queued.success();
     queued.setPending(true);
     queued.complete();
-    assert.deepEqual(queued.messages, [], "do not add a competing prompt");
+    await queuedOuter;
+    assert.deepEqual(queued.messages, [], "queued user work is never duplicated");
 });
-test("foreign or unconfirmed reset events cannot trigger a successful continuation", () => {
+test("foreign boundaries and native compactions do not manufacture a continuation", async () => {
     const h = harness();
     h.lifecycle.request();
-    h.settle();
-    // isCurrentReset stands in for the reset-v2/window-id check index.ts runs against the
-    // compaction entry's details. Emitting the foreign boundary twice proves it is never
-    // marked handled, and the request stays in flight rather than completing.
+    const outer = h.settle();
     h.emit("session_compact", { compactionEntry: { id: "foreign" }, willRetry: false });
     h.emit("session_compact", { compactionEntry: { id: "foreign" }, willRetry: false });
-    assert.equal(h.lifecycle.request(), "rollover_already_pending", "the ignored event did not complete or clear the attempt");
+    assert.equal(h.lifecycle.request(), "rollover_already_pending");
     h.complete();
-    assert.deepEqual(h.messages, [], "an unconfirmed boundary never resumes the run");
-    assert.equal(h.lifecycle.request(), "rollover_requested", "the request is released after its own completion");
+    await outer;
+    assert.deepEqual(h.messages, []);
+    const native = harness();
+    native.lifecycle.request();
+    native.success("native", false);
+    await native.settle();
+    assert.equal(native.requests.length, 0);
+    assert.deepEqual(native.messages, []);
 });

package/docs/reset-lifecycle.md

@@ -7,9 +7,9 @@
 | `new_context` | Mark explicit request; repeated calls report already pending. Tool returns terminal output. |
 | Manual, threshold or overflow `session_before_compact`, idle or streaming | Build the reset boundary immediately and return it. Never cancel and never take a model turn; an aborted signal returns `{ cancel: true }`. |
 | `agent_end` | No-op for an instant reset. |
-| `agent_settled` | If idle and an explicit request is pending, create one identified attempt and request `ctx.compact`. |
+| `agent_settled` | If idle and an explicit request is pending, create one identified attempt and request `ctx.compact`. The originating handler owns and awaits that attempt through its continuation's settlement. |
 | Matching `session_compact` | Confirm boundary, persist window state. Native compaction retains its own scheduling. |
-| Attempt `onComplete` | Consume attempt; send continuation only for a confirmed boundary when idle with no queued messages. |
+| Attempt `onComplete` | Consume attempt; for a confirmed boundary when idle with no queued messages, register continuation ownership before sending it. Its nested `agent_settled` settles that owner; a reset requested by the continuation completes its own handoff before releasing its predecessor. |
 | Attempt `onError` or synchronous throw | Clear attempt/request, warn, retain history. No automatic retry loop. |
 | Shutdown / start / tree / toggle off | Invalidate outstanding attempt. Identity checks reject callbacks from older attempts. |
 
@@ -17,6 +17,8 @@ The final checkpoint warning is steered earlier from the context hook (`warning.
 
 The completion callback is the scheduling boundary: `session_compact` fires before Pi clears manual compaction state. Sending a prompt inside that hook is too early. An explicit reset uses the manual `ctx.compact` route and therefore needs this completion logic; an automatic compaction is already the reset and resumes through Pi's own caller.
 
+`sendMessage(..., { triggerTurn: true })` starts its run detached from the extension API. The explicit attempt therefore retains an attempt-owned waiter before sending it, and its originating `agent_settled` handler awaits that waiter. The continuation's `agent_settled` releases the waiter without awaiting itself. If that continuation calls `new_context`, its settled handler starts and awaits the next attempt before it releases the prior waiter, forming a bounded reset chain. Failure, cancellation, shutdown, tree navigation, and toggling off release the relevant waiter exactly once.
+
 Public APIs cannot guarantee immediate reset inside mixed tool batches or before queued steering/follow-up messages finish. `terminate` ends the tool-followup path; `agent_settled` remains the safe point to request compaction. The scheduler does not manipulate user queues. Pi also determines compaction eligibility before the extension hook; an uncompactable session produces a warning and waits for a new prompt.
 
 Validation is split into persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. The SDK tests cover explicit success, instant automatic reset, and core compaction rejection followed by a user prompt. Lifecycle tests cover callback races and queue guards without pretending to exercise provider/network behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.22.1",
+  "version": "0.23.1",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/playbook.md

@@ -24,9 +24,9 @@ access_count: 0
 2. **Merge threshold.** Supersede another note only when all three hold: same topic (name it in the survivor's body), same kind of note (checkpoint/design/log…), and the survivor is strictly newer or strictly more specific. Otherwise keep both and record the open conflict in the survivor.
 3. **Size budget.** Keep every note under ~200 lines / ~8KB. Oversized notes get split by topic with a one-line cross-link in each (`see also: @home/<vpath>`). Checkpoints may exceed the budget — trim prose, never facts.
 4. **Keep the maps.** Each home's `MAP.md` maps that home's durable notes: one line per entry — its address and a short gist in your own words, never a mechanical body slice. Project notes go on `@project/MAP.md`, cross-project knowledge on `@personal/MAP.md`; session notes are never mapped — the pocket covers them. When a note is promoted across homes, move its line to the destination map; when a note goes stale, drop its line. Maps obey the same size budget as any note.
-5. **Jurisdiction.** Your mandate is the whole store — every session home, every project home, personal. Nothing is skipped: notes are never physically deleted and every run is bracketed by git commits, so the human gate can audit and revert whatever you touch. Group your report by home so the gate can see what moved. In every home: map entry lines are yours to maintain, but prose that carries rules or guidance is not — flag it in your report instead of rewriting it.
+5. **Jurisdiction.** Read the whole store, including every session home, to extract durable knowledge. `pi/session/**` is a live agent's write-ahead log: never write or edit anything there, including frontmatter or stale markers. Promote useful facts by writing to project or personal instead. Other notes are never physically deleted and every run is bracketed by git commits, so the human gate can audit and revert whatever you touch. Group your report by home so the gate can see what moved. In writable homes: map entry lines are yours to maintain, but prose that carries rules or guidance is not — flag it in your report instead of rewriting it.
 6. **Leave stable notes alone.** Change notes to incorporate new evidence, resolve verified errors, merge genuine duplicates, or split oversized files—not merely to shorten or rephrase them. Preserve facts, conditions, exceptions, and uncertainty. No change is a valid outcome.
 
-Read the files and merge genuinely duplicate notes by editing the survivor, then set `stale: true` in the absorbed note's frontmatter. Nothing is physically deleted; stale notes remain readable. Promote durable cross-project knowledge by writing or editing at `@personal/<vpath>`. Keep notes compact and preserve useful provenance in the body.
+Read the files and merge genuinely duplicate notes in writable homes by editing the survivor, then set `stale: true` in the absorbed note's frontmatter if it is writable. Session notes remain untouched even when promoted; record their source in the destination. Nothing is physically deleted; stale notes remain readable. Promote durable cross-project knowledge by writing or editing at `@personal/<vpath>`. Keep notes compact and preserve useful provenance in the body.
 
 Do not write skill ideas as files. Put skill ideas and unresolved questions in your final assistant message as proposals for the human. Your final message should be a concise report of what you inspected, changed, and left unresolved. If you made no file writes, say so.

package/src/dream/cli.ts

@@ -12,7 +12,7 @@ import { notesRoot } from "../notes/paths.js";
 
 function args(argv: string[]) { const out: Record<string, string | boolean> = {}; for (let i=0;i<argv.length;i++) { const a=argv[i]!; if (a === "--force" || a === "--help") out[a.slice(2)] = true; else if (a.startsWith("--")) out[a.slice(2)] = argv[++i] ?? ""; } return out; }
 function packageRoot(): string {
-	let dir = dirname(new URL(import.meta.url).pathname);
+	let dir = dirname(fileURLToPath(import.meta.url));
 	while (true) { if (existsSync(join(dir, "package.json"))) return dir; const parent = dirname(dir); if (parent === dir) throw new Error("could not locate installed package root"); dir = parent; }
 }
 

package/src/history-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, readWindowBlock, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
 
@@ -61,7 +61,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_read",
 		label: "History read item",
-		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
+		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response begins with the shared READ WINDOW block naming window_id and item_id; concatenate only the content after that block to reconstruct the item.",
 		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes.` })), window_id: Type.String() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const item = allItems(ctx).find((candidate) => candidate.windowId === params.window_id && candidate.itemId === params.item_id);
@@ -72,10 +72,9 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
 				return output({ error: `offset_chars ${params.offset_chars} is past the end: the item has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, window_id: item.windowId, item_id: item.itemId, offset_chars: params.offset_chars, total_chars: totalChars });
 			}
-			const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
 			return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
 				const { content, ...cursor } = window;
-				return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
+				return outputRaw(readWindowBlock([["window_id", item.windowId], ["item_id", item.itemId]], window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor });
 			}, (result) => withinTextBudget(result.content[0].text));
 		},
 	}));

package/src/notes/store.ts

@@ -220,19 +220,25 @@ export function editNote(ctx: ExtensionContext, vpath: string, scope: Scope, edi
 	return { meta, applied: operations.length, resolved_scope: scope, diff };
 }
 
+/** Normalize a parsed note exactly as a read does, including its access metadata mutation. */
+function accessedMeta(meta: NoteMeta, scope: Scope, now: number): NoteMeta {
+	const next = { ...meta, scope };
+	next.last_accessed = now;
+	next.access_count = (typeof next.access_count === "number" ? next.access_count : 0) + 1;
+	return next;
+}
+
 /** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
-export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope): { meta: NoteMeta; body: string; resolvedScope: Scope } | undefined {
+export function readNote(ctx: ExtensionContext, vpath: string, scope: Scope): { meta: NoteMeta; body: string; text: string; resolvedScope: Scope } | undefined {
 	assertVirtualPath(vpath);
 	const path = physicalPath(scope, vpath, ctx);
 	if (!existsSync(path)) return undefined;
 	const now = Date.now();
-	const { meta, body } = parseNote(readFileSync(path, "utf8"), now);
-	meta.scope = scope;
-	// Only the two access keys move; updated_at and every other key keep their bytes.
-	meta.last_accessed = now;
-	meta.access_count = (typeof meta.access_count === "number" ? meta.access_count : 0) + 1;
-	atomicWrite(path, serializeNote(meta, body));
-	return { meta, body, resolvedScope: scope };
+	const parsed = parseNote(readFileSync(path, "utf8"), now);
+	const meta = accessedMeta(parsed.meta, scope, now);
+	const text = serializeNote(meta, parsed.body);
+	atomicWrite(path, text);
+	return { meta, body: parsed.body, text, resolvedScope: scope };
 }
 
 /** Merged rows across homes, most recently updated first (address breaks ties). */
@@ -264,11 +270,12 @@ export function searchNotes(ctx: ExtensionContext, queries: string[], opts: { sc
 			if (matcher && !matcher.test(address)) continue;
 			const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
 			meta.scope = scope;
+			const serializedBodyOffset = Array.from(serializeNote(accessedMeta(meta, scope, Date.now()), "")).length;
 			let baseChars = 0;
 			const matches: NoteMatch[] = [];
 			for (const [index, line] of body.split("\n").entries()) {
 				if (queries.some((query) => line.includes(query))) {
-					matches.push({ line: index + 1, text: line, offsetChars: baseChars + earliestMatchOffsetChars(line, queries) });
+					matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, queries) });
 				}
 				baseChars += Array.from(line).length + 1;
 			}