@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/store-contracts/file-history-store-contract.js

@@ -293,10 +293,39 @@ export async function fileHistoryStoreContract(make, runAssertion) {
                 assert.deepEqual(await store.annulTrack("sc", join(dir, "opaque2.txt"), dir), { ok: true });
             await writeFile(join(dir, "opaque.txt"), "agent-edited");
             const r = await store.restore("sc", "b0", env, dir);
-            assert.equal(r.refused.some((f) => f.reason.includes("base_unavailable")), true, `the kept marker must still refuse a below-base restore: ${JSON.stringify(r)}`);
+            assert.equal(r.refused.some((f) => f.reason.includes("base_unavailable") && f.class === "base_unavailable"), true, `the kept marker must still refuse a below-base restore, classed base_unavailable: ${JSON.stringify(r)}`);
             assert.equal(await readFile(join(dir, "opaque.txt"), "utf8"), "agent-edited", "never overwritten with a fake baseline");
         });
     });
+    run("annulTrack's proof read that cannot re-read the path judged nothing: track_failed (aborted when the signal fired), no permanence, the record kept — never the history law's conflict", async () => {
+        await withTree(async (dir, env) => {
+            const store = make();
+            await writeFile(join(dir, "f.txt"), "pristine");
+            await writeFile(join(dir, "g.txt"), "pristine");
+            assert.deepEqual(await store.trackEdit("sc", join(dir, "f.txt"), env, dir), { ok: true, minted: true });
+            assert.deepEqual(await store.trackEdit("sc", join(dir, "g.txt"), env, dir), { ok: true, minted: true });
+            const unreadable = envWithFailingRead(env, async () => ({ ok: false, error: { code: "unknown", message: "transport gone" } }));
+            const unjudged = await store.annulTrack("sc", join(dir, "f.txt"), dir, { env: unreadable });
+            assert.equal(unjudged.ok, false, "an unread proof never retracts");
+            if (!unjudged.ok) {
+                assert.equal(unjudged.error.code, "track_failed", `a proof that could not be read is the verb's failure, not the law: ${JSON.stringify(unjudged)}`);
+                assert.equal(unjudged.error.permanence, undefined, "an env read error is not the store's own storage fault — unjudged");
+            }
+            const aborted = new AbortController();
+            aborted.abort();
+            const cut = await store.annulTrack("sc", join(dir, "g.txt"), dir, { env, signal: aborted.signal });
+            assert.equal(cut.ok, false, "a proof read cut by the signal never retracts");
+            if (!cut.ok)
+                assert.equal(cut.error.code, "aborted", `the signal fired: ${JSON.stringify(cut)}`);
+            assert.deepEqual(await store.snapshot("sc", "b1", env, dir), { ok: true });
+            await writeFile(join(dir, "f.txt"), "diverged");
+            await writeFile(join(dir, "g.txt"), "diverged");
+            const r = await store.restore("sc", "b1", env, dir);
+            assert.equal(r.outcome, "complete");
+            assert.equal(await readFile(join(dir, "f.txt"), "utf8"), "pristine", "the unjudged retraction left the record intact");
+            assert.equal(await readFile(join(dir, "g.txt"), "utf8"), "pristine", "the aborted retraction left the record intact");
+        });
+    });
     run("annulTrack refuses what is no longer a mint: a boundary-referenced record is history (typed conflict, record intact)", async () => {
         await withTree(async (dir, env) => {
             const store = make();
@@ -444,9 +473,18 @@ export async function fileHistoryStoreContract(make, runAssertion) {
                 throw Object.assign(new Error("source blob unreadable"), { code: "EACCES" });
             });
             assert.equal(thrown.ok, false);
+            if (!thrown.ok)
+                assert.equal(thrown.error.code, "adopt_failed", "a source whose read throws cannot supply a referenced blob");
             if (!thrown.ok)
                 assertPermanenceWord(thrown.error, "importHistory whose source fetch threw");
             assert.equal(await store.canRestore("sc", "b2"), false);
+            const wrongBytes = await store.importHistory("sc", missingBlob, async () => new TextEncoder().encode("bytes that are not the content this address names"));
+            assert.equal(wrongBytes.ok, false);
+            if (!wrongBytes.ok)
+                assert.equal(wrongBytes.error.code, "adopt_failed", "a source whose bytes fail their content address cannot supply a referenced blob");
+            if (!wrongBytes.ok)
+                assertPermanenceWord(wrongBytes.error, "importHistory whose source served the wrong bytes");
+            assert.equal(await store.canRestore("sc", "b2"), false);
             const duplicated = wireEnvelope({
                 formatVersion: "file-history/1",
                 tracked: [
@@ -700,6 +738,7 @@ export async function fileHistoryStoreContract(make, runAssertion) {
                 const r = await store.restore("sc", "b1", env, dir);
                 assert.equal(r.outcome, "partial", JSON.stringify(r));
                 assert.equal(r.refused.length, 2, "both kind mismatches are refused, each by name");
+                assert.deepEqual(r.refused.map((f) => f.class), ["link_safety", "link_safety"], `a kind mismatch is a link-safety refusal: ${JSON.stringify(r.refused)}`);
                 assert.equal(await readFile(join(outside, "victim.txt"), "utf8"), "OUTSIDE-UNTOUCHED", "a leaf link is never written THROUGH");
                 assert.deepEqual(r.filesChanged, []);
             }

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -1,5 +1,5 @@
 import { strict as assert } from "node:assert";
-import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
+import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_INVALID_DECISION_MOVE_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
 import { beginContract } from "./contract-harness.js";
 import { PRINCIPAL_INBOX_HANDLE } from "../../agents/cross-session-ref.js";
 import { mintCrossPrincipalRecord } from "../../agents/org-delivery-gate.js";
@@ -183,6 +183,54 @@ export async function mailboxStoreContract(mk, runAssertion) {
         const again = await s.claimLease(S, "a1", "w2", 1_000, 20_000);
         assert.deepEqual(again.messages[0].peerMeta, { fromMode: "bypass", fromSession: "sess_1" }, "重投的记录必须是原样");
     });
+    run("#972b hold decision:CAS 一胜一负、负者拿到真值;不受租约围栏;每个租约快照都带它", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        await s.append(S, "a1", msg("m2"));
+        const held = await s.claimLease(S, "a1", "holder", 60_000, 10_000);
+        assert.equal(held.messages[0].decision, undefined, "从未 held 的记录没有 decision");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, undefined, "held"), { ok: true });
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, undefined, "held"), { ok: false, current: "held" }, "同一步再走一次:负者拿到当前值");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "held", "denied"), { ok: true }, "不持租约的一方也能落人的决定");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "held", "approved"), { ok: false, current: "denied" }, "后到的答复输给先到的决定");
+        assert.deepEqual(await s.moveDecision(S, "a1", 2, "held", "approved"), { ok: false, current: "unset" }, "未 held 的记录答 unset");
+        const snap = await s.claimLease(S, "a1", "holder", 60_000, 11_000);
+        assert.deepEqual(snap.messages.map((m) => [m.seq, m.decision]), [[1, "denied"], [2, undefined]], "租约快照带每条记录的 decision");
+        await s.ack(S, "a1", "holder", 1);
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "denied", "denied").catch((e) => e.code), MAILBOX_INVALID_DECISION_MOVE_CODE, "终局不再移动(先于存在性判)");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "held", "approved"), { ok: false, current: "gone" }, "ack 掉的记录答 gone");
+    });
+    run("#972b decision 律:只向前走,终局不动;坏词 / 坏 seq / 非法边先于任何副作用被拒(带码)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const codeOf = async (p) => {
+            try {
+                await p;
+                return undefined;
+            }
+            catch (e) {
+                return e.code;
+            }
+        };
+        for (const [label, seq, expect, next] of [
+            ["unset → approved", 1, undefined, "approved"],
+            ["unset → delivered", 1, undefined, "delivered"],
+            ["held → held", 1, "held", "held"],
+            ["held → dropped", 1, "held", "dropped"],
+            ["delivered → denied", 1, "delivered", "denied"],
+            ["denied → approved", 1, "denied", "approved"],
+            ["unknown word", 1, undefined, "consumed"],
+            ["seq 0", 0, undefined, "held"],
+            ["seq 1.5", 1.5, undefined, "held"],
+        ]) {
+            assert.equal(await codeOf(s.moveDecision(S, "a1", seq, expect, next)), MAILBOX_INVALID_DECISION_MOVE_CODE, label);
+        }
+        const snap = await s.claimLease(S, "a1", "w", 60_000, 10_000);
+        assert.equal(snap.messages[0].decision, undefined, "被拒的调用零副作用");
+        for (const [from, to] of [[undefined, "held"], ["held", "approved"], ["approved", "delivered"], ["delivered", "dropped"]]) {
+            assert.deepEqual(await s.moveDecision(S, "a1", 1, from, to), { ok: true }, `${String(from)} → ${to}`);
+        }
+    });
     await settle();
 }
 export async function mailboxAckOwnershipContract(mk, runAssertion) {

package/dist/core/store-contracts/peer-directory-contract.d.ts

@@ -9,7 +9,7 @@ export interface PeerDirectoryContractHooks {
     runAssertion?: ContractAssertionRunner;
 }
 /**
- * The directory contract. Four readings, each the reason the engine can do something:
+ * The directory contract. Five readings, each the reason the engine can do something:
  *  1. **scope wall** — a listing is the ACCESSOR's scope only; the cross-principal wall's mechanical
  *     seat is this filter, so a row leaking across scopes is a tenant leak, not a display bug;
  *  2. **the full set, copies** — live, dead AND deleted rows are all listed (a `name [ref]` is minted
@@ -18,6 +18,11 @@ export interface PeerDirectoryContractHooks {
  *  3. **resolution feeds on the listing** — the engine's own resolver, over the rows as listed, finds
  *     a live row by name, still finds a dead one, and answers `deleted` for a tombstone;
  *  4. **restore is CAS-on-absent** (only where the host implements it) — an absent row is restored and
- *     then listed; a present row is never overwritten (`false`, the existing row byte-unchanged).
+ *     then listed; a present row is never overwritten (`false`, the existing row byte-unchanged);
+ *  5. **every listed row is one the engine's reader accepts** — the engine reads a listing through
+ *     `readPeerSessionRecord` and one refused row faults the WHOLE listing (dropping it would resize refs and
+ *     change resolution over the full set), so a row that does not say `where`, or a non-local row carrying a
+ *     machine-bound member, takes the directory's peer lane down. (How a host decides `where` is its own;
+ *     the kit does not require the written value back.)
  */
 export declare function peerDirectoryContract(mk: () => PeerDirectory, hooks: PeerDirectoryContractHooks): Promise<void>;

package/dist/core/store-contracts/peer-directory-contract.js

@@ -1,9 +1,9 @@
 import { strict as assert } from "node:assert";
-import { resolvePeerSessions } from "../../agents/peer-directory.js";
+import { readPeerSessionRecord, resolvePeerSessions } from "../../agents/peer-directory.js";
 import { beginContract } from "./contract-harness.js";
 export const PEER_DIRECTORY_CONTRACT_SCOPE = "peer-kit-A";
 function row(name, sessionId, over = {}) {
-    return { schemaVersion: 1, sessionId, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", ...over };
+    return { schemaVersion: 1, sessionId, scope: PEER_DIRECTORY_CONTRACT_SCOPE, name, startedAt: 1_000, updatedAt: 2_000, liveness: "live", where: "hosted", ...over };
 }
 async function withDirs(mk, fn) {
     const live = [];
@@ -78,5 +78,17 @@ export async function peerDirectoryContract(mk, hooks) {
         assert.equal(current.liveness, "live");
         assert.equal(current.updatedAt, 9_000, "the existing row is byte-unchanged by a losing restore");
     });
+    run("every listed row is one the engine's row reader accepts (live, dead and deleted alike)", async (make) => {
+        const d = make();
+        await hooks.write(d, row("alpha", "sess-a"));
+        await hooks.write(d, row("beta", "sess-b", { liveness: "dead", diedAt: 3_000 }));
+        await hooks.write(d, row("gamma", "sess-c", { liveness: "deleted", diedAt: 3_000 }));
+        const listed = await d.listPeerSessions({ scope: S });
+        assert.equal(listed.length, 3);
+        for (const r of listed) {
+            const read = readPeerSessionRecord(r);
+            assert.ok(read.ok, `listed row ${r.sessionId} is refused by the engine's reader (${read.ok ? "" : `${read.reason}${read.field !== undefined ? `: ${read.field}` : ""}`})`);
+        }
+    });
     await settle();
 }

package/dist/core/store-contracts/session-repo-contract.js

@@ -73,6 +73,44 @@ export async function sessionRepoContract(make, runAssertion) {
         assert.deepEqual(after.map((e) => e.parentId), [null, "e1"]);
         assert.equal((await repo.exportEntries(A)).length, 2, "importing into C must not disturb the donor session");
     });
