@sema-agent/core 5.27.0 → 5.28.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 5.28.0 — 2026-08-12
+
+No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.
+
+### Narrowed (behavior, ruled)
+
+- **A hook-promoted ask's provenance is stamped, never read back.** Every consumption point keying
+  on `decisionReason === "hook"` now reads an engine-stamped value: the fold reconstructs the
+  promoted ask from an explicit member whitelist and stamps `"hook"` unconditionally, so a hook
+  self-declaring any other word (or extra members like `persistedRuleShadowed`) cannot change how
+  the persisted-rule lane, the rule-suggestion factory, or the inherited-frame reuse treat the ask.
+- **A `decisionReason` outside the closed set is refused at the consumption screen.** A
+  deployment-authored `ToolPolicy.check` returning an unrecognized word (or routing the field
+  through a getter/prototype) is denied fail-closed with the closed set named; plain decisions pass
+  by reference. The HOOK seam is exempt by design (the field is a documented non-input there — see
+  the stamp above).
+- **The served org snapshot meets the same validator as a fetched one.** A persisted last-known-good
+  snapshot carrying a rule the current validator refuses now fails closed during a provider outage
+  instead of serving partial policy.
+- **Legacy rule text the current validator refuses no longer stalls sync.** A shape-whole tombstone
+  whose TEXT is refused gets the new closed-set reason `invalid_rule_text` — disclosed, quarantined,
+  and no longer withholding the whole inbound-adds round (safe: tombstones match byte-identical
+  text only, and an add with that text is refused by the same predicate).
+- **Case-colliding scope directories are refused loudly on case-insensitive filesystems.** Two
+  scopes differing only by case no longer silently share one physical directory (macOS/Windows);
+  collision detection compares folded identity (dev:ino-keyed), with lazy real probing instead of
+  platform guessing.
+- **Spill provenance is session-only, and a failing spill degrades instead of poisoning.** The agent
+  spill write points stamp `{sessionId}` (matching the offload/budget/compaction form); a failed or
+  conflicting spill put defers to a sibling-proven ref or reports honestly — a legacy-shape row can
+  no longer make an agent result permanently unreadable (guarded put + generation guard + coherent
+  poll snapshot).
+
+### Added
+
+- `onNotice` structured notice seat (first two families: bash timeout, MATERIALIZE) — absent keeps
+  the `console.warn` text verbatim; a present non-function seat is announced once and falls back
+  loudly instead of silencing both channels.
+- `tool_end.errorCode` now reads both discriminator spellings — `details.code` first (string), then
+  `details.errorKind` — so loop-thrown error frames are classifiable; `code` wins when both exist.
+- `ToolResultStore.deleteBySession?` (optional member; File + in-memory implementations, not on the
+  scoped wrapper, not in the published contract kit) — returns `{ deleted, unattributable }`;
+  selection keys on recorded provenance, unowned rows are counted and never deleted. A put refused
+  over an orphan sidecar un-publishes its own content (pre-call state restored), and a damaged
+  re-published survivor is counted unattributable.
+- Adopt-on-read ledger writes are serialized behind the existing cross-process txn mutex (lock-free
+  probe fast path; divergence acquires the mutex, reloads the ledger from disk, and re-verifies
+  lock ownership at recovery, side-effect and commit points) — cross-process lost-update closed.
+- `runTaskStream` refuses an out-of-shape `resume` synchronously (a resume without `outcome` used to
+  hang `stream.result()` forever).
+- `docs/INTEGRATION-CORE.md` — the core→embedder contract document (event-frame per-key obligations,
+  code-vocabulary pointers, TaskResult matrix, resume/decide shapes, store optional-member table);
+  maintained per L3 release.
+- Rule-suggestion admission honesty (#174 adjacency): the suggestion factory keys on the stamped
+  provenance.
+
+### Fixed
+
+- Control-character gate: five bench probe arms now genuinely reach their claimed product paths;
+  the published B2 index-truncation curve was corrected to `[0, 0, 0.005, 0.602]` (the old counting
+  masked a real N200 loss).
+- `TaskResult.retryAfterMs` and `tool_end.errorCode` JSDoc corrected to match code (two accepted
+  codes; the errorKind fallback).
+
 ## 5.27.0 — 2026-08-11
 
 No API-BREAKING changes (exports grow only). Narrowings are tighten-direction and named below.

package/dist/core/hooks.d.ts

@@ -417,6 +417,28 @@ export interface HookToolOutput {
 /**
  * A PreToolUse hook result: a {@link PermissionResult} (so a hook can `deny`/`ask`, or `allow` with an
  * `updatedInput` rewrite) plus optional `additionalContext` injected into the eventual tool result.
+ *
+ * **The provenance members are not hook-settable inputs** (#174). `decisionReason` is the ENGINE's account
+ * of which layer produced a verdict, and `persistedRuleShadowed` is the gate's own #144 disclosure that a
+ * stored rule matched without clearing the ask. The gate stamps both itself — a `decisionReason` on a hook
+ * result is DISCARDED (a hook ask always reads `"hook"` downstream), and a `persistedRuleShadowed` is
+ * dropped rather than rendered on an approval card as a rule no lane matched.
+ *
+ * Which of a hook's OTHER members reach the surviving decision depends on which fold arm ran, so read
+ * the arm, not a single list: an ask promoted from a policy `allow` is rebuilt from the hook's `message`,
+ * `requiresRealApproval` and `updatedInput`, while a hook ask folded BESIDE a policy ask contributes its
+ * message and its mandate to the policy's decision and leaves the policy's own rewrite in place (the
+ * hook's rewrite still reaches execution — through the gate's captured rewrite, not through the decision
+ * object). Both arms are at the `hookAsk` fold in {@link runToolGate}.
+ *
+ * `additionalContext` is on neither list and never was consumed as a decision member: it rides its own
+ * channel — collected into the gate's `preToolContext` as soon as the hook answers, whichever verdict it
+ * returned, and drained onto the tool result by the runner. DELIVERY is narrower than collection: the
+ * runner stashes the context only for a call that will EXECUTE, because a blocked or suspended call never
+ * reaches the result step that drains it and carries its own model-facing reason instead. The context
+ * formerly APPEARED on the promoted ask object as an undeclared property, because that fold spread the
+ * whole hook result; the concurrent arm never carried it, so the two arms disagreed on a member neither
+ * of them reads. Nothing in the engine reads it off a decision.
  */
 export type PreToolUseResult = PermissionResult & {
     additionalContext?: string;

package/dist/core/hooks.js

@@ -98,7 +98,7 @@ function preToolUseCrashReason(subject, err) {
 function screenPreToolUseResult(r) {
     if (r === undefined)
         return undefined;
-    return refuseOutOfContractDecision(r);
+    return refuseOutOfContractDecision(r, { reasonIsNonInput: true });
 }
 export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
     return brandPolicyAskClass({
@@ -125,6 +125,7 @@ export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
                     action: "ask",
                     message: decisionText(r) ?? `approval required for "${req.toolName}" (inherited PreToolUse hook)`,
                     decisionReason: "hook",
+                    ...(r.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                     ...(r.updatedInput !== undefined ? { updatedInput: r.updatedInput } : {}),
                 };
             }
@@ -220,13 +221,31 @@ export async function runToolGate(input) {
     if ((decision.action === "allow" || decision.action === "ask") && decision.updatedInput !== undefined) {
         policyRewrite = decision.updatedInput;
     }
-    else if (hookAsk?.action === "ask" && hookAsk.updatedInput !== undefined) {
+    else if (hookAsk?.updatedInput !== undefined) {
         policyRewrite = hookAsk.updatedInput;
     }
     if (decision.action === "allow" && hookAsk) {
-        decision = { ...hookAsk, decisionReason: hookAsk.decisionReason ?? "hook" };
+        decision = {
+            action: "ask",
+            ...(hookAsk.message !== undefined ? { message: hookAsk.message } : {}),
+            decisionReason: "hook",
+            ...(hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(hookAsk.updatedInput !== undefined ? { updatedInput: hookAsk.updatedInput } : {}),
+        };
         denySource = "hook";
     }
+    else if (decision.action === "ask" && hookAsk) {
+        const hookMessage = hookAsk.message;
+        const foldedMessage = hookMessage !== undefined && hookMessage !== decision.message
+            ? `${decision.message !== undefined ? `${decision.message} ` : ""}(a PreToolUse hook also asks: ${hookMessage})`
+            : decision.message;
+        decision = {
+            ...decision,
+            decisionReason: "hook",
+            ...(foldedMessage !== undefined ? { message: foldedMessage } : {}),
+            ...(hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+        };
+    }
     if (input.egress && decision.action === "allow") {
         decision = {
             action: "ask",

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

@@ -328,7 +328,7 @@ export class MemoryEngine {
         ensureDirExists(this.controlDir);
         const restricted = opts?.adoptionRestricted === true;
         const readBackend = restricted
-            ? (this.backend.restrictedAdoptionView?.({ audit: true }) ?? this.backend)
+            ? (this.backend.restrictedAdoptionView?.({ audit: true, writeScope }) ?? this.backend)
             : this.backend;
         if (writeScope !== null)
             claimRootScope(this.controlDir, writeScope);
@@ -536,9 +536,7 @@ export class MemoryEngine {
         const writeScope = handle.writeScope;
         if (writeScope === null || opts?.admitNothing !== undefined) {
             try {
-                this.backend.auditRestrictedDivergence?.([
-                    ...new Set([...handle.scopes, ...(writeScope !== null ? [writeScope] : [])]),
-                ]);
+                this.backend.auditRestrictedDivergence?.([...new Set([...handle.scopes, ...(writeScope !== null ? [writeScope] : [])])], handle.adoptionRestricted === true && writeScope !== null ? { idlessWriteScope: writeScope } : undefined);
             }
             catch (err) {
                 report.warnings.push(`restricted-session divergence audit failed: ${err instanceof Error ? err.message : String(err)}`);

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

@@ -147,13 +147,48 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  `sync` (read-side callers) adopts a committed file's CURRENT disk rev into the committed-rev
      *  ledger ONLY through the inbound gate (B2: out-of-session edits, e.g. git-pull, are scanned;
      *  a reject is moved to control-plane quarantine and the committed shadow content is restored to
-     *  disk). The applyPatches lookup passes false (the ledger must keep the baseline for CAS). */
+     *  disk). The applyPatches lookup passes false (the ledger must keep the baseline for CAS).
+     *
+     *  Ledger-write discipline: the sync=true adoption path WRITES `revs.json`, and that write is
+     *  wholesale (atomic replace) — unserialized against applyPatches' transaction it is a
+     *  lost update (the later writer drops every row the earlier one added). sync=true is therefore
+     *  reachable ONLY through {@link readScopeAdopting}: `probeOnly` runs the scan with NO adoption
+     *  side effects and returns undefined at the FIRST divergent entry (adoption required — the
+     *  caller re-runs the scan under the txn mutex against a freshly reloaded ledger); a completed
+     *  probe pass returns the entries (nothing to adopt, no lock ever taken). */
     private readScope;
+    /**
+     * The adopting read: {@link readScope} sync=true with its ledger write serialized behind the
+     * SAME cross-process txn mutex applyPatches holds (acquisition/steal/timeout semantics shared,
+     * never duplicated). Without it, an adoption landing beside a sibling process's commit is a
+     * lost update: both read the ledger, both write it wholesale, the later atomic write drops the
+     * earlier writer's rows (the entry file stays on disk but the ledger no longer knows it).
+     *  - PROBE first (no lock): disk agreeing with the ledger is the common case, and that pass writes
+     *    no LEDGER row — the read stays lock-free and never contends with a writer over the ledger.
+     *    (Precision, merged-code scan: the non-divergent branch may still BACKFILL a missing shadow
+     *    file for a committed entry, an unserialized control-plane write with a narrow pre-existing
+     *    last-writer window against a sibling's commit — see the shadow-backfill site below; that
+     *    window predates this probe and is the same one the v2 single-lock design closes.)
+     *  - Divergence ⇒ acquire the mutex, finish any interrupted transaction (the steal-safety
+     *    contract: a stolen stale lock is safe BECAUSE recovery runs inside the lock), RELOAD the
+     *    ledger from disk (the probe's cached view is exactly the stale baseline that loses
+     *    updates), then re-run the scan with adoption and save inside the lock. The save re-verifies
+     *    lock OWNERSHIP first (a holder stalled past the stale deadline was stolen from — its
+     *    snapshot is behind the stealer's commit and must abort, exactly like the applyPatches
+     *    journal write).
+     *  - A lock that cannot be acquired throws (same loud arm as the write path): an adoption that
+     *    cannot be serialized must surface, never silently skip the gate or serve stale state as
+     *    adopted.
+     * No self-deadlock: nothing under the lock re-enters acquireTxnLock — the scan's quarantine /
+     * shadow / announcement writes use their own per-file sidecar locks (whose holders never take
+     * the txn mutex), and applyPatchesLocked only issues sync=false reads. The two UNLOCKED
+     * recovery observers (constructor / checkControlPlane) are unaffected: they already stand down
+     * while a live holder exists ({@link txnInFlight}), which now covers adoption holds too.
+     */
+    private readScopeAdopting;
     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
@@ -181,6 +216,19 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  notice); a divergence whose bytes CHANGE mints a new key and is reported again. */
     private restrictedFindingKeys;
     private recordRestrictedFinding;
+    /** Id-less audit state for an adoption-restricted session's WRITE scope. Armed only by the
+     *  audited mount, which carries the caller's explicit session verdict together with the session's
+     *  write scope — never inferred from plane structure (a writeScope-null layering has no write
+     *  scope and is never given this surface: id-less files there are ordinary working files or
+     *  external drops). The baseline is the set of id-less rel paths already under the scope at the
+     *  first audited read after the mount (= materialize time): a pre-existing id-less file cannot be
+     *  attributed to this session and stays unflagged, while a session under the restriction verdict
+     *  has no sanctioned write channel into the store — so an id-less file that APPEARS after the
+     *  baseline arrived out of band by construction and is worth naming. Per-process like the finding
+     *  keys; when restricted sessions interleave on one instance the later mount re-baselines, which
+     *  degrades toward silence, never toward a false alarm. */
+    private restrictedIdlessScope?;
+    private restrictedIdlessBaseline?;
     /**
      * 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:
@@ -223,13 +271,15 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * 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;
+     *    existing quarantine door; `writeScope` (when the session has one) additionally arms the
+     *    id-less baseline for that scope — see {@link auditRestrictedDivergence};
      *  - `audit: false` (the retrieval-tool mount): a pure committed-view read — no findings, no
-     *    containment, no writes.
+     *    containment, no writes, no baseline.
      * WRITES ARE REFUSED loudly — same posture as {@link retrievalView}.
      */
     restrictedAdoptionView(opts?: {
         audit?: boolean;
+        writeScope?: string | null;
     }): MemoryBackend;
     /**
      * The harvest-boundary divergence sweep for an adoption-restricted session (the engine's
@@ -240,13 +290,22 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      * 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.
+     *
+     * `opts.idlessWriteScope` is the CALLER's per-call session verdict (same posture as the mount:
+     * the backend never guesses): when the audited session HAS a write scope, id-less files under it
+     * that were not in the mount-time baseline are named too — the session has no sanctioned write
+     * channel into the store, so a new arrival is out of band by construction. Left out (a
+     * writeScope-null layering, or a caller that never mounted the audit), the sweep is exactly the
+     * id-bearing audit above; a scope mismatch with the armed mount likewise degrades to silence
+     * rather than judging against a foreign baseline.
      */
-    auditRestrictedDivergence(scopes: readonly string[]): void;
+    auditRestrictedDivergence(scopes: readonly string[], opts?: {
+        idlessWriteScope?: 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:

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

@@ -1,5 +1,5 @@
 import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, openSync, fsyncSync, closeSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { dirname, join, relative } from "node:path";
 import { jaccardDistance, termSet } from "../memory-vector.js";
 import { MAX_MEMORY_BYTES } from "../memory.js";
@@ -263,7 +263,7 @@ export class FileMemoryEngineBackend {
         }
         return undefined;
     }
-    readScope(scope, sync = true) {
+    readScope(scope, sync, probeOnly, lockToken) {
         if (!sync && this.batchScan !== undefined) {
             const memo = this.batchScan.get(scope);
             if (memo !== undefined)
@@ -293,6 +293,10 @@ export class FileMemoryEngineBackend {
             if (ledger) {
                 const committed = ledger[entry.id];
                 if (committed !== entry.rev) {
+                    if (probeOnly)
+                        return undefined;
+                    if (lockToken !== undefined)
+                        this.assertTxnLockOwnership(lockToken);
                     const relPath = relative(this.directoryRoot, f.path);
                     let finding = this.inboundGate(relPath, text);
                     if (finding === undefined && committed !== undefined) {
@@ -343,8 +347,11 @@ export class FileMemoryEngineBackend {
             }
             entries.push(entry);
         }
-        if (ledgerChanged)
+        if (ledgerChanged) {
+            if (lockToken !== undefined)
+                this.assertTxnLockOwnership(lockToken);
             this.saveLedger();
+        }
         if (adoptedExternal.length > 0) {
             try {
                 enqueueMemoryAnnouncement(this.controlPlaneRoot, {
@@ -377,33 +384,46 @@ export class FileMemoryEngineBackend {
             this.batchScan.set(scope, entries);
         return entries;
     }
-    async listHeaders(scopes) {
-        return this.listHeadersWith(scopes, true);
+    async readScopeAdopting(scope, timings) {
+        const probed = this.readScope(scope, true, true);
+        if (probed !== undefined)
+            return probed;
+        const lock = await this.acquireTxnLock(timings);
+        try {
+            this.assertTxnLockOwnership(lock.token);
+            this.ledger = undefined;
+            this.recoverJournal();
+            return this.readScope(scope, true, false, lock.token);
+        }
+        catch (err) {
+            this.ledger = undefined;
+            throw err;
+        }
+        finally {
+            lock.release();
+        }
     }
-    listHeadersWith(scopes, adopt) {
-        return this.listHeadersFrom(scopes, (s) => this.readScope(s, adopt));
+    async listHeaders(scopes) {
+        return this.listHeadersFrom(scopes, (s) => this.readScopeAdopting(s));
     }
-    listHeadersFrom(scopes, read) {
+    async listHeadersFrom(scopes, read) {
         const out = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of read(scope)) {
+            for (const e of await read(scope)) {
                 out.push(headerOf(e, join(dir, `${e.slug}.md`)));
             }
         }
         return out;
     }
     async getByIds(ids) {
-        return this.getByIdsWith(ids, true);
-    }
-    getByIdsWith(ids, adopt) {
-        return this.getByIdsFrom(ids, (s) => this.readScope(s, adopt));
+        return this.getByIdsFrom(ids, (s) => this.readScopeAdopting(s));
     }
-    getByIdsFrom(ids, read) {
+    async getByIdsFrom(ids, read) {
         const want = new Set(ids);
         const out = [];
         for (const scope of Object.keys(registeredScopes(this.controlPlaneRoot))) {
-            for (const e of read(scope)) {
+            for (const e of await read(scope)) {
                 if (want.has(e.id))
                     out.push(e);
             }
@@ -415,9 +435,9 @@ export class FileMemoryEngineBackend {
             throw new Error(`memory retrieval view is read-only — ${op} must go through the backend itself`);
         };
         return {
-            listHeaders: async (scopes) => this.listHeadersWith(scopes, false),
-            getByIds: async (ids) => this.getByIdsWith(ids, false),
-            search: async (query, scopes, opts) => this.searchWith(query, scopes, opts, false),
+            listHeaders: async (scopes) => this.listHeadersFrom(scopes, (s) => this.readScope(s, false)),
+            getByIds: async (ids) => this.getByIdsFrom(ids, (s) => this.readScope(s, false)),
+            search: async (query, scopes, opts) => this.searchFrom(query, scopes, opts, (s) => this.readScope(s, false)),
             applyPatches: async () => refuse("applyPatches"),
             getConsolidationCursor: async (scope) => this.getConsolidationCursor(scope),
             setConsolidationCursor: async () => refuse("setConsolidationCursor"),
@@ -430,6 +450,8 @@ export class FileMemoryEngineBackend {
         this.restrictedFindingKeys.add(key);
         this.inboundFindings.push(finding);
     }
+    restrictedIdlessScope;
+    restrictedIdlessBaseline;
     readScopeCommitted(scope, audit) {
         const dir = this.scopeDir(scope);
         const isRoot = dir === this.directoryRoot;
@@ -450,6 +472,7 @@ export class FileMemoryEngineBackend {
         });
         this.ledger = undefined;
         const ledger = this.loadLedger();
+        const idlessSeen = audit && scope === this.restrictedIdlessScope ? new Set() : undefined;
         const entries = [];
         for (const f of files) {
             const rel = relative(this.directoryRoot, f.path);
@@ -468,8 +491,10 @@ export class FileMemoryEngineBackend {
                 continue;
             }
             const parsed = parseEntryFile(text);
-            if (parsed.id === undefined)
+            if (parsed.id === undefined) {
+                idlessSeen?.add(rel);
                 continue;
+            }
             const entry = entryFromFile(text, parsed.id, f.slug, scope);
             const committed = ledger[entry.id];
             if (committed === entry.rev) {
@@ -547,6 +572,8 @@ export class FileMemoryEngineBackend {
                 }
             }
         }
+        if (idlessSeen !== undefined && this.restrictedIdlessBaseline === undefined)
+            this.restrictedIdlessBaseline = idlessSeen;
         return entries;
     }
     idProjectionElsewhere(id, excludeAbsPath) {
@@ -567,6 +594,10 @@ export class FileMemoryEngineBackend {
     }
     restrictedAdoptionView(opts) {
         const audit = opts?.audit === true;
+        if (audit) {
+            this.restrictedIdlessScope = typeof opts?.writeScope === "string" ? opts.writeScope : undefined;
+            this.restrictedIdlessBaseline = undefined;
+        }
         const refuse = (op) => {
             throw new Error(`memory adoption-restricted view is read-only — ${op} must go through the backend itself`);
         };
@@ -579,9 +610,11 @@ export class FileMemoryEngineBackend {
             setConsolidationCursor: async () => refuse("setConsolidationCursor"),
         };
     }
-    auditRestrictedDivergence(scopes) {
+    auditRestrictedDivergence(scopes, opts) {
         for (const scope of scopes)
             this.readScopeCommitted(scope, true);
+        const idlessBaseline = opts?.idlessWriteScope !== undefined && opts.idlessWriteScope === this.restrictedIdlessScope ? this.restrictedIdlessBaseline : undefined;
+        const idlessScope = idlessBaseline !== undefined ? opts?.idlessWriteScope : undefined;
         const ledger = { ...this.loadLedger() };
         const present = new Map();
         let complete = true;
@@ -602,8 +635,20 @@ export class FileMemoryEngineBackend {
                     continue;
                 }
                 const id = parseEntryFile(text).id;
-                if (id !== undefined)
+                if (id !== undefined) {
                     present.set(id, [...(present.get(id) ?? []), relative(this.directoryRoot, f.path)]);
+                    continue;
+                }
+                if (scope === idlessScope && idlessBaseline !== undefined) {
+                    const rel = relative(this.directoryRoot, f.path);
+                    if (!idlessBaseline.has(rel)) {
+                        this.recordRestrictedFinding(`idless|${rel}|${createHash("sha256").update(text, "utf8").digest("hex").slice(0, 16)}`, {
+                            path: rel,
+                            code: "restricted_divergence",
+                            reason: "an id-less file appeared under the session's write scope after materialize, through none of this session's channels: a concurrent session's in-flight material, or an out-of-band drop — left on disk for an unrestricted harvest to adjudicate",
+                        });
+                    }
+                }
             }
         }
         for (const [id, paths] of present) {
@@ -637,12 +682,9 @@ export class FileMemoryEngineBackend {
         }
     }
     async search(query, scopes, opts) {
-        return this.searchWith(query, scopes, opts, true);
-    }
-    searchWith(query, scopes, opts, adopt) {
-        return this.searchFrom(query, scopes, opts, (s) => this.readScope(s, adopt));
+        return this.searchFrom(query, scopes, opts, (s) => this.readScopeAdopting(s));
     }
-    searchFrom(query, scopes, opts, read) {
+    async searchFrom(query, scopes, opts, read) {
         const limit = opts?.limit ?? 20;
         const q = termSet(query);
         if (q.size === 0)
@@ -650,7 +692,7 @@ export class FileMemoryEngineBackend {
         const scored = [];
         for (const scope of scopes) {
             const dir = this.scopeDir(scope);
-            for (const e of read(scope)) {
+            for (const e of await read(scope)) {
                 const haystack = `${e.frontmatter.name ?? e.slug} ${e.frontmatter.description ?? ""} ${e.body}`;
                 const d = jaccardDistance(q, haystack);
                 if (d === null)

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

@@ -111,6 +111,17 @@ export declare function resolveMemoryEngineRoot(explicit?: string): string;
  * collision (two distinct scopes → one dir name), so even a hash collision cannot silently merge scopes.
  */
 export declare function scopeDirName(scope: string): string;
+/**
+ * Whether `dir`'s volume FOLDS letter case — two names differing only in case address ONE
+ * directory entry (the macOS/Windows default). Probed on the actual directory, never guessed from
+ * the platform: case-sensitive APFS volumes and case-insensitive Linux mounts both exist, and this
+ * answer gates a fail-closed isolation refusal, so it must describe the volume the scope dirs
+ * really land on — a platform guess would fail OPEN exactly on the mismatched deployments.
+ * `undefined` = the volume answered on neither leg (unwritable AND no letter-bearing entry to read
+ * against); the caller must treat that as unresolved, never as either determined answer.
+ * Exported for the layout pins; not part of the package surface.
+ */
+export declare function dirCaseFolds(dir: string): boolean | undefined;
 /** Which scope owns the memory dir ROOT (undefined = unclaimed). */
 export declare function rootScopeOf(controlDir: string): string | undefined;
 /**
@@ -121,8 +132,26 @@ export declare function rootScopeOf(controlDir: string): string | undefined;
 export declare function claimRootScope(controlDir: string, scope: string): string;
 /** Register `scope` in the durable registry (idempotent) and return its home dir under `memoryDir`.
  *  H5 fail-closed: a dir-name collision with a DIFFERENT registered scope throws — two scopes must
- *  never share one directory (silent cross-scope merge). Lock-serialized (独立轨 F5). */
-export declare function registerScope(memoryDir: string, controlDir: string, scope: string): string;
+ *  never share one directory (silent cross-scope merge). The collision test has TWO arms:
+ *   - exact: two scopes whose labels are the SAME string (hash collision / forged registry);
+ *   - case-fold (2026-08-12): two labels differing ONLY in letter case are distinct strings to this
+ *     registry yet ONE physical directory on a case-folding volume — cross-scope bleed the exact arm
+ *     cannot see. The fold arm compares the FINAL dir labels (ASCII by construction, so toLowerCase
+ *     is an exact fold) and only fires when the volume actually folds — probed lazily on a fold-equal
+ *     candidate ({@link dirCaseFolds}), so the no-collision path never pays the probe and a
+ *     case-SENSITIVE volume keeps hosting case-differing scope pairs as the genuinely distinct
+ *     directories they are there. An UNPROBEABLE volume (neither probe leg answers) refuses the
+ *     fold-equal pair too — an unresolved semantics guess would fail open exactly where the guard
+ *     is needed. `opts.caseFoldingFs` overrides the probe for callers (and pins) that already
+ *     measured the volume's semantics. The scope→dir MAPPING itself is unchanged on purpose:
+ *     folding scopeDirName would re-home every existing mixed-case scope's directory.
+ *  Both arms compare the scope's EFFECTIVE label — the registered one when present (a registered
+ *  scope's home NEVER moves; entries live there), the formula only for a never-registered scope —
+ *  so a registry whose stored labels drifted from the current formula is judged by the directories
+ *  it actually serves, not by labels nobody uses. Lock-serialized (独立轨 F5). */
+export declare function registerScope(memoryDir: string, controlDir: string, scope: string, opts?: {
+    caseFoldingFs?: boolean;
+}): string;
 /** All registered scopes → home dir name (`""` = the root). */
 export declare function registeredScopes(controlDir: string): Record<string, string>;
 /** The stable home directory of `scope`'s entry files: the root when it owns the root, else the