@remnic/core 9.45.3 → 9.45.5

package/src/storage.ts

@@ -4,18 +4,21 @@ import {
   readdir,
   readFile,
   realpath,
+  rename,
   stat,
   writeFile,
   mkdir,
   unlink,
   appendFile,
   open,
+  type FileHandle,
 } from "node:fs/promises";
 import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync, type Dirent } from "node:fs";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { normalizeContent, computeContentHash } from "./content-hash.js";
 import path from "node:path";
 import { log } from "./logger.js";
+import { createMemorySnapshot } from "./memory-snapshot.js";
 import { assertMemoryFrontmatterId, warnProjectionFallback } from "./storage-guards.js";
 import { MemoryReadStore } from "./storage/memory-read-store.js";
 import { renderProfileWithLastUpdated } from "./storage/profile-header.js";
@@ -45,10 +48,13 @@ import {
 import { EntityCanonicalIdMigrationRunner } from "./storage/entity-canonical-id-migration-runner.js";
 import { rememberRawFrontmatter } from "./storage/memory-frontmatter-metadata.js";
 import { createMemoryEntityRefSerializer } from "./storage/memory-migration-serialization.js";
+import { readEntityAliasConfigSync } from "./storage/entity-alias-config.js";
+import { assertSafeEntityId } from "./storage/entity-id-safety.js";
 export { normalizeEntityName } from "./entity-id-normalization.js";
 import { isErrnoCode } from "./utils/errno.js";
 import { getCategoryDir, categoryDirName } from "./utils/category-dir.js";
 import { decodeYamlScalar } from "./utils/yaml-scalar.js";
+import { withHeldFileLock, type HeldFileLockController } from "./utils/serialize-mutations.js";
 import { qmdCollectionPathParts, qmdResultPathCandidates } from "./orchestration/qmd-result-resolver.js";
 import {
   clearMemoryCache,
@@ -72,6 +78,7 @@ import {
 } from "./in-flight-reads.js";
 import { rotateMarkdownFileToArchive } from "./hygiene.js";
 import { sanitizeMemoryContent } from "./sanitize.js";
+import { withholdToolScopedFromSharedNamespace } from "./tool-scoped-memory.js";
 import {
   serializeProvenanceFields,
   parseProvenanceSources,
@@ -191,6 +198,11 @@ import {
   parseTombstoneBlockedOfflineSyncMemory,
   type TombstoneBlockedCaptureIndexOptions,
 } from "./storage/tombstone-blocked-capture-index.js";
+import {
+  buildCapturePathLockIdentity,
+  isQueuedReviewMemory,
+  tombstoneBlocked,
+} from "./storage/tombstone-blocked-capture-mutation.js";
 export { ContentHashIndex, FactHashIndexNotAuthoritativeError };
 export type { ContentHashIndexLockOptions };
 export {
@@ -264,6 +276,37 @@ type OfflineSyncDigestCacheEntry = {
   bytes: number;
 };
 
+type DeletionRevisionMetadata = {
+  version: 1;
+  deletions: Array<{ path: string; mtimeMs: number }>;
+};
+
+const DELETION_REVISION_MAX_MTIME_MS = 8_640_000_000_000_000;
+const DELETION_REVISION_LOCK_STALE_MS = 60_000;
+const DELETION_REVISION_LOCK_MAX_WAIT_MS = 120_000;
+
+function isValidDeletionRevisionPath(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    !value.includes("\\") &&
+    !value.includes("\0") &&
+    !path.posix.isAbsolute(value) &&
+    path.posix.normalize(value) === value &&
+    value !== "." &&
+    value !== ".." &&
+    !value.startsWith("../")
+  );
+}
+
+function deletionRevisionPathIdentity(value: string): string {
+  return value
+    .normalize("NFC")
+    .toUpperCase()
+    .toLowerCase()
+    .replace(/\u00df/g, "ss");
+}
+
 export interface ReextractJobRequest {
   memoryId: string;
   model: string;
@@ -343,6 +386,7 @@ function serializeFrontmatter(fm: MemoryFrontmatter): string {
     const safe = /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(fm.sourceConnector);
     lines.push(`sourceConnector: ${safe ? fm.sourceConnector : JSON.stringify(fm.sourceConnector)}`);
   }
+  if (fm.toolScoped === true) lines.push("toolScoped: true");
   if (fm.supersedes) lines.push(`supersedes: ${fm.supersedes}`);
   if (fm.expiresAt) lines.push(`expiresAt: ${fm.expiresAt}`);
   if (fm.lineage && fm.lineage.length > 0) {
@@ -609,7 +653,7 @@ function parseReinforcementCountField(raw: string | undefined): number | undefin
 }
 
 export function parseFrontmatter(raw: string): { frontmatter: MemoryFrontmatter; content: string } | null {
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/);
   if (!match) return null;
 
   const fmBlock = match[1];
@@ -867,6 +911,7 @@ export function parseFrontmatter(raw: string): { frontmatter: MemoryFrontmatter;
       tags,
       entityRef: fm.entityRef || undefined,
       sourceConnector: fm.sourceConnector ? decodeYamlScalar(fm.sourceConnector) || undefined : undefined,
+      toolScoped: fm.toolScoped === "true" ? true : undefined,
       supersedes: fm.supersedes || undefined,
       expiresAt: fm.expiresAt || undefined,
       lineage: lineage && lineage.length > 0 ? lineage : undefined,
@@ -1024,7 +1069,6 @@ function inferCurrentStateStatus(
   return inferMemoryStatus(frontmatter, pathRel, fallbackStatus);
 }
 
-
 /**
  * Simple Levenshtein distance between two strings.
  */
@@ -1720,6 +1764,7 @@ export interface WriteMemoryOptions {
   sources?: ProvenanceSource[];
   provenance?: "verified" | "unverified" | "none";
   sourceConnector?: string;
+  toolScoped?: true;
 }
 
 /**
@@ -1735,6 +1780,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   private knowledgeIndexCache: { result: string; builtAt: number } | null = null;
   private artifactIndexCache: { memories: MemoryFile[]; loadedAtMs: number; writeVersion: number } | null = null;
   private projectionLedgerLagManager = new ProjectionLedgerLagManager();
+  private static readonly loadedMemorySnapshots = new WeakMap<MemoryFile, string>();
   static readonly KNOWLEDGE_INDEX_CACHE_TTL_MS = 600_000; // 10 minutes (entity mutations invalidate)
   /** Read by storage/memory-read-store.ts (decomposition). */
   static readonly ARTIFACT_INDEX_CACHE_TTL_MS = 60_000; // 1 minute
@@ -2005,9 +2051,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   setSecureStoreKey(key: Buffer | null, encryptOnWrite = true): void {
     if (!this.applySecureStoreKey(key, encryptOnWrite) || key === null) return;
     void this.entityCanonicalIdMigration.triggerAfterUnlock().catch((error: unknown) => {
-      log.warn(
-        `secure-store unlock migration failed: ${error instanceof Error ? error.message : String(error)}`,
-      );
+      log.warn(`secure-store unlock migration failed: ${error instanceof Error ? error.message : String(error)}`);
     });
   }
 
@@ -2316,10 +2360,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return path.join(this.stateDir, `.${kind}-version.log`);
   }
 
-  private bumpSharedVersion(
-    kind: SharedVersionKind,
-    fallbackMap: Map<string, number>
-  ): number {
+  private bumpSharedVersion(kind: SharedVersionKind, fallbackMap: Map<string, number>): number {
     const filePath = this.versionFilePath(kind);
     try {
       mkdirSync(this.stateDir, { recursive: true });
@@ -2334,10 +2375,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     }
   }
 
-  private readSharedVersion(
-    kind: SharedVersionKind,
-    fallbackMap: Map<string, number>
-  ): number {
+  private readSharedVersion(kind: SharedVersionKind, fallbackMap: Map<string, number>): number {
     const filePath = this.versionFilePath(kind);
     try {
       return statSync(filePath).size;
@@ -2364,15 +2402,14 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   }
 
   /**
-   * Entity-mutation sentinel: advanced only by entity-store content writes.
-   * The migration fingerprint keys on this instead of memory-status, so
-   * supersede/archive/delete no longer re-trigger discovery scans (#2213).
+   * Entity content revision used by migration discovery and entity-page cache coherence.
    */
   getEntityMutationVersion(): number {
     return this.readSharedVersion("entity-mutation", StorageManager.entityMutationVersionByDir);
   }
 
   protected bumpEntityMutationVersion(): void {
+    invalidateForScope(this.baseDir, "entity-write");
     this.bumpSharedVersion("entity-mutation", StorageManager.entityMutationVersionByDir);
   }
 
@@ -2646,6 +2683,217 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return resolved;
   }
 
+  private parseDeletionRevisionMetadata(raw: string): Map<string, number> {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new Error("Deletion revision metadata is invalid.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Deletion revision metadata is invalid.");
+    }
+    const root = parsed as Record<string, unknown>;
+    if (
+      Object.keys(root).sort().join(",") !== "deletions,version" ||
+      root.version !== 1 ||
+      !Array.isArray(root.deletions)
+    ) {
+      throw new Error("Deletion revision metadata is invalid.");
+    }
+    const revisions = new Map<string, number>();
+    const pathByIdentity = new Map<string, string>();
+    for (const rawEntry of root.deletions) {
+      if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+        throw new Error("Deletion revision metadata is invalid.");
+      }
+      const entry = rawEntry as Record<string, unknown>;
+      if (
+        Object.keys(entry).sort().join(",") !== "mtimeMs,path" ||
+        !isValidDeletionRevisionPath(entry.path) ||
+        typeof entry.mtimeMs !== "number" ||
+        !Number.isFinite(entry.mtimeMs) ||
+        entry.mtimeMs < 0 ||
+        entry.mtimeMs > DELETION_REVISION_MAX_MTIME_MS ||
+        revisions.has(entry.path)
+      ) {
+        throw new Error("Deletion revision metadata is invalid.");
+      }
+      const identity = deletionRevisionPathIdentity(entry.path);
+      if (pathByIdentity.has(identity)) {
+        throw new Error("Deletion revision metadata is invalid.");
+      }
+      pathByIdentity.set(identity, entry.path);
+      revisions.set(entry.path, entry.mtimeMs);
+    }
+    return new Map([...revisions.entries()].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+  }
+
+  private async readDeletionRevisionMetadata(): Promise<Map<string, number>> {
+    let raw: string;
+    try {
+      raw = await readFile(this.deletionRevisionMetadataPath, "utf8");
+    } catch (error) {
+      if (isErrnoCode(error, "ENOENT")) return new Map();
+      throw new Error("Deletion revision metadata is unavailable.");
+    }
+    return this.parseDeletionRevisionMetadata(raw);
+  }
+
+  private async writeDeletionRevisionMetadata(
+    revisions: ReadonlyMap<string, number>,
+    lock: HeldFileLockController
+  ): Promise<void> {
+    const deletions = [...revisions.entries()]
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([entryPath, mtimeMs]) => ({ path: entryPath, mtimeMs }));
+    const metadata: DeletionRevisionMetadata = { version: 1, deletions };
+    const temporaryPath = `${this.deletionRevisionMetadataPath}.${process.pid}.${randomUUID()}.tmp`;
+    let handle: FileHandle | null = null;
+    try {
+      handle = await open(temporaryPath, "wx", 0o600);
+      await handle.writeFile(`${JSON.stringify(metadata)}\n`, "utf8");
+      await handle.sync();
+      await handle.close();
+      handle = null;
+      if (!(await lock.refresh())) {
+        throw new Error("Deletion revision metadata lock was lost.");
+      }
+      await rename(temporaryPath, this.deletionRevisionMetadataPath);
+    } finally {
+      if (handle !== null) await handle.close().catch(() => undefined);
+      await unlink(temporaryPath).catch((error: unknown) => {
+        if (!isErrnoCode(error, "ENOENT")) throw error;
+      });
+    }
+  }
+
+  private async withDeletionRevisionLock<T>(task: (lock: HeldFileLockController) => Promise<T>): Promise<T> {
+    return withHeldFileLock(
+      this.deletionRevisionLockPath,
+      {
+        staleMs: DELETION_REVISION_LOCK_STALE_MS,
+        maxWaitMs: DELETION_REVISION_LOCK_MAX_WAIT_MS,
+      },
+      async (acquired, lock) => {
+        if (!acquired) throw new Error("Deletion revision metadata lock is unavailable.");
+        return task(lock);
+      }
+    );
+  }
+
+  async readDeletionRevisions(): Promise<ReadonlyMap<string, number>> {
+    return this.withDeletionRevisionLock(async () => this.readDeletionRevisionMetadata());
+  }
+
+  async recordReplicatedDeletionRevision(filePath: string, mtimeMs: number): Promise<void> {
+    const target = this.assertManagedStoragePath(filePath, "storage.recordReplicatedDeletionRevision");
+    if (
+      typeof mtimeMs !== "number" ||
+      !Number.isFinite(mtimeMs) ||
+      mtimeMs < 0 ||
+      mtimeMs > DELETION_REVISION_MAX_MTIME_MS
+    ) {
+      throw new Error("Deletion revision timestamp is invalid.");
+    }
+    const relativePath = path.relative(this.baseDir, target).split(path.sep).join("/");
+    if (!isValidDeletionRevisionPath(relativePath)) {
+      throw new Error("Deletion revision path is invalid.");
+    }
+    await this.withDeletionRevisionLock(async (lock) => {
+      const revisions = await this.readDeletionRevisionMetadata();
+      const identity = deletionRevisionPathIdentity(relativePath);
+      let existingPath: string | undefined;
+      for (const candidatePath of revisions.keys()) {
+        if (deletionRevisionPathIdentity(candidatePath) === identity) {
+          existingPath = candidatePath;
+          break;
+        }
+      }
+      const existingMtimeMs = existingPath === undefined ? undefined : revisions.get(existingPath);
+      if (existingMtimeMs !== undefined && existingMtimeMs >= mtimeMs) return;
+
+      const updated = new Map(revisions);
+      if (existingPath !== undefined) updated.delete(existingPath);
+      updated.set(relativePath, mtimeMs);
+      await this.writeDeletionRevisionMetadata(updated, lock);
+    });
+  }
+
+  protected async writeManagedStorageFile(filePath: string, write: () => Promise<void>): Promise<void> {
+    const target = this.assertManagedStoragePath(filePath, "storage.writeManagedStorageFile");
+    const relativePath = path.relative(this.baseDir, target).split(path.sep).join("/");
+    if (!isValidDeletionRevisionPath(relativePath)) {
+      throw new Error("Deletion revision path is invalid.");
+    }
+    await this.withDeletionRevisionLock(async (lock) => {
+      const before = await this.readDeletionRevisionMetadata();
+      const identity = deletionRevisionPathIdentity(relativePath);
+      const existingPath = [...before.keys()].find(
+        (candidatePath) => deletionRevisionPathIdentity(candidatePath) === identity
+      );
+      await write();
+      if (existingPath === undefined) return;
+      const updated = new Map(before);
+      updated.delete(existingPath);
+      await this.writeDeletionRevisionMetadata(updated, lock);
+    });
+  }
+
+  protected async deleteManagedStorageFile(filePath: string, deletionMtimeMs?: number | null): Promise<boolean> {
+    const target = this.assertManagedStoragePath(filePath, "storage.deleteManagedStorageFile");
+    if (
+      deletionMtimeMs !== undefined &&
+      deletionMtimeMs !== null &&
+      (typeof deletionMtimeMs !== "number" ||
+        !Number.isFinite(deletionMtimeMs) ||
+        deletionMtimeMs < 0 ||
+        deletionMtimeMs > DELETION_REVISION_MAX_MTIME_MS)
+    ) {
+      throw new Error("Deletion revision timestamp is invalid.");
+    }
+    return this.withDeletionRevisionLock(async (lock) => {
+      try {
+        await lstat(target);
+      } catch (error) {
+        if (isErrnoCode(error, "ENOENT")) return false;
+        throw error;
+      }
+      const relativePath = path.relative(this.baseDir, target).split(path.sep).join("/");
+      if (!isValidDeletionRevisionPath(relativePath)) {
+        throw new Error("Deletion revision path is invalid.");
+      }
+      const revision = deletionMtimeMs === null ? undefined : (deletionMtimeMs ?? Date.now());
+      const before = await this.readDeletionRevisionMetadata();
+      const identity = deletionRevisionPathIdentity(relativePath);
+      let existingPath: string | undefined;
+      for (const candidatePath of before.keys()) {
+        if (deletionRevisionPathIdentity(candidatePath) === identity) {
+          existingPath = candidatePath;
+          break;
+        }
+      }
+      const existing = existingPath === undefined ? undefined : before.get(existingPath);
+      const changed =
+        (existingPath !== undefined && existingPath !== relativePath) ||
+        (revision === undefined ? existing !== undefined : existing !== revision);
+      if (changed) {
+        const updated = new Map(before);
+        if (existingPath !== undefined) updated.delete(existingPath);
+        if (revision !== undefined) updated.set(relativePath, revision);
+        await this.writeDeletionRevisionMetadata(updated, lock);
+      }
+      try {
+        await unlink(target);
+        return true;
+      } catch (error) {
+        if (changed) await this.writeDeletionRevisionMetadata(before, lock);
+        if (isErrnoCode(error, "ENOENT")) return false;
+        throw error;
+      }
+    });
+  }
+
   async readOfflineSyncFile(filePath: string): Promise<Buffer> {
     const target = this.assertManagedStoragePath(filePath, "storage.readOfflineSyncFile");
     return readMaybeEncryptedFileBuffer(target, this._secureStoreKey, this.baseDir);
@@ -2929,6 +3177,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   private get offlineSyncDigestCachePath(): string {
     return path.join(this.baseDir, ".offline-sync", "digest-cache.v1.json");
   }
+  private get deletionRevisionMetadataPath(): string {
+    return path.join(this.baseDir, ".offline-sync", "deletion-revisions.v1.json");
+  }
+  private get deletionRevisionLockPath(): string {
+    return `${this.deletionRevisionMetadataPath}.lock`;
+  }
   private get entitySynthesisQueuePath(): string {
     return path.join(this.stateDir, "entity-synthesis-queue.json");
   }
@@ -3062,7 +3316,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         () => this.currentHistoricalIds(),
         (identity) => store.appendTombstone({ ...input, rawContent: strippedRawContent, ...identity }),
         (tombstoneId) => store.revoke(tombstoneId, input.createdBy),
-        input.sourceMemoryId,
+        input.sourceMemoryId
       );
     } catch (err) {
       log.warn(`tombstone append failed (memory=${input.sourceMemoryId}): ${err}`);
@@ -3455,12 +3709,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   private readonly entityCanonicalIdMigration = new EntityCanonicalIdMigrationRunner(
     () => !(this._secureStoreRequired && !this.isSecureStoreUnlocked()),
     () => this.runLegacyEntityCanonicalIdMigration(),
-    () => entityMigration.getFingerprint(this.baseDir, this.entitiesDir, () => String(this.getEntityMutationVersion())),
+    () => entityMigration.getFingerprint(this.baseDir, this.entitiesDir, () => String(this.getEntityMutationVersion()))
   );
   normalizeEntityName(raw: string, type: string): string {
     return entityRefs.resolveHistoricalEntityCanonicalId(
       this.entityStore.normalizeEntityName(raw, type),
-      this.currentHistoricalIds(),
+      this.currentHistoricalIds()
     );
   }
 
@@ -3485,27 +3739,28 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
 
   private loadAliasesSync(): void {
     const aliasPath = path.join(this.baseDir, "config", "aliases.json");
-    // Re-derive from the file on every call: a reload after the file was
-    // fixed, emptied, or removed must never leave a previous table active.
     this.userAliases = {};
+    const raw = readEntityAliasConfigSync(this.baseDir);
+    if (raw === undefined) return;
+    let parsed: unknown;
     try {
-      const raw = readFileSync(aliasPath, "utf-8");
-      const parsed = JSON.parse(raw);
-      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-        const cleaned: Record<string, string> = {};
-        for (const [key, value] of Object.entries(parsed)) {
-          if (typeof value === "string" && value.trim().length > 0) {
-            cleaned[key] = value;
-          }
+      parsed = JSON.parse(raw);
+    } catch {
+      log.debug("invalid config/aliases.json — using built-in aliases only");
+      return;
+    }
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      const cleaned: Record<string, string> = {};
+      for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value === "string" && value.trim().length > 0) {
+          assertSafeEntityId(value);
+          cleaned[key] = value;
         }
-        this.userAliases = cleaned;
-        log.debug(`loaded ${Object.keys(cleaned).length} entity aliases from ${aliasPath}`);
-      } else {
-        log.warn(`ignoring ${aliasPath}: payload must be a JSON object mapping variant → canonical strings`);
       }
-    } catch {
-      // No aliases file — that's fine, use built-in only
-      log.debug("no config/aliases.json found — using built-in aliases only");
+      this.userAliases = cleaned;
+      log.debug(`loaded ${Object.keys(cleaned).length} entity aliases from ${aliasPath}`);
+    } else {
+      log.warn(`ignoring ${aliasPath}: payload must be a JSON object mapping variant → canonical strings`);
     }
   }
   private async runLegacyEntityCanonicalIdMigration(): Promise<string | undefined> {
@@ -3513,7 +3768,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       this as unknown as EntityCanonicalIdMigrationHost,
       (content) => parseEntityFile(content, this.entitySchemas),
       (entity) => serializeEntityFile(entity, this.entitySchemas),
-      createMemoryEntityRefSerializer(serializeFrontmatter),
+      createMemoryEntityRefSerializer(serializeFrontmatter)
     );
     return completionFingerprint;
   }
@@ -3690,6 +3945,15 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     if (!sanitized.clean) {
       log.warn(`memory content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
     }
+    if (
+      options.toolScoped ||
+      withholdToolScopedFromSharedNamespace({
+        content: sanitized.text,
+        sourceConnector: options.sourceConnector,
+      })
+    ) {
+      fm.toolScoped = true;
+    }
 
     // Persist the raw-content dedup hash on the frontmatter so archive and
     // consolidation paths can remove the correct hash from ContentHashIndex
@@ -3754,14 +4018,41 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       await this.writeTombstoneBlockedMemory(filePath, fileContent, fm, sanitized.text, async () => {
         this.invalidateAllMemoriesCache();
       });
+      if (refIds && typeof rawEntityRef === "string") {
+        const refBeforeRepair = fm.entityRef;
+        try {
+          await entityRefs.repairEntityRefAfterJournalMove({
+            stateDir: this.stateDir,
+            currentIds: () => this.currentHistoricalIds(),
+            idsAtResolve: refIds,
+            rawRef: rawEntityRef,
+            frontmatter: fm,
+            rewrite: async () => {
+              await applyTombstoneGate();
+              await this.writeTombstoneBlockedMemory(
+                filePath,
+                `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`,
+                fm,
+                sanitized.text,
+                async () => this.invalidateAllMemoriesCache()
+              );
+              this.invalidateAllMemoriesCache();
+            },
+          });
+        } catch (err) {
+          await unlink(filePath).catch(() => undefined);
+          this.invalidateAllMemoriesCache();
+          await this.rebuildTombstoneBlockedCaptureAfterInvalidationForPath(filePath);
+          throw err;
+        }
+        await this.entityRefRepair.syncProjection(id, refBeforeRepair, fm.entityRef);
+      }
       return null;
     };
-    const duplicateBlocked = tombstoneBlocked
-      ? await this.withTombstoneBlockedCaptureWriteLock(
-          persistFile,
-          buildExplicitCaptureDedupKey(sanitized.text, category, fm.sourceConnector)
-        )
-      : await persistFile();
+    const duplicateBlocked = await this.withTombstoneBlockedCaptureWriteLock(persistFile, [
+      buildCapturePathLockIdentity(filePath),
+      buildExplicitCaptureDedupKey(sanitized.text, category, fm.sourceConnector),
+    ]);
     if (duplicateBlocked) {
       return {
         id: duplicateBlocked.frontmatter.id,
@@ -3770,38 +4061,6 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         duplicateOf: duplicateBlocked.frontmatter.id,
       };
     }
-    if (refIds && typeof rawEntityRef === "string") {
-      const refBeforeRepair = fm.entityRef;
-      try {
-        await entityRefs.repairEntityRefAfterJournalMove({
-          stateDir: this.stateDir,
-          currentIds: () => this.currentHistoricalIds(),
-          idsAtResolve: refIds,
-          rawRef: rawEntityRef,
-          frontmatter: fm,
-          rewrite: async () => {
-            // Re-gate under the final ref, then rewrite THROUGH the blocked-
-            // capture surface so any verdict change keeps the index consistent.
-            await applyTombstoneGate();
-            await this.writeTombstoneBlockedMemory(
-              filePath,
-              `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`,
-              fm,
-              sanitized.text,
-              async () => this.invalidateAllMemoriesCache(),
-            );
-            this.invalidateAllMemoriesCache();
-          },
-        });
-      } catch (err) {
-        // Remove the just-created file before propagating (§14): it would
-        // linger un-bumped/un-indexed and a retry would duplicate it.
-        await unlink(filePath).catch(() => undefined);
-        this.invalidateAllMemoriesCache();
-        throw err;
-      }
-      await this.entityRefRepair.syncProjection(id, refBeforeRepair, fm.entityRef);
-    }
     await this.patchHotMemoriesCache({ addedPath: filePath }, "memory-create");
     this.notifyMemoryWrite(filePath);
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeMemory", {
@@ -4073,6 +4332,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       intentActionType?: string;
       intentEntityTypes?: string[];
       sourceConnector?: string;
+      toolScoped?: true;
     } = {}
   ): Promise<string> {
     await this.ensureDirectories();
@@ -4098,6 +4358,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       intentActionType: options.intentActionType,
       intentEntityTypes: options.intentEntityTypes,
       ...(options.sourceConnector ? { sourceConnector: options.sourceConnector } : {}),
+      ...(options.toolScoped ? { toolScoped: true as const } : {}),
     };
 
     const sanitized = sanitizeMemoryContent(quote);
@@ -4227,16 +4488,10 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     if (newBullets.length === 0) return;
 
     if (!existing) {
-      const content = [
-        "# Behavioral Profile",
-        "",
-        ...newBullets.map((b) => `- ${b}`),
-        "",
-      ].join("\n");
+      const content = ["# Behavioral Profile", "", ...newBullets.map((b) => `- ${b}`), ""].join("\n");
       await this.writeProfile(content);
     } else {
-      const withBullets =
-        existing.trimEnd() + "\n" + newBullets.map((b) => `- ${b}`).join("\n") + "\n";
+      const withBullets = existing.trimEnd() + "\n" + newBullets.map((b) => `- ${b}`).join("\n") + "\n";
       await this.writeProfile(withBullets);
     }
   }
@@ -4251,13 +4506,19 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return lineCount > threshold;
   }
 
+  private rememberMemorySnapshot<T extends MemoryFile | null>(memory: T): T {
+    if (memory !== null && !StorageManager.loadedMemorySnapshots.has(memory)) {
+      StorageManager.loadedMemorySnapshots.set(memory, createMemorySnapshot(memory));
+    }
+    return memory;
+  }
+
+  private rememberMemorySnapshots(memories: MemoryFile[]): MemoryFile[] {
+    for (const memory of memories) this.rememberMemorySnapshot(memory);
+    return memories;
+  }
+
   async readAllMemories(): Promise<MemoryFile[]> {
-    // Version-keyed hot-memories cache (issue #1902): once populated, serve the
-    // full parsed corpus from memory within a version epoch. getCachedMemories
-    // returns null when the sentinel is 0 (fresh/test dirs) or the stored
-    // version differs from the current on-disk sentinel (a peer or local write
-    // bumped it), so a stale entry is never served — the miss falls through to
-    // a fresh disk scan below.
     if (this.hotMemoriesCacheEnabled) {
       const cached = getCachedMemories(
         this.baseDir,
@@ -4265,13 +4526,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         this.hotCacheKeyId(),
         this.hotCacheTtlMs()
       );
-      // Null-check, not truthiness (kilo WARNING): getCachedMemories returns []
-      // for a cached EMPTY corpus, which is falsy — a truthiness guard would
-      // force a full disk scan on every read of an empty/near-empty store.
-      if (cached !== null) return cached;
+      if (cached !== null) return this.rememberMemorySnapshots(cached);
     }
-    // Deduplicate concurrent reads for the same directory so multiple
-    // callers in the same recall share one disk scan.
     // Snapshot the secure-store key identity ONCE (issue #1902, Codex Medium):
     // hotCacheKeyId() can change mid-scan if setSecureStoreKey(null/other) runs
     // during the await. Recomputing it at publish time would store K-decrypted
@@ -4281,13 +4537,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     // key change can't orphan the slot registered under the old identity.
     const keyId = this.hotCacheKeyId();
     const inFlight = getInFlightRead(this.baseDir, keyId);
-    if (inFlight) return inFlight;
+    if (inFlight) return this.rememberMemorySnapshots(await inFlight);
 
     const readPromise = (async (): Promise<MemoryFile[]> => {
-      // Capture the version BEFORE the scan and store under it. If a concurrent
-      // bump (peer or local write) lands during the scan, the stored entry's
-      // version is older than the sentinel, so the next getCachedMemories()
-      // rejects it (version mismatch → rescan) — correct, never stale.
       const version = this.getMemoryCorpusVersion();
       const memories = await this._readAllMemoriesFromDisk();
       // Publish only if neither the corpus version NOR the key identity changed
@@ -4301,11 +4553,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     })();
     setInFlightRead(this.baseDir, keyId, readPromise);
     try {
-      return await readPromise;
+      return this.rememberMemorySnapshots(await readPromise);
     } finally {
-      // Only delete if we still own the slot for our snapshot key identity —
-      // invalidateAllMemoriesCache() may have already cleared it and a new read
-      // may have claimed it (the expected-promise guard enforces owner-only).
       deleteInFlightRead(this.baseDir, keyId, readPromise);
     }
   }
@@ -4601,15 +4850,18 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
             const raw = await readMaybeEncryptedFile(fullPath, this._secureStoreKey, this.baseDir);
             const parsed = parseFrontmatter(raw);
             if (!parsed) return null;
-            return rememberRawFrontmatter({
-              path: fullPath,
-              frontmatter: normalizeFrontmatterForPath(
-                parsed.frontmatter,
-                toMemoryPathRel(this.baseDir, fullPath),
-                parsed.content
-              ),
-              content: parsed.content,
-            } satisfies MemoryFile, raw);
+            return rememberRawFrontmatter(
+              {
+                path: fullPath,
+                frontmatter: normalizeFrontmatterForPath(
+                  parsed.frontmatter,
+                  toMemoryPathRel(this.baseDir, fullPath),
+                  parsed.content
+                ),
+                content: parsed.content,
+              } satisfies MemoryFile,
+              raw
+            );
           } catch (err) {
             // Re-throw store-locked errors so a locked encrypted store fails
             // loudly rather than appearing as an empty memory corpus (Cursor
@@ -4737,7 +4989,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   }
 
   async readAllColdMemories(): Promise<MemoryFile[]> {
-    return this.memoryReadStore.readAllColdMemories();
+    return this.rememberMemorySnapshots(await this.memoryReadStore.readAllColdMemories());
   }
 
   /**
@@ -4760,15 +5012,20 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
               const raw = await readMaybeEncryptedFile(fullPath, this._secureStoreKey, this.baseDir);
               const parsed = parseFrontmatter(raw);
               if (parsed) {
-                memories.push(rememberRawFrontmatter({
-                  path: fullPath,
-                  frontmatter: normalizeFrontmatterForPath(
-                    parsed.frontmatter,
-                    toMemoryPathRel(this.baseDir, fullPath),
-                    parsed.content
-                  ),
-                  content: parsed.content,
-                }, raw));
+                memories.push(
+                  rememberRawFrontmatter(
+                    {
+                      path: fullPath,
+                      frontmatter: normalizeFrontmatterForPath(
+                        parsed.frontmatter,
+                        toMemoryPathRel(this.baseDir, fullPath),
+                        parsed.content
+                      ),
+                      content: parsed.content,
+                    },
+                    raw
+                  )
+                );
               }
             } catch (err) {
               // Re-throw store-locked errors — a locked encrypted store
@@ -4784,11 +5041,11 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     };
 
     await readDir(root);
-    return memories;
+    return this.rememberMemorySnapshots(memories);
   }
 
   async readMemoryByPath(filePath: string): Promise<MemoryFile | null> {
-    return this.memoryReadStore.readMemoryByPath(filePath);
+    return this.rememberMemorySnapshot(await this.memoryReadStore.readMemoryByPath(filePath));
   }
 
   private resolveTierRootDir(tier: "hot" | "cold"): string {
@@ -4816,12 +5073,6 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       // corrections/ is flat (no date subdir); preserved across tier moves.
       return path.join(root, "corrections", `${memory.frontmatter.id}.md`);
     }
-    // Every other category — decisions/, preferences/, reasoning-traces/, ...
-    // plus the facts/ fallback for fact/entity/unknown — resolves through the
-    // shared categoryDirName() chokepoint so tier moves land in the SAME dir the
-    // writer used, instead of funneling non-{correction,procedure,reasoning_trace}
-    // categories into facts/ (issue #564 PR 3 preserved reasoning-traces/; #1546
-    // generalizes it to every category dir).
     const dir = categoryDirName(memory.frontmatter.category);
     return path.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
   }
@@ -4838,7 +5089,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         `${serializeFrontmatter(frontmatter)}\n\n${memory.content}\n`,
         this.resolveWriteKey(),
         {},
-        this.baseDir,
+        this.baseDir
       );
     // Snapshot pre-write destination bytes (raw — encryption-agnostic) so a
     // repair failure restores them or removes a fresh copy (§14): a retained
@@ -4876,25 +5127,67 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     this.invalidateAllMemoriesCache();
     this.notifyCatalogWrite();
   }
-  async moveMemoryToPath(memory: MemoryFile, targetPath: string): Promise<void> {
-    await this.writeMemoryFileAtomic(targetPath, memory);
-    const sourcePath = path.resolve(memory.path);
-    const destPath = path.resolve(targetPath);
-    if (sourcePath !== destPath) {
-      try {
-        await unlink(memory.path);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (!message.includes("ENOENT")) {
-          throw err;
+  async moveMemoryToPath(memory: MemoryFile, targetPath: string): Promise<boolean> {
+    const changed = await this.withTombstoneBlockedMemoryPathLock(
+      memory.path,
+      async (current) => {
+        const destination = await this.readMemoryByPath(targetPath);
+        if (current?.frontmatter.id !== memory.frontmatter.id) {
+          if (current === null && destination?.frontmatter.id === memory.frontmatter.id) return false;
+          throw new Error(`memory ${memory.frontmatter.id} changed before its tier move`);
         }
-      }
-      // Re-invalidate after the unlink — writeMemoryFileAtomic already
-      // invalidated, but a concurrent readAllMemories() may have re-populated
-      // the cache between the write and the unlink.
-      this.invalidateAllMemoriesCache();
-      updateProjectedMemoryPath(this.baseDir, memory.frontmatter.id, toMemoryPathRel(this.baseDir, targetPath));
+        const callerSnapshot = StorageManager.loadedMemorySnapshots.get(memory);
+        const currentSnapshot = createMemorySnapshot(current);
+        if (
+          callerSnapshot === undefined
+            ? current.frontmatter.updated !== memory.frontmatter.updated
+            : currentSnapshot !== callerSnapshot
+        ) {
+          throw new Error(`memory ${memory.frontmatter.id} changed before its tier move`);
+        }
+        const coordinate =
+          tombstoneBlocked(current.frontmatter) ||
+          isQueuedReviewMemory(current) ||
+          (destination !== null && tombstoneBlocked(destination.frontmatter)) ||
+          isQueuedReviewMemory(destination);
+        const index = this.getTombstoneBlockedCaptureIndex();
+        const marker = coordinate ? await index.prepareWrite() : undefined;
+        const projectedPath = toMemoryPathRel(this.baseDir, targetPath);
+        let durable = false;
+        try {
+          if (destination?.frontmatter.id === current.frontmatter.id) {
+            await this.deleteManagedStorageFile(current.path);
+            durable = true;
+            this.invalidateAllMemoriesCache();
+            updateProjectedMemoryPath(this.baseDir, current.frontmatter.id, projectedPath);
+          } else {
+            await this.writeMemoryFileAtomic(targetPath, current);
+            if (memory.frontmatter.entityRef !== current.frontmatter.entityRef) {
+              memory.frontmatter.entityRef = current.frontmatter.entityRef;
+            }
+            durable = true;
+            const sourcePath = path.resolve(current.path);
+            const destPath = path.resolve(targetPath);
+            if (sourcePath !== destPath) {
+              await this.deleteManagedStorageFile(current.path);
+              this.invalidateAllMemoriesCache();
+              updateProjectedMemoryPath(this.baseDir, current.frontmatter.id, projectedPath);
+            }
+          }
+          if (marker !== undefined) await this.rebuildTombstoneBlockedCaptureAfterInvalidation(marker);
+        } catch (error) {
+          if (marker !== undefined && !durable) await index.discardWrite(marker).catch(() => index.markUntrusted());
+          if (marker !== undefined && durable) index.markUntrusted();
+          throw error;
+        }
+        return true;
+      },
+      [targetPath]
+    );
+    if (this.isColdOrArchiveTierPath(memory.path) || this.isColdOrArchiveTierPath(targetPath)) {
+      this.invalidateColdMemoriesCache();
     }
+    return changed;
   }
 
   async migrateMemoryToTier(
@@ -4907,31 +5200,10 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     if (sourcePath === destPath) {
       return { changed: false, targetPath };
     }
-
-    const existing = await this.readMemoryByPath(targetPath);
-    if (existing?.frontmatter.id === memory.frontmatter.id) {
-      try {
-        await unlink(memory.path);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (!message.includes("ENOENT")) {
-          throw err;
-        }
-      }
-      updateProjectedMemoryPath(this.baseDir, memory.frontmatter.id, toMemoryPathRel(this.baseDir, targetPath));
-      this.bumpMemoryStatusVersion();
-      return { changed: false, targetPath };
-    }
-
-    await this.moveMemoryToPath(memory, targetPath);
-    this.invalidateAllMemoriesCache();
-    // If moving to cold, also invalidate the cold-scan cache so the next
-    // readAllColdMemories() call sees the newly-demoted file (Finding UOGi fix).
-    if (targetTier === "cold") {
-      this.invalidateColdMemoriesCache();
-    }
+    const changed = await this.moveMemoryToPath(memory, targetPath);
+    if (!changed) return { changed: false, targetPath };
     this.bumpMemoryStatusVersion();
-    return { changed: true, targetPath };
+    return { changed, targetPath };
   }
 
   private get archiveDir(): string {
@@ -4959,7 +5231,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
             archivedAt: now.toISOString(),
             updated: now.toISOString(),
           },
-          refIdsAtWrite,
+          refIdsAtWrite
         );
         const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${current.content}\n`;
         const destPath = path.join(destDir, path.basename(current.path));
@@ -4970,7 +5242,11 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         if (typeof current.frontmatter.entityRef === "string") {
           try {
             await this.entityRefRepair.repair(
-              destPath, updatedFm, current.frontmatter.entityRef, refIdsAtWrite, current.content,
+              destPath,
+              updatedFm,
+              current.frontmatter.entityRef,
+              refIdsAtWrite,
+              current.content
             );
           } catch (err) {
             // Restore/remove the destination before reporting failure (§14):
@@ -4983,7 +5259,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
             throw err;
           }
         }
-        await unlink(current.path);
+        if (!(await this.deleteManagedStorageFile(current.path))) return null;
         markDurable();
         markProjectedMemoryPathInvalid(this.baseDir, current.frontmatter.id);
         this.invalidateAllMemoriesCache();
@@ -5076,25 +5352,21 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return null;
   }
 
-
   async invalidateMemory(id: string): Promise<boolean> {
     const memories = await this.readAllMemories();
     const memory = memories.find((candidate) => candidate.frontmatter.id === id);
     if (!memory) return false;
 
-    return await this.runTombstoneBlockedInvalidation(
-      memory,
-      async (current, rebuildMarker, markDurable) => {
-        await unlink(current.path);
-        markDurable();
-        markProjectedMemoryPathInvalid(this.baseDir, id);
-        this.invalidateAllMemoriesCache();
-        await this.rebuildTombstoneBlockedCaptureAfterInvalidation(rebuildMarker);
-        this.bumpMemoryStatusVersion();
-        log.debug(`invalidated memory ${id}`);
-        return true;
-      }
-    );
+    return await this.runTombstoneBlockedInvalidation(memory, async (current, rebuildMarker, markDurable) => {
+      if (!(await this.deleteManagedStorageFile(current.path))) return false;
+      markDurable();
+      markProjectedMemoryPathInvalid(this.baseDir, id);
+      this.invalidateAllMemoriesCache();
+      await this.rebuildTombstoneBlockedCaptureAfterInvalidation(rebuildMarker);
+      this.bumpMemoryStatusVersion();
+      log.debug(`invalidated memory ${id}`);
+      return true;
+    });
   }
 
   async updateMemory(
@@ -5122,7 +5394,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
           ? { sourceConnector: options.sourceConnector }
           : {}),
       },
-      refIdsAtWrite,
+      refIdsAtWrite
     );
     const sanitized = sanitizeMemoryContent(newContent);
     if (!sanitized.clean) {
@@ -5134,8 +5406,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     });
     if (typeof memory.frontmatter.entityRef === "string") {
       await this.entityRefRepair.repair(
-        memory.path, updated, memory.frontmatter.entityRef, refIdsAtWrite, sanitized.text,
-        { onFailRestore: memory },
+        memory.path,
+        updated,
+        memory.frontmatter.entityRef,
+        refIdsAtWrite,
+        sanitized.text,
+        { onFailRestore: memory }
       );
     }
     await this.patchHotMemoriesCache({ addedPath: memory.path });
