@sema-agent/core 5.26.0 → 5.27.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 5.27.0 — 2026-08-11
+
+No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.
+
+### Narrowed (behavior, ruled)
+
+- **A declared-unavailable session reads the committed memory view.** Under
+  `memoryPersistenceCapable: false`, materialize/search/harvest serve the committed account
+  (ledger + shadow): disk divergence with no transaction backing is neither adopted nor served —
+  it stays on disk, is loudly reported (`restricted_divergence`, a new `HarvestRejectionCode`
+  member — consumers pinning that enum as a closed set must add the row), and a later unrestricted
+  session adopts it through the normal gates. Legitimate flows are untouched: user hand-edits and
+  git-pull drops keep working (deferred, not destroyed), a concurrent writable session's committed
+  changes pass as transaction-backed, and **a writeScope-null plane (org layers default read-only;
+  the dual-root non-write plane) keeps its ordinary adopt-on-read semantics** — the restriction is
+  the SESSION's declaration, never the plane's structure.
+- **Rule suggestions appear only where a persisted rule could actually work.** Mandated
+  (`shellGate:"always"` / tool marks / org / requiresRealApproval), shadowed, hook-originated,
+  inherited-unresolved, ancestor-resolved (a live parent approver), and anonymous-task (no
+  principal, no local-owner declaration) asks no longer carry `ruleSuggestions` — a card whose rule
+  could never silence it stops offering to mint one. Classifier-tier and ordinary policy asks keep
+  their suggestions.
+- **Known residual (registered)**: bytes refused by a restricted session remain on disk and are
+  adoptable by a later unrestricted session — the alternative (destroying bytes indistinguishable
+  from user edits) is ruled out; the boundary is "the restricted session is never polluted and
+  tampering is always visible", not "the bytes can never enter".
+
+### Added
+
+- **Prefix rule candidates**: the suggestion engine mints a reviewed PREFIX option beside the exact
+  one for lexicon-listed command bodies (`git push origin main` → optional `Bash(git push:*)`),
+  longest word-boundary hit, no fallback; candidate arrays grow from ≤1 to ≤2 with `exact` fixed at
+  index 0 (a documented contract across `AskRequest.ruleSuggestions`, checkpoint park rows, and the
+  approval card record). Consumers reading `[0]` unconditionally only miss the new option.
+- **CJK lexical retrieval**: `termSet` now mints CJK character bigrams and unigrams beside
+  alphanumeric runs — a pure-Chinese memory entry was previously INVISIBLE to the File backend's
+  lexical rung (empty term set); the class is written in explicit escapes (a literal compat
+  ideograph NFC-folds to its unified twin, silently widening the range).
+- **`toolResultContentSegment` exported** from the package root (the digest segment the engine's
+  own mints carry — consumers derive it instead of inventing a placeholder).
+- `MemoryEngine.materialize` accepts an optional `adoptionRestricted` verdict;
+  `MemorySessionHandle.adoptionRestricted` reports it (both additive).
+
+### Fixed
+
+- Three loaded-suite timing margins widened without losing discrimination; the defectscan
+  guardrail audit skips a concurrently-vanished temp dir instead of throwing; 24 stale doc/JSDoc
+  claims restated to actual behavior (bidirectional sweep + rescan trio).
+
 ## 5.26.0 — 2026-08-11
 
 No API-BREAKING changes (exports grow only; new members optional/additive). Several

package/dist/agents/agent-transcript-tool.d.ts

