@astrosheep/pi-context 0.22.0 → 0.23.0

package/dist/test/notes.test.js

@@ -26,6 +26,20 @@ function setUpdatedAt(scope, path, ctx, timestamp) {
     const raw = readFileSync(file, "utf8");
     writeFileSync(file, raw.replace(/^updated_at: .*$/m, `updated_at: ${new Date(timestamp).toISOString()}`));
 }
+function assertNoPublicScope(value, label) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertNoPublicScope(item, label);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        assert.notEqual(key, "scope", `${label} does not expose scope`);
+        assert.notEqual(key, "resolved_scope", `${label} does not expose resolved_scope`);
+        assertNoPublicScope(child, label);
+    }
+}
 test("exactly the five notes tools are registered; the legacy five are gone", () => {
     const captured = makeExtension(manager());
     for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
@@ -34,6 +48,10 @@ test("exactly the five notes tools are registered; the legacy five are gone", ()
     for (const legacy of ["notes_write_file", "notes_append_to_file", "notes_read_file", "notes_search_contents", "notes_list_files"]) {
         assert.equal(captured.tools.get(legacy), undefined, `${legacy} is unregistered`);
     }
+    for (const name of ["notes_write", "notes_edit", "notes_read", "notes_list", "notes_search"]) {
+        const description = captured.tools.get(name)?.description ?? "";
+        assert.equal(/resolved_scope|\bscope\b/.test(description), false, `${name} describes home identity through address only`);
+    }
     assert.equal(captured.tools.get("notes_write")?.executionMode, "sequential");
     assert.equal(captured.tools.get("notes_edit")?.executionMode, "sequential");
     assert.equal(captured.tools.get("notes_read")?.executionMode, undefined);
@@ -45,8 +63,7 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     const ctx = context(session);
     const sessionId = session.getSessionId();
     const result = resultJson(await call(captured, "notes_write", { path: "a/b.md", content: "hello" }, ctx));
-    assert.equal(result.scope, "session");
-    assert.equal(result.size_bytes, 5);
+    assert.deepEqual(Object.keys(result).sort(), ["address", "written"]);
     const file = physicalPath("session", "a/b.md", ctx);
     assert.equal(file, join(root, "pi", "session", sessionId, "a", "b.md"));
     assert.ok(existsSync(file), "the note is a real file under the session scope dir");
@@ -60,7 +77,8 @@ test("write lands a real markdown file with harness frontmatter and a pure body"
     for (const key of ["created_at", "updated_at", "last_accessed"]) {
         assert.match(raw, new RegExp(`^${key}: \\d{4}-\\d{2}-\\d{2}T`, "m"), `frontmatter renders ${key} via localIso`);
     }
-    assert.equal(typeof result.meta.created_at, "string", "wire meta renders timestamps as ISO strings");
+    assert.equal(result.address, "a/b.md");
+    assert.equal(result.written, true);
     // A leading YAML block in user content is stripped from the body.
     await call(captured, "notes_write", { path: "stripped.md", content: "---\nscope: personal\nnonsense: true\n---\nreal body" }, ctx);
     const stripped = readFileSync(physicalPath("session", "stripped.md", ctx), "utf8");
@@ -83,7 +101,7 @@ test("overwrite preserves created_at and unknown keys, bumps updated_at, and cle
     assert.equal(after.includes("sleep_shift_key: keep-me"), true, "an unknown key survives a rewrite");
     assert.equal(after.includes("recurrence_count: 4"), true, "a known sleep-shift key survives a rewrite");
     assert.match(after, /\n---\n\nsecond$/, "the body is replaced");
-    assert.equal(rewrite.meta.origin, "self");
+    assert.deepEqual(Object.keys(rewrite).sort(), ["address", "written"]);
     const listed = listNotes(ctx, { scope: "session" })[0];
     assert.equal(listed.meta.created_at, created, "created_at is preserved across an overwrite");
     assert.ok(listed.meta.updated_at >= created, "updated_at is bumped");
@@ -111,7 +129,8 @@ test("edit is body-scoped with named failures and a replace_all escape hatch", a
     assert.equal(missing.edit_index, 0, "a zero-match anchor names the failing edit index");
     const all = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "beta", newText: "B" }], replace_all: true }, ctx));
     assert.equal(all.applied, 1);
-    assert.equal(all.resolved_scope, "session", "the success return names the layer the file was resolved from");
+    assert.equal(all.address, "edit.md");
+    assertNoPublicScope(all, "notes_edit");
     assert.equal(resultRead(await call(captured, "notes_read", { path: "edit.md" }, ctx)).content.endsWith("alpha\nB\nB\ngamma"), true, "replace_all replaces every occurrence");
     // An anchor that occurs only in frontmatter is not matched: edits are body-only.
     const frontmatterOnly = resultJson(await call(captured, "notes_edit", { path: "edit.md", edits: [{ oldText: "scope", newText: "x" }] }, ctx));
@@ -149,11 +168,13 @@ test("metadata-only edit updates setters without touching the body", async () =>
     await call(captured, "notes_write", { path: "journal.md", content: "log line" }, ctx);
     const bare = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: true }, ctx));
     assert.equal(bare.applied, 0, "a metadata-only update applies no edits");