@@ -5170,7 +5446,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     const resolveIds = this.currentHistoricalIds();
     const updated: MemoryFrontmatter = entityRefs.canonicalizeEntityRefOption(
       { ...memory.frontmatter, ...patch },
-      resolveIds,
+      resolveIds
     );
     const refIds = typeof updated.entityRef === "string" ? resolveIds : null;
     const afterStatus = updated.status ?? "active";
@@ -5185,10 +5461,9 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     });
     const rawMergedRef = typeof patch.entityRef === "string" ? patch.entityRef : memory.frontmatter.entityRef;
     if (refIds && typeof rawMergedRef === "string") {
-      await this.entityRefRepair.repair(
-        memory.path, updated, rawMergedRef, refIds, memory.content,
-        { onFailRestore: memory },
-      );
+      await this.entityRefRepair.repair(memory.path, updated, rawMergedRef, refIds, memory.content, {
+        onFailRestore: memory,
+      });
     }
     await this.patchHotMemoriesCache({ addedPath: memory.path });
     if (memory.path.includes(`${path.sep}cold${path.sep}`)) {
@@ -6336,26 +6611,31 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         : memoryMap.get(entry.memoryId);
       if (!memory) continue;
 
-      const rowIds = this.currentHistoricalIds();
-      const newFm: MemoryFrontmatter = entityRefs.canonicalizeEntityRefOption(
-        { ...memory.frontmatter, accessCount: entry.newCount, lastAccessed: entry.lastAccessed },
-        rowIds,
-      );
-
       try {
-        const fileContent = `${serializeFrontmatter(newFm)}\n\n${memory.content}\n`;
-        await this.writeStorageSecureFile(memory.path, fileContent);
-        if (typeof memory.frontmatter.entityRef === "string") {
-          // onFailRestore (§14): the count patch was never reported applied.
-          await this.entityRefRepair.repair(
-            memory.path, newFm, memory.frontmatter.entityRef, rowIds, memory.content,
-            { onFailRestore: memory },
+        const applied = await this.withTombstoneBlockedMemoryPathLock(memory.path, async (current) => {
+          if (current?.frontmatter.id !== entry.memoryId) return null;
+          const rowIds = this.currentHistoricalIds();
+          const newFm: MemoryFrontmatter = entityRefs.canonicalizeEntityRefOption(
+            { ...current.frontmatter, accessCount: entry.newCount, lastAccessed: entry.lastAccessed },
+            rowIds
           );
-        }
-        // Patch the hot corpus cache entry in place (#1902); the shared
-        // sentinel is bumped once after the loop for cross-process coherence.
+          const fileContent = `${serializeFrontmatter(newFm)}\n\n${current.content}\n`;
+          await this.writeTombstoneBlockedFrontmatter(current, fileContent, newFm);
+          if (typeof current.frontmatter.entityRef === "string") {
+            await this.entityRefRepair.repair(
+              current.path,
+              newFm,
+              current.frontmatter.entityRef,
+              rowIds,
+              current.content,
+              { onFailRestore: current }
+            );
+          }
+          return { current, newFm };
+        });
+        if (applied === null) continue;
         if (warm) {
-          updateCacheOnWrite(this.baseDir, { ...memory, frontmatter: newFm }, keyId);
+          updateCacheOnWrite(this.baseDir, { ...applied.current, frontmatter: applied.newFm }, keyId);
         }
         appliedPatches.set(path.resolve(memory.path), {
           accessCount: entry.newCount,
@@ -6602,6 +6882,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       observedAt?: string;
       eventTimeSource?: "extracted" | "assumed";
       sourceConnector?: string;
+      toolScoped?: true;
     } = {}
   ): Promise<string> {
     await this.ensureDirectories();
@@ -6616,6 +6897,10 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     const validAt = normalizeMemoryWriteTimestamp("validAt", options.validAt);
     const chunkInvalidAt = normalizeMemoryWriteTimestamp("invalidAt", options.invalidAt);
     const chunkObservedAt = normalizeMemoryWriteTimestamp("observedAt", options.observedAt);
+    const sanitized = sanitizeMemoryContent(content);
+    if (!sanitized.clean) {
+      log.warn(`chunk content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
+    }
 
     const fm: MemoryFrontmatter = {
       id,
@@ -6645,28 +6930,17 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       ...(options.sources ? { sources: options.sources } : {}),
       ...(options.provenance ? { provenance: options.provenance } : {}),
       ...(options.sourceConnector ? { sourceConnector: options.sourceConnector } : {}),
+      ...(options.toolScoped ||
+      withholdToolScopedFromSharedNamespace({
+        content: sanitized.text,
+        sourceConnector: options.sourceConnector,
+      })
+        ? { toolScoped: true as const }
+        : {}),
     };
 
-    const sanitized = sanitizeMemoryContent(content);
-    if (!sanitized.clean) {
-      log.warn(`chunk content sanitized for ${id}; violations=${sanitized.violations.join(", ")}`);
-    }
     const filePath = await this.resolveCategoryWritePath(category, id, today);
     const fileContent = `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`;
-    // A retried chunk write lands on the SAME deterministic path, so the
-    // target can already hold a valid prior chunk: snapshot it, and a repair
-    // failure restores it — unlink only a file THIS invocation created
-    // (Codex P2, round 22).
-    let priorChunk: MemoryFile | null = null;
-    try {
-      const priorRaw = await readMaybeEncryptedFile(filePath, this._secureStoreKey, this.baseDir);
-      const parsedPrior = parseFrontmatter(priorRaw);
-      if (parsedPrior) {
-        priorChunk = { path: filePath, frontmatter: parsedPrior.frontmatter, content: parsedPrior.content };
-      }
-    } catch {
-      priorChunk = null;
-    }
 
     const written = await this.writeTombstoneBlockedChunk(
       filePath,
@@ -6674,24 +6948,19 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       fm,
       sanitized.text,
       () => this.findExistingTombstoneBlockedMemory(sanitized.text, category, fm.sourceConnector),
-      async () => {
+      async (priorChunk) => {
+        if (refIds && typeof rawEntityRef === "string") {
+          await this.entityRefRepair.repair(filePath, fm, rawEntityRef, refIds, sanitized.text, {
+            regateFact: true,
+            ...(priorChunk ? { onFailRestore: priorChunk } : { onFailRemove: filePath }),
+          });
+        }
         // Keep the version-keyed hot-memories cache coherent with the new chunk
         // file (issue #1902) — same single-file patch path writeMemory uses.
         await this.patchHotMemoriesCache({ addedPath: filePath }, "memory-create");
         log.debug(`wrote chunk ${id} (${chunkIndex + 1}/${chunkTotal}) to ${filePath}`);
       }
     );
-    // Repair only when THIS chunk persisted: a tombstone-dedupe result
-    // returns an existing id without writing filePath, and an unconditional
-    // repair rewrite would create a stray second chunk from scratch. The
-    // rewrite RE-GATES under the final ref (Bugbot): a journal move into
-    // tombstone-blocked identity space must not leave a fact chunk active.
-    if (written === id && refIds && typeof rawEntityRef === "string") {
-      await this.entityRefRepair.repair(filePath, fm, rawEntityRef, refIds, sanitized.text, {
-        regateFact: true,
-        ...(priorChunk ? { onFailRestore: priorChunk } : { onFailRemove: filePath }),
-      });
-    }
     return written;
   }
 
@@ -6720,25 +6989,33 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     if (!oldMemory) return false;
 
     const now = new Date().toISOString();
-    // Whole-record rewrite — inherited-entityRef rule (issue #2213).
-    const refIdsAtWrite = this.currentHistoricalIds();
-    const updatedFm: MemoryFrontmatter = entityRefs.canonicalizeEntityRefOption(
-      { ...oldMemory.frontmatter, status: "superseded", supersededBy: newMemoryId, supersededAt: now, updated: now },
-      refIdsAtWrite,
-    );
-
-    const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${oldMemory.content}\n`;
+    let currentBefore = oldMemory;
+    let updatedFm = oldMemory.frontmatter;
 
     try {
-      await this.writeStorageSecureFile(oldMemory.path, fileContent);
-      if (typeof oldMemory.frontmatter.entityRef === "string") {
-        // onFailRestore (§14): a record left superseded on disk would skip
-        // its non-resurrection tombstone while caches expose the old state.
-        await this.entityRefRepair.repair(
-          oldMemory.path, updatedFm, oldMemory.frontmatter.entityRef, refIdsAtWrite, oldMemory.content,
-          { onFailRestore: oldMemory },
+      const written = await this.withTombstoneBlockedMemoryPathLock(oldMemory.path, async (current) => {
+        if (current?.frontmatter.id !== oldMemoryId) return false;
+        currentBefore = current;
+        const refIdsAtWrite = this.currentHistoricalIds();
+        updatedFm = entityRefs.canonicalizeEntityRefOption(
+          { ...current.frontmatter, status: "superseded", supersededBy: newMemoryId, supersededAt: now, updated: now },
+          refIdsAtWrite
         );
-      }
+        const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${current.content}\n`;
+        await this.writeTombstoneBlockedFrontmatter(current, fileContent, updatedFm);
+        if (typeof current.frontmatter.entityRef === "string") {
+          await this.entityRefRepair.repair(
+            current.path,
+            updatedFm,
+            current.frontmatter.entityRef,
+            refIdsAtWrite,
+            current.content,
+            { onFailRestore: current }
+          );
+        }
+        return true;
+      });
+      if (!written) return false;
       // Advance the corpus sentinel immediately after the on-disk write, BEFORE
       // the awaited lifecycle append (Cursor Medium, #1902). Otherwise a warm
       // hot-memories cache keeps serving the pre-supersede snapshot during the
@@ -6751,8 +7028,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
         timestamp: now,
         actor: "storage.supersedeMemory",
         reasonCode: reason,
-        before: this.summarizeLifecycleState(oldMemory.frontmatter, oldMemory.path),
-        after: this.summarizeLifecycleState(updatedFm, oldMemory.path),
+        before: this.summarizeLifecycleState(currentBefore.frontmatter, currentBefore.path),
+        after: this.summarizeLifecycleState(updatedFm, currentBefore.path),
         relatedMemoryIds: [newMemoryId],
       });
       this.bumpMemoryStatusVersion();
@@ -6762,14 +7039,14 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       // so emitting covers each exactly once (rule 22); facts only. One
       // tombstone PER derived supersession key (thread Oci-Y) so a
       // paraphrased re-write is caught on the keyed tier.
-      if (oldMemory.frontmatter.category === "fact") {
+      if (currentBefore.frontmatter.category === "fact") {
         for (const input of buildRetiredFactTombstoneInputs(
           {
             id: oldMemoryId,
-            content: stripCitationForTemplate(oldMemory.content, this.citationTemplate),
-            contentHash: oldMemory.frontmatter.contentHash,
+            content: stripCitationForTemplate(currentBefore.content, this.citationTemplate),
+            contentHash: currentBefore.frontmatter.contentHash,
             entityRef: updatedFm.entityRef,
-            structuredAttributes: oldMemory.frontmatter.structuredAttributes,
+            structuredAttributes: currentBefore.frontmatter.structuredAttributes,
           },
           {
             reason: "contradiction_resolution",
@@ -6783,7 +7060,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       }
 
       // Audit-trail correction — sealed even INSIDE the engine (#2022 review).
-      const auditBody = `Superseded: ${oldMemory.content}\n\nReason: ${reason}`;
+      const auditBody = `Superseded: ${currentBefore.content}\n\nReason: ${reason}`;
       const auditInput = {
         content: auditBody,
         category: "correction" as const,
@@ -6854,22 +7131,33 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       if (!memory) continue;
 
       const now = new Date().toISOString();
-      const rowIds = this.currentHistoricalIds();
-      const updatedFm: MemoryFrontmatter = entityRefs.canonicalizeEntityRefOption(
-        { ...memory.frontmatter, status: "archived", archivedAt: now, updated: now },
-        rowIds,
-      );
+      let currentBefore = memory;
+      let updatedFm = memory.frontmatter;
 
       try {
-        const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${memory.content}\n`;
-        await this.writeStorageSecureFile(memory.path, fileContent);
-        if (typeof memory.frontmatter.entityRef === "string") {
-          // onFailRestore (§14): the method reports the row NOT archived.
-          await this.entityRefRepair.repair(
-            memory.path, updatedFm, memory.frontmatter.entityRef, rowIds, memory.content,
-            { onFailRestore: memory },
+        const written = await this.withTombstoneBlockedMemoryPathLock(memory.path, async (current) => {
+          if (current?.frontmatter.id !== id) return false;
+          currentBefore = current;
+          const rowIds = this.currentHistoricalIds();
+          updatedFm = entityRefs.canonicalizeEntityRefOption(
+            { ...current.frontmatter, status: "archived", archivedAt: now, updated: now },
+            rowIds
           );
-        }
+          const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${current.content}\n`;
+          await this.writeTombstoneBlockedFrontmatter(current, fileContent, updatedFm);
+          if (typeof current.frontmatter.entityRef === "string") {
+            await this.entityRefRepair.repair(
+              current.path,
+              updatedFm,
+              current.frontmatter.entityRef,
+              rowIds,
+              current.content,
+              { onFailRestore: current }
+            );
+          }
+          return true;
+        });
+        if (!written) continue;
         // Per-file corpus bump BEFORE the awaited lifecycle append (#1902):
         // the end-of-loop status bump fires only after the whole batch.
         this.bumpMemoryCorpusVersion();
@@ -6879,8 +7167,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
           timestamp: updatedFm.archivedAt ?? updatedFm.updated,
           actor: "storage.archiveMemories",
           reasonCode: `summary:${summaryId}`,
-          before: this.summarizeLifecycleState(memory.frontmatter, memory.path),
-          after: this.summarizeLifecycleState(updatedFm, memory.path),
+          before: this.summarizeLifecycleState(currentBefore.frontmatter, currentBefore.path),
+          after: this.summarizeLifecycleState(updatedFm, currentBefore.path),
           relatedMemoryIds: [summaryId],
         });
         archived++;