@sema-agent/core 5.65.0 → 7.0.0

package/dist/core/runner/prepare-memory.js

@@ -4,10 +4,13 @@ import { admitMemoryScopes } from "../memory-admission.js";
 import { adoptLegacyRepoDirs, canonicalize, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, isContainedIn, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
 import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
 import { normalizeMemorySpec } from "../memory.js";
-import { MEMORY_ANNOUNCEMENT_READONLY_CODA, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MemoryEngine, entryFileHeadCarriesOrigin, memoryConsolidationRecommendedNotice, memoryHarvestQuarantinedNotice, memoryHoldNotices, memoryRecallDisciplineSegment, memorySessionPollutedNotice, pollutionContainmentCounts, } from "../memory-engine/engine.js";
+import { MEMORY_ANNOUNCEMENT_CAPTURE_OPTOUT_CODA, MEMORY_ANNOUNCEMENT_READONLY_CODA, MEMORY_CAPTURE_INDETERMINATE_NOTICE, MEMORY_CAPTURE_OPTOUT_NOTICE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MemoryEngine, entryFileHeadCarriesOrigin, memoryCaptureOptedOutNotice, memoryCaptureOptOutUnpersistedNotice, memoryConsolidationRecommendedNotice, memoryHarvestQuarantinedNotice, memoryHoldNotices, memoryRecallDisciplineSegment, memorySessionPollutedNotice, pollutionContainmentCounts, } from "../memory-engine/engine.js";
+import { adjudicateCaptureOptOut, captureOptOutDeniedError, captureOptOutUnpersistedError } from "./memory-capture-optout.js";
+import { readSessionCaptureOptOut } from "../memory-engine/layout.js";
 import { createMemoryEngineTools } from "../memory-engine/tools.js";
 import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
 import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
+let undeclaredCapturePostureAnnounced = false;
 export async function prepareMemory(input) {
     const { spec, deps, sessionId, taskRootPath, memoryWriteGateRef, admissionCtx } = input;
     const memorySpec = normalizeMemorySpec(spec.memory);
@@ -41,8 +44,37 @@ export async function prepareMemory(input) {
         memorySpec.writeScope = outcome.writeScope;
     }
     const useMemoryEngine = Boolean(memorySpec && memorySpec.enabled && deps.memoryBackend);
+    const capturePosture = input.memoryCapturePolicy ?? "open";
+    const captureEntitlement = input.captureEntitlement ?? { value: undefined, faulted: false };
+    const captureDeclaredRaw = memorySpec?.capture === "off";
+    if (captureDeclaredRaw && memorySpec !== undefined && !memorySpec.enabled) {
+        deps.onError?.(new Error(`memory.capture:"off" appears beside memory.enabled:false — not a contradiction (memory is off entirely, so nothing is captured either way); the opt-out declaration is covered by enabled:false this run.`), { phase: "config", sessionId });
+    }
+    const captureDeclared = captureDeclaredRaw && useMemoryEngine;
+    const captureFloored = input.captureFloor === true && useMemoryEngine;
+    if (captureDeclared && !captureFloored) {
+        const verdict = adjudicateCaptureOptOut({ posture: capturePosture, entitlement: captureEntitlement, subject: "declaration" });
+        if (!verdict.allowed)
+            throw captureOptOutDeniedError(verdict.detail);
+        if (verdict.faultDisclosure !== undefined) {
+            deps.onError?.(new Error(verdict.faultDisclosure), { phase: "config", sessionId });
+        }
+        if (input.captureCarrierUnsupported === true) {
+            const e = new Error(`memory.capture:"off" cannot be honored on this deployment shape: the execution environment is remote/per-run ` +
+                `and no RunnerDeps.memoryCaptureRecordStore is supplied, so core cannot know the control plane survives to a ` +
+                `resume replica — a privacy promise that silently expires at the first resume is refused rather than made. A ` +
+                `deployment whose control plane IS durable (a single persistent host using a remote sandbox) opts back in by ` +
+                `supplying the store explicitly — fileSessionCaptureRecordStore(controlDir) is that one-line declaration.`);
+            e.code = "config.memory_capture_unsupported";
+            throw e;
+        }
+    }
+    let captureOptedOut = false;
+    let captureIndeterminate = false;
+    let captureLineageIndeterminate = false;
     let memoryEngineSession;
     let memoryTools;
+    let memoryMarkedEntriesServed = false;
     let effectiveMemoryScopes;
     const originOf = (scope) => scopeOriginsSnapshot !== undefined
         ? scopeOriginsSnapshot[scope] === "deployment"
@@ -132,15 +164,106 @@ export async function prepareMemory(input) {
                 const pinnedCtl = b.controlPlaneRoot;
                 return typeof pinnedCtl === "string" && pinnedCtl ? pinnedCtl : fallback;
             };
+            const captureStoreOpt = (b, fallback) => deps.memoryCaptureRecordStore !== undefined ? { captureRecordStore: deps.memoryCaptureRecordStore({ controlDir: effectiveControlDir(b, fallback) }) } : {};
             const choosePersonalBackend = () => typeof pinned === "string" && pinned ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir }) : backend;
             const createPersonalEngine = (personalBackend) => {
                 return {
-                    engine: new MemoryEngine({ backend: personalBackend, memoryDir: personalMemoryDir, controlDir: personalControlDir, onIncident: onEngineIncident, provenance: input.memoryProvenance, ...(input.deps.memoryConsolidation !== undefined ? { consolidation: input.deps.memoryConsolidation } : {}) }),
+                    engine: new MemoryEngine({ backend: personalBackend, memoryDir: personalMemoryDir, controlDir: personalControlDir, onIncident: onEngineIncident, provenance: input.memoryProvenance, ...captureStoreOpt(personalBackend, personalControlDir), ...(input.deps.memoryConsolidation !== undefined ? { consolidation: input.deps.memoryConsolidation } : {}) }),
                     backend: personalBackend,
                 };
             };
             const onEngineIncident = (err) => deps.onError?.(err, { phase: "memory", sessionId });
             const adoptionRestricted = input.memoryPersistenceDeclared === false;