@@ -37,8 +37,11 @@ export interface AgentTranscriptToolOptions {
  * into a child's tail when the residual isn't enough.
  *
  * Safety: reads are bounded to the parent's OWN lineage — the same non-leaking registry access scope as
- * SendMessage/TaskOutput (an unknown or out-of-scope id reads identically to "not found"). Only a
- * RETAINED child's session survives to be read; a throwaway child returns an honest "not retained".
+ * SendMessage/TaskOutput (an unknown or out-of-scope id reads identically to "not found"). Two read
+ * paths keep a child's session reachable: the retain ledger (a RETAINED child), and the durable
+ * agent-store fallback (`agentStore` wired + accessible row + preserved `sessionId` — readable even
+ * with retain off/expired/evicted). Only when BOTH miss does the call return the honest
+ * "not retained" / "not found".
  */
 export declare function createAgentTranscriptTool(opts: AgentTranscriptToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{
     id: Type.TString;

package/dist/agents/agent-transcript-tool.js

@@ -16,7 +16,8 @@ export function createAgentTranscriptTool(opts) {
         description: `Read the recent tool steps of a background agent you launched (task_id 'a…' from the Agent tool with ` +
             `run_in_background), so you can see precisely where it got to — useful before SendMessage-ing a follow-up, ` +
             `or to inspect a stopped agent's tail. Returns the last N steps (tool, target, outcome); it does not re-run ` +
-            `the agent. Only works for agents this run retained (retainSubagentSessions); otherwise you get an honest error.`,
+            `the agent. Works for agents this run retained (retainSubagentSessions) and for agents whose durable ` +
+            `record preserved their transcript session; when neither holds you get an honest error.`,
         parameters: Type.Object({
             id: Type.String({ description: "The background agent's task_id (a…) returned by the Agent tool." }),
             lastN: Type.Optional(Type.Integer({ minimum: 1, maximum: AGENT_TRANSCRIPT_MAX_N, description: `How many recent steps to return (default ${AGENT_TRANSCRIPT_DEFAULT_N}).` })),

package/dist/agents/send-message-tool.d.ts

@@ -19,7 +19,10 @@ export interface SendMessageToolOptions {
     owner?: string;
     scope?: string;
     sessionId?: string;
-    /** Deployment-level background-notify sink — the resumed run's completion rides the existing chain. */
+    /** Completion-notify sink for the resumed run. The Runner mount wires the SENDING run's own
+     *  notification injector here (its runtask-wrapped `injectTaskNotification`), so the completion
+     *  notice lands in the sender's live injection queue at a turn boundary; a direct mount may wire a
+     *  deployment-level background-notify sink instead. Absent ⇒ completion is silent. */
     notify?: (n: TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;

package/dist/agents/subagent.d.ts

@@ -361,8 +361,11 @@ export interface SubagentSteerHandle {
  * before any await; rolled back on pre-launch failure) → session exists AND non-empty (r1-m1).
  * Then: fenced revive prompt (unpredictable marker) →
  * `runTaskStream` on the FROZEN spawn snapshot + `requireExistingSession` (spec is tighten-only: the caller
- * contributes ONLY `content`) → ledger `activeRun` bookkeeping → completion via the deployment-level
- * background-notify sink ONLY (no sink ⇒ silent; NEVER the parent-model notification lane — r1-M5).
+ * contributes ONLY `content`) → ledger `activeRun` bookkeeping → completion announced through
+ * `deps.notify` (no sink ⇒ silent). Which lane
+ * that is depends on the mount: the background Agent lane wires the deployment-level background-notify
+ * sink, while the SendMessage mount wires the SENDING run's own notification injector — there the
+ * completion notice lands in the sender's live injection queue at its next turn boundary.
  */
 export declare function createSubagentResume(deps: {
     ledger: SubagentRetainLedger | undefined;

package/dist/core/checkpoint-store.d.ts

@@ -574,8 +574,13 @@ export type PendingAction = {
     /** design/179 §4 (additive) — the persistable allow-rule forms this parked call could be covered by,
      *  minted from the SAME post-hook args the row executes. Advisory display metadata for the approval
      *  inbox's "stop asking me this" option; never read by the resume path, and never a rule by itself
-     *  (minting one goes through the approval-record protocol). Absent when no rule lane is armed or the
-     *  command is one the lane cannot speak for. */
+     *  (minting one goes through the approval-record protocol). Absent when no rule lane is armed, the
+     *  command is one the lane cannot speak for, or the parked ask is one a persisted rule could not
+     *  clear (mandated marks / a real-approval demand / a shadowed matching rule).
+     *  CONTRACT (same as the synchronous `AskRequest.ruleSuggestions`) — array order is display order,
+     *  narrowest first: the EXACT form is always index 0, a broader reviewed PREFIX form (at most one)
+     *  follows; basis ≤ 2, and selection/ticket indices are keyed against this order. A row persisted
+     *  before the prefix arm existed carries ≤ 1 entry and stays valid under the same reading. */
     ruleSuggestions?: readonly import("./permission-rule-model.js").RuleSuggestion[];
     /**
      * design/80 D-1 §2 (slice 1a.2): the server-minted **opaque** boundInputHash of {@link args} — a

package/dist/core/hooks.d.ts

@@ -1,10 +1,10 @@
 import type { DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
-import type { PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
+import type { DecisionReason, PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
 import { type AskClass } from "./ask-class.js";
 /**
- * In-process hook seam (design/37) — a small, provider-agnostic interception layer modeled on CC's
- * hooks but reduced to three process-internal callbacks (no shell/HTTP executors, no settings files):
+ * In-process hook seam (design/37) — a provider-agnostic interception layer modeled on CC's hooks,
+ * kept process-internal (no shell/HTTP executors, no settings files). The original tool-call trio:
  *
  *  - {@link Hooks.preToolUse} runs before a tool executes. It may **rewrite** the args (an `allow` with
  *    `updatedInput`), **restrict** the call (`deny`/`ask`), and/or inject `additionalContext`. It is a
@@ -15,6 +15,13 @@ import { type AskClass } from "./ask-class.js";
  *  - {@link Hooks.userPromptSubmit} runs before the objective becomes a user message. It may `block`
  *    submission (the task fails with a model-readable reason) or inject `additionalContext` ahead of it.
  *
+ * The seam has since grown well past the trio — each later member carries its own contract below:
+ * {@link Hooks.stop} / {@link Hooks.stopFailure} (run-end pushback / API-error terminal observer),
+ * {@link Hooks.postToolUseFailure} and {@link Hooks.postToolBatch} (failure + batch-boundary taps),
+ * {@link Hooks.preCompact} / {@link Hooks.postCompact} (compaction gate + observer),
+ * {@link Hooks.permissionDenied} (deny observer), and the {@link Hooks.preToolUseObservational}
+ * declaration flag.
+ *
  * All feedback the model should see (a block reason, injected context) is wrapped as a
  * `<system-reminder>` via {@link formatHookFeedback} so the model can read and self-correct.
  */
@@ -611,7 +618,12 @@ export interface ToolGateInput {
     realApproval?: import("./checkpoint-store.js").RealApprovalGateBit, 
     /** #144: the matched-but-outranked persisted rule (the surviving ask's `persistedRuleShadowed`)
      *  — threaded so the park mint's risk descriptor carries the disclosure on the durable route. */
-    shadowedRule?: string) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
+    shadowedRule?: string, 
+    /** The surviving ask's `decisionReason` — threaded so the park mint's rule-suggestion door can
+     *  read the ask's origin on the durable route exactly as the synchronous mints read it off the
+     *  decision (a hook-raised ask is one no persisted rule may clear, so its parked card must not
+     *  offer to mint one). */
+    askDecisionReason?: DecisionReason) => Promise<ToolGateResult["suspend"] | ParkAttemptFailed | undefined>;
     /**
      * design/174 — route a policy `ask` on the reserved question tool to this run's CONTENT-ask channel
      * before it can become a park or a refusal. Called in the `ask` branch with the FINAL post-hook,
@@ -871,6 +883,29 @@ export interface ToolGateInput {
  * reach the same lane from inside a descendant's fold.
  */
 export declare function createPreToolUseConstraintPolicy(preToolUse: NonNullable<Hooks["preToolUse"]>, env?: HookEnvCapabilities, onCrash?: (err: unknown) => void): ToolPolicy;
+/**
+ * The mandate provenance of one call, judged from the SAME mark inputs the gate is driven with —
+ * the single source for "could a persisted allow rule clear this ask?". Allow rules silence the
+ * classifier's questions, never a mandated one, and this predicate is the mandated-family half of
+ * that boundary (the real-approval/governance half rides the decision's own `requiresRealApproval`
+ * bit, which the org layer stamps):
+ *  · `egress` — the tool's own external-write mark, judged FIRST: it is the tool's declaration even
+ *    when the coarse doctrine also installed a shell tier on the same seat;
+ *  · `shellGated` + tier `"always"` — the operator's per-call confirmation doctrine
+ *    (`"operator_always"`); the classify doctrine installs `"maybe"`, and THOSE asks stay the rule
+ *    lane's home turf (`undefined`);
+ *  · a tool's OWN `"always"`/`"maybe"` irreversibility tier without the doctrine (`"tool_marks"`).
+ *
+ * Two consumers, one derivation: the gate's silencing arm (a matching rule is disclosed as shadowed
+ * instead of clearing the ask) and the runner's suggestion factory (a mandated ask offers no
+ * "stop asking me this" option — a rule minted from it would never clear it). A drift between the
+ * two would let a card offer a rule the lane then refuses to honor.
+ */
+export declare function persistedRuleMandateOf(marks: {
+    egress?: boolean;
+    shellGated?: boolean;
+    irreversibility?: "never" | "maybe" | "always";
+}): "operator_always" | "tool_marks" | undefined;
 /**
  * The design/37 **two-phase tool gate** — the single chokepoint that makes the load-bearing invariant
  * structural ("a hook's `allow` cannot bypass the policy's `deny`/`ask`"):

package/dist/core/hooks.js

@@ -161,6 +161,17 @@ function withProbeTimeout(p, ms, signal) {
         p.then((v) => done(resolve, v), (err) => done(reject, err));
     });
 }
+export function persistedRuleMandateOf(marks) {
+    return marks.egress === true
+        ? "tool_marks"
+        : marks.shellGated === true
+            ? marks.irreversibility === "always"
+                ? "operator_always"
+                : undefined
+            : marks.irreversibility === "always" || marks.irreversibility === "maybe"
+                ? "tool_marks"
+                : undefined;
+}
 export async function runToolGate(input) {
     const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
@@ -315,15 +326,7 @@ export async function runToolGate(input) {
             currentInput = policyRewrite;
             req.args = policyRewrite;
         }
-        const persistedRuleMandate = input.egress === true
-            ? "tool_marks"
-            : input.shellGated === true
-                ? input.irreversibility === "always"
-                    ? "operator_always"
-                    : undefined
-                : input.irreversibility === "always" || input.irreversibility === "maybe"
-                    ? "tool_marks"
-                    : undefined;
+        const persistedRuleMandate = persistedRuleMandateOf(input);
         if (input.persistedRules &&
             !orgRealApprovalRequired &&
             decision.action === "ask" &&
@@ -408,7 +411,7 @@ export async function runToolGate(input) {
             ? { origin: orgAskOrigin !== undefined ? `org_${orgAskOrigin}` : "policy" }
             : undefined;
         if (suspendAsk && decision.action === "ask") {
-            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
+            const suspended = await suspendAsk(req, currentInput, safety, undefined, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined);
             if (suspended) {
                 if ("parkFailed" in suspended)
                     parkFailed = suspended.parkFailed;
@@ -427,7 +430,7 @@ export async function runToolGate(input) {
                     req.args = outcome.presentedInput;
                 }
                 if (suspendAsk && outcome.parkDeclined && parkFailed === undefined) {
-                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined);
+                    const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(decision), decision.action === "ask" ? decision.persistedRuleShadowed : undefined, decision.action === "ask" ? decision.decisionReason : undefined);
                     if (suspended) {
                         if ("parkFailed" in suspended)
                             parkFailed = suspended.parkFailed;
@@ -455,7 +458,7 @@ export async function runToolGate(input) {
             const resolved = await resolveAsk(decision, req);
             decision = resolved;
             if (resolved.action === "deny" && resolved.approverUnavailable === true && suspendAsk && parkFailed === undefined) {
-                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined);
+                const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.decisionReason : undefined);
                 if (suspended) {
                     if ("parkFailed" in suspended)
                         parkFailed = suspended.parkFailed;

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

@@ -321,7 +321,9 @@ export declare class MemoryEngine {
      *  eventId anchors on the pollution record (sessionId + marked-at), so however many times this
      *  settlement replays the same pollution event, the generation is allocated once. */
     private settlePromotions;
-    materialize(scopes: readonly string[], writeScope: string | null): Promise<MemorySessionHandle>;
+    materialize(scopes: readonly string[], writeScope: string | null, opts?: {
+        adoptionRestricted?: boolean;
+    }): Promise<MemorySessionHandle>;
     inject(handle: MemorySessionHandle, opts?: {
         writeToolMounted?: boolean;
     }): MemoryInjection;
@@ -365,10 +367,11 @@ export declare class MemoryEngine {
      * @param keepBaseline RB-440 (2026-07-31, hardening probe P3) — relative paths whose baseline must NOT
      * advance: the files a DEGRADED harvest deferred (`report.degraded.pending`).
      *
-     * The deferral contract at :659-665 promises "the REST is deferred to the next harvest (still on disk),
-     * never dropped", but execution then continued into this scan, which re-baselined EVERY file carrying an
-     * id — the pending ones included — writing the CURRENT disk rev into `handle.baseRevs`. The next harvest
-     * hit the unchanged-baseline fast path at :679 and skipped the file FOREVER: the deferred edit never
+     * The deferral contract in the harvest scan (the budget/deadline arm — see `harvestDeadlineMs`)
+     * promises "the REST is deferred to the next harvest (still on disk), never dropped", but execution
+     * then continued into this scan, which re-baselined EVERY file carrying an id — the pending ones
+     * included — writing the CURRENT disk rev into `handle.baseRevs`. The next harvest hit the harvest
+     * scan's unchanged-baseline fast path and skipped the file FOREVER: the deferred edit never
      * became a patch. Session-NEW files escaped it (no id ⇒ `continue` below), which is exactly why the
      * existing budget test passed. Measured with a copy-out backend: harvest#1 {update:1} + pending ["b.md"],
      * harvest#2 {update:0}, and the backend still held v1 — so the next `materialize` wrote the stale text

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

@@ -323,9 +323,13 @@ export class MemoryEngine {
         catch {
         }
     }
-    async materialize(scopes, writeScope) {
+    async materialize(scopes, writeScope, opts) {
         ensureDirExists(this.memoryDir);
         ensureDirExists(this.controlDir);
+        const restricted = opts?.adoptionRestricted === true;
+        const readBackend = restricted
+            ? (this.backend.restrictedAdoptionView?.({ audit: true }) ?? this.backend)
+            : this.backend;
         if (writeScope !== null)
             claimRootScope(this.controlDir, writeScope);
         const scopeDirs = new Map();
@@ -336,8 +340,8 @@ export class MemoryEngine {
         for (const [scope, dir] of scopeDirs)
             this.chmodScopeTree(dir, 0o755, 0o644, { excludeTopDirs: this.siblingScopeDirNames(dir, scope) });
         const allScopes = [...scopeDirs.keys()];
-        const headers = await this.backend.listHeaders(allScopes);
-        const entries = await this.backend.getByIds(headers.map((h) => h.id));
+        const headers = await readBackend.listHeaders(allScopes);
+        const entries = await readBackend.getByIds(headers.map((h) => h.id));
         const byScope = new Map();
         for (const e of entries) {
             const arr = byScope.get(e.scope) ?? [];
@@ -357,6 +361,7 @@ export class MemoryEngine {
             repoIndexTargets: new Map(),
             indexBaselineLines: 0,
             indexText: "",
+            ...(restricted ? { adoptionRestricted: true } : {}),
         };
         if (writeScope !== null)
             ensureDirExists(handle.writableRoot);
@@ -382,7 +387,8 @@ export class MemoryEngine {
                 const { deleted: _stubDrop, ...stubFm } = entry.frontmatter;
                 const text = stub ? serializeEntryFile({ id: entry.id, frontmatter: stubFm, body: STUB_ARCHIVED_LINE }) : fullText;
                 const target = join(dir, `${entry.slug}.md`);
-                this.writeIfChanged(target, text);
+                if (!(zeroCopy && restricted))
+                    this.writeIfChanged(target, text);
                 const onDiskRev = stub ? revOfText(text, entry.id) : entry.rev;
                 const path = canonicalize(target);
                 handle.materialized.push({
@@ -415,7 +421,7 @@ export class MemoryEngine {
                 this.discloseAnnounceFailure("index-gate enqueue", err);
             }
         }
-        const indexText = this.rebuildIndex(handle, headers, { write: writeScope !== null, ignoreOnDisk: indexGate !== undefined });
+        const indexText = this.rebuildIndex(handle, headers, { write: writeScope !== null && !restricted, ignoreOnDisk: indexGate !== undefined || restricted });
         handle.indexBaselineLines = countIndexLines(indexText);
         handle.indexText = indexText;
         for (const [scope, dir] of scopeDirs) {
@@ -433,7 +439,7 @@ export class MemoryEngine {
         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 onDisk = handle.indexOnDiskUntrusted === true || handle.adoptionRestricted === true ? undefined : readSafe(indexPath);
         const indexText = onDisk !== undefined && onDisk.trim() !== "" ? onDisk : handle.indexText;
         const truncated = truncateIndex(indexText);
         const index = composeMemoryBlock(truncated, handle.writeScope ?? handle.scopes[0] ?? "memory");
@@ -529,6 +535,14 @@ export class MemoryEngine {
         };
         const writeScope = handle.writeScope;
         if (writeScope === null || opts?.admitNothing !== undefined) {
+            try {
+                this.backend.auditRestrictedDivergence?.([
+                    ...new Set([...handle.scopes, ...(writeScope !== null ? [writeScope] : [])]),
+                ]);
+            }
+            catch (err) {
+                report.warnings.push(`restricted-session divergence audit failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
             const roFindings = this.backend.drainInboundFindings?.();
             if (roFindings !== undefined && roFindings.length > 0)
                 report.inboundFindings = roFindings;

package/dist/core/memory-engine/file-backend.d.ts

@@ -128,6 +128,15 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     /** The names of sibling scope subdirs to exclude when scanning the ROOT scope's own nested content. */
     private excludedSubdirNames;
     private scopeDir;
+    /** B2/C-F9 — contain one inbound-gate REJECT, shared by the adopting read (`readScope` sync) and
+     *  the adoption-restricted committed view (`readScopeCommitted`) so the two doors can never drift:
+     *  report the finding, capture the SCANNED bytes into control-plane quarantine (never a path
+     *  re-read — TOCTOU), restore the committed shadow over the suspect where one exists (the write
+     *  lands by `rename`, which REPLACES a link at the final component instead of traversing it —
+     *  pinned by test), and escalate any deviation as a report-visible `quarantine_failed`. Returns
+     *  the shadow text that now backs the entry (undefined ⇔ never committed / shadow-less legacy —
+     *  each caller decides what leaving the set means on its channel). */
+    private containInboundReject;
     /** B2 inbound gate for content that did NOT come through applyPatches (git pull / hand edits /
      *  a hand-seeded file): secret + cap + structure. Returns the rejection, or undefined (clean). */
     private inboundGate;
@@ -142,8 +151,10 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     private readScope;
     listHeaders(scopes: readonly string[]): Promise<MemoryEntryHeader[]>;
     private listHeadersWith;
+    private listHeadersFrom;
     getByIds(ids: readonly string[]): Promise<MemoryEntry[]>;
     private getByIdsWith;
+    private getByIdsFrom;
     /**
      * design/178 §3 (ruled 2026-08-08) — a SIDE-EFFECT-FREE projection of this backend for the session's
      * RETRIEVAL face (`memory_search` / `memory_get`).
@@ -162,11 +173,81 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * WRITES ARE REFUSED, loudly — a view handed to a write path is a defect, not a fallback.
      */
     retrievalView(): MemoryBackend;
+    /** Dedup keys for divergence findings the restricted view already recorded on THIS instance: one
+     *  materialize reads a scope several times (listHeaders, then getByIds per scope), and a
+     *  checkpoint-cadence harvest re-audits the same still-pending state — without the key, one
+     *  untouched divergence would mint a finding per read. Per-process on purpose (no durable state to
+     *  lifecycle: a cross-process resume re-discloses once, which is the desired "still pending"
+     *  notice); a divergence whose bytes CHANGE mints a new key and is reported again. */
+    private restrictedFindingKeys;
+    private recordRestrictedFinding;
+    /**
+     * The ADOPTION-RESTRICTED read of one scope: serve the COMMITTED account (ledger + control-plane
+     * shadow) and never advance it. This is the tamper boundary for a session with no write intent:
+     * the ordinary `readScope(sync=true)` ADOPTS disk divergence as the new committed baseline
+     * regardless of session intent, so a byte landed by a side channel (e.g. a shell write under a
+     * session whose persistence is declared unavailable, or into a read-only layering) would be
+     * committed by the very session that was told it cannot persist — its own checkpoint-resume
+     * materialize included. Here instead:
+     *  - disk rev == committed rev ⇒ served as-is (it IS the committed content);
+     *  - divergence whose bytes equal the committed SHADOW ⇒ served as-is: the shadow is written at
+     *    the applyPatches commit point, so matching it is transactional proof that a concurrent
+     *    writable session committed this state and only this call's ledger snapshot raced it —
+     *    never treated as tampering;
+     *  - other divergence of a shadow-backed entry ⇒ the SHADOW (committed content) is served; the
+     *    divergent disk bytes stay in place UNLESS they fail the inbound gate (the existing
+     *    quarantine door, unchanged under restriction). Scan-clean divergence is never quarantined,
+     *    overwritten, or adopted — it stays on disk as deferred external state a later unrestricted
+     *    session adjudicates normally;
+     *  - a divergent entry with NO shadow (shadow-less legacy), and a never-committed id-bearing
+     *    file, have no committed content to serve ⇒ WITHHELD with a loud finding, never served from
+     *    disk, never adopted.
+     * The ledger is reloaded from disk on every call (a stale cache would misread a concurrent commit
+     * as divergence) and NEVER written here; the only writes this path may perform are the
+     * gate-failing containment above and a shadow backfill for a rev-matching entry (recording
+     * committed content — the account itself does not move).
+     *
+     * `audit` picks the mount: true = the engine's materialize/harvest boundary (findings recorded,
+     * gate-failing divergence contained); false = the retrieval-tool face (a PURE committed read —
+     * no findings, no containment, no writes: a model lookup must be side-effect-free).
+     */
+    private readScopeCommitted;
+    /** Does `id` have a projection file anywhere in the store OTHER than `excludeAbsPath`? Returns
+     *  that projection's rel path, or undefined. Early-exits on the first hit; only consulted on the
+     *  rare divergent-with-shadow path (the scope-binding guard above), never on clean reads. */
+    private idProjectionElsewhere;
+    /**
+     * The ADOPTION-RESTRICTED projection of this backend (see {@link readScopeCommitted}) — what a
+     * session with no write intent materializes and retrieves through. The CALLER decides restriction
+     * (an explicit verdict: a read-only layering, or persistence declared unavailable) and mounts this
+     * view; the backend never guesses a session's intent from its own state.
+     *  - `audit: true` (the engine's materialize/harvest mount): divergence findings are recorded for
+     *    the harvest report + announcement queue, and gate-FAILING divergence is contained by the
+     *    existing quarantine door;
+     *  - `audit: false` (the retrieval-tool mount): a pure committed-view read — no findings, no
+     *    containment, no writes.
+     * WRITES ARE REFUSED loudly — same posture as {@link retrievalView}.
+     */
+    restrictedAdoptionView(opts?: {
+        audit?: boolean;
+    }): MemoryBackend;
+    /**
+     * The harvest-boundary divergence sweep for an adoption-restricted session (the engine's
+     * zero-admission harvest arm calls this BEFORE draining findings): re-run the committed-view audit
+     * over the session's scopes — bytes landed AFTER materialize (a mid-session shell write) are
+     * detected here, at the very boundary where an unrestricted harvest would have admitted them —
+     * then check the committed account for entries MISSING from disk entirely (an unattributed delete
+     * is divergence too). Ledger rows carry no scope, so presence is judged across every registered
+     * scope, the same resolution `getByIds` uses; a rename or cross-scope move therefore never reads
+     * as missing. Non-destructive throughout: nothing is restored, forgotten, or adopted here.
+     */
+    auditRestrictedDivergence(scopes: readonly string[]): void;
     /** Lexical floor (design/138 §2.1): `1 - Jaccard` distance over name+description+body, ascending. */
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
     }): Promise<ScoredMemoryEntry[]>;
     private searchWith;
+    private searchFrom;
     /**
      * H4 — the entry transaction, staged and journaled:
      *  1. RELOAD the ledger from disk (验收 M2: a concurrently-committed transaction from another