-    assert.equal(bare.resolved_scope, "session");
-    assert.equal(bare.meta.stale, true, "stale is set without a body edit");
+    assert.equal(bare.address, "journal.md");
+    assert.deepEqual(Object.keys(bare).sort(), ["address", "applied", "diff"]);
+    assert.equal(listNotes(ctx, { scope: "session" })[0].meta.stale, true, "stale is set without a body edit");
     assert.equal(resultRead(await call(captured, "notes_read", { path: "journal.md" }, ctx)).content.endsWith("log line"), true, "the body is untouched");
     const revived = resultJson(await call(captured, "notes_edit", { path: "journal.md", stale: false }, ctx));
-    assert.equal(revived.meta.stale, false, "a later metadata-only update revives the note");
+    assert.deepEqual(Object.keys(revived).sort(), ["address", "applied", "diff"]);
+    assert.equal(listNotes(ctx, { scope: "session" })[0].meta.stale, false, "a later metadata-only update revives the note");
 });
 test("notes_edit returns a pi-edit-style diff of what changed", async () => {
     freshRoot();
@@ -234,7 +255,39 @@ test.skip("scope resolution and movement are superseded by explicit address test
     assert.match(refusal.error, /already exists/);
     assert.equal(readFileSync(physicalPath("personal", "clash.md", ctx), "utf8"), beforePersonal, "the target survives a refused move");
 });
-test("list and search merge scopes and carry scope; the path jail rejects escapes", async () => {
+test("all notes tool results use address as the only home identity", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const notes = [
+        { address: "session.md", body: "session needle" },
+        { address: "@project/project.md", body: "project needle" },
+        { address: "@personal/personal.md", body: "personal needle" },
+    ];
+    for (const note of notes) {
+        const written = resultJson(await call(captured, "notes_write", { address: note.address, content: note.body }, ctx));
+        assert.equal(written.address, note.address, `notes_write returns ${note.address}`);
+        assertNoPublicScope(written, `notes_write ${note.address}`);
+        const edited = resultJson(await call(captured, "notes_edit", { address: note.address, edits: [{ oldText: "needle", newText: "match" }] }, ctx));
+        assert.equal(edited.address, note.address, `notes_edit returns ${note.address}`);
+        assertNoPublicScope(edited, `notes_edit ${note.address}`);
+        const rawRead = await call(captured, "notes_read", { address: note.address }, ctx);
+        const read = resultRead(rawRead);
+        assert.equal(read.details.address, note.address, `notes_read details returns ${note.address}`);
+        assert.equal(read.header.startsWith("--- READ WINDOW ---\naddress: "), true, `notes_read starts a READ WINDOW block for ${note.address}`);
+        assert.equal(read.header.includes("scope"), false, `notes_read header omits scope for ${note.address}`);
+        assert.equal(read.header.includes("resolved_scope"), false, `notes_read header omits resolved_scope for ${note.address}`);
+        assertNoPublicScope(read.details, `notes_read ${note.address}`);
+    }
+    const listed = resultJson(await call(captured, "notes_list", { pattern: "**" }, ctx));
+    assert.deepEqual(listed.files.map((file) => file.address).sort(), notes.map((note) => note.address).sort(), "notes_list returns each full address");
+    assertNoPublicScope(listed, "notes_list");
+    const searched = resultJson(await call(captured, "notes_search", { query: "match", pattern: "**" }, ctx));
+    assert.deepEqual(searched.files.map((file) => file.address), notes.map((note) => note.address).sort(), "notes_search returns each full address");
+    assertNoPublicScope(searched, "notes_search");
+});
+test("list and search merge scopes and carry addresses; the path jail rejects escapes", async () => {
     freshRoot();
     const session = manager();
     const captured = makeExtension(session);
@@ -243,24 +296,24 @@ test("list and search merge scopes and carry scope; the path jail rejects escape
     await call(captured, "notes_write", { path: "two.md", content: "needle two", scope: "project" }, ctx);
     await call(captured, "notes_write", { path: "three.md", content: "needle three", scope: "personal" }, ctx);
     const listed = resultJson(await call(captured, "notes_list", {}, ctx));
-    assert.deepEqual([...listed.files].map((file) => file.scope).sort(), ["personal", "project", "session"], "every merged row carries its scope");
+    assert.deepEqual([...listed.files].map((file) => file.address).sort(), ["@personal/three.md", "@project/two.md", "one.md"], "every merged row carries its full address");
     for (const row of listed.files) {
-        assert.equal(typeof row.size_bytes, "number");
-        assert.equal(row.origin, "self");
-        assert.equal(row.status, "active");
+        assert.deepEqual(Object.keys(row).sort(), ["address", "stale", "updated_at"]);
         assert.equal(row.stale, false);
     }
     const scoped = resultJson(await call(captured, "notes_list", { scope: "personal" }, ctx));
-    assert.deepEqual(scoped.files.map((file) => file.path), ["three.md"], "a scope filter narrows the set");
+    assert.deepEqual(scoped.files.map((file) => file.address), ["@personal/three.md"], "an address-pattern filter narrows the set");
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     assert.equal(searched.files.length, 3, "literal search finds matches in every scope");
-    assert.deepEqual([...searched.files].map((file) => file.scope).sort(), ["personal", "project", "session"]);
+    assert.deepEqual([...searched.files].map((file) => file.address).sort(), ["@personal/three.md", "@project/two.md", "one.md"]);
+    for (const row of [...listed.files, ...searched.files])
+        assertNoPublicScope(row, "notes_list/search");
     assert.equal(searched.files.every((file) => file.matches_total === 1), true);
     const hit = searched.files[0].matches[0];
     assert.equal(hit.line, 1);
-    assert.equal(hit.offset_chars, 0);
+    assert.ok(hit.offset_chars > 0, "the offset includes serialized frontmatter");
     assert.equal(hit.truncated, false);
-    assert.equal(hit.total_chars, searched.files[0].path === "three.md" ? "needle three".length : hit.text.length, "total_chars names the real line length");
+    assert.deepEqual(Object.keys(hit).sort(), ["line", "offset_chars", "text", "truncated"]);
     const escaped = ["../evil", "/abs", "a\\b"];
     for (const tool of ["notes_write", "notes_edit", "notes_read"]) {
         for (const path of escaped) {
@@ -291,6 +344,38 @@ test("the boot index reads the physical store across scopes and excludes stale n
         assert.equal(PROTOCOL_BLOCK.includes(legacy), false, `the protocol block no longer names ${legacy}`);
     }
 });
+test("search offsets start reads at Unicode matches across homes without mutating search results", async () => {
+    freshRoot();
+    const session = manager();
+    const captured = makeExtension(session);
+    const ctx = context(session);
+    const notes = [
+        { address: "session.md", scope: "session", body: "first line\n前置 🐉 needle-session\nend", needle: "needle-session" },
+        { address: "@project/crossing.md", scope: "project", body: "prefix\nneedle-project 😀", needle: "needle-project" },
+        { address: "@personal/legacy.md", scope: "personal", body: "legacy 😺 needle-personal", needle: "needle-personal" },
+    ];
+    for (const note of notes)
+        await call(captured, "notes_write", { address: note.address, content: note.body }, ctx);
+    const crossing = physicalPath("project", "crossing.md", ctx);
+    writeFileSync(crossing, readFileSync(crossing, "utf8").replace(/^access_count: 0$/m, "access_count: 9"));
+    const legacy = physicalPath("personal", "legacy.md", ctx);
+    writeFileSync(legacy, notes[2].body);
+    const before = new Map(notes.map((note) => [note.address, readFileSync(physicalPath(note.scope, note.address.replace(/^@(?:project|personal)\//, ""), ctx), "utf8")]));
+    const searched = resultJson(await call(captured, "notes_search", { query: notes.map((note) => note.needle), pattern: "**" }, ctx));
+    for (const note of notes) {
+        assert.equal(readFileSync(physicalPath(note.scope, note.address.replace(/^@(?:project|personal)\//, ""), ctx), "utf8"), before.get(note.address), `search leaves ${note.address} byte-identical`);
+        const file = searched.files.find((candidate) => candidate.address === note.address);
+        assert.ok(file, `search returns ${note.address}`);
+        assert.deepEqual(Object.keys(file).sort(), ["address", "matches", "matches_total", "stale", "updated_at"]);
+        const hit = file.matches[0];
+        assert.deepEqual(Object.keys(hit).sort(), ["line", "offset_chars", "text", "truncated"]);
+        const read = resultRead(await call(captured, "notes_read", { address: note.address, offset_chars: hit.offset_chars }, ctx));
+        assert.ok(read.content.startsWith(note.needle), `search offset starts notes_read at ${note.needle}`);
+        assert.deepEqual(Object.keys(read.details).sort(), ["address", "next_offset_chars", "offset_chars", "total_chars"]);
+    }
+    assert.match(readFileSync(crossing, "utf8"), /^access_count: 10$/m, "the predicted read crosses access_count from 9 to 10");
+    assert.match(resultRead(await call(captured, "notes_read", { address: "@personal/legacy.md" }, ctx)).content, /^---\n/, "a missing-frontmatter note is normalized only by read");
+});
 test("notes_read surfaces frontmatter and search reports body lines", async () => {
     freshRoot();
     const session = manager();
@@ -303,7 +388,7 @@ test("notes_read surfaces frontmatter and search reports body lines", async () =
     const searched = resultJson(await call(captured, "notes_search", { query: "needle" }, ctx));
     const match = searched.files[0].matches[0];
     assert.equal(match.line, 2, "search reports the body line number");
-    assert.equal(match.offset_chars, Array.from("line one\n").length, "offset_chars addresses the query within the body");
+    assert.equal(match.offset_chars, read.content.indexOf("needle"), "offset_chars addresses the query in the serialized read stream");
 });
 test("mutations are atomic, leave no temp files, and a read bumps only the access keys", async () => {
     freshRoot();
@@ -443,11 +528,12 @@ test("full addresses drive outputs and patterns; on-disk scope is read then drop
     assert.deepEqual(resultJson(await call(captured, "notes_list", { pattern: "*.md" }, ctx)).files.map((file) => file.address), ["root.md"]);
     assert.deepEqual(resultJson(await call(captured, "notes_search", { query: "needle", pattern: "@project/**" }, ctx)).files.map((file) => file.address), ["@project/project.md"]);
     const read = resultRead(await call(captured, "notes_read", { address: "@personal/personal.md" }, ctx));
-    assert.match(read.header, /^\[@personal\/personal\.md /, "the raw read header echoes the full address");
+    assert.equal(read.header, "--- READ WINDOW ---\naddress: @personal/personal.md\nchars: [0," + read.total_chars + ") of " + read.total_chars + "\nnext_offset_chars: null\n", "the raw READ WINDOW block echoes the full address");
     const legacy = physicalPath("project", "legacy.md", ctx);
     writeFileSync(legacy, "---\nscope: personal\norigin: self\nstatus: active\nstale: false\ncreated_at: 2026-01-01T00:00:00.000+00:00\nupdated_at: 2026-01-01T00:00:00.000+00:00\nlast_accessed: 2026-01-01T00:00:00.000+00:00\naccess_count: 0\n---\n\nlegacy");
     const legacyRead = resultRead(await call(captured, "notes_read", { address: "@project/legacy.md" }, ctx));
-    assert.equal(legacyRead.details.scope, "project", "scope is derived from the file location");
+    assert.equal(legacyRead.details.address, "@project/legacy.md", "the read keeps the requested address while deriving its home internally");
+    assertNoPublicScope(legacyRead.details, "legacy notes_read");
     await call(captured, "notes_edit", { address: "@project/legacy.md", stale: true }, ctx);
     assert.equal(/^scope:/m.test(readFileSync(legacy, "utf8")), false, "the next write removes legacy scope frontmatter");
 });

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.