+            const armCaptureOptOut = (eng) => {
+                const standingRead = eng.sessionCaptureOptOutOrFault(sessionId);
+                if (standingRead.fault) {
+                    captureIndeterminate = true;
+                    deps.onError?.(new Error(`the capture opt-out record store is unreadable at prepare — this session's capture state is indeterminate, and every memory commit boundary (read-side adoption included) suppresses fail-closed until the store answers.`), { phase: "memory", sessionId });
+                }
+                if (input.captureLineageFault === true) {
+                    const firstIndeterminate = !captureIndeterminate;
+                    captureIndeterminate = true;
+                    captureLineageIndeterminate = true;
+                    if (firstIndeterminate) {
+                        deps.onError?.(new Error(`this session's fork-lineage metadata is unreadable — whether it continues an opted-out source session cannot be established, so its capture state is indeterminate: every memory commit boundary (read-side adoption included) suppresses fail-closed; no opt-out record is minted from an unreadable state.`), { phase: "memory", sessionId });
+                    }
+                }
+                const standing = standingRead.record;
+                let floored = captureFloored;
+                if (!floored && !captureDeclared && standing === undefined && input.captureFloorIndeterminate === true) {
+                    const rows = new Map();
+                    for (const row of input.captureAncestors ?? [])
+                        rows.set(row.sessionId, row.controlDir);
+                    if (input.parentSessionId !== undefined && !rows.has(input.parentSessionId))
+                        rows.set(input.parentSessionId, input.parentCaptureQueryDir);
+                    let anyFault = standingRead.fault;
+                    let found = false;
+                    for (const [ancestorId, ancestorDir] of rows) {
+                        const samePlane = eng.sessionCaptureOptOutOrFault(ancestorId);
+                        if (samePlane.record !== undefined) {
+                            found = true;
+                            break;
+                        }
+                        if (samePlane.fault)
+                            anyFault = true;
+                        if (ancestorDir !== undefined && ancestorDir !== eng.controlPlaneDir) {
+                            try {
+                                const crossPlane = deps.memoryCaptureRecordStore !== undefined ? deps.memoryCaptureRecordStore({ controlDir: ancestorDir }).read(ancestorId) : readSessionCaptureOptOut(ancestorDir, ancestorId);
+                                if (crossPlane !== undefined) {
+                                    found = true;
+                                    break;
+                                }
+                            }
+                            catch {
+                                anyFault = true;
+                            }
+                        }
+                    }
+                    if (found)
+                        floored = true;
+                    else if (anyFault) {
+                        if (!captureIndeterminate) {
+                            captureIndeterminate = true;
+                            deps.onError?.(new Error(`the spawning session's capture opt-out state was INDETERMINATE at spawn (its record store faulted) and the live re-query still cannot answer — this delegated session inherits the suppression: every memory commit boundary (read-side adoption included) suppresses fail-closed until the store answers; no opt-out record is minted from an unreadable state.`), { phase: "memory", sessionId });
+                        }
+                    }
+                }
+                let forkInherited = false;
+                if (!floored && !captureDeclared && standing === undefined && input.captureForkOrigin !== undefined) {
+                    const src = eng.sessionCaptureOptOutOrFault(input.captureForkOrigin);
+                    if (src.record !== undefined)
+                        forkInherited = true;
+                    else if (src.fault && !captureIndeterminate) {
+                        captureIndeterminate = true;
+                        deps.onError?.(new Error(`this session is a FORK of session "${input.captureForkOrigin}" whose capture opt-out record store is unreadable — the fork's capture state is indeterminate (the copied transcript may be governed by a standing opt-out), so every memory commit boundary suppresses fail-closed until the store answers; no opt-out record is minted from an unreadable state.`), { phase: "memory", sessionId });
+                    }
+                }
+                if (standing === undefined && !captureDeclared && !floored && !forkInherited)
+                    return;
+                if (standing !== undefined && !captureDeclared && !floored && capturePosture !== "open") {
+                    const verdict = adjudicateCaptureOptOut({ posture: capturePosture, entitlement: captureEntitlement, subject: "standing-record" });
+                    if (!verdict.allowed)
+                        throw captureOptOutDeniedError(verdict.detail);
+                }
+                if (standing === undefined) {
+                    const outcome = eng.markSessionCaptureOptOut(sessionId, captureDeclared ? `declared on TaskSpec.memory.capture` : forkInherited ? `inherited capture opt-out from the forked source session` : `inherited capture opt-out floor from the spawning session`);
+                    if (outcome === "unpersisted") {
+                        deliverEngineNotice(deps.onNotice, memoryCaptureOptOutUnpersistedNotice({ sessionId, ingress: "declaration" }));
+                        throw captureOptOutUnpersistedError(sessionId, "declaration");
+                    }
+                    if (outcome === "created")
+                        deliverEngineNotice(deps.onNotice, memoryCaptureOptedOutNotice({ sessionId, origin: captureDeclared ? "declaration" : forkInherited ? "fork-origin" : "delegation-floor" }));
+                }
+                else if (!captureDeclared) {
+                    deliverEngineNotice(deps.onNotice, memoryCaptureOptedOutNotice({ sessionId, origin: "standing-record" }));
+                }
+                captureOptedOut = true;
+                if (input.memoryCapturePolicyDeclared !== true && !undeclaredCapturePostureAnnounced) {
+                    undeclaredCapturePostureAnnounced = true;
+                    deps.onError?.(new Error(`a session memory-capture opt-out was honored under the DEFAULT capture posture (no RunnerDeps.memoryCapturePolicy configured) — ` +
+                        `the switch is now in use; declare "open", "governed" or "capture-required" to make the deployment's stance explicit.`), { phase: "config", sessionId });
+                }
+            };
             const retrievalBackend = (b, planeRestricted) => planeRestricted
                 ? (b.restrictedAdoptionView?.({ audit: false }) ??
                     b.retrievalView?.() ??
@@ -164,9 +287,47 @@ export async function prepareMemory(input) {
             let injectFn;
             let harvestBoth;
             let toolPlanes;
-            const admitNothingOpts = input.memoryPersistenceDeclared === false
-                ? { admitNothing: { reason: "harvest admitted nothing: memory persistence is declared unavailable for this session (memoryPersistenceCapable: false)" } }
-                : {};
+            const admitNothingOptsNow = () => {
+                if (input.memoryPersistenceDeclared === false) {
+                    return { admitNothing: { reason: "harvest admitted nothing: memory persistence is declared unavailable for this session (memoryPersistenceCapable: false)" } };
+                }
+                if (captureLineageIndeterminate) {
+                    return { admitNothing: { reason: `harvest admitted nothing: this session's fork-lineage metadata is unreadable — whether it continues an opted-out source cannot be established, so commits are suppressed fail-closed` } };
+                }
+                const own = captureOptedOut ? { record: { at: 0, reason: "in-run state" }, fault: false } : writeEngine.sessionCaptureOptOutOrFault(sessionId);
+                if (own.record !== undefined) {
+                    return { admitNothing: { reason: `harvest admitted nothing: this session declared memory capture opt-out (memory.capture: "off")` } };
+                }
+                if (own.fault) {
+                    return { admitNothing: { reason: `harvest admitted nothing: the capture opt-out record store is unreadable — the opt-out state is indeterminate and commits are suppressed fail-closed` } };
+                }
+                const ancestors = new Map();
+                for (const row of input.captureAncestors ?? [])
+                    ancestors.set(row.sessionId, row.controlDir);
+                if (input.parentSessionId !== undefined && !ancestors.has(input.parentSessionId))
+                    ancestors.set(input.parentSessionId, input.parentCaptureQueryDir);
+                if (input.captureForkOrigin !== undefined && !ancestors.has(input.captureForkOrigin))
+                    ancestors.set(input.captureForkOrigin, undefined);
+                for (const [ancestorId, ancestorDir] of ancestors) {
+                    const samePlane = writeEngine.sessionCaptureOptOutOrFault(ancestorId);
+                    let crossPlane;
+                    if (ancestorDir !== undefined && ancestorDir !== writeEngine.controlPlaneDir) {
+                        try {
+                            crossPlane = deps.memoryCaptureRecordStore !== undefined ? deps.memoryCaptureRecordStore({ controlDir: ancestorDir }).read(ancestorId) : readSessionCaptureOptOut(ancestorDir, ancestorId);
+                        }
+                        catch {
+                            return { admitNothing: { reason: `harvest admitted nothing: a spawning session's capture record store is unreadable — the floor state is indeterminate and commits are suppressed fail-closed` } };
+                        }
+                    }
+                    if (samePlane.record !== undefined || crossPlane !== undefined) {
+                        return { admitNothing: { reason: `harvest admitted nothing: a spawning session declared memory capture opt-out — the opt-out is a delegation floor no descendant loosens`, cause: "capture_optout_inherited" } };
+                    }
+                    if (samePlane.fault) {
+                        return { admitNothing: { reason: `harvest admitted nothing: the capture opt-out record store is unreadable while a spawning session's floor is in question — suppressed fail-closed` } };
+                    }
+                }
+                return {};
+            };
             if (dual) {
                 const personalBackendChosen = choosePersonalBackend();
                 {
@@ -195,16 +356,19 @@ export async function prepareMemory(input) {
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
                     provenance: input.memoryProvenance,
+                    ...captureStoreOpt(backend, identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot)),
                     ...(input.deps.memoryConsolidation !== undefined ? { consolidation: input.deps.memoryConsolidation } : {}),
                 });
                 const personal = createPersonalEngine(personalBackendChosen);
                 const personalEngine = personal.engine;
                 const p = planes;
-                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null, { adoptionRestricted, sessionId });
+                armCaptureOptOut(p.writePlane === "personal" ? personalEngine : projectEngine);
+                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null, { adoptionRestricted: adoptionRestricted || captureOptedOut || captureIndeterminate, sessionId });
                 materializedResidue.push(...planeScopes(p.project, p.writePlane === "project" ? memorySpec.writeScope : null));
