@sema-agent/core 7.21.0 → 7.22.0

package/dist/core/memory-engine/layout.js

@@ -1114,16 +1114,76 @@ export function writeIndexRevs(controlDir, revs) {
 export function scanFuseCount(controlDir, key) {
     return coerceFuse(readSidecarJson(controlDir, SCAN_FUSE_FILE))[key] ?? 0;
 }
-export const SESSION_POLLUTION_DIR = "session-pollution";
-function pollutionPath(controlDir, sessionId) {
-    return join(controlDir, SESSION_POLLUTION_DIR, `${encodeURIComponent(sessionId)}.json`);
+export function sessionRecordBindsIncarnation(recorded, asking) {
+    return recorded === undefined || asking === undefined || recorded === asking;
 }
-export function markSessionPolluted(controlDir, sessionId, reason, now, cause) {
-    const path = pollutionPath(controlDir, sessionId);
+function readIncarnationSeat(parsed) {
+    return isIncarnationSeat(parsed.incarnation) && parsed.incarnation !== undefined ? parsed.incarnation : undefined;
+}
+function isIncarnationSeat(raw) {
+    if (raw === undefined)
+        return true;
+    if (typeof raw !== "string" || raw === "")
+        return false;
+    try {
+        encodeURIComponent(raw);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function usableSessionIncarnation(raw) {
+    return isIncarnationSeat(raw) ? raw : undefined;
+}
+function sessionRecordPath(controlDir, dir, sessionId, incarnation) {
+    const name = incarnation === undefined ? `${encodeURIComponent(sessionId)}.json` : `${encodeURIComponent(sessionId)}@${encodeURIComponent(incarnation)}.json`;
+    return join(controlDir, dir, name);
+}
+function standingOwnerAt(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            return "unattributable";
+        try {
+            lstatSync(path);
+        }
+        catch {
+            return "unattributable";
+        }
+        return { owner: undefined };
+    }
     try {
-        ensureDirExists(dirname(path));
-        const record = { at: now(), reason, ...(cause !== undefined ? { cause } : {}) };
-        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === "object")
+            return { owner: readIncarnationSeat(parsed) };
+    }
+    catch {
+    }
+    return "unattributable";
+}
+function mintSessionRecordSlots(controlDir, dir, sessionId, incarnation, text) {
+    const idSlot = sessionRecordPath(controlDir, dir, sessionId);
+    try {
+        ensureDirExists(dirname(idSlot));
+        writeFileSync(idSlot, text, { encoding: "utf8", flag: "wx" });
+        return "created";
+    }
+    catch (err) {
+        if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
+            return "unpersisted";
+    }
+    const own = usableSessionIncarnation(incarnation);
+    const standing = standingOwnerAt(idSlot);
+    const vouches = standing !== "unattributable" && (standing.owner === undefined || standing.owner === own);
+    const unnamed = vouches || own === undefined ? undefined : standingOwnerAt(sessionRecordPath(controlDir, dir, sessionId, ""));
+    if (vouches || (unnamed !== undefined && unnamed !== "unattributable" && unnamed.owner === undefined))
+        return "existed";
+    try {
+        writeFileSync(sessionRecordPath(controlDir, dir, sessionId, own ?? ""), text, { encoding: "utf8", flag: "wx" });
         return "created";
     }
     catch (err) {
@@ -1132,15 +1192,59 @@ export function markSessionPolluted(controlDir, sessionId, reason, now, cause) {
         return "unpersisted";
     }
 }
-export function readSessionPollution(controlDir, sessionId) {
-    const path = pollutionPath(controlDir, sessionId);
+function bindOrSeparate(record, identity, asking, unknownSlot) {
+    if (sessionRecordBindsIncarnation(record.incarnation, asking))
+        return record;
+    const unnamed = unknownSlot();
+    if (unnamed !== undefined && sessionRecordBindsIncarnation(unnamed.incarnation, asking))
+        return unnamed;
+    if (record.incarnation !== undefined)
+        identity?.onSeparated?.(record.incarnation);
+    return undefined;
+}
+function sessionIdOfRecordName(name) {
+    if (!name.endsWith(".json"))
+        return undefined;
+    const stem = name.slice(0, -".json".length);
+    const at = stem.indexOf("@");
+    try {
+        return decodeURIComponent(at < 0 ? stem : stem.slice(0, at));
+    }
+    catch {
+        return undefined;
+    }
+}
+export const SESSION_POLLUTION_DIR = "session-pollution";
+function pollutionPath(controlDir, sessionId, incarnation) {
+    return sessionRecordPath(controlDir, SESSION_POLLUTION_DIR, sessionId, incarnation);
+}
+export function markSessionPolluted(controlDir, sessionId, reason, now, cause, incarnation) {
+    const record = { at: now(), reason, ...(cause !== undefined ? { cause } : {}), ...(incarnation !== undefined ? { incarnation } : {}) };
+    return mintSessionRecordSlots(controlDir, SESSION_POLLUTION_DIR, sessionId, incarnation, `${JSON.stringify(record, null, 2)}\n`);
+}
+export function readSessionPollution(controlDir, sessionId, identity) {
+    const asking = usableSessionIncarnation(identity?.incarnation);
+    if (asking !== undefined) {
+        const own = readPollutionAt(pollutionPath(controlDir, sessionId, asking));
+        if (own !== undefined)
+            return own;
+    }
+    const unnamedSlot = () => readPollutionAt(pollutionPath(controlDir, sessionId, ""));
+    const standing = readPollutionAt(pollutionPath(controlDir, sessionId));
+    return standing === undefined ? unnamedSlot() : bindOrSeparate(standing, identity, asking, unnamedSlot);
+}
+function readPollutionAt(path) {
     let raw;
     try {
         raw = readFileSync(path, "utf8");
     }
     catch {
-        if (!existsSync(path))
+        try {
+            lstatSync(path);
+        }
+        catch {
             return undefined;
+        }
         return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
     }
     try {
@@ -1150,8 +1254,9 @@ export function readSessionPollution(controlDir, sessionId) {
             const reason = parsed.reason;
             const cause = parsed.cause;
             const knownCause = typeof cause === "string" && MEMORY_ORIGIN_CAUSES.includes(cause) ? cause : undefined;
+            const incarnation = readIncarnationSeat(parsed);
             if (typeof at === "number" && typeof reason === "string")
-                return { at, reason, ...(knownCause !== undefined ? { cause: knownCause } : {}) };
+                return { at, reason, ...(knownCause !== undefined ? { cause: knownCause } : {}), ...(incarnation !== undefined ? { incarnation } : {}) };
         }
     }
     catch {
@@ -1171,16 +1276,10 @@ export function listSessionPollution(controlDir) {
     }
     const out = Object.create(null);
     for (const name of names.sort()) {
-        if (!name.endsWith(".json"))
+        const sessionId = sessionIdOfRecordName(name);
+        if (sessionId === undefined || Object.prototype.hasOwnProperty.call(out, sessionId))
             continue;
-        let sessionId;
-        try {
-            sessionId = decodeURIComponent(name.slice(0, -".json".length));
-        }
-        catch {
-            continue;
-        }
-        const rec = readSessionPollution(controlDir, sessionId);
+        const rec = readPollutionAt(join(dir, name));
         if (rec !== undefined)
             out[sessionId] = rec;
     }
@@ -1201,25 +1300,25 @@ export function importSessionPollution(controlDir, sessionId, record) {
     return standing !== undefined && standing.at === record.at && standing.reason === record.reason ? "already" : "divergent";
 }
 export const SESSION_CAPTURE_OPTOUT_DIR = "session-capture-optout";
-function captureOptOutPath(controlDir, sessionId) {
-    return join(controlDir, SESSION_CAPTURE_OPTOUT_DIR, `${encodeURIComponent(sessionId)}.json`);
+function captureOptOutPath(controlDir, sessionId, incarnation) {
+    return sessionRecordPath(controlDir, SESSION_CAPTURE_OPTOUT_DIR, sessionId, incarnation);
 }
-export function markSessionCaptureOptOut(controlDir, sessionId, reason, now) {
-    const path = captureOptOutPath(controlDir, sessionId);
-    try {
-        ensureDirExists(dirname(path));
-        const record = { at: now(), reason };
-        writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
-        return "created";
-    }
-    catch (err) {
-        if (err instanceof Error && "code" in err && err.code === "EEXIST")
-            return "existed";
-        return "unpersisted";
+export function markSessionCaptureOptOut(controlDir, sessionId, reason, now, incarnation) {
+    const record = { at: now(), reason, ...(incarnation !== undefined ? { incarnation } : {}) };
+    return mintSessionRecordSlots(controlDir, SESSION_CAPTURE_OPTOUT_DIR, sessionId, incarnation, `${JSON.stringify(record, null, 2)}\n`);
+}
+export function readSessionCaptureOptOut(controlDir, sessionId, identity) {
+    const asking = usableSessionIncarnation(identity?.incarnation);
+    if (asking !== undefined) {
+        const own = readCaptureOptOutAt(captureOptOutPath(controlDir, sessionId, asking));
+        if (own !== undefined)
+            return own;
     }
+    const unnamedSlot = () => readCaptureOptOutAt(captureOptOutPath(controlDir, sessionId, ""));
+    const standing = readCaptureOptOutAt(captureOptOutPath(controlDir, sessionId));
+    return standing === undefined ? unnamedSlot() : bindOrSeparate(standing, identity, asking, unnamedSlot);
 }
-export function readSessionCaptureOptOut(controlDir, sessionId) {
-    const path = captureOptOutPath(controlDir, sessionId);
+function readCaptureOptOutAt(path) {
     let raw;
     try {
         raw = readFileSync(path, "utf8");
@@ -1249,8 +1348,9 @@ export function readSessionCaptureOptOut(controlDir, sessionId) {
         if (parsed !== null && typeof parsed === "object") {
             const at = parsed.at;
             const reason = parsed.reason;
+            const incarnation = readIncarnationSeat(parsed);
             if (typeof at === "number" && typeof reason === "string")
-                return { at, reason };
+                return { at, reason, ...(incarnation !== undefined ? { incarnation } : {}) };
         }
     }
     catch {
@@ -1270,16 +1370,10 @@ export function listSessionCaptureOptOut(controlDir) {
     }
     const out = Object.create(null);
     for (const name of names.sort()) {
-        if (!name.endsWith(".json"))
+        const sessionId = sessionIdOfRecordName(name);
+        if (sessionId === undefined || Object.prototype.hasOwnProperty.call(out, sessionId))
             continue;
-        let sessionId;
-        try {
-            sessionId = decodeURIComponent(name.slice(0, -".json".length));
-        }
-        catch {
-            continue;
-        }
-        const rec = readSessionCaptureOptOut(controlDir, sessionId);
+        const rec = readCaptureOptOutAt(join(dir, name));
         if (rec !== undefined)
             out[sessionId] = rec;
     }
@@ -1287,8 +1381,8 @@ export function listSessionCaptureOptOut(controlDir) {
 }
 export function fileSessionCaptureRecordStore(controlDir) {
     return {
-        mark: (sessionId, record) => markSessionCaptureOptOut(controlDir, sessionId, record.reason, () => record.at),
-        read: (sessionId) => readSessionCaptureOptOut(controlDir, sessionId),
+        mark: (sessionId, record) => markSessionCaptureOptOut(controlDir, sessionId, record.reason, () => record.at, record.incarnation),
+        read: (sessionId, identity) => readSessionCaptureOptOut(controlDir, sessionId, identity),
         list: () => listSessionCaptureOptOut(controlDir),
     };
 }
@@ -1461,6 +1555,9 @@ function coerceLineage(raw) {
             }
             if (row.marked !== undefined && row.marked !== true)
                 throw badShape(`committed[${JSON.stringify(entryId)}][${JSON.stringify(sid)}] marked`);
+            if (!isIncarnationSeat(row.incarnation)) {
+                throw badShape(`committed[${JSON.stringify(entryId)}][${JSON.stringify(sid)}] incarnation`);
+            }
         }
     }
     for (const [txnId, t] of Object.entries(r.pending)) {
@@ -1470,6 +1567,8 @@ function coerceLineage(raw) {
         }
         if (txn.kind !== undefined && txn.kind !== "latch-only")
             throw badShape(`pending[${JSON.stringify(txnId)}] kind`);
+        if (!isIncarnationSeat(txn.incarnation))
+            throw badShape(`pending[${JSON.stringify(txnId)}] incarnation`);
         for (const row of txn.rows) {
             const p = row;
             if (!p || typeof p !== "object" || typeof p.entryId !== "string" || typeof p.rev !== "string")
@@ -1498,9 +1597,9 @@ function coerceLineage(raw) {
         pending[txnId] = t;
     return { version: 1, committed, pending };
 }
-export function stageLineagePending(controlDir, txnId, sessionId, rows, now) {
+export function stageLineagePending(controlDir, txnId, sessionId, rows, now, incarnation) {
     lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
-        rec.pending[txnId] = { sessionId, at: now(), rows: [...rows] };
+        rec.pending[txnId] = { sessionId, at: now(), rows: [...rows], ...(incarnation !== undefined ? { incarnation } : {}) };
         return { next: rec, result: undefined };
     });
 }
@@ -1536,7 +1635,7 @@ export function promoteLineagePending(controlDir, txnId, now) {
             if (!applied.has(row.entryId))
                 continue;
             const sessions = (rec.committed[row.entryId] ??= Object.create(null));
-            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}) };
+            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}), ...(txn.incarnation !== undefined ? { incarnation: txn.incarnation } : {}) };
             promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev, ...(row.marked === true ? { marked: true } : {}) });
         }
         delete rec.pending[txnId];
@@ -1562,7 +1661,7 @@ export function adjudicateLineagePending(controlDir, txnId, action, now) {
             if (applied !== undefined && !applied.has(row.entryId))
                 continue;
             const sessions = (rec.committed[row.entryId] ??= Object.create(null));
-            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}) };
+            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}), ...(txn.incarnation !== undefined ? { incarnation: txn.incarnation } : {}) };
             promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev, ...(row.marked === true ? { marked: true } : {}) });
         }
         delete rec.pending[txnId];