+    run("list answers each row once, with its owner cell; a row's lastActiveAt, where the repo records it, is a finite time that a later write or touch never moves back", async () => {
+        const repo = make();
+        const B = "0198fa00-0000-7000-8000-00000000000b";
+        await (await repo.create({ id: A, owner: "kit-alice" })).getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        await (await repo.create({ id: B })).getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        let rows = await repo.list();
+        for (const id of [A, B])
+            assert.equal(rows.filter((r) => r.id === id).length, 1, `row ${id} is listed once`);
+        const rowA = rows.find((r) => r.id === A);
+        const rowB = rows.find((r) => r.id === B);
+        assert.equal(rowA.owner ?? null, "kit-alice", "a listed row carries its owner cell");
+        assert.equal(rowB.owner ?? null, null);
+        const timeOf = (id) => {
+            const row = rows.find((r) => r.id === id);
+            return row.lastActiveAt ?? Date.parse(row.createdAt);
+        };
+        if (rowA.lastActiveAt !== undefined && rowB.lastActiveAt !== undefined) {
+            assert.ok(Number.isFinite(rowA.lastActiveAt) && Number.isFinite(rowB.lastActiveAt), "a recorded activity time is a finite epoch-ms number");
+            assert.ok(rowB.lastActiveAt >= rowA.lastActiveAt, "the row written later is not listed as older");
+            const before = rowA.lastActiveAt;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            await (await repo.open({ id: A, createdAt: "" })).getStorage().appendEntry(SESSION_ENTRY("e2", "e1"));
+            rows = await repo.list();
+            assert.ok(timeOf(A) >= before && timeOf(A) >= rowB.lastActiveAt, "a write moves its row's time forward, past the rows written before it");
+        }
+        if (repo.touch === undefined)
+            return;
+        const latest = Math.max(timeOf(A), timeOf(B));
+        const older = timeOf(A) <= timeOf(B) ? A : B;
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        await repo.touch(older);
+        rows = await repo.list();
+        const touched = rows.find((r) => r.id === older).lastActiveAt;
+        assert.ok(touched !== undefined && Number.isFinite(touched), "a touched row lists a recorded time");
+        assert.ok(touched >= latest, "a touch moves its row's time forward, past the rows active before it");
+        await repo.touch("0198fa00-0000-7000-8000-0000000000ff");
+    });
     run("the owner cell round-trips: create({id, owner}) records it and open() reads it back; a create naming no owner records null", async () => {
         const repo = make();
         const owned = await repo.create({ id: A, owner: "kit-alice" });
@@ -82,6 +120,19 @@ export async function sessionRepoContract(make, runAssertion) {
         await repo.create({ id: B });
         assert.equal((await (await repo.open({ id: B, createdAt: "" })).getMetadata()).owner ?? null, null, "no owner named ⇒ anonymous");
     });
+    run("a create or fork whose owner is no principal name (the empty string, a blank string, a string holding a control or invisible character) is refused and leaves no row", async () => {
+        const repo = make();
+        for (const owner of ["", " \t ", "ali\u0000ce", "\u200b"])
+            await assert.rejects(() => repo.create({ id: A, owner }), `create with owner ${JSON.stringify(owner)}`);
+        await assert.rejects(() => repo.open({ id: A, createdAt: "" }), "the refused creates stored nothing");
+        const src = await repo.create({ id: A, owner: "kit-alice" });
+        await src.getStorage().appendEntry(SESSION_ENTRY("e1", null));
+        const B = "0198fa00-0000-7000-8000-00000000000b";
+        for (const owner of ["", " \t ", "ali\u0000ce", "\u200b"])
+            await assert.rejects(() => repo.fork({ id: A, createdAt: "" }, { id: B, owner }), `fork with owner ${JSON.stringify(owner)}`);
+        await assert.rejects(() => repo.open({ id: B, createdAt: "" }), "the refused forks stored nothing");
+        assert.equal((await (await repo.open({ id: A, createdAt: "" })).getMetadata()).owner, "kit-alice", "the source row is untouched");
+    });
     run("create({id, owner: Y}) onto an existing row owned by X reopens it untouched: the row keeps X, and the session it returns carries X", async () => {
         const repo = make();
         const first = await repo.create({ id: A, owner: "kit-x" });

package/dist/core/store-contracts/session-store-contract.d.ts

@@ -18,7 +18,8 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
  * clock seam), what `release` does to an ordinary session's live set (`size` is best-effort and a durable
  * `list` may still show the history), a durable backend's crash recovery, and a delete that fails half-way.
  *
- * Semantics since @sema-agent/core 7.55.0.
+ * Semantics since @sema-agent/core 7.56.0: the list reads the store's rows (a reopened store lists them), pages by the
+ * `(lastActiveAt, sessionId)` keyset, filters by the row's owner, and refuses a bad query through `readSessionListQuery`.
  */
 export interface SessionStoreContractHooks {
     /** Delete `sessionId`'s session ROW through the backend's own deletion path (history and all), so that a later

package/dist/core/store-contracts/session-store-contract.js

@@ -1,6 +1,6 @@
 import { strict as assert } from "node:assert";
 import { uuidv7 } from "../../internal/harness.js";
-import { hasSessionFork, isSessionConflict } from "../session.js";
+import { SESSION_LIST_LIMITS, hasSessionFork, isSessionConflict } from "../session.js";
 import { readMember } from "../thrown-value.js";
 import { receiptRefusal, receiveOwnProperties } from "../own-property-receipt.js";
 import { beginContract } from "./contract-harness.js";
@@ -483,7 +483,7 @@ async function runSessionStoreContract(make, hooks) {
         const sf = await store.fork(settled);
         assert.deepEqual(await pathIds((await readBack(store, sf))), ["u1", "a1"], "a settled text turn forks whole");
     });
-    faceRun("[list] list projects each live session once, newest-first by lastActiveAt, and a touch counts as activity", ["list"], async (store) => {
+    faceRun("[list] list projects each session row once, newest-first by lastActiveAt, and a touch counts as activity", ["list"], async (store) => {
         const [a, b, c] = [freshId(), freshId(), freshId()];
         await store.acquire(a);
         await tick();
@@ -494,7 +494,7 @@ async function runSessionStoreContract(make, hooks) {
         assertNewestFirst(rows);
         for (const id of [a, b, c])
             assert.equal(rows.filter((r) => r.sessionId === id).length, 1, `session ${id} is listed exactly once`);
-        assertActivityOrder(rows, [c, b, a], "acquire is activity");
+        assertActivityOrder(rows, [c, b, a], "a session created later is more recent");
         for (const r of rows)
             assert.ok(r.createdAt === undefined || (typeof r.createdAt === "string" && r.createdAt !== ""), "createdAt is a real timestamp or absent, never an empty placeholder");
         const before = rowOf(rows, a).lastActiveAt;
@@ -513,25 +513,148 @@ async function runSessionStoreContract(make, hooks) {
         assert.equal(rowOf(rows, forkedId)?.forkedFrom, src, "the fork's row carries its lineage");
         assert.equal(rowOf(rows, src)?.forkedFrom, undefined, "the source is no fork");
     });
-    faceRun("[list] noteTaskRun lands on the summary and counts as activity; a call without a run id clears lastTaskRunId; an unknown id never throws", ["noteTaskRun"], async (store) => {
+    faceRun("[list] noteTaskRun lands on the summary; a call without a run id clears lastTaskRunId; an unknown id never throws", ["noteTaskRun"], async (store) => {
         await store.noteTaskRun(freshId(), "kit-task", "kit-run");
         if (typeof store.list !== "function")
             return;
-        const [a, b] = [freshId(), freshId()];
+        const a = freshId();
         await store.acquire(a);
-        await tick();
-        await store.acquire(b);
-        await tick();
         await store.noteTaskRun(a, "task-1", "run-1");
         let rows = await store.list();
         assert.equal(rowOf(rows, a)?.lastTaskId, "task-1");
         assert.equal(rowOf(rows, a)?.lastTaskRunId, "run-1");
-        assertActivityOrder(rows, [a, b], "a run is activity: the session that just ran is the most recently active");
         await store.noteTaskRun(a, "task-2");
         rows = await store.list();
         assert.equal(rowOf(rows, a)?.lastTaskId, "task-2");
         assert.equal(rowOf(rows, a)?.lastTaskRunId, undefined, "the two seats describe one run: a newer task with no run id must not keep the older run's id");
     });
+    faceRun("[list] the list reads the rows, not a cache: sessions are listed after their cached view is dropped and on a store reopened over the same rows (a restart), newest first", ["list"], async (store, open) => {
+        const [a, b] = [freshId(), freshId()];
+        await append((await store.acquire(a)).session, userEntry("e1", null));
+        await tick();
+        await append((await store.acquire(b)).session, userEntry("e1", null));
+        if (typeof store.forget === "function") {
+            await store.forget(a);
+            assert.ok(rowOf(await store.list({ limit: SESSION_LIST_LIMITS.max }), a) !== undefined, "a session whose cached view was dropped is still a row");
+        }
+        const second = await open(hooks.reopen(store));
+        const rows = await second.list({ limit: SESSION_LIST_LIMITS.max });
+        assertNewestFirst(rows);
+        assertActivityOrder(rows, [b, a], "a restart keeps the activity order the rows recorded");
+    });
+    faceRun("[list] a touch is recorded on the row: the touched session is still the most recent on a store reopened over the same rows (a restart)", ["list"], async (store, open) => {
+        const [a, b] = [freshId(), freshId()];
+        await append((await store.acquire(a)).session, userEntry("e1", null));
+        await tick();
+        await append((await store.acquire(b)).session, userEntry("e1", null));
+        await tick();
+        await store.touch(a);
+        const second = await open(hooks.reopen(store));
+        assertActivityOrder(await second.list({ limit: SESSION_LIST_LIMITS.max }), [a, b], "the touch outlives the process that made it");
+    });
+    faceRun("[list] a cached view of an occupant the listed row does not name lends it nothing: after another instance deleted the row and registered the id to another owner, the row lists without the old occupant's run", ["list", "noteTaskRun", "ownership", "replica"], async (store, open) => {
+        const id = freshId();
+        const other = await open(hooks.replica(store));
+        await store.register(id, "kit-alice");
+        await store.acquire(id);
+        await store.noteTaskRun(id, "alice-task", "alice-run");
+        await other.acquire(id);
+        await hooks.deleteSession(other, id);
+        await other.register(id, "kit-bob");
+        const row = rowOf(await store.list({ owner: "kit-bob", limit: SESSION_LIST_LIMITS.max }), id);
+        assert.ok(row !== undefined, "the new owner's row is listed");
+        assert.equal(row.lastTaskId, undefined, "the previous occupant's run is not lent to the new owner's row");
+        assert.equal(row.lastTaskRunId, undefined);
+    });
+    faceRun("[list] paging survives a dropped cache: a session whose cached view is dropped between two pages is not read again", ["list", "ownership", "forget"], async (store) => {
+        const owner = `kit-forget-${uuidv7().slice(-12)}`;
+        const ids = [freshId(), freshId(), freshId()];
+        for (const id of ids) {
+            await store.register(id, owner);
+            await tick();
+        }
+        for (const id of ids)
+            await store.acquire(id);
+        const first = await store.list({ owner, limit: 1 });
+        assert.equal(first.length, 1);
+        const top = first[0];
+        await store.forget(top.sessionId);
+        const rest = await store.list({ owner, after: { lastActiveAt: top.lastActiveAt, sessionId: top.sessionId } });
+        assert.ok(!rest.some((r) => r.sessionId === top.sessionId), "the first page's row is not on the next page");
+        assert.equal(rest.length, ids.length - 1, "and every other row is");
+    });
+    faceRun("[list] owner filters by the row's owner cell: an owner's rows only; with includeUnowned the unowned rows too; no owner = every owner's rows", ["list", "ownership"], async (store) => {
+        const [alice, bob] = [`kit-alice-${uuidv7().slice(-12)}`, `kit-bob-${uuidv7().slice(-12)}`];
+        const [a1, a2, b1, u1] = [freshId(), freshId(), freshId(), freshId()];
+        await store.register(a1, alice);
+        await store.register(a2, alice);
+        await store.register(b1, bob);
+        await store.acquire(u1);
+        const ids = (rows) => new Set(rows.map((r) => r.sessionId));
+        const own = ids(await store.list({ owner: alice, limit: SESSION_LIST_LIMITS.max }));
+        assert.ok(own.has(a1) && own.has(a2), "the owner's rows are listed");
+        assert.ok(!own.has(b1) && !own.has(u1), "another owner's row and an unowned row are not");
+        const withUnowned = ids(await store.list({ owner: alice, includeUnowned: true, limit: SESSION_LIST_LIMITS.max }));
+        assert.ok(withUnowned.has(a1) && withUnowned.has(a2) && withUnowned.has(u1), "includeUnowned adds the unowned rows");
+        assert.ok(!withUnowned.has(b1), "and never another owner's");
+        const all = ids(await store.list({ limit: SESSION_LIST_LIMITS.max }));
+        for (const id of [a1, a2, b1, u1])
+            assert.ok(all.has(id), `no owner filter lists every owner's rows (${id})`);
+    });
+    faceRun("[list] keyset paging reads each row once: pages cut with limit and the after cursor, concatenated, are the one-page list — ties ordered by session id, descending", ["list", "ownership"], async (store) => {
+        const owner = `kit-pager-${uuidv7().slice(-12)}`;
+        const ids = [freshId(), freshId(), freshId(), freshId(), freshId()];
+        for (const id of ids)
+            await store.register(id, owner);
+        const whole = await store.list({ owner, limit: SESSION_LIST_LIMITS.max });
+        assert.deepEqual(new Set(whole.map((r) => r.sessionId)), new Set(ids), "the owner's five rows");
+        for (let i = 1; i < whole.length; i++) {
+            const [prev, row] = [whole[i - 1], whole[i]];
+            assert.ok(prev.lastActiveAt > row.lastActiveAt || (prev.lastActiveAt === row.lastActiveAt && prev.sessionId > row.sessionId), `row ${i} follows row ${i - 1} in (lastActiveAt, sessionId) descending order`);
+        }
+        const paged = [];
+        let after;
+        for (let pages = 0; pages < 10; pages++) {
+            const page = await store.list({ owner, limit: 2, ...(after !== undefined ? { after } : {}) });
+            assert.ok(page.length <= 2, "a page holds at most limit rows");
+            if (page.length === 0)
+                break;
+            paged.push(...page.map((r) => r.sessionId));
+            const last = page[page.length - 1];
+            after = { lastActiveAt: last.lastActiveAt, sessionId: last.sessionId };
+        }
+        assert.deepEqual(paged, whole.map((r) => r.sessionId), "the pages, in order, are the one-page list: no row twice, none skipped");
+    });
+    faceRun("[list] a query without limit reads the default page; an explicit limit reads that many", ["list", "ownership"], async (store) => {
+        const owner = `kit-page-${uuidv7().slice(-12)}`;
+        const total = SESSION_LIST_LIMITS.default + 1;
+        for (let i = 0; i < total; i++)
+            await store.register(freshId(), owner);
+        assert.equal((await store.list({ owner })).length, SESSION_LIST_LIMITS.default, `no limit = the first ${SESSION_LIST_LIMITS.default} rows`);
+        assert.equal((await store.list({ owner, limit: total })).length, total);
+        assert.equal((await store.list({ owner, limit: 1 })).length, 1);
+    });
+    faceRun("[list] a bad query is refused config.invalid_argument, never read as a default: a limit out of 1..max or not an integer, a member of the wrong type, includeUnowned without owner, a malformed cursor, a member the store does not read", ["list"], async (store) => {
+        const bad = [
+            ["limit 0", { limit: 0 }],
+            ["a negative limit", { limit: -1 }],
+            ["a fractional limit", { limit: 1.5 }],
+            ["a limit past the bound", { limit: SESSION_LIST_LIMITS.max + 1 }],
+            ["a limit spelled as a string", { limit: "10" }],
+            ["a NaN limit", { limit: Number.NaN }],
+            ["an owner that is not a string", { owner: 7 }],
+            ["includeUnowned that is not a boolean", { owner: "kit-x", includeUnowned: "yes" }],
+            ["includeUnowned without owner", { includeUnowned: true }],
+            ["a cursor without a session id", { after: { lastActiveAt: 1 } }],
+            ["a cursor whose time is not a finite number", { after: { lastActiveAt: Number.POSITIVE_INFINITY, sessionId: "x" } }],
+            ["a cursor carrying another member", { after: { lastActiveAt: 1, sessionId: "x", page: 2 } }],
+            ["a member the store does not read", { kitUnreadFilter: "x" }],
+            ["a query that is not an object", 7],
+        ];
+        for (const [what, query] of bad) {
+            await rejectsWithCode(() => Reflect.apply(store.list, store, [query]), "config.invalid_argument", `list(${what})`);
+        }
+    });
     faceRun("[placements] a placed session stays off the host list — before and after a restart, also when read back with require-existing", ["placements"], async (store, open) => {
         const placed = freshId();
         const plain = freshId();
@@ -716,16 +839,29 @@ async function runSessionStoreContract(make, hooks) {
         await store.register(acquired, "kit-carol");
         assert.equal(await ownerOf(store, acquired, "a row acquire created"), null, "there is no claiming of a row that exists");
         if (declaresPlacements(store)) {
-            const placed = freshId();
-            await store.acquire(placed, { placement: placementFor() });
-            await store.register(placed, "kit-dave");
-            assert.equal(await ownerOf(store, placed, "a placed row"), null, "a placed row records no owner");
+            for (const owner of [`kit-claimant-${freshId()}`, null]) {
+                const placed = freshId();
+                await store.acquire(placed, { placement: placementFor() });
+                const recorded = await ownerOf(store, placed, "a placed row");
+                await store.register(placed, owner);
+                assert.equal(await ownerOf(store, placed, "a placed row after a register"), recorded, `a register carrying ${owner === null ? "null" : "an owner"} left the placed row's owner as its placing write recorded it`);
+            }
+            const sequenced = freshId();
+            await store.acquire(sequenced, { placement: placementFor() });
+            const recordedSeq = await ownerOf(store, sequenced, "a placed row (sequence)");
+            await store.register(sequenced, null);
+            await store.register(sequenced, `kit-claimant-${freshId()}`);
+            assert.equal(await ownerOf(store, sequenced, "a placed row after two registers"), recordedSeq, "two registers in sequence (null, then a name) left the placed row's owner as its placing write recorded it");
         }
     });
-    faceRun("[ownership] a FIRST register whose owner is neither a string nor null is refused loudly and leaves no row behind", ["ownership"], async (store) => {
+    faceRun("[ownership] a FIRST register whose owner is neither a principal name nor null is refused loudly and leaves no row behind — a blank string, or one holding a control or invisible character, names nobody", ["ownership"], async (store) => {
         const id = freshId();
         await thrownBy(() => registerUntyped(store, id, undefined), "a first register with owner undefined");
         await thrownBy(() => registerUntyped(store, id, 42), "a first register with a numeric owner");
+        await thrownBy(() => registerUntyped(store, id, ""), "a first register with the empty string as owner");
+        await thrownBy(() => registerUntyped(store, id, " \t "), "a first register with a blank string as owner");
+        await thrownBy(() => registerUntyped(store, id, "ali\u0000ce"), "a first register with a control character inside the owner");
+        await thrownBy(() => registerUntyped(store, id, "\u200b"), "a first register with an invisible character as owner");
         assert.equal(await headOf(store, id), undefined, "the refused writes stored nothing");
         await store.register(id, "kit-carol");
         assert.equal(await ownerOf(store, id, "the first well-formed register"), "kit-carol", "the id is still ownable");

package/dist/core/stub-env.d.ts

@@ -14,6 +14,8 @@ export declare class StubExecutionEnv implements ExecutionEnv {
     readonly externalContentTarget?: boolean;
     /** `ExecutionEnv.cdPath`: the stub runs no shell, so no shell receives a `CDPATH`. */
     readonly cdPath: readonly string[];
+    /** `ExecutionEnv.withheldEnv`: no shell child, so nothing is withheld from one. */
+    readonly withheldEnv: readonly [];
     constructor(cwd?: string);
     private fsErr;
     absolutePath(path: string): Promise<Result<string, FileError>>;

package/dist/core/stub-env.js

@@ -3,6 +3,7 @@ export class StubExecutionEnv {
     cwd;
     externalContentTarget;
     cdPath = [];
+    withheldEnv = [];
     constructor(cwd = "/") {
         this.cwd = cwd;
     }

package/dist/core/synthetic-read-verdict.js

@@ -134,7 +134,7 @@ function createProbeJudge(layers, kind) {
             }
             let read;
             try {
-                read = refuseOutOfContractDecision(d);
+                read = refuseOutOfContractDecision(d, { call: req });
             }
             catch (err) {
                 cannot(layer, "threw", describeThrown(err));
@@ -144,7 +144,7 @@ function createProbeJudge(layers, kind) {
                 cannot(layer, "rewritten", "the layer would rewrite the call's arguments, so its answer is not about this call");
             }
             if (read.action === "ask") {
-                ask(layer, read.message, ancestorOwned || ruleClearanceOf(ownedClearanceFacts(read), {}).mandated);
+                ask(layer, read.message, ancestorOwned || ruleClearanceOf(ownedClearanceFacts(read, req), {}).mandated);
                 return undefined;
             }
             if (read.action !== "deny")
@@ -182,7 +182,7 @@ function createProbeJudge(layers, kind) {
         }
         if (layers.persistedRuleLane !== undefined && !spent("persisted_rules")) {
             const read = await readPersistedRuleLane(layers.persistedRuleLane, req, layers.signal, left());
-            const tightened = applyPersistedTightening({ action: "allow" }, read).tightened;
+            const tightened = applyPersistedTightening({ action: "allow" }, read, req).tightened;
             if (tightened === "deny")
                 return { verdict: "deny", layer: "persisted_rules", ...judged };
             if (tightened === "ask")

package/dist/core/task-event.d.ts

@@ -269,6 +269,15 @@ export type HumanInputDelivery = "applied" | "queued" | "parked_for_wake" | "blo
  * re-listing is what keeps the two faces from drifting into two vocabularies.
  */
 export type DelegationTaskType = Extract<TaskNotificationPayload["task_type"], "background_agent" | "workflow">;
+/**
+ * Who asked for a tool call no model message carried: an extension's own call (`$.tool.call`), by its registration name.
+ * A display and audit fact only — the call runs under the run's principal, rules, mode and approver, and the name decides
+ * nothing. Carried by the call's `tool_start` / `tool_end` and by the approval card an ask for it puts to the person.
+ */
+export interface ExtensionRequester {
+    readonly kind: "extension";
+    readonly name: string;
+}
 /** Streaming events surfaced from a running task (for live UIs). */
 export type TaskEvent = ({
     type: "text_delta";
@@ -282,9 +291,12 @@ export type TaskEvent = ({
      * the provider's `content_block_stop`), and this event is that same boundary surfaced on the TaskEvent
      * wire.
      *
-     * `content` = the authoritative FULL text of the completed segment (byte-equal to that
-     * segment's accumulated deltas, from the brain's own accumulation) — a consumer commits the
-     * segment from it instead of trusting its own delta stitching. UNTRUSTED model output for
+     * `content` = the FULL text of the completed segment as the brain closed it — a consumer commits
+     * the segment from it instead of trusting its own delta stitching. It is not a promise about the
+     * committed message: when the turn finalizes the brain may still trim a degenerate cut's looped tail,
+     * add engine notes as blocks of their own, or (opt-in) rewrite text it read as tool calls. The final
+     * answer's one authority is `TaskResult.result`, and `TaskResult.resultEntryIds` names the committed
+     * messages it was read from. UNTRUSTED model output for
      * display only, same contract as `text_delta`. Emitted only for a segment that holds bytes: an
      * empty text block closes silently (a boundary with no segment would render phantom rows).
      *
@@ -315,6 +327,9 @@ export type TaskEvent = ({
      * ran is the paired `tool_end.notExecuted`); absent on every start the loop announced itself.
      */
     recovered?: true;
+    /** An extension's own call (`$.tool.call`): who asked for it. Absent on every call a model message carried. The call is
+     *  not part of the conversation — no tool-result message follows it into the transcript. */
+    requestedBy?: ExtensionRequester;
 } & TaskEventIdentity) | ({
     /**
      * A LIVENESS TICK for a tool call that is still running. Emitted on the run's own queue between this
@@ -564,8 +579,18 @@ export type TaskEvent = ({
      * ABSENT means only that no such evidence exists — never "it ran": a call closed with its outcome unknown
      * (a reconcile at the next process start, a call interrupted mid-execution) carries no mark, because
      * telling a consumer it did not run could invite a replay of a write that already took effect.
+     * One more source of that evidence: an extension at `tool.call` answered for the call in place of its body (its own
+     * result, or its refusal) — the body was never called; {@link answeredBy} names it.
      */
     notExecuted?: true;
+    /**
+     * The extension (its registration name) that answered for this call at `tool.call` in place of the tool's body — a
+     * result of its own, or a refusal — so the body never ran (`notExecuted` is set beside it). Absent on every call
+     * whose body ran or that no extension answered.
+     */
+    answeredBy?: string;
+    /** The same member as the paired `tool_start`'s: an extension's own call, and who asked for it. */
+    requestedBy?: ExtensionRequester;
     /**
      * design/99 §E1 — `true` exactly when {@link output} is not the content the tool returned: text was cut at the cap
      * (the string, or the block at the cut, carries the marker; the stream's later blocks left), a media block was
@@ -831,6 +856,9 @@ export type TaskEvent = ({
      * on the model lane). [c209-C]: the listing family's FIRST-FRAME deliveries (initial roster /
      * `<skills>` block riding the first user message, not a steer) emit the same echo frames.
      *
+     * `mcp_unavailable`: the declared MCP servers that did not connect for this message — echoed where the notice rides
+     * (a fresh leg's first user message; a resumed leg's continuation). It used to ride `tools_delta`.
+     *
      * `git_status` (env-tail migration, additive member): the git-status frame — the turn-dynamic
      * git facts' carrier since they left the system prompt. Emitted at the frame's append RECEIPT
      * (first-frame / resume-continuation / compaction re-assert deliveries alike). Its `preview`
@@ -843,7 +871,7 @@ export type TaskEvent = ({
      * echo; the retired `plan_mode` member was the echo of the opt-in planning reminder they replaced.
      */
     type: "steering_injected";
-    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "output_style" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "total_tokens_reminder" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
+    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "output_style" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "total_tokens_reminder" | "background_tasks" | "tools_delta" | "mcp_unavailable" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
     preview: string;
 } & TaskEventIdentity) | ({
     /**