-                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null, { adoptionRestricted, sessionId });
+                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null, { adoptionRestricted: adoptionRestricted || captureOptedOut || captureIndeterminate, sessionId });
                 materializedResidue.push(...planeScopes(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null));
                 const writeIsPersonal = p.writePlane === "personal";
+                memoryMarkedEntriesServed = projectHandle.markedEntriesPresent === true || personalHandle.markedEntriesPresent === true;
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
                 readOnlyEngine = writeIsPersonal ? projectEngine : personalEngine;
@@ -212,22 +376,24 @@ export async function prepareMemory(input) {
                 injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark }));
                 toolPlanes = [
                     {
-                        backend: retrievalBackend(backend, adoptionRestricted || p.writePlane !== "project"),
+                        backend: retrievalBackend(backend, adoptionRestricted || captureOptedOut || captureIndeterminate || p.writePlane !== "project"),
                         scopes: planeScopes(p.project, p.writePlane === "project" ? memorySpec.writeScope : null),
                         recordRetrieved: (ids) => projectEngine.recordRetrieved(ids),
                         challengeExclusions: () => projectEngine.readChallengeExclusions(),
+                        enginePlaneProvenance: projectEngine.provenanceMode,
                     },
                     {
-                        backend: retrievalBackend(personal.backend, adoptionRestricted || p.writePlane !== "personal"),
+                        backend: retrievalBackend(personal.backend, adoptionRestricted || captureOptedOut || captureIndeterminate || p.writePlane !== "personal"),
                         scopes: planeScopes(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null),
                         recordRetrieved: (ids) => personalEngine.recordRetrieved(ids),
                         challengeExclusions: () => personalEngine.readChallengeExclusions(),
+                        enginePlaneProvenance: personalEngine.provenanceMode,
                     },
                 ];
                 harvestBoth = async () => {
                     const writeFirst = writeIsPersonal ? [personalEngine, personalHandle] : [projectEngine, projectHandle];
                     const readOther = writeIsPersonal ? [projectEngine, projectHandle] : [personalEngine, personalHandle];
-                    const writeReport = await writeFirst[0].harvest(writeFirst[1], { ...pollutedOpts(writeFirst[0]), sessionId, ...admitNothingOpts });
+                    const writeReport = await writeFirst[0].harvest(writeFirst[1], { ...pollutedOpts(writeFirst[0]), sessionId, ...admitNothingOptsNow() });
                     let readReport;
                     let readFailure;
                     try {
@@ -245,18 +411,21 @@ export async function prepareMemory(input) {
             else if (personalOnly) {
                 const personal = createPersonalEngine(choosePersonalBackend());
                 const personalEngine = personal.engine;
-                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted, sessionId });
+                armCaptureOptOut(personalEngine);
+                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted: adoptionRestricted || captureOptedOut || captureIndeterminate, sessionId });
                 materializedResidue.push(...planeScopes(memorySpec.scopes, memorySpec.writeScope));
