@astrosheep/pi-context 0.22.1 → 0.23.0

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.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

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;
 			}

package/src/notes/tools.ts

@@ -1,10 +1,10 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { localIso } from "./model.js";
-import { characterWindowHeader, DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, withinTextBudget } from "../tool-output.js";
+import { DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, readWindowBlock, withinTextBudget } from "../tool-output.js";
 import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
 import { assertAddress } from "./address.js";
-import { serializeNote, stripLeadingFrontmatter, type NoteMeta, type Origin } from "./frontmatter.js";
+import { type Origin } from "./frontmatter.js";
 import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
 
 const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.Literal("external")], {
@@ -12,10 +12,6 @@ const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("sel
 }));
 const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project's home, and `@personal/<vpath>` for the human's cross-project home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@personal/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
 
-function wireMeta(meta: NoteMeta): Record<string, unknown> {
-	return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
-}
-
 function failure(error: unknown) {
 	if (error instanceof NoteError) {
 		const payload: Record<string, unknown> = { error: error.message };
@@ -35,28 +31,28 @@ export function registerNotesTools(pi: ExtensionAPI) {
 			const content = params.content;
 			try {
 				const destination = assertAddress(params.address);
-				const { meta } = writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self") as Origin, stale: params.stale });
-				return output({ address: params.address, scope: meta.scope, size_bytes: Buffer.byteLength(stripLeadingFrontmatter(content), "utf8"), meta: wireMeta(meta) });
+				writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self") as Origin, stale: params.stale });
+				return output({ address: params.address, written: true });
 			} catch (error) { return failure(error); }
 		},
 	}));
 
 	pi.registerTool(defineTool({
 		name: "notes_edit", label: "Notes edit",
-		description: `Edit a note body by exact-text replacement; frontmatter is never editable this way. ${ADDRESS_DESCRIPTION} Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries resolved_scope and a diff of what changed.`,
+		description: `Edit a note body by exact-text replacement; frontmatter is never editable this way. ${ADDRESS_DESCRIPTION} Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries the address and a diff of what changed.`,
 		parameters: Type.Object({ address: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), origin: ORIGIN, stale: Type.Optional(Type.Boolean()), replace_all: Type.Optional(Type.Boolean()) }, { additionalProperties: false }), executionMode: "sequential",
 		async execute(_id, params, _signal, _update, ctx) {
 			try {
 				const destination = assertAddress(params.address);
-				const { meta, applied, resolved_scope, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
-				return output({ address: params.address, applied, resolved_scope, diff, meta: wireMeta(meta) });
+				const { applied, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin as Origin | undefined, stale: params.stale, replaceAll: params.replace_all });
+				return output({ address: params.address, applied, diff });
 			} catch (error) { return failure(error); }
 		},
 	}));
 
 	pi.registerTool(defineTool({
 		name: "notes_read", label: "Notes read",
-		description: `Read a character window of a note file, frontmatter included. ${ADDRESS_DESCRIPTION} offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end — and limit_chars caps the window (default ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). Each response delivers the longest fitting prefix of that window: concatenate pages in order to reconstruct the note. The response is the raw frontmatter + body behind a one-line [bracketed] header naming the address, the resolved offset, the delivered char range, and the resume cursor.`,
+		description: `Read a character window of a note file, frontmatter included. ${ADDRESS_DESCRIPTION} offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end — and limit_chars caps the window (default ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). Each response delivers the longest fitting prefix of that window in the shared READ WINDOW block: concatenate only the content after the block to reconstruct the note.`,
 		parameters: Type.Object({ address: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from (default 0). 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.` })) }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			let note: ReturnType<typeof readNote>;
@@ -65,27 +61,24 @@ export function registerNotesTools(pi: ExtensionAPI) {
 				note = readNote(ctx, destination.path, destination.scope);
 			} catch (error) { return failure(error); }
 			if (!note) return output({ error: "note not found", address: params.address });
-			const text = serializeNote(note.meta, note.body);
+			const text = note.text;
 			const totalChars = Array.from(text).length;
 			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) return output({ error: `offset_chars ${params.offset_chars} is past the end: the note has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, address: params.address, offset_chars: params.offset_chars, total_chars: totalChars });
-			const created_at = localIso(note.meta.created_at);
-			const updated_at = localIso(note.meta.updated_at);
-			const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
 			return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
 				const { content, ...rest } = window;
-				return outputRaw(characterWindowHeader(params.address, window, ` · ${note.resolvedScope} · created ${created_at} · updated ${updated_at}`), content, { address: params.address, scope: note.resolvedScope, ...rest, limit_chars, created_at, updated_at });
+				return outputRaw(readWindowBlock([["address", params.address]], window), content, { address: params.address, ...rest });
 			}, (result) => withinTextBudget(result.content[0].text));
 		},
 	}));
 
 	pi.registerTool(defineTool({
 		name: "notes_list", label: "Notes list",
-		description: `List note files as rows carrying address, scope, origin, status, stale, size_bytes, created_at, and updated_at, most recently updated first. ${ADDRESS_DESCRIPTION} All three homes are merged. A glob pattern (* within a path segment, ** across segments) filters full address strings: *.md is session-only, @project/** is project-only, and ** covers every home.`,
+		description: `List note files as rows carrying address, updated_at, and stale, most recently updated first. ${ADDRESS_DESCRIPTION} All three homes are merged. A glob pattern (* within a path segment, ** across segments) filters full address strings: *.md is session-only, @project/** is project-only, and ** covers every home.`,
 		parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			let rows: ReturnType<typeof listNotes>;
 			try { rows = listNotes(ctx, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
-			const files: Array<{ address: string; scope: string; origin: Origin; status: string; stale: boolean; size_bytes: number; created_at: string; updated_at: string; address_truncated?: boolean }> = rows.map((row) => ({ address: row.address, scope: row.scope, origin: row.meta.origin, status: row.meta.status, stale: row.meta.stale, size_bytes: row.sizeBytes, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at) }));
+			const files: Array<{ address: string; stale: boolean; updated_at: string; address_truncated?: boolean }> = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updated_at) }));
 			return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
 				if (fits(file)) return file;
 				const address = middleTruncate(file.address, (candidate) => fits({ ...file, address: candidate, address_truncated: true }));
