@sema-agent/core 7.54.1 → 7.55.0

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

@@ -4,7 +4,6 @@ import { 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";
-import { registerSessionIncarnationCases } from "./session-store-incarnation-contract.js";
 const AT = "2026-10-18T00:00:00.000Z";
 const AT_MS = Date.parse(AT);
 const STAMP = { api: "openai-completions", provider: "contract-kit", model: "contract-kit-model" };
@@ -12,9 +11,9 @@ const ZERO_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalToke
 function userEntry(id, parentId, text = `t-${id}`) {
     return { id, parentId, type: "message", timestamp: AT, message: { role: "user", content: [{ type: "text", text }], timestamp: AT_MS } };
 }
-function assistantEntry(id, parentId, toolCall) {
-    const content = toolCall !== undefined ? [{ type: "toolCall", id: toolCall, name: "Read", arguments: { file_path: "/kit/x" } }] : [{ type: "text", text: `a-${id}` }];
-    return { id, parentId, type: "message", timestamp: AT, message: { role: "assistant", content, ...STAMP, usage: ZERO_USAGE, stopReason: toolCall !== undefined ? "toolUse" : "stop", timestamp: AT_MS } };
+function assistantEntry(id, parentId, ...toolCalls) {
+    const content = toolCalls.length > 0 ? toolCalls.map((call) => ({ type: "toolCall", id: call, name: "Read", arguments: { file_path: "/kit/x" } })) : [{ type: "text", text: `a-${id}` }];
+    return { id, parentId, type: "message", timestamp: AT, message: { role: "assistant", content, ...STAMP, usage: ZERO_USAGE, stopReason: toolCalls.length > 0 ? "toolUse" : "stop", timestamp: AT_MS } };
 }
 function toolResultEntry(id, parentId, toolCallId) {
     return { id, parentId, type: "message", timestamp: AT, message: { role: "toolResult", toolCallId, toolName: "Read", content: [{ type: "text", text: "ok" }], isError: false, timestamp: AT_MS } };
@@ -89,8 +88,22 @@ function assertNewestFirst(rows) {
 function registerUntyped(store, sessionId, owner) {
     return Reflect.apply(store.register, store, [sessionId, owner]);
 }
-const hasOwnership = (s) => typeof s.ownerOf === "function" && typeof s.register === "function";
+const hasHead = (s) => typeof s.headOf === "function";
+const hasOwnership = (s) => hasHead(s) && typeof s.register === "function";
 const declaresPlacements = (s) => s.placements?.subagent !== undefined;
+const headOf = (store, sessionId) => store.headOf(sessionId);
+async function ownerOf(store, sessionId, what) {
+    const head = await headOf(store, sessionId);
+    assert.ok(head !== undefined, `${what}: the row exists, so headOf must answer it`);
+    return head.owner;
+}
+async function tokenOf(store, sessionId, what) {
+    const head = await headOf(store, sessionId);
+    assert.ok(head !== undefined, `${what}: the row exists, so headOf must answer it`);
+    assert.equal(typeof head.incarnation, "string", `${what}: a session row created through this store must carry an incarnation`);
+    assert.notEqual(head.incarnation, "", `${what}: an empty token names nobody`);
+    return head.incarnation;
+}
 async function honorsRequireExisting(store) {
     const probe = freshId();
     await store.acquire(probe);
@@ -165,8 +178,8 @@ async function runSessionStoreContract(make, hooks) {
         noteTaskRun: (s) => typeof s.noteTaskRun === "function",
         listPlaced: (s) => declaresPlacements(s) && typeof s.listPlaced === "function",
         placements: declaresPlacements,
+        headOf: hasHead,
         ownership: hasOwnership,
-        incarnationOf: (s) => typeof s.incarnationOf === "function",
         replica: () => hooks.replica !== undefined,
     };
     const faceRun = (name, needs, fn) => run(name, async (store, open) => {
@@ -214,8 +227,8 @@ async function runSessionStoreContract(make, hooks) {
         }
         if (typeof store.list === "function")
             assert.equal(rowOf(await store.list(), id), undefined, "the refused acquire must not surface on the session list");
-        if (typeof store.incarnationOf === "function")
-            assert.equal(await store.incarnationOf(id), undefined, "nor have a row");
+        if (hasHead(store))
+            assert.equal(await headOf(store, id), undefined, "nor have a row");
         report("requireExisting", honored ? "verified" : "absent");
     });
     run("[acquire] two concurrent acquires of one id are one session: one log, and the second write on the same parent loses the CAS", async (store) => {
@@ -438,10 +451,10 @@ async function runSessionStoreContract(make, hooks) {
         assert.equal(await store.fork(missing), null);
         if (await honorsRequireExisting(store))
             await rejectsWithCode(() => store.acquire(missing, { requireExisting: true }), "not_found", "a fork of a missing source must not create it");
-        if (typeof store.incarnationOf === "function")
-            assert.equal(await store.incarnationOf(missing), undefined, "a fork of a missing source must not create it");
+        if (hasHead(store))
+            assert.equal(await headOf(store, missing), undefined, "a fork of a missing source must not create it");
     });
-    faceRun("[fork] a fork never inherits an in-flight assistant turn: a leaf turn whose tool call has no result yet (with or without sibling results already in) is left out", ["fork"], async (store) => {
+    faceRun("[fork] a fork never inherits an in-flight assistant turn: a turn with a tool call no result answers yet (with or without sibling results already in) is left out; a turn every call of which is answered is kept", ["fork"], async (store) => {
         const parallel = freshId();
         const p = (await store.acquire(parallel)).session;
         await append(p, userEntry("u1", null));
@@ -451,10 +464,18 @@ async function runSessionStoreContract(make, hooks) {
         const sequential = freshId();
         const q = (await store.acquire(sequential)).session;
         await append(q, userEntry("u1", null));
-        await append(q, assistantEntry("a1", "u1", "call-1"));
+        await append(q, assistantEntry("a1", "u1", "call-1", "call-2"));
         await append(q, toolResultEntry("r1", "a1", "call-1"));
         const qf = await store.fork(sequential);
-        assert.deepEqual(await pathIds((await readBack(store, qf))), ["u1"], "a sibling call's committed result does not settle the turn");
+        assert.deepEqual(await pathIds((await readBack(store, qf))), ["u1"], "a sibling call's committed result does not settle the turn: call-2 has none");
+        const answered = freshId();
+        const t = (await store.acquire(answered)).session;
+        await append(t, userEntry("u1", null));
+        await append(t, assistantEntry("a1", "u1", "call-1", "call-2"));
+        await append(t, toolResultEntry("r1", "a1", "call-2"));
+        await append(t, toolResultEntry("r2", "r1", "call-1"));
+        const tf = await store.fork(answered);
+        assert.deepEqual(await pathIds((await readBack(store, tf))), ["u1", "a1", "r1", "r2"], "a tool turn every call of which has its result is settled: a fork keeps it");
         const settled = freshId();
         const s = (await store.acquire(settled)).session;
         await append(s, userEntry("u1", null));
@@ -620,64 +641,217 @@ async function runSessionStoreContract(make, hooks) {
         assert.ok(scoped.includes(complete) && scoped.includes(incomplete) && !scoped.includes(elsewhere), "scope narrows to one tenant");
         assert.ok(!(await store.listPlaced("subagent", { olderThanMs: 60 * 60 * 1000 })).some((r) => r.sessionId === complete), "a session placed just now is not an hour old");
     });
-    faceRun("[ownership] ownerOf answers three states that never collapse: an id never registered ⇒ undefined, anonymous ⇒ null, owned ⇒ the owner", ["ownership"], async (store) => {
-        const [unknown, owned, anonymous] = [freshId(), freshId(), freshId()];
-        assert.equal(await store.ownerOf(unknown), undefined, "no ownership row ⇒ undefined, never null");
+    faceRun("[head] headOf answers undefined for an id with no row; for a row, its owner, its occupant and its active leaf — the leaf follows appends and a branch switch", ["headOf"], async (store) => {
+        const id = freshId();
+        assert.equal(await headOf(store, id), undefined, "no row ⇒ undefined");
+        const { session } = await store.acquire(id);
+        assert.deepEqual(await headOf(store, id), { owner: null, incarnation: (await session.getMetadata()).incarnation, leafId: null }, "a row acquire created: no owner, its occupant, no leaf");
+        await append(session, userEntry("e1", null));
+        await append(session, assistantEntry("e2", "e1"));
+        assert.equal((await headOf(store, id))?.leafId, "e2", "an append moves the head's leaf");
+        await session.getStorage().setLeafId("e1");
+        assert.equal((await headOf(store, id))?.leafId, "e1", "a branch switch moves it back");
+        await session.getStorage().setLeafId(null);
+        assert.equal((await headOf(store, id))?.leafId, null);
+    });
+    faceRun("[head] the head lives in the row: a store reopened over the same rows (a restart) answers the same owner, occupant and leaf", ["headOf"], async (store, open) => {
+        const id = freshId();
+        const { session } = await store.acquire(id);
+        await append(session, userEntry("e1", null));
+        await append(session, assistantEntry("e2", "e1"));
+        await session.getStorage().setLeafId("e1");
+        const before = await headOf(store, id);
+        const second = await open(hooks.reopen(store));
+        assert.deepEqual(await headOf(second, id), before, "a head an instance kept for itself would answer differently after every restart");
+    });
+    faceRun("[head] one read, one generation: while an id is deleted and created again under other owners, no head pairs one generation's owner with another's occupant", ["ownership"], async (store) => {
+        const id = freshId();
+        const generations = [];
+        const reads = [];
+        const probe = () => {
+            for (let k = 0; k < 3; k++)
+                reads.push(headOf(store, id));
+        };
+        for (let i = 0; i < 12; i++) {
+            if (i > 0) {
+                probe();
+                await hooks.deleteSession(store, id);
+            }
+            probe();
+            await store.register(id, `kit-gen-${i}`);
+            probe();
+            await store.acquire(id);
+            generations.push((await headOf(store, id)));
+        }
+        const whole = new Set(generations.map((g) => `${g.owner}|${g.incarnation}`));
+        assert.equal(whole.size, generations.length, "each generation is its own owner and occupant");
+        for (const head of await Promise.all(reads)) {
+            if (head === undefined)
+                continue;
+            assert.ok(whole.has(`${head.owner}|${head.incarnation}`), `a head read ${head.owner} with occupant ${head.incarnation}, a pair no generation of the row ever held`);
+        }
+    });
+    faceRun("[ownership] register on an id with no row creates its row recording the owner — a string, or null for anonymous; a row acquire created records null", ["ownership"], async (store) => {
+        const [owned, anonymous, acquired] = [freshId(), freshId(), freshId()];
         await store.register(owned, "kit-alice");
         await store.register(anonymous, null);
-        assert.equal(await store.ownerOf(owned), "kit-alice");
-        assert.equal(await store.ownerOf(anonymous), null, "an anonymous row ⇒ null, never undefined");
-    });
-    faceRun("[ownership] register is first-write-wins: later calls neither overwrite nor throw, whatever they carry", ["ownership"], async (store) => {
-        const [owned, anonymous] = [freshId(), freshId()];
+        await store.acquire(acquired);
+        assert.equal(await ownerOf(store, owned, "a registered id"), "kit-alice");
+        assert.equal(await ownerOf(store, anonymous, "an anonymous registration"), null);
+        assert.equal(await ownerOf(store, acquired, "a row acquire created"), null, "acquire names no owner");
+        const token = await tokenOf(store, owned, "a registered row");
+        assert.equal((await (await readBack(store, owned)).getMetadata()).incarnation, token, "the registered row is the session acquire then hands out");
+    });
+    faceRun("[ownership] register on a row that exists does nothing, whatever it carries — an owned row, an anonymous row, a row acquire created, a placed row", ["ownership"], async (store) => {
+        const [owned, anonymous, acquired] = [freshId(), freshId(), freshId()];
         await store.register(owned, "kit-alice");
         await store.register(owned, "kit-bob");
         await store.register(owned, null);
         await registerUntyped(store, owned, undefined);
-        assert.equal(await store.ownerOf(owned), "kit-alice");
+        assert.equal(await ownerOf(store, owned, "an owned row"), "kit-alice");
         await store.register(anonymous, null);
         await store.register(anonymous, "kit-bob");
-        assert.equal(await store.ownerOf(anonymous), null, "an anonymous row is not claimable by a later register");
+        assert.equal(await ownerOf(store, anonymous, "an anonymous row"), null, "an anonymous row is not claimable by a later register");
+        await store.acquire(acquired);
+        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");
+        }
     });
     faceRun("[ownership] a FIRST register whose owner is neither a string nor null is refused loudly and leaves no row behind", ["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");
-        assert.equal(await store.ownerOf(id), undefined, "the refused writes stored nothing");
+        assert.equal(await headOf(store, id), undefined, "the refused writes stored nothing");
         await store.register(id, "kit-carol");
-        assert.equal(await store.ownerOf(id), "kit-carol", "the id is still ownable — no row that reads as 'no row' was minted");
+        assert.equal(await ownerOf(store, id, "the first well-formed register"), "kit-carol", "the id is still ownable");
     });
     faceRun("[ownership] two concurrent first registers: each caller's own re-read sees the same winner, one of the two", ["ownership"], async (store) => {
         const id = freshId();
         const caller = async (owner) => {
             await store.register(id, owner);
-            return store.ownerOf(id);
+            return ownerOf(store, id, "after a register");
         };
         const [x, y] = await Promise.all([caller("kit-x"), caller("kit-y")]);
         assert.equal(x, y, "the loser must see the winner on its own re-read, or both callers attach to one session");
         assert.ok(x === "kit-x" || x === "kit-y");
-        assert.equal(await store.ownerOf(id), x, "and the row keeps that winner");
+        assert.equal(await ownerOf(store, id, "the settled row"), x, "and the row keeps that winner");
     });
-    faceRun("[ownership] the ownership row outlives the cached view: a registered session that is forgotten still reads its owner", ["ownership", "forget"], async (store) => {
-        const id = freshId();
-        await store.register(id, "kit-alice");
-        await append((await store.acquire(id)).session, userEntry("e1", null));
-        await store.forget(id);
-        assert.equal(await store.ownerOf(id), "kit-alice", "a live session reading undefined would be re-claimable by anyone");
+    faceRun("[ownership] the owner is a cell of the row: it reads back after the cached view is dropped and on a store reopened over the same rows (a restart)", ["ownership"], async (store, open) => {
+        const [owned, acquired] = [freshId(), freshId()];
+        await store.register(owned, "kit-alice");
+        await append((await store.acquire(owned)).session, userEntry("e1", null));
+        await store.acquire(acquired);
+        if (typeof store.forget === "function") {
+            await store.forget(owned);
+            assert.equal(await ownerOf(store, owned, "a forgotten session"), "kit-alice", "a live session must never lose its owner with the cached view");
+        }
+        const second = await open(hooks.reopen(store));
+        assert.equal(await ownerOf(second, owned, "after a restart"), "kit-alice", "an owner an instance kept for itself is lost on every restart, and the session is then anyone's");
+        assert.equal(await ownerOf(second, acquired, "after a restart"), null);
+        await second.register(owned, "kit-bob");
+        assert.equal(await ownerOf(second, owned, "a register after a restart"), "kit-alice", "a restart opens no claiming window");
     });
-    faceRun("[ownership] a fork's ownership agrees with its source: no owner or null ⇒ the source's (an owned copy is never downgraded), an explicit owner ⇒ that owner, an anonymous source ⇒ anonymous", ["ownership", "fork"], async (store) => {
+    faceRun("[ownership] a fork records its owner in its own row: no owner or null ⇒ the source's (an owned copy is never downgraded), an explicit owner ⇒ that owner, an anonymous source ⇒ anonymous", ["ownership", "fork"], async (store) => {
         const owned = freshId();
         await store.register(owned, "kit-alice");
         await append((await store.acquire(owned)).session, userEntry("e1", null));
-        assert.equal(await store.ownerOf((await store.fork(owned))), "kit-alice", "no owner argument ⇒ the source's owner");
-        assert.equal(await store.ownerOf((await store.fork(owned, null))), "kit-alice", "an explicit null never downgrades a copy of an owned history to anonymous");
-        assert.equal(await store.ownerOf((await store.fork(owned, "kit-bob"))), "kit-bob", "an explicit owner scopes the fork");
+        assert.equal(await ownerOf(store, (await store.fork(owned)), "a fork"), "kit-alice", "no owner argument ⇒ the source's owner");
+        assert.equal(await ownerOf(store, (await store.fork(owned, null)), "a fork"), "kit-alice", "an explicit null never downgrades a copy of an owned history to anonymous");
+        assert.equal(await ownerOf(store, (await store.fork(owned, "kit-bob")), "a fork"), "kit-bob", "an explicit owner scopes the fork");
         const anonymous = freshId();
-        await store.register(anonymous, null);
         await append((await store.acquire(anonymous)).session, userEntry("e1", null));
-        assert.equal(await store.ownerOf((await store.fork(anonymous))), null);
-        assert.equal(await store.ownerOf((await store.fork(anonymous, null))), null);
+        assert.equal(await ownerOf(store, (await store.fork(anonymous)), "a fork"), null);
+        assert.equal(await ownerOf(store, (await store.fork(anonymous, null)), "a fork"), null);
+    });
+    faceRun("[ownership] an id registered first is an ordinary row: a placement-carrying acquire of it is refused placement_refused", ["ownership", "placements"], async (store) => {
+        const id = freshId();
+        await store.register(id, "kit-alice");
+        await rejectsWithCode(() => store.acquire(id, { placement: placementFor() }), "placement_refused", "a placed creation onto an id a register already created");
+        assert.equal(await ownerOf(store, id, "the registered row"), "kit-alice", "the refused acquire rewrote nothing");
+    });
+    faceRun("[ownership] acquire serves only the occupant the row holds: after another instance deleted the row and registered the id to another owner, this instance's next acquire serves the new occupant, never its cached view of the old one", ["ownership", "replica"], async (store, open) => {
+        const id = freshId();
+        const other = await open(hooks.replica(store));
+        await store.register(id, "kit-alice");
+        await append((await store.acquire(id)).session, userEntry("alice-only", null));
+        await other.acquire(id);
+        await hooks.deleteSession(other, id);
+        await other.register(id, "kit-bob");
+        const head = await headOf(store, id);
+        assert.equal(head?.owner, "kit-bob", "this instance's head reads the row");
+        const served = (await store.acquire(id)).session;
+        assert.equal((await served.getMetadata()).incarnation, head?.incarnation, "the session handed out is the row the owner was read from");
+        assert.deepEqual(await entryIds(served), [], "the previous occupant's transcript is not served under the new owner");
+    });
+    faceRun("[ownership] the metadata a session hands out is not the row: writing to it changes no owner or occupant the head answers", ["ownership"], async (store) => {
+        const id = freshId();
+        await store.register(id, "kit-alice");
+        const before = await headOf(store, id);
+        try {
+            Object.assign(await (await store.acquire(id)).session.getMetadata(), { owner: null, incarnation: "kit-forged" });
+        }
+        catch {
+        }
+        assert.deepEqual(await headOf(store, id), before, "admission changes only through a write of the row");
+    });
+    faceRun("[incarnation] a session created through acquire carries a token, and every later read of the row answers the same one", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        await store.acquire(id);
+        const first = await tokenOf(store, id, "after acquire");
+        await store.acquire(id);
+        assert.equal(await tokenOf(store, id, "a re-acquire"), first, "a re-acquire reopens the same occupant");
+        await store.forget?.(id);
+        assert.equal(await tokenOf(store, id, "after forget"), first, "the token is the row's, not the cache's: forgetting the cached view must not change it");
+        await store.acquire(id, { requireExisting: true });
+        assert.equal(await tokenOf(store, id, "a require-existing reopen"), first, "a require-existing reopen after the cache forgot it is still the same occupant");
+    });
+    faceRun("[incarnation] the session acquire hands back carries the token headOf answers — a run's memory seat reads the former", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        const acquired = await store.acquire(id);
+        const byId = await tokenOf(store, id, "by-id read");
+        assert.equal((await acquired.session.getMetadata()).incarnation, byId, "two faces of one row cell must agree, or the seat and the by-id read name two occupants");
+    });
+    faceRun("[incarnation] a second store over the same rows (a restart, a replica) answers the same token — the token lives in the row, not in an instance", ["headOf", "requireExisting"], async (store, open) => {
+        const id = freshId();
+        await store.acquire(id);
+        const first = await tokenOf(store, id, "first instance");
+        const second = await open(hooks.reopen(store));
+        assert.equal(await tokenOf(second, id, "second instance"), first, "an instance-local token would name a different occupant after every restart");
+        await second.acquire(id, { requireExisting: true });
+        assert.equal(await tokenOf(second, id, "reopened on the second instance"), first, "reopening the session on the second instance is still the same occupant");
+    });
+    faceRun("[incarnation] two sessions never share a token, and an id with no session has no head (unknown — not an error, not a token)", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        await store.acquire(id);
+        const generated = await store.acquire();
+        const a = await tokenOf(store, id, "explicit id");
+        const g = await tokenOf(store, generated.sessionId, "generated id");
+        assert.notEqual(a, g, "two sessions are two occupants");
+        assert.equal(await headOf(store, freshId()), undefined, "no row ⇒ unknown");
+    });
+    faceRun("[incarnation] a deleted id handed out again is a NEW occupant: a fresh token, never the previous occupant's", ["headOf", "requireExisting"], async (store) => {
+        const id = freshId();
+        await store.acquire(id);
+        const before = await tokenOf(store, id, "first occupant");
+        await hooks.deleteSession(store, id);
+        assert.equal(await headOf(store, id), undefined, "a deleted row has no occupant");
+        await store.acquire(id);
+        const after = await tokenOf(store, id, "second occupant");
+        assert.notEqual(after, before, "the id was recycled — the previous occupant's records must not bind this one");
+    });
+    faceRun("[incarnation] a fork is a new occupant: a fresh token, and the source keeps its own", ["headOf", "requireExisting", "fork"], async (store) => {
+        const src = freshId();
+        await store.acquire(src);
+        const source = await tokenOf(store, src, "fork source");
+        const forkedId = await store.fork(src);
+        assert.ok(forkedId !== null, "forking an existing session returns the fork's id");
+        assert.notEqual(await tokenOf(store, forkedId, "fork"), source, "a fork copies the history, never the occupant");
+        assert.equal(await tokenOf(store, src, "fork source after"), source, "forking does not touch the source's occupant");
     });
-    registerSessionIncarnationCases((name, fn) => faceRun(`[incarnation] ${name}`, ["incarnationOf", "requireExisting"], (store) => fn(store)), hooks);
     await settle();
 }

package/dist/core/store-contracts/workflow-journal-store-contract.js

@@ -1,5 +1,5 @@
 import { strict as assert } from "node:assert";
-import { JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES, } from "../workflow-journal-store.js";
+import { JOURNAL_INCOMPATIBLE_ERROR_CODE, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES, } from "../workflow-journal-store.js";
 import { beginContract } from "./contract-harness.js";
 const key = (ordinal) => `${ordinal}:h`;
 const completed = (ordinal, over = {}) => ({
@@ -22,6 +22,7 @@ const parked = (ordinal, over = {}) => ({
 });
 const OVER_CAP = "x".repeat(MAX_JOURNAL_RESULT_BYTES + 1024);
 const isOversizeRefusal = (e) => e instanceof Error && e.code === JOURNAL_OVERSIZE_ERROR_CODE;
+const isIncompatibleRefusal = (e) => e instanceof Error && e.code === JOURNAL_INCOMPATIBLE_ERROR_CODE;
 export async function workflowJournalStoreContract(make, runAssertion) {
     const { run, settle } = beginContract(runAssertion);
     run("append → load returns entries ASCENDING by ordinal, both arms verbatim; a re-append per ordinal OVERWRITES", async () => {
@@ -64,6 +65,30 @@ export async function workflowJournalStoreContract(make, runAssertion) {
         await store.append("run-1", "tenant-a", { callKey: key(1), parked: parked(1) });
         assert.equal((await store.load("run-1", "tenant-a"))[1].parked?.terminal.kind, "paused");
     });
+    run("a PARKED row whose payload is not a paused result is refused — at append, or by the whole load — never read back as an entry, never dropped", async () => {
+        const bad = [
+            ["terminal completed", { ...parked(1), terminal: { kind: "completed" } }],
+            ["paused terminal without a checkpoint token", { ...parked(1), terminal: { kind: "paused", gate: { kind: "human", reason: "approve", toolName: "Write" } } }],
+            ["parked arm a string", "paused"],
+        ];
+        for (const [what, payload] of bad) {
+            const store = make();
+            await store.append("run-1", "tenant-a", { callKey: key(0), result: completed(0) });
+            let appended = true;
+            try {
+                await store.append("run-1", "tenant-a", { callKey: key(1), parked: payload });
+            }
+            catch {
+                appended = false;
+            }
+            if (appended) {
+                await assert.rejects(store.load("run-1", "tenant-a"), isIncompatibleRefusal, `${what}: the row was journaled, so the load must refuse — with code "${JOURNAL_INCOMPATIBLE_ERROR_CODE}" — rather than answer around it`);
+            }
+            else {
+                assert.deepEqual((await store.load("run-1", "tenant-a")).map((e) => e.callKey), [key(0)], `${what}: an append that refused must have journaled nothing`);
+            }
+        }
+    });
     run("the cap is inclusive: a payload of EXACTLY the cap's byte count is accepted on both arms", async () => {
         const store = make();
         const fit = (payload) => {

package/dist/core/surrogate-safe-slice.d.ts

@@ -9,7 +9,7 @@
  * same defect has been found and fixed one site at a time (RB-122 in `clipWithFilePointer`, then
  * `truncateError`, then the three siblings above), which is exactly the shape a shared primitive prevents.
  *
- * Anchored on CC 2.1.220 `A7e`'s helpers `ma` (head) / `_W` (tail): drop the straddling code point WHOLE
+ * Head / tail helpers: drop the straddling code point WHOLE
  * rather than emit half of it. Zero imports, so any module in the repo may depend on it without risking an
  * import cycle.
  *
@@ -25,7 +25,7 @@ export declare const isHighSurrogate: (c: number) => boolean;
 export declare const isLowSurrogate: (c: number) => boolean;
 /**
  * Head-keep of at most `keep` code UNITS that never ends on a lone high surrogate — a code point straddling
- * the cut is dropped whole (CC 2.1.220 `ma`).
+ * the cut is dropped whole.
  *
  * Callers must derive any "how much was dropped" count from the RETURNED length, never from `keep`: when
  * the rollback fires the result is one unit SHORTER than the budget, and a count computed from `keep`
@@ -33,7 +33,7 @@ export declare const isLowSurrogate: (c: number) => boolean;
  */
 export declare function sliceHeadSafe(s: string, keep: number): string;
 /**
- * Tail-keep counterpart: at most `keep` code units, never STARTING on a lone low surrogate (CC 2.1.220
+ * Tail-keep counterpart: at most `keep` code units, never STARTING on a lone low surrogate (the reference's
  * `_W`). Same rule for the caller's dropped-count arithmetic — read it off the returned length.
  */
 export declare function sliceTailSafe(s: string, keep: number): string;

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

@@ -322,7 +322,7 @@ export type TaskEvent = ({
      * forwarded to a parent's display sink under the SAME opt-in as those two
      * (`TaskSpec.forwardSubagentEvents`).
      *
-     * ONE FRAME, not two: CC 2.1.259 splits this into a per-tool `tool_heartbeat` plus Bash's own
+     * ONE FRAME, not two: the reference splits this into a per-tool `tool_heartbeat` plus Bash's own
      * `bash_progress`; this engine mints the single shape and lets the OUTPUT KEYS be what is conditional.
      * Registered divergence.
      *
@@ -413,7 +413,7 @@ export type TaskEvent = ({
      * document/worktree/todo/task/task-list/task-output/task-stop/agent/fork/workflow-run/web-fetch/
      * web-search/cron-create/cron-delete/cron-list/tool-search/repo-map/monitor-start/
      * enter-plan-mode/exit-plan-mode/report-findings/schedule-wakeup/send-message/agent-transcript/
-     * a2a/path_not_in_root/readonly_out_of_root/read_unestablished), surfaced on the live wire so a CC-faithful shell
+     * a2a/path_not_in_root/readonly_out_of_root/read_unestablished/advisor), surfaced on the live wire so a CC-faithful shell
      * renders rich cards (red/green diff, stdout panes, file cards) without re-parsing the
      * model-facing string. Absent when the tool carries no card shape or when the serialized card
      * exceeds the size bound (omitted whole; a consumer falls back to `output`).
@@ -427,13 +427,19 @@ export type TaskEvent = ({
      * memory-saved / memory-recall, three words with no producer anywhere in core (a batch MultiEdit
      * replay mints `type:"edit"` with an `edits[]` array; core mounts no memory tool at all).
      *
+     * The **advisor** card (`type:"advisor"`, the advisor tool's every call) carries closed words, numbers and catalog ids
+     * only — `outcome` (`reviewed` / `declined` / `unavailable`, and `isError` ⇔ `unavailable`), `model`, `servedModel?`,
+     * `stopReason?`, `code?` / `errorKind?` (the failure's own words), `hold?: true` (this failure's cause switches the
+     * advisor off for the conversation until it is compacted — a classification, not a promise: the transcript says so once
+     * the result is recorded) and `usage?`. The guidance, a refusal's reason and an error's message ride {@link output}.
+     *
      * **Leak boundary**: the allowlist gates by `type`, so what rides is whatever the minting tool put
      * in the object — which makes each mint site responsible for its own field set. The Agent family's
      * completed card is therefore built from an EXPLICIT whitelist rather than a child-`TaskResult`
      * spread: a `TaskResult` can carry `checkpointToken` (the resume CAPABILITY) on the
      * `unexpected.suspended` terminal, and that field, with `checkpointGate`, never leaves the process.
      *
-     * **双面契约(CC 2.1.207 @765495 成文,`tool_use_result` describe;CC207-CORE-SWEEP P2-3)** — a tool
+     * **双面契约(`tool_use_result` describe;P2-3)** — a tool
      * result has TWO faces that never substitute for each other:
      * - **模型面** = {@link output} / the tool_result text: the string the MODEL reads. It may carry
      *   model-directed framing — e.g. a delegation tool's trailer (agentId / usage lines the model uses to
@@ -841,7 +847,7 @@ export type TaskEvent = ({
     preview: string;
 } & TaskEventIdentity) | ({
     /**
-     * design/121 (CC 198 `<new-diagnostics>` parity): NEW LSP diagnostics that appeared after the
+     * design/121 (`<new-diagnostics>`): NEW LSP diagnostics that appeared after the
      * agent's edits, drained at a turn boundary. The SAME data was injected into the model as a
      * `<new-diagnostics>` context message; this frame is the shell's render source (CC's collapsed
      * `Found N new diagnostic issues in M files (ctrl+o to expand)` row). UNTRUSTED RAW (language-

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

@@ -26,7 +26,7 @@ export declare function isNotificationInjectionOutcome(value: unknown): value is
 export type NotificationDisposition = Exclude<NotificationInjectionOutcome, "dropped_duplicate">;
 /** The closed value set of {@link SystemInjectionPriority}, as data — the wire-facing entries validate
  *  against THIS rather than against three inline string literals, so widening the type widens the guard.
- *  (Names taken verbatim from CC 2.1.223's `UYo` @ `CC:644918`; see the semantics note on
+ *  (Names taken from the reference; see the semantics note on
  *  {@link SystemInjection.priority} for which of CC's behaviors this engine implements.) */
 export declare const SYSTEM_INJECTION_PRIORITIES: readonly SystemInjectionPriority[];
 /** backlog #389 伴生 (D-3, bad-value loudness) — is this a priority this engine knows at all? A value
@@ -327,8 +327,8 @@ export interface ExternalNotificationInput {
 export interface SystemInjection<TPayload = unknown> {
     kind: "task_notification";
     /**
-     * design/373 — the injection ladder is LIVE (all three values carry delivery semantics, the CC
-     * 2.1.223 form; the flat "every priority delivers at the next boundary" era ended with this
+     * design/373 — the injection ladder is LIVE (all three values carry delivery semantics, the reference's
+     * form; the flat "every priority delivers at the next boundary" era ended with this
      * design — its H-1 anchor-correction note is preserved in the design archive, and the ruled
      * changes it named are exactly what landed here):
      *

package/dist/core/task-registry-agent.d.ts

@@ -282,12 +282,12 @@ export declare function abortBackgroundAgentsForOwnerLane(core: DurableAgentCore
     skipSessionScoped?: boolean;
     sessionScopedOnly?: boolean;
 }): number;
-/** CC206-B name resolution over the caller-visible background_agent rows (CC `cgo`/`gvy`, 206:575142-575178
- *  and 206:575199-575210 — sema's single-lane subset: no teammate/name-registry branches).
+/** Name resolution over the caller-visible background_agent rows
+ *  (sema's single-lane subset: no teammate/name-registry branches).
  *
  *  [c209-D] PUBLIC + explicit-name layer 0: the single resolver both TaskStop (:1839 leg) and
  *  SendMessage consume, so the two verbs can never drift. Ladder:
- *   0a. verbatim `handle.name` match — LATEST-WINS (CC SendMessage.md: "a newer agent took the name
+ *   0a. exact `handle.name` match — LATEST-WINS (the reference's SendMessage doc: "a newer agent took the name
  *       (latest wins)"; older rows stay task_id-addressable), any status (names keep working after
  *       completion — the resume face is the CC "resumes it from its transcript" counterpart).
  *       **Latest-wins is RESOLUTION, not permission to redirect a conversation**: CC pairs the same
@@ -446,7 +446,7 @@ export declare function deliverToRunningAgentLane(core: DurableAgentCore, id: st
  *  very rows a retry needs. The task faces' split lives in `runningAgentFooterLane` (RB-332). */
 export declare function runningBackgroundAgentLabelsLane(core: DurableAgentCore, access: TaskAccess): string[];
 /**
- * The not-found FOOTER's two rows, split the way CC 220 assembles them:
+ * The not-found FOOTER's two rows, split the way the reference assembles them:
  *  - `named`  = CC `uG_` (220:467941-467953): the agentNameRegistry's KEYS whose task is a running local
  *               agent, listed as BARE NAMES — the string a retry should pass verbatim. sema's counterpart
  *               of "has a registry entry" is the handle carrying an explicit `name` (spawn-time label),

package/dist/core/task-registry-shared.d.ts

@@ -590,10 +590,10 @@ export declare const MONITOR_DEFAULT_TIMEOUT_MS = 300000;
 export declare const MONITOR_MAX_TIMEOUT_MS = 3600000;
 export declare const MONITOR_MAX_BATCHES_PER_MINUTE = 50;
 /** Burst capacity of the storm token bucket — how many batches may fire
- *  back-to-back before the SUPPRESSION level engages. CC value, adopted verbatim. */
+ *  back-to-back before the SUPPRESSION level engages. Adopted from the reference. */
 export declare const MONITOR_STORM_BURST = 10;
 /** How long a monitor must stay CONTINUOUSLY over budget before the
- *  second level (kill) fires. CC value, adopted verbatim. */
+ *  second level (kill) fires. Adopted from the reference. */
 export declare const MONITOR_STORM_KILL_AFTER_MS = 30000;
 /** The partial-line accumulator bound. sema's `lineBuf` had NO bound —
  *  a monitored process emitting megabytes without a single newline grew it without limit (the spool's
@@ -789,7 +789,7 @@ export declare function firstDropNote(spool: {
 /** ONE wording for "you stopped nothing" across every already-terminal stop face —
  *  the in-process bash/monitor/agent arms and the durable-row fallback previously split: the durable
  *  arm answered honestly while the in-process arms claimed `Terminated <id>.` over work that finished
- *  (or was killed) on its own. CC 220 refuses the call outright (`Task X is not running (status: …)`,
+ *  (or was killed) on its own. The reference refuses the call outright (`Task X is not running (status: …)`,
  *  220:468231-468236); sema keeps the idempotent no-op posture (stopWorkflow / durable-arm precedent,
  *  no isError) but the receipt must tell the truth. */
 export declare function alreadyTerminalStopNote(id: string, status: string): string;
@@ -840,7 +840,7 @@ export declare const DURABLE_AGENT_HANDLE_RE: RegExp;
  *  real child error — settleBackgroundAgent never stores it (status "killed" + stoppedBy already say
  *  it); exported so the subagent call sites and the registry agree on the exact sentinel. */
 export declare const BG_AGENT_REAP_STOP_ERROR = "stopped (parent task ended or TaskStop)";
-/** CC206-B 欠账 — TaskStop name addressing, CC `XN` verbatim (206:574955-574962): NFKC-normalize, strip
+/** TaskStop name addressing: NFKC-normalize, strip
  *  control/format chars (whitespace-class ones survive), trim, lowercase, whitespace runs → hyphens. Both
  *  the query and the candidate label go through this, so "Fix Tests" addresses "fix tests".
  *  [c209-D]: EXPORTED — SendMessage's "main" reserved lane must use the SAME canonicalization

package/dist/core/task-registry-shared.js

@@ -217,6 +217,7 @@ export function formatWorkflowRun(run) {
             runId: run.id,
             type: "workflow",
             status: run.status,
+            ...(summary.parked ? { parked: true } : {}),
             ...(summary.name ? { name: summary.name } : {}),
             ...(summary.currentPhase ? { currentPhase: summary.currentPhase } : {}),
             agents: { done, total: run.agents.length, failed },

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

@@ -33,7 +33,7 @@ export interface RegisterBackgroundBashInput extends TaskAccess {
      *  rolling bound) and fires ONE completion task-notification at the terminal state — the background-bash
      *  half of CC's LocalShellTask completion notify. Also flips TaskOutput to re-readable spool reads. */
     onTerminal?: (notification: TaskNotificationPayload) => void;
-    /** CC 2.1.209 对齐批A A5: the task's OUTPUT FILE — the launch receipt advertises it and the watcher
+    /** The task's OUTPUT FILE — the launch receipt advertises it and the watcher
      *  mirrors every polled increment into it (append-only, unbounded — unlike the rolling in-memory
      *  spool), so "Read the output file path" is a real alternative to TaskOutput. Terminal
      *  task-notifications carry the same path (`output_file`). Primarily meaningful with `onTerminal`
@@ -66,9 +66,9 @@ export interface TaskPollOptions {
     filter?: string;
     /** design/116 W3 (CC TaskOutput `block`): wait until the task reaches a terminal state (or `timeoutMs`)
      *  instead of returning the instantaneous snapshot — saves the model blind re-poll turns. The TOOL layer
-     *  defaults this to TRUE (CC 187 `block: default(!0)`, 裁定 2026-07-02); registry callers pass it explicitly. */
+     *  defaults this to TRUE (裁定 2026-07-02); registry callers pass it explicitly. */
     block?: boolean;
-    /** Max wait for `block` (ms). Default 30s, capped at 600s (CC 187). */
+    /** Max wait for `block` (ms). Default 30s, capped at 600s. */
     timeoutMs?: number;
     /** Abort signal — a blocked wait must stop when the tool call is cancelled. */
     signal?: AbortSignal;
@@ -101,7 +101,7 @@ export interface TaskToolOptions extends TaskAccess {
      *  foreground clamp (design/130 P2b). When present, a BLOCKING TaskOutput wait is clamped so it
      *  cannot eat the write-out window: the model gets an honest, visible clamp note instead of a
      *  silent 10-minute blind wait into the finalize wall (TB rs**: 9.1min poll = the exact tax).
-     *  CC posture note (anchors/2.1.212/print-mode-drain.md): CC classifies WIND-DOWN waits, and its
+     *  CC posture note: CC classifies WIND-DOWN waits, and its
      *  block cap rides per-query budgets — a deadline-aware wait is the sema equivalent on the tool face. */
     deadlineMs?: () => number | undefined;
     /** design/157 B17 S2 (fable 终判 D4) — whether a terminal <task-notification> is actually wired for

package/dist/core/task-registry.js

@@ -12,7 +12,7 @@ import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutp
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
 import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
-import { toolFace } from "./tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
 import { thrownText } from "./thrown-value.js";
 import { agentStateSourceOfHandle, agentStateSourceOfRecord, agentStateSummary, readAgentState } from "./agent-state.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
@@ -1307,6 +1307,7 @@ export function createTaskOutputTool(opts) {
     return defineTool({
         name: TASK_OUTPUT_TOOL_NAME,
         ...toolFace("task-output"),
+        ruleFace: mountRuleFace("task-output"),
         description: composeTaskOutputDescription(caps),
         parameters: composeTaskOutputParams(caps),
         boundaryLegsFor: (rawArgs, at) => {
@@ -1360,6 +1361,7 @@ export function createTaskStopTool(opts) {
     return defineTool({
         name: TASK_STOP_TOOL_NAME,
         ...toolFace("task-stop"),
+        ruleFace: mountRuleFace("task-stop"),
         description: composeTaskStopDescription(REGISTRY_TASK_TOOL_CAPS),
         parameters: TASK_STOP_PARAMS,
         boundaryLegsFor: (rawArgs, at) => {