+                memoryMarkedEntriesServed = handle.markedEntriesPresent === true;
                 writeEngine = personalEngine;
                 writeHandle = handle;
                 injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark });
-                harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...admitNothingOpts });
+                harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...admitNothingOptsNow() });
                 toolPlanes = [
                     {
-                        backend: retrievalBackend(personal.backend, adoptionRestricted || memorySpec.writeScope === null),
+                        backend: retrievalBackend(personal.backend, adoptionRestricted || captureOptedOut || captureIndeterminate || memorySpec.writeScope === null),
                         scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope),
                         recordRetrieved: (ids) => personalEngine.recordRetrieved(ids),
                         challengeExclusions: () => personalEngine.readChallengeExclusions(),
+                        enginePlaneProvenance: personalEngine.provenanceMode,
                     },
                 ];
             }
@@ -267,20 +436,24 @@ export async function prepareMemory(input) {
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
                     provenance: input.memoryProvenance,
+                    ...captureStoreOpt(backend, identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot)),
                     ...(input.deps.memoryConsolidation !== undefined ? { consolidation: input.deps.memoryConsolidation } : {}),
                 });
-                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted, sessionId });
+                armCaptureOptOut(engine);
+                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted: adoptionRestricted || captureOptedOut || captureIndeterminate, sessionId });
                 materializedResidue.push(...planeScopes(memorySpec.scopes, memorySpec.writeScope));
