@sema-agent/core 7.0.1 → 7.1.0

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

@@ -457,37 +457,47 @@ export class MemoryEngine {
                 return "unpersisted";
             }
         }
-        let outcome;
+        let raw;
         try {
-            outcome = this.captureRecords.mark(sessionId, record);
+            raw = this.captureRecords.mark(sessionId, record);
         }
         catch {
-            outcome = "unpersisted";
+            raw = "unpersisted";
         }
-        if (outcome !== "unpersisted" && !this.captureOptOutSessions.has(sessionId))
-            this.captureOptOutSessions.set(sessionId, record);
-        return outcome;
+        const settle = (outcome) => {
+            if (outcome !== "unpersisted" && !this.captureOptOutSessions.has(sessionId))
+                this.captureOptOutSessions.set(sessionId, record);
+            return outcome;
+        };
+        return raw instanceof Promise ? raw.then(settle, () => "unpersisted") : settle(raw);
     }
     sessionCaptureOptOut(sessionId) {
-        return this.sessionCaptureOptOutOrFault(sessionId).record;
+        const r = this.sessionCaptureOptOutOrFault(sessionId);
+        return r instanceof Promise ? r.then((s) => s.record) : r.record;
     }
     sessionCaptureOptOutOrFault(sessionId) {
         const inProcess = this.captureOptOutSessions.get(sessionId);
         if (inProcess !== undefined)
             return { record: inProcess, fault: false };
+        let raw;
         try {
-            const record = this.captureRecords.read(sessionId);
-            return record !== undefined ? { record, fault: false } : { fault: false };
+            raw = this.captureRecords.read(sessionId);
         }
         catch {
             return { fault: true };
         }
+        const fold = (record) => record !== undefined ? { record, fault: false } : { fault: false };
+        return raw instanceof Promise ? raw.then(fold, () => ({ fault: true })) : fold(raw);
     }
     listCaptureOptOutSessions() {
-        const out = new Set(Object.keys(this.captureRecords.list()));
-        for (const id of this.captureOptOutSessions.keys())
-            out.add(id);
-        return out;
+        const raw = this.captureRecords.list();
+        const fold = (rows) => {
+            const out = new Set(Object.keys(rows));
+            for (const id of this.captureOptOutSessions.keys())
+                out.add(id);
+            return out;
+        };
+        return raw instanceof Promise ? raw.then(fold) : fold(raw);
     }
     async sweepSessionCaptureResidue(handle) {
         const out = { swept: [], restored: [], failures: [] };
@@ -1546,7 +1556,7 @@ export class MemoryEngine {
             warnings: [],
         };
         const writeScope = handle.writeScope;
-        const captureRead = opts?.sessionId !== undefined ? this.sessionCaptureOptOutOrFault(opts.sessionId) : { fault: false };
+        const captureRead = opts?.sessionId !== undefined ? await this.sessionCaptureOptOutOrFault(opts.sessionId) : { fault: false };
         const captureOptOut = captureRead.record;
         if (writeScope === null || opts?.admitNothing !== undefined || captureOptOut !== undefined || captureRead.fault) {
             try {
@@ -2194,7 +2204,7 @@ export class MemoryEngine {
                     return report;
                 }
             }
-            const preCommitRead = lineageSessionId !== undefined ? this.sessionCaptureOptOutOrFault(lineageSessionId) : { fault: false, record: undefined };
+            const preCommitRead = lineageSessionId !== undefined ? await this.sessionCaptureOptOutOrFault(lineageSessionId) : { fault: false, record: undefined };
             if (preCommitRead.record !== undefined || preCommitRead.fault) {
                 if (lineageArmed) {
                     try {
@@ -2796,7 +2806,7 @@ export class MemoryEngine {
             return false;
         return frozenToken === undefined || held.token === frozenToken;
     }
-    consolidationEligibility(headers) {
+    async consolidationEligibility(headers) {
         let exclusions;
         try {
             exclusions = this.readChallengeExclusions();
@@ -2823,7 +2833,7 @@ export class MemoryEngine {
         }
         let optOutSessions;
         try {
-            optOutSessions = this.listCaptureOptOutSessions();
+            optOutSessions = await this.listCaptureOptOutSessions();
         }
         catch (err) {
             throw new ConsolidationRefusedError("memory.consolidation_governance_unreadable", `memory consolidation refused: the capture opt-out roster cannot be trusted (fail-closed): ${err instanceof Error ? err.message : String(err)}`);
@@ -2874,7 +2884,7 @@ export class MemoryEngine {
         }
         const face = this.committedAuditFace();
         const headers = await face.listHeaders([scope]);
-        const { eligible } = this.consolidationEligibility(headers);
+        const { eligible } = await this.consolidationEligibility(headers);
         const fingerprint = opts.full === true ? undefined : row?.fingerprint;
         const candidateIds = [];
         for (const [id, h] of eligible) {
@@ -3040,7 +3050,7 @@ export class MemoryEngine {
         const at = this.now();
         const face = this.committedAuditFace();
         const headers = await face.listHeaders([scope]);
-        const { exclusions, superseded } = this.consolidationEligibility(headers);
+        const { exclusions, superseded } = await this.consolidationEligibility(headers);
         const headerById = new Map(headers.map((h) => [h.id, h]));
         const wholeReasons = [];
         for (let i = 0; i < proposal.products.length; i++) {
@@ -3921,6 +3931,67 @@ export class MemoryEngine {
         }
         return await b.listScopes();
     }
+    async sessionMemoryStatus(sessionId) {
+        const out = {};
+        const capture = await this.sessionCaptureOptOutOrFault(sessionId);
+        if (capture.fault) {
+            out.optOutSource = "fault";
+        }
+        else if (capture.record !== undefined) {
+            out.captureOptedOut = true;
+            out.optOutSource = "record";
+        }
+        else {
+            out.captureOptedOut = false;
+        }
+        let mine;
+        try {
+            const committed = readLineageRecord(this.controlDir).committed;
+            const ids = new Set();
+            let lastAt;
+            for (const [entryId, sessions] of Object.entries(committed)) {
+                const c = sessions[sessionId];
+                if (c === undefined)
+                    continue;
+                ids.add(entryId);
+                if (lastAt === undefined || c.lastAt > lastAt)
+                    lastAt = c.lastAt;
+            }
+            mine = ids;
+            out.committedCount = ids.size;
+            if (lastAt !== undefined)
+                out.lastCaptureAt = lastAt;
+        }
+        catch {
+        }
+        if (mine !== undefined) {
+            if (mine.size === 0) {
+                out.foldedCount = 0;
+            }
+            else {
+                try {
+                    const enumeration = await this.listMemoryScopes();
+                    if (enumeration.supported) {
+                        const face = this.committedAuditFace();
+                        const headers = await face.listHeaders(enumeration.scopes);
+                        const productIds = headers.filter((h) => h.distilled !== undefined).map((h) => h.id);
+                        const folded = new Set();
+                        if (productIds.length > 0) {
+                            for (const p of await face.getByIds(productIds)) {
+                                for (const row of p.frontmatter.distilled?.inputs ?? [])
+                                    if (mine.has(row.id))
+                                        folded.add(row.id);
+                            }
+                        }
+                        out.foldedCount = folded.size;
+                    }
+                }
+                catch {
+                }
+            }
+        }
+        return out;
+    }
     committedAuditFace() {
         const b = this.backend;
         return b.restrictedAdoptionView?.({ audit: false }) ?? b.retrievalView?.() ?? this.backend;

package/dist/core/memory-engine/index.d.ts

@@ -1,4 +1,4 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, memoryRecallDisciplineSegment, entryFileHeadCarriesOrigin, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, memoryConsolidationWithheldNotice, MEMORY_CAPTURE_OPTOUT_NOTICE, memoryCaptureOptedOutNotice, memoryCaptureOptOutUnpersistedNotice, type ConsolidationCommitReceipt, type ConsolidationReconcileReport, type ConsolidationResolveReceipt, type ConsolidationPlanSummary, type ConsolidationPlanFoldEvidence, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, memoryRecallDisciplineSegment, entryFileHeadCarriesOrigin, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, memoryConsolidationRecommendedNotice, memoryConsolidationCommittedNotice, memoryConsolidationConflictNotice, memoryConsolidationIncompleteNotice, memoryConsolidationRefusedNotice, memoryConsolidationWithheldNotice, MEMORY_CAPTURE_OPTOUT_NOTICE, memoryCaptureOptedOutNotice, memoryCaptureOptOutUnpersistedNotice, type ConsolidationCommitReceipt, type ConsolidationReconcileReport, type ConsolidationResolveReceipt, type ConsolidationPlanSummary, type ConsolidationPlanFoldEvidence, type SessionMemoryStatus, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_INDEX_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type CleanMemorySearchHit, type ExposedMemorySearchHit, type MemoryGetDetails, type MemoryIndexDetails, type MemoryIndexRow, type CleanMemoryIndexRow, type ExposedMemoryIndexRow, } from "./tools.js";
 export { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_RECALL_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, memoryExposureIndexRow, parseMemoryExposureIndexRow, } from "./provenance-wording.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";

package/dist/core/memory-engine/layout.d.ts

@@ -407,11 +407,19 @@ export declare function listSessionCaptureOptOut(controlDir: string): Record<str
  * (`controlDir` + `sessionId` coordinates that outlive any live object — see the settlement handle
  * doc in prepare-task.ts), and a live store object cannot ride that lane; its migration needs its
  * own seam design and is registered here rather than half-built.
+ *
+ * DUAL FORM (#511 件2, additive): each leg may answer `T` OR `Promise<T>` — a SQL/remote carrier is
+ * async by nature and could not implement the sync-only trio at all. Every core consumption point
+ * awaits (or `.then`-chains where a sync public seat must stay sync-transparent), so a sync store's
+ * behavior is unchanged and an async store's Promise legs keep the exact same contract per leg:
+ * a rejected `mark` promise is held to the `"unpersisted"` refusal arm, a rejected `read` promise
+ * is the INDETERMINATE fault axis, a rejected `list` promise propagates as the enumeration failure.
+ * The File trio below keeps its synchronous signatures byte-identical.
  */
 export interface SessionCaptureRecordStore {
-    mark(sessionId: string, record: SessionCaptureOptOutRecord): SessionCaptureOptOutMarkOutcome;
-    read(sessionId: string): SessionCaptureOptOutRecord | undefined;
-    list(): Record<string, SessionCaptureOptOutRecord>;
+    mark(sessionId: string, record: SessionCaptureOptOutRecord): SessionCaptureOptOutMarkOutcome | Promise<SessionCaptureOptOutMarkOutcome>;
+    read(sessionId: string): SessionCaptureOptOutRecord | undefined | Promise<SessionCaptureOptOutRecord | undefined>;
+    list(): Record<string, SessionCaptureOptOutRecord> | Promise<Record<string, SessionCaptureOptOutRecord>>;
 }
 /** The core-default {@link SessionCaptureRecordStore}: the file trio over `controlDir` (single-
  *  process / single-host deployments keep today's carrier byte-identical). */

package/dist/core/roles.d.ts

@@ -9,6 +9,12 @@ export declare function resolveModel(ref: ModelRef, models?: Record<string, Mode
 export declare const DEFAULT_TIER_ORDER: readonly string[];
 /** CC 档位词 → sema 档位(内置固定,兼容层):fable/mythos→max · opus→pro · sonnet→flash · haiku→lite。 */
 export declare const CC_MODEL_TIER_ALIASES: Readonly<Record<string, string>>;
+/** the DISPLAY face of a string model ref: a CC tier ALIAS (haiku/sonnet/…) resolves to its
+ *  sema tier name (lite/flash/…) for labels — the alias verbatim reads as a strong claim about a
+ *  specific vendor's model while the actual routing may land anywhere ("haiku" showing over a
+ *  DeepSeek run, an operator field report). A non-alias string is the deployment's own model key — its
+ *  honest name — and passes through unchanged. Display only; routing (`expandTiers`) is untouched. */
+export declare function resolveModelDisplayLabel(ref: string): string;
 /**
  * Expand a deployment's tier bindings into the model catalog: every tier name (and every CC alias whose
  * tier resolves) becomes a catalog key pointing at the bound Model, so the ENTIRE resolve surface
@@ -22,14 +28,13 @@ export declare const CC_MODEL_TIER_ALIASES: Readonly<Record<string, string>>;
  * - an existing catalog key of the same name WINS (deployment SHADOW semantics, mirroring agents):
  *   a deployment that already ships a model literally named "pro" keeps it untouched;
  * - a binding may itself be a catalog name or a Model object (resolved through `resolveModel`);
- *   an unknown binding name throws at construction (config error surfaces at boot, not first use).
+ *   an unknown binding name throws at construction (config error surfaces at boot, not first use);
+ * - `"best"` (dynamic head-of-chain alias, CC `$L` parity) resolves to the FIRST tier in
+ *   {@link DEFAULT_TIER_ORDER} that carries a DIRECT binding — "the strongest model this deployment
+ *   actually bound", not a fixed tier — under the same SHADOW rule (a deployment catalog key named
+ *   `best` wins); with no bound known-order tier (or no tiers at all) the key stays absent and
+ *   `resolveModel("best")` refuses like any unknown ref.
  */
-/** the DISPLAY face of a string model ref: a CC tier ALIAS (haiku/sonnet/…) resolves to its
- *  sema tier name (lite/flash/…) for labels — the alias verbatim reads as a strong claim about a
- *  specific vendor's model while the actual routing may land anywhere ("haiku" showing over a
- *  DeepSeek run, an operator field report). A non-alias string is the deployment's own model key — its
- *  honest name — and passes through unchanged. Display only; routing (`expandTiers`) is untouched. */
-export declare function resolveModelDisplayLabel(ref: string): string;
 export declare function expandTiers(models: Record<string, Model> | undefined, tiers: Record<string, ModelRef> | undefined): Record<string, Model> | undefined;
 export interface ModelMention {
     /** The matched model name — always one of `allowedNames` — or undefined if none was found. */
@@ -44,8 +49,27 @@ export interface ModelMention {
  * pick *which configured model* to use, but can never inject an arbitrary `baseUrl`/`apiKey`/Model
  * (see design/11). Matches the first allow-listed mention; the rest of the text is returned cleaned.
  *
- * Typical use: `const { model, cleanedText } = parseModelMention(userMsg, Object.keys(deps.models));`
+ * **Case-INSENSITIVE, deliberately** — and deliberately UNLIKE the catalog, whose lookups
+ * ({@link resolveModel}) are exact. The two answer different questions and the asymmetry is the
+ * design, not an oversight: a chat mention is a HUMAN-typed UX surface where `@Opus` and `@opus` are
+ * the same intent, so intake is wide; a catalog key is a machine identifier a deployment declared, so
+ * lookup is exact. The join is safe because the wide half never widens the narrow one: this returns
+ * the allowlist's OWN canonical spelling (never the user's casing), so the value handed to
+ * `resolveModel` is always a key the deployment wrote. The only visible consequence is that a catalog
+ * carrying two keys differing ONLY in case is addressed by whichever the allowlist iterates last —
+ * `@x` cannot name both, and there is no spelling that disambiguates them.
+ *
+ * Typical use: `const { model, cleanedText } = parseModelMention(userMsg, Object.keys(runner.agentCatalog.models ?? {}));`
  * then `runTask({ objective: cleanedText, model })` (omit `model` to fall back to the default role).
+ *
+ * **Feed it the EXPANDED table.** The allowlist this takes is the host's own, and on a deployment that
+ * configured `RunnerDeps.tiers` the host's `deps.models` is NOT what the Runner resolves against: the
+ * constructor runs {@link expandTiers} once and keeps the expansion PRIVATE, so tier words and CC
+ * aliases (`pro`/`flash`/`opus`/`sonnet`/`best`/…) are catalog keys inside the Runner and absent from
+ * the host's table. Passing `Object.keys(deps.models)` therefore makes a user's `@opus` silently not
+ * match — the mention falls through as ordinary text and the task quietly runs on the default role.
+ * `runner.agentCatalog.models` is the expanded table (a per-read copy); a caller that has no Runner in
+ * hand can pre-expand its own with the exported {@link expandTiers}.
  */
 export declare function parseModelMention(text: string, allowedNames: Iterable<string>): ModelMention;
 /**
@@ -55,7 +79,10 @@ export declare function parseModelMention(text: string, allowedNames: Iterable<s
  * - `summarize` → `flash`(压缩本该便宜;flash 未绑沿降档链到 lite);
  * - `advisor` → 第一档(`ultra` 起,未绑降档到 max/pro——teacher 用最强的);
  * - `verifier` → `pro`;
- * - `subagent`/`team`/`synthesize` 无档位默认 = 走 FALLBACK 继承主模型(LLM 可经 model 参数自选档)。
+ * - `classifier` → `flash`(design/143 批2b:auto-mode 权限分类腿是便宜档;flash 未绑沿降档链到 lite);
+ * - `subagent`/`team`/`synthesize` 无档位默认 = 走 FALLBACK 继承主模型(LLM 可经 model 参数自选档);
+ * - `consolidate` 同样无档位默认,但它的 FALLBACK 刻意只有 `summarize` 一站(design/376,见
+ *   {@link FALLBACK} 的注):未配即响亮拒,不静默骑主模型。
  * 未配 tiers 的部署:catalog 无 TIERS_ACTIVE 标记 → 表整体 INERT,行为与从前逐字节一致
  * (即使 catalog 恰有裸模型名 `pro`/`flash` 也不入档位路由——INERT 靠配置成立,不靠键名运气)。
  */

package/dist/core/roles.js

@@ -18,7 +18,7 @@ export const CC_MODEL_TIER_ALIASES = {
     haiku: "lite",
 };
 export function resolveModelDisplayLabel(ref) {
-    return CC_MODEL_TIER_ALIASES[ref] ?? ref;
+    return Object.hasOwn(CC_MODEL_TIER_ALIASES, ref) ? CC_MODEL_TIER_ALIASES[ref] : ref;
 }
 const TIERS_ACTIVE = Symbol.for("sema.tiersActive");
 export function expandTiers(models, tiers) {
@@ -27,7 +27,7 @@ export function expandTiers(models, tiers) {
     const out = { ...models };
     out[TIERS_ACTIVE] = true;
     const bound = (name) => {
-        const b = tiers[name];
+        const b = Object.hasOwn(tiers, name) ? tiers[name] : undefined;
         return b === undefined ? undefined : resolveModel(b, models);
     };
     const resolveTier = (name) => {
@@ -44,20 +44,33 @@ export function expandTiers(models, tiers) {
         }
         return undefined;
     };
+    const shadowed = (key) => Object.hasOwn(out, key) && Boolean(out[key]);
+    const put = (key, m) => {
+        Object.defineProperty(out, key, { value: m, writable: true, enumerable: true, configurable: true });
+    };
     const tierNames = new Set([...DEFAULT_TIER_ORDER, ...Object.keys(tiers)]);
     for (const name of tierNames) {
-        if (out[name])
+        if (shadowed(name))
             continue;
         const m = resolveTier(name);
         if (m)
-            out[name] = m;
+            put(name, m);
     }
     for (const [alias, tier] of Object.entries(CC_MODEL_TIER_ALIASES)) {
-        if (out[alias])
+        if (shadowed(alias))
             continue;
         const m = resolveTier(tier);
         if (m)
-            out[alias] = m;
+            put(alias, m);
+    }
+    if (!shadowed("best")) {
+        for (const name of DEFAULT_TIER_ORDER) {
+            const m = bound(name);
+            if (m) {
+                put("best", m);
+                break;
+            }
+        }
     }
     return out;
 }

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

@@ -174,8 +174,8 @@ export async function prepareMemory(input) {
             };
             const onEngineIncident = (err) => deps.onError?.(err, { phase: "memory", sessionId });
             const adoptionRestricted = input.memoryPersistenceDeclared === false;
-            const armCaptureOptOut = (eng) => {
-                const standingRead = eng.sessionCaptureOptOutOrFault(sessionId);
+            const armCaptureOptOut = async (eng) => {
+                const standingRead = await 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 });
@@ -199,7 +199,7 @@ export async function prepareMemory(input) {
                     let anyFault = standingRead.fault;
                     let found = false;
                     for (const [ancestorId, ancestorDir] of rows) {
-                        const samePlane = eng.sessionCaptureOptOutOrFault(ancestorId);
+                        const samePlane = await eng.sessionCaptureOptOutOrFault(ancestorId);
                         if (samePlane.record !== undefined) {
                             found = true;
                             break;
@@ -208,7 +208,7 @@ export async function prepareMemory(input) {
                             anyFault = true;
                         if (ancestorDir !== undefined && ancestorDir !== eng.controlPlaneDir) {
                             try {
-                                const crossPlane = deps.memoryCaptureRecordStore !== undefined ? deps.memoryCaptureRecordStore({ controlDir: ancestorDir }).read(ancestorId) : readSessionCaptureOptOut(ancestorDir, ancestorId);
+                                const crossPlane = deps.memoryCaptureRecordStore !== undefined ? await deps.memoryCaptureRecordStore({ controlDir: ancestorDir }).read(ancestorId) : readSessionCaptureOptOut(ancestorDir, ancestorId);
                                 if (crossPlane !== undefined) {
                                     found = true;
                                     break;
@@ -230,7 +230,7 @@ export async function prepareMemory(input) {
                 }
                 let forkInherited = false;
                 if (!floored && !captureDeclared && standing === undefined && input.captureForkOrigin !== undefined) {
-                    const src = eng.sessionCaptureOptOutOrFault(input.captureForkOrigin);
+                    const src = await eng.sessionCaptureOptOutOrFault(input.captureForkOrigin);
                     if (src.record !== undefined)
                         forkInherited = true;
                     else if (src.fault && !captureIndeterminate) {
@@ -246,7 +246,7 @@ export async function prepareMemory(input) {
                         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`);
+                    const outcome = await 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");
@@ -287,14 +287,14 @@ export async function prepareMemory(input) {
             let injectFn;
             let harvestBoth;
             let toolPlanes;
-            const admitNothingOptsNow = () => {
+            const admitNothingOptsNow = async () => {
                 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);
+                const own = captureOptedOut ? { record: { at: 0, reason: "in-run state" }, fault: false } : await writeEngine.sessionCaptureOptOutOrFault(sessionId);
                 if (own.record !== undefined) {
                     return { admitNothing: { reason: `harvest admitted nothing: this session declared memory capture opt-out (memory.capture: "off")` } };
                 }
@@ -309,11 +309,11 @@ export async function prepareMemory(input) {
                 if (input.captureForkOrigin !== undefined && !ancestors.has(input.captureForkOrigin))
                     ancestors.set(input.captureForkOrigin, undefined);
                 for (const [ancestorId, ancestorDir] of ancestors) {
-                    const samePlane = writeEngine.sessionCaptureOptOutOrFault(ancestorId);
+                    const samePlane = await 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);
+                            crossPlane = deps.memoryCaptureRecordStore !== undefined ? await 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` } };
@@ -362,7 +362,7 @@ export async function prepareMemory(input) {
                 const personal = createPersonalEngine(personalBackendChosen);
                 const personalEngine = personal.engine;
                 const p = planes;
-                armCaptureOptOut(p.writePlane === "personal" ? personalEngine : projectEngine);
+                await 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: adoptionRestricted || captureOptedOut || captureIndeterminate, sessionId });
@@ -393,7 +393,7 @@ export async function prepareMemory(input) {
                 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, ...admitNothingOptsNow() });
+                    const writeReport = await writeFirst[0].harvest(writeFirst[1], { ...pollutedOpts(writeFirst[0]), sessionId, ...(await admitNothingOptsNow()) });
                     let readReport;
                     let readFailure;
                     try {
@@ -411,14 +411,14 @@ export async function prepareMemory(input) {
             else if (personalOnly) {
                 const personal = createPersonalEngine(choosePersonalBackend());
                 const personalEngine = personal.engine;
-                armCaptureOptOut(personalEngine);
+                await 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, ...admitNothingOptsNow() });
+                harvestBoth = async () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...(await admitNothingOptsNow()) });
                 toolPlanes = [
                     {
                         backend: retrievalBackend(personal.backend, adoptionRestricted || captureOptedOut || captureIndeterminate || memorySpec.writeScope === null),
@@ -439,14 +439,14 @@ export async function prepareMemory(input) {
                     ...captureStoreOpt(backend, identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot)),
                     ...(input.deps.memoryConsolidation !== undefined ? { consolidation: input.deps.memoryConsolidation } : {}),
                 });
-                armCaptureOptOut(engine);
+                await 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, ...admitNothingOptsNow() });
+                harvestBoth = async () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...(await admitNothingOptsNow()) });
                 toolPlanes = [
                     {
                         backend: retrievalBackend(backend, adoptionRestricted || captureOptedOut || captureIndeterminate || memorySpec.writeScope === null),
@@ -457,7 +457,7 @@ export async function prepareMemory(input) {
                     },
                 ];
             }
-            memoryWriteGateRef.current = (w) => {
+            memoryWriteGateRef.current = async (w) => {
                 if (readOnlyEngine !== undefined && readOnlyHandle !== undefined) {
                     const ro = readOnlyEngine.gateWrite(readOnlyHandle, w.key, w.content);
                     if (!ro.ok)
@@ -477,7 +477,7 @@ 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);
+                        const state = captureOptedOut ? { record: { at: 0, reason: "in-run state" }, fault: false } : await writeEngine.sessionCaptureOptOutOrFault(sessionId);
                         if (state.record !== undefined || state.fault) {
                             return {
                                 ok: false,
@@ -555,12 +555,19 @@ export async function prepareMemory(input) {
                 inject: injectFn,
                 harvest: harvestSafe,
                 captureOptOut: {
-                    optedOut: () => captureOptedOut || writeEngine.sessionCaptureOptOutOrFault(sessionId).record !== undefined,
+                    optedOut: () => {
+                        if (captureOptedOut)
+                            return true;
+                        const r = writeEngine.sessionCaptureOptOutOrFault(sessionId);
+                        return r instanceof Promise ? r.then((s) => s.record !== undefined) : r.record !== undefined;
+                    },
                     indeterminate: () => {
                         if (captureOptedOut)
                             return false;
-                        const s = writeEngine.sessionCaptureOptOutOrFault(sessionId);
-                        return s.record === undefined && (captureIndeterminate || s.fault);
+                        const r = writeEngine.sessionCaptureOptOutOrFault(sessionId);
+                        return r instanceof Promise
+                            ? r.then((s) => s.record === undefined && (captureIndeterminate || s.fault))
+                            : r.record === undefined && (captureIndeterminate || r.fault);
                     },
                     flip: async (reason) => {
                         const entitlement = await resolveCaptureEntitlementFresh();
@@ -576,7 +583,7 @@ export async function prepareMemory(input) {
                             throw e;
                         }
                         const trimmed = reason?.trim();
-                        const outcome = writeEngine.markSessionCaptureOptOut(sessionId, trimmed !== undefined && trimmed !== "" ? `host flip verb: ${trimmed.slice(0, 200)}` : "host flip verb");
+                        const outcome = await 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");

package/dist/core/runner/prepare-task.d.ts

@@ -550,8 +550,9 @@ export interface Prepared {
          * the memory session mounted.
          */
         captureOptOut?: {
-            optedOut: () => boolean;
-            indeterminate: () => boolean;
+            /** Dual form: a sync capture store answers synchronously; a Promise-form store answers a Promise. `await` is correct on either arm. */
+            optedOut: () => boolean | Promise<boolean>;
+            indeterminate: () => boolean | Promise<boolean>;
             flip: (reason?: string) => Promise<{
                 outcome: "created" | "existed";
             }>;
@@ -1120,7 +1121,8 @@ export interface PrepareResume {
      *  to restore — prepare rebuilds the per-task env via `deps.executionEnvFactory` then `resumeVM(snapshotId)`
      *  + `postResumeInit()` (instead of running on a fresh, empty env). Threaded HERE (not via `ResumeTaskConfig`)
      *  so the factory stays a deployment-level `RunnerDeps` capability and never pollutes `TaskSpec` — preserving
-     *  the "untrusted caller can't inject an env" red line (remote-env.ts:234, code-ready council round-2). */
+     *  the "untrusted caller can't inject an env" red line ({@link import("../remote-env.js").ExecutionEnvFactory}'s
+   *  own contract states it: "Lives on `RunnerDeps` (deployment-level) — NOT on `TaskSpec`"; code-ready council round-2). */
     workspaceHandle?: import("../remote-env.js").WorkspaceHandle;
     /**
      * design/174 — the call id of the CONTENT ask whose answer an operator's approval was spent on, when