@sema-agent/core 5.25.0 → 5.27.0

package/dist/core/memory-vector.js

@@ -1,8 +1,18 @@
+const CJK_RUN = /[\u3040-\u30FF\u31F0-\u31FF\u3400-\u4DBF\u4E00-\u9FFF\uAC00-\uD7A3\uF900-\uFAFF]+/g;
 export function termSet(s) {
-    return new Set(s
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter(Boolean));
+    const lower = s.toLowerCase();
+    const out = new Set();
+    for (const run of lower.split(/[^a-z0-9]+/))
+        if (run)
+            out.add(run);
+    for (const m of lower.matchAll(CJK_RUN)) {
+        const chars = [...m[0]];
+        for (const c of chars)
+            out.add(c);
+        for (let i = 0; i + 1 < chars.length; i++)
+            out.add(chars[i] + chars[i + 1]);
+    }
+    return out;
 }
 export function jaccardDistance(query, text) {
     const t = termSet(text);

package/dist/core/memory.js

@@ -1,5 +1,6 @@
 import { uuidv7 } from "../internal/harness.js";
 import { parseScopeKey } from "./memory-engine/scope-contract.js";
+import { termSet } from "./memory-vector.js";
 import { sanitizeUntrustedText } from "./untrusted-text.js";
 export function supportsConsolidation(store) {
     return (typeof store.searchScored === "function" &&
@@ -148,12 +149,6 @@ export function guardedMemoryStore(inner, utilityGate) {
 function renderBullet(e) {
     return `- (${e.ts} UTC) ${e.text}`;
 }
-function termSet(s) {
-    return new Set(s
-        .toLowerCase()
-        .split(/[^a-z0-9]+/)
-        .filter(Boolean));
-}
 export class InMemoryMemoryStore {
     byScope = new Map();
     cursorByScope = new Map();

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-model.d.ts

@@ -120,6 +120,53 @@ export declare const MAX_RULE_TEXT_CHARS = 512;
  * an EXACT rule naming a whole interpreter command line stays legal, since it authorizes one command.
  */
 export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
+/**
+ * design/185 §1 — the reviewed command/subcommand grammar the PREFIX suggestion is generated from
+ * (exactly the "reviewed command/subcommand grammar" the generator's history note names as the one
+ * thing that would let it produce a prefix).
+ *
+ * A flat set of BODIES — word sequences, each at least two words. A prefix candidate exists for a
+ * command iff some body here is a word-boundary prefix of its folded form, and the LONGEST hit wins:
+ * the deeper body is the narrower rule, so listing (or not listing) a deeper body is how this table
+ * sets suggestion granularity per branch. No groups, no denylist, and no fallback arm: a head outside
+ * the table, an unreviewed subcommand, a runtime-defined name (a git alias, a `git-<x>`/`cargo-<x>`
+ * external subcommand, a gh extension, a kubectl plugin), a flag or operand in a body position and a
+ * quoted token all fail the same way — by not being listed. Closure comes from positive enumeration
+ * itself, never from an exclusion list racing names that only exist at runtime.
+ *
+ * Review criteria — every row must pass BOTH axes (the same principle as the interpreter refusal
+ * above: the rule text must not read narrower than what it grants):
+ *  · "runs what it is told to": a body whose use is fetching or naming a program to execute
+ *    (`npm exec`, `docker run`, `kubectl exec`, `gh extension`, `git submodule foreach`, the install
+ *    family) is refused — one click cannot be read as having granted arbitrary execution. Running the
+ *    WORKSPACE'S OWN pinned content (`npm run`, `npm ci`, `cargo run`, `cargo test`) is inside the
+ *    boundary: the scripts and lockfiles those execute are checked into the repository being worked on.
+ *  · "rewrites what others execute": a body whose main use is writing configuration that changes what
+ *    OTHER commands later run (`git config` — hooksPath/pager/alias; `kubectl config` —
+ *    exec-credential; `npm config`/`npm set` — script-shell; `go env` — persisted GOFLAGS/GOBIN) is
+ *    refused — its readable width and its real width differ by a whole composition surface.
+ * Past both axes there is deliberately NO "dangerousness" axis: `git push:*` and `git rebase:*` are
+ * wide but readable, and a person nodding at that text is granting exactly that.
+ *
+ * Residual width, stated rather than hidden (a reviewed trade, not an oversight): a prefix rule
+ * admits ANY arguments after its body, and some listed bodies carry flags that name a program to
+ * execute (`go build`/`go test`/`go vet -toolexec`, `git fetch --upload-pack`, `git rebase -x`,
+ * `git grep -O`, `git push --receive-pack`). The axes judge a body's MAIN use, not every flag —
+ * per-flag grammar is the road this module's history rejected twice, and applied consistently it
+ * would empty the table. Three standing fences hold that residue: the org deny/ask layer runs ahead
+ * of the rule lane and cannot be silenced by it; a mandated ask (egress/irreversibility marks,
+ * shellGate:"always") is not rule-clearable either; and the narrower exact candidate — plus minting
+ * no rule at all — is always on the same card.
+ *
+ * Maintenance: adding a row is a reviewed change — keep the per-group reasoning beside it current.
+ * The integrity pins (every body ≥ 2 words, lowercase word shape, no interpreter heads, no
+ * duplicates) are enforced by this module's test suite. This table and the read-only classifier's
+ * allowlists are DIFFERENT instruments and must never be merged or cross-referenced: that one is a
+ * machine auto-allow face whose criterion is "provably read-only"; this one is a human suggestion
+ * face whose criterion is "width a person can read off the rule text". One guards against a machine
+ * loosening; the other against a person being misled.
+ */
+export declare const SUGGESTION_LEXICON: readonly string[];
 /**
  * Parse one rule text into its canonical shape, or refuse it with a reason.
  *
@@ -184,11 +231,29 @@ export interface RuleSuggestion {
 /**
  * The 1-2 candidates offered on an approval card for `command`.
  *
- * The exact form (this whole command line) is always offered when the command is matchable at all. A
- * prefix form is offered only when it is a shape a person can read as narrow: the upstream multi-word
- * convention (`git status`, `npm run`) is preferred over a bare program name, and no prefix at all is
- * offered for an interpreter head — that candidate would be refused by the validator anyway, and
- * offering a candidate the store will not accept is worse than offering one fewer.
+ * **Array order is a documented CONTRACT, not an implementation accident**: display order = array
+ * order = narrowest first. The EXACT form (this whole command line) is always index 0 whenever
+ * anything is offered at all; a broader reviewed PREFIX form — at most one — follows at index 1.
+ * Selection indices and redemption tickets are index-keyed against this order (a card's
+ * `selectedCandidate` and its `rt.<index>.` tickets), so consumers may rely on it.
+ *
+ * The prefix candidate comes ONLY from {@link SUGGESTION_LEXICON} — the longest reviewed body that is
+ * a word-boundary prefix of the folded command. History, and why there is no heuristic arm: two
+ * rounds of guessing produced two different wrong answers — a bare program name (`rm -f x` →
+ * `Bash(rm:*)`), then an operand mistaken for a subcommand (`rm harmless.txt` →
+ * `Bash(rm harmless.txt:*)`, which admits a second, unnamed target) — and both failed the same way:
+ * nothing in the command TEXT distinguishes a subcommand from an operand without a per-command
+ * grammar. The lexicon IS that grammar, per reviewed row; anything it does not list (a bare verb, an
+ * interpreter head, an unreviewed subcommand, a runtime-defined name) yields no prefix, with no
+ * fallback. Naive spacing note: `folded` keeps quoted whitespace, so splitting on single spaces can
+ * shear a quoted segment — harmless in this direction, because the sheared pieces carry quote
+ * characters and can never equal a bare lexicon word; every suspicious shape lands on "no prefix".
+ *
+ * Every produced candidate must survive the round trip — parse as a rule AND admit the very command
+ * it was minted from. True by construction (a word-boundary lexicon prefix of a folded simple command
+ * is exactly the matcher's two arms); enforced anyway, fail-closed: a candidate that would not
+ * round-trip is silently not offered, since offering an option redemption would refuse is worse than
+ * offering one fewer.
  *
  * Returns an empty array for anything the rule lane cannot speak for (compounds, redirections,
  * substitutions) — the card then simply carries no "don't ask again" option, which is the honest answer.

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

@@ -6,6 +6,54 @@ export const BARE_INTERPRETER_NAMES = new Set([
     "node", "deno", "bun", "python", "python2", "python3", "perl", "ruby", "php",
     "osascript", "env", "eval", "exec", "xargs", "nohup", "sudo", "doas", "su", "ssh",
 ]);
+export const SUGGESTION_LEXICON = [
+    "git status", "git log", "git diff", "git show", "git branch", "git checkout", "git switch",
+    "git add", "git commit", "git push", "git pull", "git fetch", "git merge", "git rebase",
+    "git tag", "git blame", "git describe", "git cherry-pick", "git restore", "git reset",
+    "git rev-parse", "git ls-files", "git grep",
+    "git stash list", "git stash show", "git stash push", "git stash pop", "git stash drop",
+    "git remote show", "git worktree list", "git submodule update", "git submodule status",
+    "npm run", "npm test", "npm ci", "npm ls", "npm view", "npm outdated", "npm audit",
+    "npm pack", "npm publish", "npm version", "npm why",
+    "pnpm run", "pnpm test", "pnpm ls", "pnpm outdated", "pnpm audit", "pnpm why",
+    "yarn run", "yarn test", "yarn workspaces list",
+    "cargo build", "cargo test", "cargo run", "cargo check", "cargo clippy", "cargo fmt",
+    "cargo doc", "cargo tree", "cargo bench", "cargo update", "cargo metadata",
+    "go build", "go test", "go vet", "go fmt", "go doc",
+    "go mod tidy", "go mod download", "go mod verify", "go mod graph",
+    "docker ps", "docker images", "docker logs", "docker inspect", "docker build", "docker pull",
+    "docker push", "docker stop", "docker start", "docker restart", "docker rm", "docker rmi",
+    "docker compose up", "docker compose down", "docker compose ps", "docker compose logs",
+    "docker compose build", "docker compose pull",
+    "kubectl get", "kubectl describe", "kubectl logs", "kubectl apply", "kubectl delete",
+    "kubectl diff", "kubectl explain", "kubectl top",
+    "kubectl rollout status", "kubectl rollout restart", "kubectl rollout history",
+    "gh pr view", "gh pr list", "gh pr diff", "gh pr checks", "gh pr status", "gh pr create",
+    "gh pr merge", "gh issue view", "gh issue list", "gh issue create", "gh repo view",
+    "gh repo clone", "gh release list", "gh release view", "gh run list", "gh run view",
+    "gh run watch", "gh workflow list", "gh workflow view", "gh auth status",
+    "gh search repos", "gh search issues", "gh search prs", "gh search code",
+];
+const LEXICON_BODIES = SUGGESTION_LEXICON.map((b) => b.split(" "));
+function longestReviewedBody(tokens) {
+    let best;
+    for (const words of LEXICON_BODIES) {
+        if (words.length > tokens.length)
+            continue;
+        if (best !== undefined && words.length <= best.length)
+            continue;
+        let hit = true;
+        for (let i = 0; i < words.length; i++) {
+            if (words[i] !== tokens[i]) {
+                hit = false;
+                break;
+            }
+        }
+        if (hit)
+            best = words;
+    }
+    return best?.join(" ");
+}
 function foldSpacing(s) {
     let out = "";
     let quote;
@@ -131,5 +179,15 @@ export function suggestRulesForCommand(command) {
     const exact = parseAllowRuleText(formatAllowRuleText(folded, "exact"));
     if ("rule" in exact)
         out.push({ rule: exact.rule.rule, match: "exact", command: exact.rule.command });
+    if (out.length === 1) {
+        const body = longestReviewedBody(folded.split(" "));
+        if (body !== undefined) {
+            const text = formatAllowRuleText(body, "prefix");
+            const parsed = parseAllowRuleText(text);
+            if ("rule" in parsed && parsed.rule.match === "prefix" && ruleAdmitsCommand(parsed.rule, command)) {
+                out.push({ rule: parsed.rule.rule, match: "prefix", command: parsed.rule.command });
+            }
+        }
+    }
     return out;
 }

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,17 +114,24 @@ 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,
                 };
             };
             const onEngineIncident = (err) => deps.onError?.(err, { phase: "memory", sessionId });
-            const retrievalBackend = (b) => b.retrievalView?.() ?? b;
+            const adoptionRestricted = input.memoryPersistenceDeclared === false;
+            const retrievalBackend = (b, planeRestricted) => planeRestricted
+                ? (b.restrictedAdoptionView?.({ audit: false }) ??
+                    b.retrievalView?.() ??
+                    b)
+                : (b.retrievalView?.() ?? b);
             const planeScopes = (scopes, write) => [...new Set([...scopes, ...(write !== null ? [write] : [])])];
             const pollutedOpts = (engine) => {
                 const rec = engine.sessionPollution(sessionId);
@@ -131,34 +139,62 @@ 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);
-                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null);
+                const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null, { adoptionRestricted });
+                const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null, { adoptionRestricted });
                 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 = [
                     {
-                        backend: retrievalBackend(backend),
+                        backend: retrievalBackend(backend, adoptionRestricted || p.writePlane !== "project"),
                         scopes: planeScopes(p.project, p.writePlane === "project" ? memorySpec.writeScope : null),
                         recordRetrieved: (ids) => projectEngine.recordRetrieved(ids),
                         challengeExclusions: () => projectEngine.readChallengeExclusions(),
                     },
                     {
-                        backend: retrievalBackend(personal.backend),
+                        backend: retrievalBackend(personal.backend, adoptionRestricted || p.writePlane !== "personal"),
                         scopes: planeScopes(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null),
                         recordRetrieved: (ids) => personalEngine.recordRetrieved(ids),
                         challengeExclusions: () => personalEngine.readChallengeExclusions(),
@@ -167,7 +203,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,16 +219,16 @@ 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);
+                const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
                 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),
+                        backend: retrievalBackend(personal.backend, adoptionRestricted || memorySpec.writeScope === null),
                         scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope),
                         recordRetrieved: (ids) => personalEngine.recordRetrieved(ids),
                         challengeExclusions: () => personalEngine.readChallengeExclusions(),
@@ -206,21 +242,39 @@ export async function prepareMemory(input) {
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
                     onIncident: onEngineIncident,
                 });
-                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
+                const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope, { adoptionRestricted });
                 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),
+                        backend: retrievalBackend(backend, adoptionRestricted || memorySpec.writeScope === null),
                         scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope),
                         recordRetrieved: (ids) => engine.recordRetrieved(ids),
                         challengeExclusions: () => engine.readChallengeExclusions(),
                     },
                 ];
             }
-            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 +315,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 +332,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

@@ -354,7 +354,10 @@ export interface Prepared {
      *  deferred; a caller with no accessor has no deferred family to describe. */
     staticFaceFor?: (name: string) => boolean;
     /**
-     * design/138 S1 — the MemoryEngine session (present iff `deps.memoryBackend` + `spec.memory.enabled`).
+     * design/138 S1 — the MemoryEngine session. Present when `deps.memoryBackend` + `spec.memory.enabled`
+     * hold AND the engine mount succeeded: a materialize failure without a `config.memory_*` code is
+     * fail-open (reported via `deps.onError`, the task runs memory-less), leaving this absent even though
+     * both flags hold.
      * `harvest` is the swallow-guarded boundary hook (task terminal in runtask + the checkpoint mint
      * point in commitSuspendSaga): it runs the FULL gate set (containment/secret/caps/deletion fuse),
      * commits entry patches to the backend, self-heals the derived index, and re-baselines (a second
@@ -1296,8 +1299,11 @@ export interface RunInternals {
      * design/99 (nested-subagent live tree) — an OPT-IN, DISPLAY-ONLY event sink a deployment sets on the TOP run to
      * receive a subagent's live `task_progress` ticks (which otherwise stay in the child's ISOLATED stream). Threaded
      * recursively down the delegation tree (via `ctx.forwardEvent`), so every nested subagent's ticks bubble to the
-     * SAME sink. The Runner forwards ONLY `task_progress` through it; the child stream is NEVER merged into the
-     * parent's MODEL context (this is purely a render channel). Absent unless the deployment opted in.
+     * SAME sink. The Runner's ctx wrapper forwards `task_progress` always; when the run's spec sets
+     * `forwardSubagentEvents: true` it ALSO forwards the child's content events (`text_delta` / `reasoning_delta` /
+     * `tool_start` / `tool_end` — the subagent viewing pane, carrying the same UNTRUSTED-RAW/consumer-must-redact
+     * contract as the main stream's tool events). Either way the child stream is NEVER merged into the parent's
+     * MODEL context (this is purely a render channel). Absent unless the deployment opted in.
      */
     onForwardEvent?: (event: TaskEvent) => void;
     /**