+                memoryMarkedEntriesServed = handle.markedEntriesPresent === true;
                 writeEngine = engine;
                 writeHandle = handle;
                 injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark });
-                harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...admitNothingOpts });
+                harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...admitNothingOptsNow() });
                 toolPlanes = [
                     {
-                        backend: retrievalBackend(backend, adoptionRestricted || memorySpec.writeScope === null),
+                        backend: retrievalBackend(backend, adoptionRestricted || captureOptedOut || captureIndeterminate || memorySpec.writeScope === null),
                         scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope),
                         recordRetrieved: (ids) => engine.recordRetrieved(ids),
                         challengeExclusions: () => engine.readChallengeExclusions(),
+                        enginePlaneProvenance: engine.provenanceMode,
                     },
                 ];
             }
@@ -301,6 +474,22 @@ export async function prepareMemory(input) {
                         };
                     }
                 }
+                {
+                    const root = writeHandle.writableRoot;
+                    if (w.key === root || w.key.startsWith(`${root}${sep}`)) {
+                        const state = captureOptedOut ? { record: { at: 0, reason: "in-run state" }, fault: false } : writeEngine.sessionCaptureOptOutOrFault(sessionId);
+                        if (state.record !== undefined || state.fault) {
+                            return {
+                                ok: false,
+                                code: "read_only_layering",
+                                reason: state.record !== undefined
+                                    ? `memory capture is off for this session at the user's request (memory.capture: "off") — writes into the memory store are refused. Nothing was written.`
+                                    : `the capture opt-out record store is unreadable, so this session's capture state is indeterminate — writes into the memory store are refused fail-closed. Nothing was written.`,
+                                muted: false,
+                            };
+                        }
+                    }
+                }
                 return writeEngine.gateWrite(writeHandle, w.key, w.content);
             };
             let pollutionAnnounced = false;
