@sema-agent/core 5.24.0 → 5.26.0

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

@@ -34,6 +34,11 @@ export function buildMemoryInstruction(memoryDir, instructionFileName) {
 }
 export const MEMORY_RECALL_DISCIPLINE = "Before answering questions about earlier work, decisions, dates, people, or the user's preferences, look them up: `memory_search` finds entries by keyword and `memory_get` reads a full entry — the injected memory index only lists what exists. When a lookup comes up empty, say that you checked memory and found nothing instead of guessing.";
 export const MEMORY_PREFERENCE_DISCIPLINE = "When the user confirms a stored preference or fact still holds, refresh that entry's `last-confirmed: <YYYY-MM-DD>` frontmatter line (add it when absent). When you save a preference, add an `applies-when: <context>` frontmatter line naming when it applies. Both are plain frontmatter lines — write them yourself; nothing fills them in for you.";
+export const MEMORY_ANNOUNCEMENT_READONLY_PLANE_CODA = "The notices immediately above concern a READ-ONLY memory store: any guidance in them to record, update, or tombstone an entry cannot be applied to that store this session — surface it to the user instead of claiming it done.";
+export const MEMORY_ANNOUNCEMENT_READONLY_CODA = "The memory store itself is not writable this session, so any guidance above to record, update, or tombstone a memory entry cannot be applied here — surface it to the user instead of claiming it done.";
+export const MEMORY_READONLY_NOTICE = `# Memory
+
+You have READ-ONLY access to persistent memory in this session: stored notes are available below, but this session has no memory write channel — the engine will not accept writes into the memory store. If the user asks you to remember something for later, say plainly that you cannot save it in this session — never claim to have noted or remembered it.`;
 export const MEMORY_INDEX_MAX_LINES = 200;
 export const MEMORY_INDEX_MAX_BYTES = 25 * 1024;
 export const STUB_ARCHIVED_LINE = "[body archived — request hydration by listing the slug in memory/.hydrate]";
@@ -41,6 +46,7 @@ export const DEFAULT_MAX_MEMORY_FILES = 500;
 export const DEFAULT_HARVEST_DEADLINE_MS = 5_000;
 export const DEFAULT_HARVEST_FILE_BUDGET = 2_000;
 export const MASS_DELETION_FUSE_RATIO = 0.5;