@@ -96,16 +89,16 @@ export function registerNotesTools(pi: ExtensionAPI) {
 
 	pi.registerTool(defineTool({
 		name: "notes_search", label: "Notes search",
-		description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} All three homes are merged and every entry carries its full address and derived scope. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (the body-absolute code-point offset of the earliest match).`,
+		description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} All three homes are merged and every entry carries its full address. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (a code-point offset into the serialized note returned by notes_read, at the earliest query match), and truncated.`,
 		parameters: Type.Object({ query: searchQuery(), pattern: nullableString(), cursor: cursor(), max_matches_per_file: positiveInteger(), max_files: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const queries = searchQueries(params.query);
 			let rows: ReturnType<typeof searchNotes>;
 			try { rows = searchNotes(ctx, queries, { pattern: params.pattern ?? undefined }); } catch (error) { return failure(error); }
 			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
-			const result: Array<{ address: string; scope: string; created_at: string; updated_at: string; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; total_chars: number; offset_chars: number }>; address_truncated?: boolean }> = rows.map((row) => {
-				const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, total_chars: Array.from(match.text).length, offset_chars: match.offsetChars }));
-				return { address: row.address, scope: row.scope, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at), matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+			const result: Array<{ address: string; updated_at: string; stale: boolean; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; offset_chars: number }>; address_truncated?: boolean }> = rows.map((row) => {
+				const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, offset_chars: match.offsetChars }));
+				return { address: row.address, updated_at: localIso(row.meta.updated_at), stale: row.meta.stale, matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
 			});
 			const fitFile = (file: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
 				if (fits(file)) return file;