@@ -326,7 +515,8 @@ export async function prepareMemory(input) {
                 try {
                     const report = await harvestBoth();
                     if (!report.ok && report.incident) {
-                        deps.onError?.(new Error(`memory harvest refused (${report.incident.kind}): ${report.incident.detail}`), { phase: "memory", sessionId });
+                        const named = report.reportId !== undefined ? `${report.incident.kind}, report ${report.reportId}` : report.incident.kind;
+                        deps.onError?.(new Error(`memory harvest refused (${named}): ${report.incident.detail}`), { phase: "memory", sessionId });
                     }
                     announceHarvestContainment(report);
                     try {
@@ -345,11 +535,76 @@ export async function prepareMemory(input) {
                     return undefined;
                 }
             };
+            const resolveCaptureEntitlementFresh = async () => {
+                if (deps.runtimeCapsResolver === undefined)
+                    return { value: undefined, faulted: false };
+                try {
+                    const caps = (await deps.runtimeCapsResolver(spec.principal)) ?? undefined;
+                    const v = caps?.allowMemoryOptOut;
+                    if (v !== undefined && typeof v !== "boolean")
+                        return { value: undefined, faulted: true };
+                    return { value: v, faulted: false };
+                }
+                catch {
+                    return { value: undefined, faulted: true };
+                }
+            };
             memoryEngineSession = {
                 engine: writeEngine,
                 handle: writeHandle,
                 inject: injectFn,
                 harvest: harvestSafe,
+                captureOptOut: {
+                    optedOut: () => captureOptedOut || writeEngine.sessionCaptureOptOutOrFault(sessionId).record !== undefined,
+                    indeterminate: () => {
+                        if (captureOptedOut)
+                            return false;
+                        const s = writeEngine.sessionCaptureOptOutOrFault(sessionId);
+                        return s.record === undefined && (captureIndeterminate || s.fault);
+                    },
+                    flip: async (reason) => {
+                        const entitlement = await resolveCaptureEntitlementFresh();
+                        const verdict = adjudicateCaptureOptOut({ posture: capturePosture, entitlement, subject: "declaration" });
+                        if (!verdict.allowed)
+                            throw captureOptOutDeniedError(verdict.detail);
+                        if (verdict.faultDisclosure !== undefined)
+                            deps.onError?.(new Error(verdict.faultDisclosure), { phase: "config", sessionId });
+                        if (input.captureCarrierUnsupported === true) {
+                            const e = new Error(`memory capture opt-out cannot be honored on this deployment shape: the execution environment is remote/per-run ` +
+                                `and no RunnerDeps.memoryCaptureRecordStore is supplied — the record would not survive to a resume replica. Nothing was recorded.`);
+                            e.code = "config.memory_capture_unsupported";
+                            throw e;
+                        }
+                        const trimmed = reason?.trim();
+                        const outcome = writeEngine.markSessionCaptureOptOut(sessionId, trimmed !== undefined && trimmed !== "" ? `host flip verb: ${trimmed.slice(0, 200)}` : "host flip verb");
+                        if (outcome === "unpersisted") {
+                            deliverEngineNotice(deps.onNotice, memoryCaptureOptOutUnpersistedNotice({ sessionId, ingress: "flip-verb" }));
+                            throw captureOptOutUnpersistedError(sessionId, "flip-verb");
+                        }
+                        captureOptedOut = true;
+                        if (outcome === "created") {
+                            deliverEngineNotice(deps.onNotice, memoryCaptureOptedOutNotice({ sessionId, origin: "flip-verb" }));
+                            if (input.memoryCapturePolicyDeclared !== true && !undeclaredCapturePostureAnnounced) {
+                                undeclaredCapturePostureAnnounced = true;
+                                deps.onError?.(new Error(`a session memory-capture opt-out was honored under the DEFAULT capture posture (no RunnerDeps.memoryCapturePolicy configured) — ` +
+                                    `the switch is now in use; declare "open", "governed" or "capture-required" to make the deployment's stance explicit.`), { phase: "config", sessionId });
+                            }
+                        }
+                        const sweep = await writeEngine.sweepSessionCaptureResidue(writeHandle);
+                        if (sweep.failures.length > 0) {
+                            const named = sweep.failures
+                                .slice(0, 5)
+                                .map((f) => `${f.path} (${f.detail})`)
+                                .join("; ");
+                            const e = new Error(`memory capture opt-out is ON (the one-way record stands) but the boundary sweep could not contain ` +
+                                `${sweep.failures.length} path(s) on the writable memory root — the named residue stays on the authoritative ` +
+                                `plane until a retry or host action clears it: ${named}${sweep.failures.length > 5 ? "; …" : ""}`);
+                            e.code = "memory.capture_optout_sweep_failed";
+                            throw e;
+                        }
+                        return { outcome };
+                    },
+                },
                 pollution: {
                     polluted: () => writeEngine.sessionPollution(sessionId),
                     markPolluted: (reason, cause) => {
@@ -409,7 +664,10 @@ export async function prepareMemory(input) {
             if (typeof err.code === "string" &&
                 (err.code.startsWith("config.memory_scope") ||
                     err.code.startsWith("config.memory_project") ||
-                    err.code === "config.memory_dual_root_overlap")) {
+                    err.code === "config.memory_dual_root_overlap" ||
+                    err.code === "memory.capture_optout_denied" ||
+                    err.code === "memory.capture_optout_unpersisted" ||
+                    err.code.startsWith("config.memory_capture"))) {
                 throw err;
             }
             deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
@@ -427,6 +685,7 @@ export async function prepareMemory(input) {
     }
     let memoryBlock;
     let seedFiles;
+    let recallDisciplineSegment;
     if (memorySpec && memorySpec.enabled && !useMemoryEngine) {
         const detail = "TaskSpec.memory is enabled but RunnerDeps.memoryBackend is not configured; memory is inactive for this task (the legacy memoryStore fallback was retired in design/138 S4 and the dep was removed in design/157 B19).";
         deps.onError?.(new Error(detail), { phase: "config", sessionId });
@@ -434,7 +693,13 @@ export async function prepareMemory(input) {
     if (memoryEngineSession) {
         const injection = memoryEngineSession.inject();
         let blockBody = injection.block;
-        if (!input.rosterCanPersist && injection.instruction === "" && injection.readOnlyNotice === undefined) {
+        if (captureOptedOut) {
+            blockBody = [MEMORY_CAPTURE_OPTOUT_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        }
+        else if (captureIndeterminate && input.rosterCanPersist) {
+            blockBody = [MEMORY_CAPTURE_INDETERMINATE_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        }
+        else if (!input.rosterCanPersist && injection.instruction === "" && injection.readOnlyNotice === undefined) {
             blockBody = blockBody.trim() ? `${MEMORY_READONLY_NOTICE}\n\n${blockBody}` : MEMORY_READONLY_NOTICE;
         }
         else if (!input.rosterCanPersist && injection.instruction !== "") {
@@ -449,16 +714,23 @@ export async function prepareMemory(input) {
             !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_READONLY_CODA)) {
             blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_READONLY_CODA}`;
         }
+        if (captureOptedOut &&
+            input.rosterCanPersist &&
+            (injection.announceBlock?.trim() ?? "") !== "" &&
+            blockBody.includes(injection.announceBlock) &&
+            !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_CAPTURE_OPTOUT_CODA)) {
+            blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_CAPTURE_OPTOUT_CODA}`;
+        }
         if (blockBody.trim())
             memoryBlock = blockBody;
         if (memoryTools !== undefined) {
-            const segment = memoryRecallDisciplineSegment(input.memoryProvenance);
-            memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${segment}` : segment;
+            recallDisciplineSegment = memoryRecallDisciplineSegment(input.memoryProvenance, { markedEntriesServed: memoryMarkedEntriesServed });
+            memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${recallDisciplineSegment}` : recallDisciplineSegment;
         }
-        if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted && input.rosterCanPersist) {
+        if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted && input.rosterCanPersist && !captureOptedOut && !captureIndeterminate) {
             memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_PREFERENCE_DISCIPLINE}` : MEMORY_PREFERENCE_DISCIPLINE;
         }
-        if (memoryBlock !== undefined && injection.indexSeed !== undefined && input.rosterCanPersist)
+        if (memoryBlock !== undefined && injection.indexSeed !== undefined && input.rosterCanPersist && !captureOptedOut && !captureIndeterminate)
             seedFiles = [injection.indexSeed];
     }
     if (effectiveMemoryScopes === undefined) {
@@ -468,5 +740,14 @@ export async function prepareMemory(input) {
                 : { state: "none", reason: "disabled", scopes: [], writeScope: null }
             : { state: "none", reason: "no-spec", scopes: [], writeScope: null };
     }
-    return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, effectiveMemoryScopes, ...(memoryTools !== undefined ? { memoryTools } : {}), ...(seedFiles !== undefined ? { seedFiles } : {}) };
+    return {
+        memoryEngineSession,
+        memoryBlock,
+        admittedOrgScopes,
+        ownOrgVerdict,
+        effectiveMemoryScopes,
+        ...(memoryTools !== undefined ? { memoryTools } : {}),
+        ...(recallDisciplineSegment !== undefined ? { recallDisciplineSegment } : {}),
+        ...(seedFiles !== undefined ? { seedFiles } : {}),
+    };
 }