+let indexCaptureSeq = 0;
 export class MemoryEngine {
     backend;
     memoryDir;
@@ -425,6 +431,7 @@ export class MemoryEngine {
     inject(handle, opts) {
         const writeChannel = handle.writeScope !== null && opts?.writeToolMounted !== false;
         const instruction = writeChannel ? buildMemoryInstruction(handle.writableRoot) : "";
+        const readOnlyNotice = handle.writeScope === null ? MEMORY_READONLY_NOTICE : undefined;
         const indexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
         const onDisk = handle.indexOnDiskUntrusted === true ? undefined : readSafe(indexPath);
         const indexText = onDisk !== undefined && onDisk.trim() !== "" ? onDisk : handle.indexText;
@@ -440,14 +447,17 @@ export class MemoryEngine {
             if (drained.queue.length > 0 || drained.folded > 0) {
                 announcements = drained.queue;
                 announceBlock = renderAnnouncements(drained.queue, drained.folded);
+                if (handle.writeScope === null)
+                    announceBlock = `${announceBlock}\n\n${MEMORY_ANNOUNCEMENT_READONLY_PLANE_CODA}`;
             }
         }
         catch (err) {
             this.discloseAnnounceFailure("inject drain", err);
         }
-        const block = [instruction, index, announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        const block = [instruction || readOnlyNotice, index, announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
         return {
             instruction,
+            ...(readOnlyNotice !== undefined ? { readOnlyNotice } : {}),
             ...(index !== undefined ? { index } : {}),
             ...(announcements !== undefined ? { announcements } : {}),
             ...(announceBlock !== undefined ? { announceBlock } : {}),
@@ -459,8 +469,14 @@ export class MemoryEngine {
         const root = handle.writableRoot;
         if (canonicalPath !== root && !canonicalPath.startsWith(`${root}${sep}`))
             return { ok: true };
-        if (handle.writeScope === null)
-            return { ok: true };
+        if (handle.writeScope === null) {
+            return {
+                ok: false,
+                code: "read_only_layering",
+                reason: "this session's memory is read-only (no write scope) — the engine does not accept writes into the memory domain. Nothing was written.",
+                muted: false,
+            };
+        }
         const findings = [];
         const nameFinding = scanMemoryFileName(relative(root, canonicalPath));
         if (nameFinding !== undefined)
@@ -512,10 +528,12 @@ export class MemoryEngine {
             warnings: [],
         };
         const writeScope = handle.writeScope;
-        if (writeScope === null) {
+        if (writeScope === null || opts?.admitNothing !== undefined) {
             const roFindings = this.backend.drainInboundFindings?.();
             if (roFindings !== undefined && roFindings.length > 0)
                 report.inboundFindings = roFindings;
+            if (opts?.admitNothing !== undefined)
+                report.warnings.push(opts.admitNothing.reason);
             return report;
         }
         try {
@@ -656,16 +674,18 @@ export class MemoryEngine {
             const indexNow = readSafe(pollutedIndexPath);
             if (indexNow === undefined || indexNow === handle.indexText)
                 return;
+            let indexCaptureLanded = false;
             try {
                 const dest = join(this.controlDir, QUARANTINE_DIR, `${this.now()}-polluted-${MEMORY_INDEX_FILENAME}`);
                 ensureDirExists(dirname(dest));
-                writeFileSync(dest, indexNow, "utf8");
+                writeFileSync(dest, indexNow, { encoding: "utf8", flag: "wx" });
+                indexCaptureLanded = true;
             }
             catch {
             }
             try {
                 writeFileNoFollow(pollutedIndexPath, handle.indexText);
-                report.warnings.push("memory index restored to its pre-session state — this session's index additions were not retained (session polluted; the removed text was captured to quarantine)");
+                report.warnings.push(`memory index restored to its pre-session state — this session's index additions were not retained (session polluted; ${indexCaptureLanded ? "the removed text was captured to quarantine" : "the quarantine capture did NOT land — the removed text is gone"})`);
             }
             catch (err) {
                 report.warnings.push(`memory index could NOT be restored to its pre-session state: ${err instanceof Error ? err.message : String(err)}`);
@@ -1225,7 +1245,20 @@ export class MemoryEngine {
         try {
             const dest = join(this.controlDir, QUARANTINE_DIR, `${this.now()}-${MEMORY_INDEX_FILENAME}`);
             ensureDirExists(dirname(dest));
-            writeFileSync(dest, text, "utf8");
+            let landed = false;
+            for (let attempt = 0; !landed && attempt < 10; attempt++) {
+                const candidate = attempt === 0 ? dest : `${dest}.${attempt}`;
+                try {
+                    writeFileSync(candidate, text, { encoding: "utf8", flag: "wx" });
+                    landed = true;
+                }
+                catch (err) {
+                    if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
+                        throw err;
+                }
+            }
+            if (!landed)
+                writeFileSync(`${dest}.${process.pid}.${indexCaptureSeq++}`, text, { encoding: "utf8", flag: "wx" });
             captured = true;
         }
         catch (err) {

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

@@ -1,4 +1,4 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, 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, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, 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, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.js";

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

@@ -1,4 +1,4 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, 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, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, 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, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.js";

package/dist/core/permission-rule-consent.js

@@ -281,8 +281,15 @@ export async function prepareCcImport(opts) {
                 skipped.push({ rule: String(entry), reason: "settings entry is not a string" });
                 continue;
             }
-            if (!entry.startsWith("Bash("))
+            if (!entry.startsWith("Bash(")) {
+                const reason = /^[A-Za-z][A-Za-z0-9_]*\(.*\)$/.test(entry)
+                    ? "unsupported.tool: only Bash(...) command rules import in v1 — this entry stays in the settings file, unimported"
+                    : /^[A-Za-z][A-Za-z0-9_-]*$/.test(entry)
+                        ? "unsupported.form: a bare tool-name entry is a name-set item, not a command rule — it stays in the settings file, unimported"
+                        : "unsupported.form: not a Bash(...) command rule — it stays in the settings file, unimported";
+                skipped.push({ rule: entry, reason });
                 continue;
+            }
             const parsed = parseAllowRuleText(entry);
             if ("reject" in parsed) {
                 skipped.push({ rule: entry, reason: `${parsed.reject.code}: ${parsed.reject.message}` });

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

@@ -112,6 +112,15 @@ export declare const ORG_ADJUDICATION_TIMEOUT_MS = 15000;
 export declare function settleOrgVerdictWithin<T>(p: Promise<T>, fallback: T, opts: {
     signal?: AbortSignal;
     timeoutMs: number;
+    /**
+     * backlog #136④ — which arm WON, reported at the moment it won. A consumer that wants to tell a
+     * cancelled wait from an unreadable provider cannot get that by sampling `signal.aborted` after
+     * the await: a cancellation queued between the settlement and the continuation reads identically
+     * to one that actually ended the wait, and the operator-facing account would name the wrong
+     * cause. Called at most once, before `p` resolves, and only for the two non-provider arms —
+     * absent call ⇒ the awaited promise itself settled.
+     */
+    onFallback?: (cause: "aborted" | "timeout") => void;
 }): Promise<T>;
 /** The `decisionReason` of a decision an ORG RULE produced (a deny, or a non-dismissable ask). Same
  *  single-spelling contract as {@link ORG_UNAVAILABLE_DECISION_REASON}. */

package/dist/core/permission-rule-org.js

@@ -11,22 +11,29 @@ export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
 export function settleOrgVerdictWithin(p, fallback, opts) {
     return new Promise((resolve) => {
         let settled = false;
-        const finish = (v) => {
+        const finish = (v, cause) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
             opts.signal?.removeEventListener("abort", onAbort);
+            if (cause !== undefined) {
+                try {
+                    opts.onFallback?.(cause);
+                }
+                catch {
+                }
+            }
             resolve(v);
         };
-        const onAbort = () => finish(fallback);
-        const timer = setTimeout(() => finish(fallback), opts.timeoutMs);
+        const onAbort = () => finish(fallback, "aborted");
+        const timer = setTimeout(() => finish(fallback, "timeout"), opts.timeoutMs);
         if (opts.signal?.aborted === true) {
-            finish(fallback);
+            finish(fallback, "aborted");
             return;
         }
         opts.signal?.addEventListener("abort", onAbort);
-        p.then(finish, () => finish(fallback));
+        p.then((v) => finish(v), () => finish(fallback));
     });
 }
 export const ORG_RULE_DECISION_REASON = "org_rule";

package/dist/core/runner/compaction-call-options.d.ts

@@ -95,10 +95,10 @@ export declare function buildStaleOffloadPointer(toolName: string, ref: string,
  * The session transcript is NEVER touched — this runs on the outgoing {@link Context} only.
  * Error results, image/document-bearing blocks' non-text parts, already-offloaded previews, and
  * replacements that would save < `minSavingsChars` are left verbatim. The full text is persisted
- * under a deterministic content-digested ref (design/30's mint helper over
- * `<toolCallId>_s<sha256-12 of the text>` — write-once, so re-projection on every turn re-puts a
- * no-op; the digest exists because tool-call ids carry no cross-turn uniqueness contract),
- * readable back via `read_tool_result`.
+ * under a deterministic content-digested ref (`buildToolResultRef(sessionId, toolCallId,
+ * toolResultContentSegment(text))` — a `~`-separated three-segment mint whose digest is its OWN
+ * segment; write-once, so re-projection on every turn re-puts a no-op; the digest exists because
+ * tool-call ids carry no cross-turn uniqueness contract), readable back via `read_tool_result`.
  */
 export declare function projectStaleToolResults(context: Context, cfg: ResolvedStaleToolResultOffload, store: ToolResultStore, sessionId: string, 
 /** Run-scoped cache of refs already persisted by THIS run (独立复审 MED,已修): without it the

package/dist/core/runner/compaction-call-options.js

@@ -1,6 +1,5 @@
-import { createHash } from "node:crypto";
 import { emitTrace } from "../trace.js";
-import { buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX } from "../tool-result-store.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "../tool-result-store.js";
 export function buildWorkingFileAttachments(spec, prepared) {
     if (spec.compaction?.attachWorkingFiles === false || !prepared.readTaskFile)
         return undefined;
@@ -73,13 +72,13 @@ export async function projectStaleToolResults(context, cfg, store, sessionId, wr
             const text = toolResultText(msg);
             if (text.startsWith(PERSISTED_OUTPUT_PREFIX))
                 continue;
-            const ref = buildToolResultRef(sessionId, `${msg.toolCallId}_s${createHash("sha256").update(text, "utf8").digest("hex").slice(0, 32)}`);
+            const ref = buildToolResultRef(sessionId, msg.toolCallId, toolResultContentSegment(text));
             const pointer = buildStaleOffloadPointer(toolName, ref, text.length);
             if (text.length - pointer.length < cfg.minSavingsChars)
                 continue;
             if (!writtenRefs.has(ref)) {
                 try {
-                    await store.put(ref, text);
+                    await store.put(ref, text, toolResultProvenanceOf(sessionId));
                     writtenRefs.add(ref);
                 }
                 catch {

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

@@ -1,11 +1,3 @@
-/**
- * design/157 B15 一期 (P6 相位抽取) — prepareTask's long-term-memory phase, verbatim. The ONLY inputs
- * are the five fields below (measured, not assumed: spec.memory + deps.* + the three ambient values);
- * the ONLY outputs are the memory-engine session and the composed injection block. `deps.onError`
- * call order and payloads are part of the contract (event-sequence snapshot pin recorded across the
- * move). Throws pass through unchanged: a `config.memory_*`-coded violation is a DELIBERATE refusal
- * (design/142 S1 硬门) and must keep failing prepare loudly.
- */
 import type { BeforeWriteHook, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import type { Prepared } from "./prepare-task.js";
 export interface PrepareMemoryInput {
@@ -18,15 +10,42 @@ export interface PrepareMemoryInput {
     };
     /**
      * #181-F5 — whether a tool NAMED `Write` (the tool the CC `# Memory` instruction names) is on the
-     * ASSEMBLED roster this run and not excluded: prepare-task's
-     * `tools.some(t => t.name === "Write") && !exclude.includes("Write")`. Name occupancy IS the channel
-     * declaration, so the hands band is only one of the arms that can satisfy it — a hands-less run that
-     * mounts its own `Write` counts, and an `excludeTools: ["Write"]` run reads as unmounted whatever the
-     * hands band did. Threaded into `engine.inject` so a run with a writable memory scope but no write
-     * channel is not instructed to call a tool that is not on its roster; the RB-276 index seed follows
-     * the same gate (it exists only to satisfy the Write tool's unread-overwrite guard).
+     * ASSEMBLED roster this run, not excluded, AND can actually REACH the host-side memory root:
+     * prepare-task's `tools.some(t => t.name === "Write") && !exclude.includes("Write")` plus the
+     * remote-env conjunct (a hand-band Write on a remote ExecutionEnv writes the sandbox filesystem,
+     * not the host memory root — it does not count unless the deployment declares the mount shared
+     * via `memoryPersistenceCapable: true`). Name occupancy IS the channel declaration for the local
+     * arms — a hands-less run that mounts its own `Write` counts, and an `excludeTools: ["Write"]`
+     * run reads as unmounted whatever the hands band did. Threaded into `engine.inject` so a run with
+     * a writable memory scope but no write channel is not instructed to call a tool that is not on
+     * its roster (or cannot reach the store); the RB-276 index seed follows the same gate.
      */
     writeToolsMounted: boolean;
+    /**
+     * The session-wide persistence verdict: `TaskSpec.memoryPersistenceCapable` (the deployment's own
+     * statement — the only honest channel for a custom memory writer persisting through its closure,
+     * which no inference can see) when set, else the KNOWN-store-path inference: a mounted,
+     * non-excluded file-write tool (Write/Edit/NotebookEdit) or a write-capable shell. A generic
+     * write-effect tool does NOT count — a mail sender's side effect is not a memory store, and
+     * counting it re-opened the silent-confabulation hole. `false` ⇒ this phase mounts
+     * {@link MEMORY_READONLY_NOTICE} where the engine is silent.
+     */
+    rosterCanPersist: boolean;
+    /**
+     * The raw `TaskSpec.memoryPersistenceCapable` DECLARATION, kept separate from the composed
+     * {@link rosterCanPersist} verdict because the two drive different arms:
+     * - `true` (declared) RETRACTS the engine's own read-only notice — the deployment vouches for a
+     *   persistence channel the engine cannot see (a custom writer persisting through its closure),
+     *   so "you cannot save" beside it would be a false claim. An INFERRED-true roster must NOT
+     *   retract: over a writeScope-null layering the engine will refuse those very file writes
+     *   (`read_only_layering`), so the roster's write tools prove nothing about THIS store and
+     *   stripping the notice re-opens the silent-confabulation hole for exactly the state the
+     *   notice was built for.
+     * - `false` (declared) also CLOSES the file-tool write channel into the writable memory root
+     *   (the write gate refuses), so the mounted notice's "the engine will not accept writes into
+     *   the memory store" stays a true statement instead of a disclosure the store then contradicts.
+     */
+    memoryPersistenceDeclared?: boolean;
     /**
      * design/178 ②-1 — whether the `memory_search`/`memory_get` pair PASSED its early mount conjuncts
      * (exclusion + name occupancy, decided in prepare-task BEFORE this phase). True ⇒ this phase builds

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

@@ -1,8 +1,9 @@
+import { sep } from "node:path";
 import { admitMemoryScopes } from "../memory-admission.js";
-import { adoptLegacyRepoDirs, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.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_PREFERENCE_DISCIPLINE, MEMORY_RECALL_DISCIPLINE, MemoryEngine } from "../memory-engine/engine.js";
+import { MEMORY_ANNOUNCEMENT_READONLY_CODA, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_RECALL_DISCIPLINE, MemoryEngine } from "../memory-engine/engine.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";
@@ -113,10 +114,12 @@ export async function prepareMemory(input) {
             }
             const personalMemoryDir = derivePersonalMemoryDir(engineRoot);
             const personalControlDir = derivePersonalControlDir(engineRoot);
-            const createPersonalEngine = () => {
-                const personalBackend = typeof pinned === "string" && pinned
-                    ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir })
-                    : backend;
+            const effectiveControlDir = (b, fallback) => {
+                const pinnedCtl = b.controlPlaneRoot;
+                return typeof pinnedCtl === "string" && pinnedCtl ? pinnedCtl : 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 }),
                     backend: personalBackend,
@@ -131,17 +134,43 @@ export async function prepareMemory(input) {
             };
             let writeEngine;
             let writeHandle;
+            let readOnlyEngine;
+            let readOnlyHandle;
             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)" } }
+                : {};
             if (dual) {
+                const personalBackendChosen = choosePersonalBackend();
+                {
+                    const projCtl = effectiveControlDir(backend, identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot));
+                    const persCtl = effectiveControlDir(personalBackendChosen, personalControlDir);
+                    const overlap = (a, b) => isContainedIn(a, b) || isContainedIn(b, a);
+                    const refuse = (what, a, b) => {
+                        const e = new Error(`memory dual-root configuration error: ${what} overlap (${canonicalize(a)} vs ${canonicalize(b)}) — the planes' data roots and control planes must all be disjoint.`);
+                        e.code = "config.memory_dual_root_overlap";
+                        throw e;
+                    };
+                    if (overlap(memoryDir, personalMemoryDir))
+                        refuse("the project and personal memory roots", memoryDir, personalMemoryDir);
+                    if (overlap(projCtl, persCtl))
+                        refuse("the project and personal control planes", projCtl, persCtl);
+                    for (const [ctlName, ctl] of [["project control plane", projCtl], ["personal control plane", persCtl]]) {
+                        for (const [rootName, dataRoot] of [["project memory root", memoryDir], ["personal memory mount", personalMemoryDir]]) {
+                            if (overlap(ctl, dataRoot))
+                                refuse(`the ${ctlName} and the ${rootName}`, ctl, dataRoot);
+                        }
+                    }
+                }
                 const projectEngine = new MemoryEngine({
                     backend,
                     memoryDir,
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
                 });
-                const personal = createPersonalEngine();
+                const personal = createPersonalEngine(personalBackendChosen);
                 const personalEngine = personal.engine;
                 const p = planes;
                 const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null);
@@ -149,6 +178,8 @@ export async function prepareMemory(input) {
                 const writeIsPersonal = p.writePlane === "personal";
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
+                readOnlyEngine = writeIsPersonal ? projectEngine : personalEngine;
+                readOnlyHandle = writeIsPersonal ? projectHandle : personalHandle;
                 injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted }));
                 toolPlanes = [
                     {
@@ -167,7 +198,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 });
+                    const writeReport = await writeFirst[0].harvest(writeFirst[1], { ...pollutedOpts(writeFirst[0]), sessionId, ...admitNothingOpts });
                     let readReport;
                     let readFailure;
                     try {
@@ -183,13 +214,13 @@ export async function prepareMemory(input) {
                 };
             }
             else if (personalOnly) {
-                const personal = createPersonalEngine();
+                const personal = createPersonalEngine(choosePersonalBackend());
                 const personalEngine = personal.engine;
                 const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
                 writeEngine = personalEngine;
                 writeHandle = handle;
                 injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted });
-                harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId });
+                harvestBoth = () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
                         backend: retrievalBackend(personal.backend),
@@ -210,7 +241,7 @@ export async function prepareMemory(input) {
                 writeEngine = engine;
                 writeHandle = handle;
                 injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted });
-                harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId });
+                harvestBoth = () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...admitNothingOpts });
                 toolPlanes = [
                     {
                         backend: retrievalBackend(backend),
@@ -220,7 +251,25 @@ export async function prepareMemory(input) {
                     },
                 ];
             }
-            memoryWriteGateRef.current = (w) => writeEngine.gateWrite(writeHandle, w.key, w.content);
+            memoryWriteGateRef.current = (w) => {
+                if (readOnlyEngine !== undefined && readOnlyHandle !== undefined) {
+                    const ro = readOnlyEngine.gateWrite(readOnlyHandle, w.key, w.content);
+                    if (!ro.ok)
+                        return ro;
+                }
+                if (input.memoryPersistenceDeclared === false) {
+                    const root = writeHandle.writableRoot;
+                    if (w.key === root || w.key.startsWith(`${root}${sep}`)) {
+                        return {
+                            ok: false,
+                            code: "read_only_layering",
+                            reason: `memory persistence is declared unavailable for this session (memoryPersistenceCapable: false) — writes into the memory store are refused. Nothing was written.`,
+                            muted: false,
+                        };
+                    }
+                }
+                return writeEngine.gateWrite(writeHandle, w.key, w.content);
+            };
             const harvestSafe = async (phase = "terminal") => {
                 try {
                     const report = await harvestBoth();
@@ -261,7 +310,10 @@ export async function prepareMemory(input) {
                 memoryTools = createMemoryEngineTools({ planes: toolPlanes });
         }
         catch (err) {
-            if (typeof err.code === "string" && (err.code.startsWith("config.memory_scope") || err.code.startsWith("config.memory_project"))) {
+            if (typeof err.code === "string" &&
+                (err.code.startsWith("config.memory_scope") ||
+                    err.code.startsWith("config.memory_project") ||
+                    err.code === "config.memory_dual_root_overlap")) {
                 throw err;
             }
             deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "memory", sessionId });
@@ -275,15 +327,31 @@ export async function prepareMemory(input) {
     }
     if (memoryEngineSession) {
         const injection = memoryEngineSession.inject();
-        if (injection.block.trim())
-            memoryBlock = injection.block;
+        let blockBody = injection.block;
+        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 !== "") {
+            blockBody = [MEMORY_READONLY_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        }
+        else if (input.memoryPersistenceDeclared === true && injection.readOnlyNotice !== undefined) {
+            blockBody = [injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+        }
+        if (!input.rosterCanPersist &&
+            (injection.announceBlock?.trim() ?? "") !== "" &&
+            blockBody.includes(injection.announceBlock) &&
+            !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_READONLY_CODA)) {
+            blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_READONLY_CODA}`;
+        }
+        if (blockBody.trim())
+            memoryBlock = blockBody;
         if (memoryTools !== undefined) {
             memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_RECALL_DISCIPLINE}` : MEMORY_RECALL_DISCIPLINE;
         }
-        if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted) {
+        if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted && input.rosterCanPersist) {
             memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_PREFERENCE_DISCIPLINE}` : MEMORY_PREFERENCE_DISCIPLINE;
         }
-        if (memoryBlock !== undefined && injection.indexSeed !== undefined)
+        if (memoryBlock !== undefined && injection.indexSeed !== undefined && input.rosterCanPersist)
             seedFiles = [injection.indexSeed];
     }
     return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, ...(memoryTools !== undefined ? { memoryTools } : {}), ...(seedFiles !== undefined ? { seedFiles } : {}) };

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

@@ -28,6 +28,8 @@ import { type WiringManifest } from "../wiring-manifest.js";
 import type { ActiveWorktreeSession, AgentMessage, AgentTool, ExecutionEnv } from "../../internal/harness.js";
 import type { NestedUsageAccum, RunnerDeps, TaskEvent, TaskLimits, TaskResult, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
 import type { RepairBundle } from "../../agents/repair-loop.js";
+/** Test seam (mirrors `__resetBashTimeoutAnnouncements`): never called by production code. */
+export declare function __resetMaterializeEnvAnnouncements(): void;
 /**
  * design/164 — validate `TaskSpec.limits` at the door and return it unchanged.
  *