@@ -1586,7 +1685,7 @@ export function reconcileLineage(controlDir, now) {
                     continue;
                 at ??= now();
                 const sessions = (rec.committed[row.entryId] ??= Object.create(null));
-                sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}) };
+                sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}), ...(txn.incarnation !== undefined ? { incarnation: txn.incarnation } : {}) };
                 promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev, ...(row.marked === true ? { marked: true } : {}) });
             }
             delete rec.pending[txnId];
@@ -1663,13 +1762,14 @@ export function lineageLatchedIds(controlDir) {
             out.add(row.entryId);
     return out;
 }
-export function lineageContributionsOfSession(controlDir, sessionId) {
+export function lineageContributionsOfSession(controlDir, sessionId, asking) {
     const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
     const out = [];
     for (const [entryId, sessions] of Object.entries(rec.committed)) {
         const c = Object.prototype.hasOwnProperty.call(sessions, sessionId) ? sessions[sessionId] : undefined;
-        if (c !== undefined)
-            out.push({ entryId, lastRev: c.lastRev, lastAt: c.lastAt, ...(c.marked === true ? { marked: true } : {}) });
+        if (c === undefined || !sessionRecordBindsIncarnation(c.incarnation, asking))
+            continue;
+        out.push({ entryId, lastRev: c.lastRev, lastAt: c.lastAt, ...(c.marked === true ? { marked: true } : {}) });
     }
     return out;
 }

package/dist/core/memory-engine/session-incarnation.d.ts

@@ -0,0 +1,27 @@
+import { type MemoryPartitionIncidentSink, type SessionIdentityRead } from "./layout.js";
+/** The current occupant's token, and the identity seat a per-session record read is made under. */
+export interface SessionIncarnationSeat {
+    incarnationOf(sessionId: string): string | undefined;
+    identityRead(sessionId: string): SessionIdentityRead;
+}
+/** Build the seat over a host resolver (absent ⇒ nothing stamped, nothing asked, every record binds
+ *  by id — the pre-incarnation answer). Both disclosures are DEDUPED on the axis their fact belongs to: the resolver
+ *  fault once per engine (a wiring fact), a separation once per session id (a fact about that id). */
+export declare function createSessionIncarnationSeat(input: {
+    resolve: ((session: {
+        sessionId: string;
+    }) => string | undefined) | undefined;
+    onIncident: MemoryPartitionIncidentSink | undefined;
+}): SessionIncarnationSeat;
+/** Remember an in-process record under its session id, FIRST-WINS PER IDENTITY: this map is the
+ *  durable half's fallback exactly when the durable write failed, so keeping only the first
+ *  occupant's row would leave the next one unprotected on the one path it exists to cover. */
+export declare function rememberForIdentity<T extends {
+    incarnation?: string;
+}>(map: Map<string, T[]>, sessionId: string, record: T): void;
+/** The remembered record that BINDS `asking` ({@link sessionRecordBindsIncarnation}), if any. */
+export declare function recalledForIdentity<T extends {
+    incarnation?: string;
+}>(map: Map<string, T[]>, sessionId: string, asking: string | undefined): T | undefined;
+/** The first record remembered for `sessionId` by ANY occupant — for the id-blind faces. */
+export declare function recalledForAnyIdentity<T>(map: Map<string, T[]>, sessionId: string): T | undefined;

package/dist/core/memory-engine/session-incarnation.js

@@ -0,0 +1,63 @@
+import { sessionRecordBindsIncarnation, usableSessionIncarnation } from "./layout.js";
+export function createSessionIncarnationSeat(input) {
+    const { resolve, onIncident } = input;
+    let faultAnnounced = false;
+    const separationAnnounced = new Set();
+    const disclose = (code, message) => {
+        if (onIncident === undefined)
+            return;
+        try {
+            const e = new Error(message);
+            e.code = code;
+            onIncident(e);
+        }
+        catch {
+        }
+    };
+    const incarnationOf = (sessionId) => {
+        if (resolve === undefined)
+            return undefined;
+        try {
+            const answer = resolve({ sessionId });
+            return usableSessionIncarnation(answer);
+        }
+        catch (err) {
+            if (!faultAnnounced) {
+                faultAnnounced = true;
+                disclose("memory.session_incarnation_unreadable", `the session incarnation resolver threw (${err instanceof Error ? err.message : String(err)}) — this run cannot tell one occupant of a session id from the next, so every durable session record binds by id alone (the conservative reading, and the behavior of a deployment that wires no resolver)`);
+            }
+            return undefined;
+        }
+    };
+    return {
+        incarnationOf,
+        identityRead: (sessionId) => {
+            const incarnation = incarnationOf(sessionId);
+            return {
+                ...(incarnation !== undefined ? { incarnation } : {}),
+                onSeparated: (recorded) => {
+                    if (separationAnnounced.has(sessionId))
+                        return;
+                    separationAnnounced.add(sessionId);
+                    disclose("memory.session_incarnation_mismatch", `a durable record stands for session ${sessionId} but it was minted by a DIFFERENT occupant of that id (recorded incarnation ${JSON.stringify(recorded)}, this run ${JSON.stringify(incarnation)}) — it does not bind this run and the record is kept where it is. Either the id was recycled after its previous session was deleted, or the deployment's incarnation resolver is not stable for the life of one session`);
+                },
+            };
+        },
+    };
+}
+export function rememberForIdentity(map, sessionId, record) {
+    const rows = map.get(sessionId);
+    if (rows === undefined) {
+        map.set(sessionId, [record]);
+        return;
+    }
+    if (rows.some((r) => r.incarnation === record.incarnation))
+        return;
+    rows.push(record);
+}
+export function recalledForIdentity(map, sessionId, asking) {
+    return map.get(sessionId)?.find((r) => sessionRecordBindsIncarnation(r.incarnation, asking));
+}
+export function recalledForAnyIdentity(map, sessionId) {
+    return map.get(sessionId)?.[0];
+}

package/dist/core/parent-spec-seat.d.ts

@@ -12,7 +12,7 @@ import type { OnQuestion } from "./ask-question.js";
 import type { ToolExecuteContext } from "./tool-spec.js";
 import type { TaskSpec } from "./types.js";
 /** The fields of a spec the seat carries — one `Pick`, shared by the mint's input and the apply's target. */
-export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable">;
+export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory">;
 /**
  * The seat a run hands its children. Every member is the parent's own value, frozen at mint (arrays copied and
  * frozen; the facts object copied). Members present iff the parent carries them — an absent member is "nothing to
@@ -26,6 +26,8 @@ export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "cli
  *  · `envFacts` — the sandbox facts (profile / egress / scratchpad).
  *  · `memoryPersistenceCapable` — the deployment's DECLARED persistence statement: `false` is a REMOVAL (floor),
  *    `true` a default a child's own declaration may narrow.
+ *  · `memoryOff` — the request-level "memory is off" FACT (`spec.memory.enabled === false`): a REMOVAL
+ *    (floor) that REWRITES the child's own memory declaration instead of travelling as a value.
  */
 export interface ParentSpecSeat {
     readonly principal?: string;
@@ -36,14 +38,15 @@ export interface ParentSpecSeat {
     readonly additionalReadDirectories?: readonly string[];
     readonly envFacts?: TaskSpec["envFacts"];
     readonly memoryPersistenceCapable?: boolean;
+    readonly memoryOff?: true;
 }
 /** Mint the seat off the parent's REBOUND spec and its frozen question face (spec over deps — the caller resolves it once,
  *  the same value the parent's own question routing reads). Absent fields stay absent; `oneShot` only when `true`. */
 export declare function parentSpecSeatOf(spec: Omit<ParentSpecSeatFields, "onQuestion">, frozenOnQuestion: OnQuestion | undefined): ParentSpecSeat;
 /**
  * Apply the seat to a child spec — ONE law for every member, both lanes:
- *   a value the child spec already carries WINS; the seat FILLS an unset one; the two REMOVAL values
- *   (`oneShot: true`, `memoryPersistenceCapable: false`) land UNCONDITIONALLY.
+ *   a value the child spec already carries WINS; the seat FILLS an unset one; the three REMOVAL values
+ *   (`oneShot: true`, `memoryPersistenceCapable: false`, `memoryOff: true`) land UNCONDITIONALLY.
  * "Already carries" is the child's own authorship — a deployment baseline, a trusted script, an agent definition's
  * fold (the Task lane folds the definition's `memoryPersistenceCapable` before applying; the workflow lane applies at
  * the launch site AFTER the agentType fold) — so a definition may narrow a parent `true` to `false`, a baseline-pinned
@@ -52,6 +55,15 @@ export declare function parentSpecSeatOf(spec: Omit<ParentSpecSeatFields, "onQue
  * No seat (a tool running outside a Runner task) ⇒ the child spec is returned as is.
  */
 export declare function applyParentSpecSeat<S extends ParentSpecSeatFields>(child: S, seat: ParentSpecSeat | undefined): S;
+/** The ONE way the memory-off floor is written onto a spec — the seat's apply above and the resume lane's
+ *  clamp fold both call it: keep every field the spec authored (scopes, write scope, content-safety knobs)
+ *  and state `enabled: false` over them. Returning a value rather than deleting the key IS the mechanism:
+ *  the next seat mint reads `spec.memory.enabled === false`, so a spec whose `memory` was removed would end
+ *  the floor one level down. A spec that declared nothing gets the bare `{ enabled: false }`, which the
+ *  normalizer reads as "no usable scopes" — identical to the absent declaration it replaces. */
+export declare function memoryTurnedOff(memory: TaskSpec["memory"]): NonNullable<TaskSpec["memory"]> & {
+    enabled: false;
+};
 /** The ctx keys that restate a seat member as THIS run's own fact (tools read them for scope / receipts / clamps). */
 declare const SEAT_FACTS_ON_CTX: readonly ["principal", "oneShot", "onQuestion", "memoryPersistenceCapable"];
 /**

package/dist/core/parent-spec-seat.js

@@ -8,6 +8,7 @@ export function parentSpecSeatOf(spec, frozenOnQuestion) {
         ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
         ...(spec.envFacts !== undefined ? { envFacts: Object.freeze({ ...spec.envFacts }) } : {}),
         ...(spec.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: spec.memoryPersistenceCapable } : {}),
+        ...(spec.memory?.enabled === false ? { memoryOff: true } : {}),
     });
 }
 export function applyParentSpecSeat(child, seat) {
@@ -24,8 +25,12 @@ export function applyParentSpecSeat(child, seat) {
         ...fill("envFacts", (seat.envFacts !== undefined ? { ...seat.envFacts } : undefined)),
         ...(seat.oneShot === true ? { oneShot: true } : {}),
         ...(seat.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : fill("memoryPersistenceCapable", seat.memoryPersistenceCapable)),
+        ...(seat.memoryOff === true ? { memory: memoryTurnedOff(child.memory) } : {}),
     };
 }
+export function memoryTurnedOff(memory) {
+    return { ...(memory ?? {}), enabled: false };
+}
 const SEAT_FACTS_ON_CTX = ["principal", "oneShot", "onQuestion", "memoryPersistenceCapable"];
 export function parentSpecSeatOfCtx(ctx) {
     const seat = ctx.parentSpecSeat;

package/dist/core/permission-rule-model.d.ts

@@ -1195,8 +1195,7 @@ export declare function suggestRulesForCommand(command: string, ctx?: {
      * design/382 §2.4-6 — the deployment's sensitive-read negative control, SAME-SOURCE with its
      * compiled read-deny judge (`ReadDenyMatcher.matchPath !== null` is the canonical wiring): the
      * engine never PROPOSES a directory authorization for a directory this judge names. Absent ⇒
-     * the built-in default deny table stands in (refusal-only; a deployment with a wired judge
-     * passes its own so the two faces cannot disagree). Explicit-consent doors (hand-written,
+     * {@link defaultDeniesDirectoryRead} stands in (refusal-only; every hands leg passes its OWN judge). Explicit-consent doors (hand-written,
      * import) are deliberately NOT behind this — they have their own preview and validation.
      */
     readonly deniesDirectoryRead?: (directory: string) => boolean;

package/dist/core/retention.d.ts

@@ -47,7 +47,7 @@ export interface ManagedRetentionCapability {
     /** Lineage-aware transcript/session deletion: a session tree is deleted only when no live
      *  reference (fork child, background child, workflow run, pending checkpoint) still points into
      *  it — references are re-checked inside the deletion transaction, never assumed from a prior
-     *  scan. */
+     *  scan; {@link RETENTION_CASCADE_EXEMPT} is never deleted with one. */
     deleteExpiredSessions(input: {
         domain: string;
         cutoffMs: number;
@@ -66,6 +66,13 @@ export interface ManagedRetentionCapability {
  * own occurrence id, operation, and timestamp inside the deleting transaction. Adding those here
  * would ask a return value to know its own call context.
  */
+/** @contract retention.cascade_domains — a managed-retention cascade deletes checkpoint rows,
+ *  session trees (transcripts and lineage) and orphan tool results; nothing else is session data. */
+export declare const RETENTION_CASCADE_DOMAINS: readonly ["checkpoints", "session-trees", "orphan-tool-results"];
+/** @contract retention.governance_records_outlive_the_purge — the pollution marker dir, the capture
+ *  opt-out record dir and the lineage ledger are governance FACTS about content that exists, not
+ *  session data: deleting them makes a one-way privacy record revocable. */
+export declare const RETENTION_CASCADE_EXEMPT: readonly ["session-pollution", "session-capture-optout", "lineage.json"];
 export interface RetentionReceipt {
     domain: string;
     /** Rows destroyed by THIS call (idempotent retries count already-gone rows as 0, not errors). */

package/dist/core/retention.js

@@ -1,3 +1,5 @@
+export const RETENTION_CASCADE_DOMAINS = ["checkpoints", "session-trees", "orphan-tool-results"];
+export const RETENTION_CASCADE_EXEMPT = ["session-pollution", "session-capture-optout", "lineage.json"];
 function codedError(code, message) {
     const e = new Error(message);
     e.code = code;

package/dist/core/runner/classifier-ladder.js

@@ -217,6 +217,7 @@ export function classifierRoundObserver(args) {
             ms: info.ms,
             verdict: info.verdict,
             ...(info.cause !== undefined ? { cause: info.cause } : {}),
+            ...(info.notAsked !== undefined ? { notAsked: info.notAsked } : {}),
             ts: Date.now(),
         }));
         announceFallback(info.classifier);

package/dist/core/runner/contracts.d.ts

@@ -248,6 +248,11 @@ export interface Prepared {
     thinking?: ThinkingLevel;
     compModel?: Model;
     mcp: MaterializedMcp;
+    /** The run handle's `reconnectMcpServer` implementation — {@link MaterializedMcp.reconnect} plus the
+     *  live-roster application and the operator disclosure, which are runner concerns and not the MCP
+     *  handle's. Present only when this leg DECLARED MCP servers; the stream verb's seat stays unbound
+     *  otherwise and it refuses typed. */
+    mcpRedial?: (server: string) => Promise<import("../mcp.js").McpReconnectResult>;
     /** Present only when `spec.a2a` declared peers — the run loop owes it the same end-of-task dispose
      *  it owes {@link mcp} (no sockets are held, but a disposed mount is what makes a post-task tool
      *  call refuse loudly instead of dialing a peer on a dead task's behalf). */
@@ -2659,6 +2664,12 @@ export interface CaptureOptOutRef {
         outcome: "created" | "existed";
     }>;
 }
+/** The MCP re-dial verb's binding; bound only when the run declared MCP servers — a leg with
+ *  none has nothing to re-dial, and the stream verb then refuses TYPED rather than answering about a
+ *  materialization that was never made. Same shape and same law as {@link CaptureOptOutRef}. */
+export interface McpRedialRef {
+    redial?: (server: string) => Promise<import("../mcp.js").McpReconnectResult>;
+}
 /**
  * The stream's LIVE state as the verb lanes read it — a view over the driver's own locals (getters, and one
  * setter), never a copy: `resultValue` is written by the run body's `setResult` callback and by the failure