@remnic/core 9.7.15 → 9.8.0

package/src/offline-sync-impression-drain.test.ts

@@ -0,0 +1,316 @@
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, readdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import {
+  drainPendingImpressionsForOfflineSync,
+  drainPendingLifecycleForOfflineSync,
+  getOfflineSyncStorage,
+} from "./offline-sync-impression-drain.js";
+import { isEncryptedFile } from "./secure-store/secure-fs.js";
+import { StorageManager } from "./storage.js";
+
+test("retries deferred drains and succeeds when the lock is released", async () => {
+  let calls = 0;
+  await drainPendingImpressionsForOfflineSync(async () => {
+    calls += 1;
+    return { pendingDeferred: calls < 2 };
+  });
+  assert.equal(calls, 2);
+});
+
+test("retries a transient drain error before succeeding", async () => {
+  let calls = 0;
+  await drainPendingImpressionsForOfflineSync(async () => {
+    calls += 1;
+    if (calls === 1) throw new Error("temporary lock failure");
+    return { pendingDeferred: false };
+  });
+  assert.equal(calls, 2);
+});
+
+test("aborts after repeated deferrals instead of producing an incomplete snapshot", async () => {
+  let calls = 0;
+  await assert.rejects(
+    drainPendingImpressionsForOfflineSync(async () => {
+      calls += 1;
+      return { pendingDeferred: true };
+    }),
+    /could not fold pending recall impressions after 3 attempts/,
+  );
+  assert.equal(calls, 3);
+});
+
+const LIFECYCLE_LEDGER_REL = "state/memory-lifecycle-ledger.jsonl";
+const LIFECYCLE_PENDING_REL = `${LIFECYCLE_LEDGER_REL}.pending.d`;
+
+// Seed one durable pending lifecycle spill exactly as appendLifecycleEventsSerialized
+// does when the ledger lock is held (#2033): a `<uuid>.jsonl` file inside the
+// offline-sync-EXCLUDED pending dir under `stateRel`. The nonce proves this row
+// was folded rather than dropped by the sync exclude glob.
+async function seedPendingLifecycle(root: string, stateRel: string): Promise<string> {
+  const nonce = randomUUID();
+  const pendingDir = path.join(root, stateRel, "memory-lifecycle-ledger.jsonl.pending.d");
+  await mkdir(pendingDir, { recursive: true });
+  const line = `${JSON.stringify({ type: "promotion", memoryId: "mem-1", timestamp: "2026-01-01T00:00:00.000Z", nonce })}\n`;
+  await writeFile(path.join(pendingDir, `${randomUUID()}.jsonl`), line, "utf-8");
+  return nonce;
+}
+
+test("drainPendingLifecycleForOfflineSync folds root and per-namespace pending spills (#2033)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-drain-"));
+  try {
+    const rootNonce = await seedPendingLifecycle(root, "state");
+    const nsNonce = await seedPendingLifecycle(root, "namespaces/team/state");
+
+    await drainPendingLifecycleForOfflineSync(root);
+
+    const rootPending = await readdir(path.join(root, LIFECYCLE_PENDING_REL)).catch(() => [] as string[]);
+    assert.deepEqual(rootPending, [], "root pending spills must be folded and finalized");
+    const rootActive = await readFile(path.join(root, LIFECYCLE_LEDGER_REL), "utf-8");
+    assert.ok(rootActive.includes(rootNonce), "root lifecycle row must land in the synced active ledger");
+
+    const nsPending = await readdir(
+      path.join(root, "namespaces/team", LIFECYCLE_PENDING_REL),
+    ).catch(() => [] as string[]);
+    assert.deepEqual(nsPending, [], "per-namespace pending spills must be folded and finalized");
+    const nsActive = await readFile(
+      path.join(root, "namespaces/team", LIFECYCLE_LEDGER_REL),
+      "utf-8",
+    );
+    assert.ok(nsActive.includes(nsNonce), "per-namespace lifecycle row must land in its active ledger");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("drains encrypted lifecycle spills through secure storage (#2033)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-drain-secure-"));
+  const key = Buffer.alloc(32, 17);
+  const storage = new StorageManager(root);
+  storage.setSecureStoreRequired(true);
+  storage.setSecureStoreKey(key);
+  try {
+    const nonce = randomUUID();
+    const pendingDir = path.join(root, LIFECYCLE_PENDING_REL);
+    const pendingPath = path.join(pendingDir, `${randomUUID()}.jsonl`);
+    await mkdir(pendingDir, { recursive: true });
+    await storage.writeMemoryLifecycleLedgerContent(
+      `${JSON.stringify({
+        type: "promotion",
+        memoryId: "mem-secure",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        nonce,
+      })}\n`,
+      pendingPath,
+    );
+
+    await drainPendingLifecycleForOfflineSync(
+      root,
+      (ledgerPath) => storage.drainPendingMemoryLifecycleEventsForSyncAt(ledgerPath),
+    );
+
+    assert.deepEqual(await readdir(pendingDir), []);
+    assert.ok(
+      isEncryptedFile(await readFile(path.join(root, LIFECYCLE_LEDGER_REL))),
+      "the active ledger must remain encrypted",
+    );
+    const activePlaintext = await storage.readMemoryLifecycleLedgerRawBufferForCompaction();
+    assert.ok(activePlaintext.toString("utf-8").includes(nonce));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("drainPendingLifecycleForOfflineSync aborts when pending rows cannot be folded (#2033)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-drain-abort-"));
+  try {
+    await seedPendingLifecycle(root, "state");
+    // The active ledger path is a DIRECTORY, so the fold's append fails on every
+    // attempt: the durable spill can never be committed, so the drain aborts
+    // rather than let a caller build a snapshot that silently omits it.
+    await mkdir(path.join(root, LIFECYCLE_LEDGER_REL), { recursive: true });
+
+    await assert.rejects(
+      drainPendingLifecycleForOfflineSync(root),
+      (err: unknown) => {
+        assert.ok(err instanceof Error);
+        assert.match(
+          err.message,
+          /lifecycle drain could not fold pending memory-lifecycle events after 3 attempts.*aborting snapshot/s,
+        );
+        assert.ok(
+          !err.message.includes(root),
+          "abort error must not leak the ledger's absolute path (#2033)",
+        );
+        return true;
+      },
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("aborted impression drain redacts the underlying error path (#2033)", async () => {
+  // A persona path standing in for a real operator's memory dir. displayErrorDetail
+  // must reduce the thrown fs error to its class + errno code so the absolute path
+  // never reaches CLI stderr / the offline snapshot failure.
+  const secretPath = "/home/user/.remnic/state/recall_impressions.jsonl";
+  await assert.rejects(
+    drainPendingImpressionsForOfflineSync(async () => {
+      const err = new Error(`EACCES: permission denied, open '${secretPath}'`);
+      (err as NodeJS.ErrnoException).code = "EACCES";
+      throw err;
+    }),
+    (err: unknown) => {
+      assert.ok(err instanceof Error);
+      assert.ok(!err.message.includes(secretPath), "raw fs path must not leak into the abort error");
+      assert.match(err.message, /could not fold pending recall impressions after 3 attempts/);
+      assert.match(err.message, /EACCES/, "the path-free error class + code still surfaces");
+      return true;
+    },
+  );
+});
+
+test("drainPendingLifecycleForOfflineSync skips a symlinked namespace child (#2033 containment)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-drain-symlink-child-"));
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-drain-outside-"));
+  try {
+    const rootNonce = await seedPendingLifecycle(root, "state");
+    const teamNonce = await seedPendingLifecycle(root, "namespaces/team/state");
+    // A poisoned namespace child symlinked outside the memory root, carrying its
+    // own pending spill. The drain must NOT fold through it (no ledger appended
+    // outside memoryDir) yet still fold the root and the legit namespace.
+    await seedPendingLifecycle(outside, "state");
+    await mkdir(path.join(root, "namespaces"), { recursive: true });
+    await symlink(outside, path.join(root, "namespaces", "evil"));
+
+    await drainPendingLifecycleForOfflineSync(root);
+
+    assert.deepEqual(await readdir(path.join(root, LIFECYCLE_PENDING_REL)).catch(() => [] as string[]), []);
+    assert.ok((await readFile(path.join(root, LIFECYCLE_LEDGER_REL), "utf-8")).includes(rootNonce));
+    assert.ok(
+      (await readFile(path.join(root, "namespaces/team", LIFECYCLE_LEDGER_REL), "utf-8")).includes(teamNonce),
+    );
+    // The escaping child's spill is left untouched and no ledger was written
+    // through the link.
+    assert.equal(
+      (await readdir(path.join(outside, LIFECYCLE_PENDING_REL))).length,
+      1,
+      "escaping namespace spill must be left untouched",
+    );
+    await assert.rejects(
+      () => readFile(path.join(outside, LIFECYCLE_LEDGER_REL), "utf-8"),
+      /ENOENT/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("drainPendingLifecycleForOfflineSync refuses a symlinked namespaces base (#2033 containment)", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-drain-symlink-base-"));
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-drain-base-outside-"));
+  try {
+    const rootNonce = await seedPendingLifecycle(root, "state");
+    // A legit-looking namespace living under the symlinked base target.
+    await seedPendingLifecycle(outside, "team/state");
+    await symlink(outside, path.join(root, "namespaces"));
+
+    await drainPendingLifecycleForOfflineSync(root);
+
+    // The root ledger is still folded through the real state dir.
+    assert.ok((await readFile(path.join(root, LIFECYCLE_LEDGER_REL), "utf-8")).includes(rootNonce));
+    // The symlinked base is refused wholesale: nothing under it is drained.
+    assert.equal(
+      (await readdir(path.join(outside, "team", "state", "memory-lifecycle-ledger.jsonl.pending.d"))).length,
+      1,
+      "namespaces base symlink must be refused, leaving its spills untouched",
+    );
+    await assert.rejects(
+      () => readFile(path.join(outside, "team", LIFECYCLE_LEDGER_REL), "utf-8"),
+      /ENOENT/,
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+type FakeLifecycleStorage = {
+  dir: string;
+  drainPendingMemoryLifecycleEventsForSync(): Promise<{ folded: boolean; pendingDeferred: boolean }>;
+};
+
+function fakeOfflineOrchestrator(memoryRoot: string, namespaceDirs: Record<string, string>) {
+  const lifecycleDrains: string[] = [];
+  let impressionDrains = 0;
+  const storages: Record<string, FakeLifecycleStorage> = {};
+  for (const [name, dir] of Object.entries(namespaceDirs)) {
+    storages[name] = {
+      dir,
+      drainPendingMemoryLifecycleEventsForSync: async () => {
+        lifecycleDrains.push(name);
+        return { folded: false, pendingDeferred: false };
+      },
+    };
+  }
+  const orchestrator = {
+    config: { memoryDir: memoryRoot },
+    drainPendingRecallImpressions: async () => {
+      impressionDrains += 1;
+      return { pendingDeferred: false };
+    },
+    getStorage: async (ns: string) => {
+      const storage = storages[ns];
+      if (!storage) throw new Error(`no fake storage for namespace ${ns}`);
+      return storage;
+    },
+    listOfflineSyncNamespaces: async () => Object.keys(namespaceDirs).filter((n) => n !== "root"),
+  };
+  return { orchestrator, lifecycleDrains, impressions: () => impressionDrains };
+}
+
+test("getOfflineSyncStorage drains every namespace ledger for a root snapshot (#2033)", async () => {
+  const memoryRoot = path.join(os.tmpdir(), "remnic-root-drain-fanout");
+  const { orchestrator, lifecycleDrains, impressions } = fakeOfflineOrchestrator(memoryRoot, {
+    root: memoryRoot,
+    team: path.join(memoryRoot, "namespaces", "team"),
+    ops: path.join(memoryRoot, "namespaces", "ops"),
+  });
+
+  await getOfflineSyncStorage(orchestrator, "root");
+
+  assert.deepEqual(lifecycleDrains, ["root", "team", "ops"], "root snapshot folds root + every namespace ledger");
+  assert.equal(impressions(), 1, "global impressions are folded for a root snapshot");
+});
+
+test("getOfflineSyncStorage folds only the namespace's own ledger for a namespace snapshot (#2033)", async () => {
+  const memoryRoot = path.join(os.tmpdir(), "remnic-ns-drain-scope");
+  const { orchestrator, lifecycleDrains, impressions } = fakeOfflineOrchestrator(memoryRoot, {
+    root: memoryRoot,
+    team: path.join(memoryRoot, "namespaces", "team"),
+  });
+
+  await getOfflineSyncStorage(orchestrator, "team");
+
+  assert.deepEqual(lifecycleDrains, ["team"], "namespace snapshot folds only its own ledger");
+  assert.equal(impressions(), 0, "global impressions are left pending for the root sync");
+});
+
+test("getOfflineSyncStorage never double-folds the root ledger when it is listed as a namespace (#2033)", async () => {
+  const memoryRoot = path.join(os.tmpdir(), "remnic-root-drain-dedup");
+  const { orchestrator, lifecycleDrains } = fakeOfflineOrchestrator(memoryRoot, {
+    root: memoryRoot,
+    // A listing that also surfaces the default namespace pointing back at root.
+    default: memoryRoot,
+    team: path.join(memoryRoot, "namespaces", "team"),
+  });
+
+  await getOfflineSyncStorage(orchestrator, "root");
+
+  assert.deepEqual(lifecycleDrains, ["root", "team"], "root ledger is folded exactly once");
+});

package/src/offline-sync-impression-drain.ts

@@ -0,0 +1,260 @@
+import fs from "node:fs";
+import path from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import {
+  drainPendingLifecycleForSyncOrThrow,
+  drainPendingLifecycleLedgerForSync,
+  type LifecyclePendingIo,
+} from "./storage/memory-lifecycle-ledger-access.js";
+import { writeFileAtomically } from "./maintenance/atomic-file.js";
+import { log } from "./logger.js";
+import { isErrnoCode } from "./utils/errno.js";
+import { assertPathInsideRoot, pathIsInside } from "./utils/path-containment.js";
+import { displayErrorDetail } from "./runtime/better-sqlite.js";
+import { getConfiguredNamespaces } from "./scopes/scope-plan.js";
+import type { PluginConfig } from "./types.js";
+
+type PendingImpressionDrain = () => Promise<{ pendingDeferred: boolean }>;
+
+type PendingLifecycleDrain = {
+  drainPendingMemoryLifecycleEventsForSync(): Promise<{ folded: boolean; pendingDeferred: boolean }>;
+};
+
+type LifecycleDrainAtPath = (
+  ledgerPath: string,
+) => Promise<{ folded: boolean; pendingDeferred: boolean }>;
+
+type PendingImpressionHost = {
+  drainPendingRecallImpressions(): Promise<{ pendingDeferred: boolean }>;
+};
+/**
+ * Fold pending recall-impression spills before building an offline-sync snapshot.
+ * A deferred or failed drain must abort the snapshot rather than silently omit
+ * durable rows from the sync payload.
+ */
+export async function drainPendingImpressionsForOfflineSync(
+  host: PendingImpressionDrain,
+): Promise<void> {
+  const maxAttempts = 3;
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const result = await host();
+      if (!result.pendingDeferred) return;
+      lastError = undefined;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  const detail = lastError
+    ? `: ${displayErrorDetail(lastError) || "unknown error"}`
+    : " (rotation lock held by a peer)";
+  throw new Error(
+    `offline-sync impression drain could not fold pending recall impressions after ${maxAttempts} attempts${detail}; aborting snapshot so the pending rows are not silently excluded (#2033)`,
+  );
+}
+
+
+export async function getOfflineSyncStorage<T extends PendingLifecycleDrain & { dir: string }>(
+  orchestrator: PendingImpressionHost & {
+    config: { memoryDir: string };
+    getStorage(namespace: string): Promise<T>;
+    listOfflineSyncNamespaces?(): Promise<string[]>;
+  },
+  namespace: string,
+): Promise<T> {
+  const storage = await orchestrator.getStorage(namespace);
+  const memoryRoot = path.resolve(orchestrator.config.memoryDir);
+  // Recall impressions are global: the orchestrator's single LastRecallStore
+  // roots at config.memoryDir, so the active recall_impressions.jsonl lives at
+  // <memoryDir>/state/. Fold the global pending queue ONLY when THIS snapshot's
+  // root actually contains that active file - a root snapshot. A namespace
+  // snapshot (storage.dir under namespaces/<token>/) cannot carry it, so
+  // draining there would empty the durable pending queue into a file this
+  // snapshot omits and strand the row until a root sync; leave it pending for
+  // the root sync instead (#2033).
+  const impressionsFile = path.join(memoryRoot, "state", "recall_impressions.jsonl");
+  if (pathIsInside(path.resolve(storage.dir), impressionsFile)) {
+    await drainPendingImpressionsForOfflineSync(() => orchestrator.drainPendingRecallImpressions());
+  }
+  await drainPendingLifecycleForSyncOrThrow(() => storage.drainPendingMemoryLifecycleEventsForSync());
+  // Root snapshot: buildOfflineSyncSnapshot walks `namespaces/<ns>/state/` for
+  // every namespace under the memory root and INCLUDES each namespace's active
+  // lifecycle ledger, but the per-namespace pending spill dirs are offline-sync
+  // EXCLUDED. Draining only the root ledger above would let a root snapshot omit
+  // append-only rows still sitting in a namespace's spill queue, so fold every
+  // namespace ledger too - each through its OWN namespace storage so secure-store
+  // AAD stays namespace-scoped (#2033, matching the CLI all-ledger drain). A
+  // namespace snapshot folds only its own ledger, already done above.
+  if (path.resolve(storage.dir) === memoryRoot && orchestrator.listOfflineSyncNamespaces) {
+    const drained = new Set<string>([memoryRoot]);
+    for (const ns of await orchestrator.listOfflineSyncNamespaces()) {
+      const nsStorage = await orchestrator.getStorage(ns);
+      const nsDir = path.resolve(nsStorage.dir);
+      if (drained.has(nsDir)) continue;
+      drained.add(nsDir);
+      await drainPendingLifecycleForSyncOrThrow(() => nsStorage.drainPendingMemoryLifecycleEventsForSync());
+    }
+  }
+  return storage;
+}
+
+type OfflineSyncNamespaceHost = {
+  config: PluginConfig;
+  namespaceCatalog: { listNamespaces(): Promise<Array<{ namespace: string }>> };
+};
+
+/**
+ * Every namespace whose lifecycle ledger a ROOT offline snapshot enumerates.
+ * Configured namespaces plus catalog-discovered ones; the catalog is queried
+ * best-effort so a catalog read failure still drains the configured set (#2033).
+ */
+export async function listOfflineSyncNamespaces(host: OfflineSyncNamespaceHost): Promise<string[]> {
+  const names = new Set<string>(getConfiguredNamespaces(host.config));
+  try {
+    for (const ledgerPath of await offlineSyncLifecycleLedgerPaths(host.config.memoryDir)) {
+      const namespaceDir = path.dirname(path.dirname(ledgerPath));
+      if (path.basename(path.dirname(namespaceDir)) === "namespaces") {
+        names.add(path.basename(namespaceDir));
+      }
+    }
+  } catch {
+    // best-effort: a filesystem scan failure must not block configured/catalog namespaces
+  }
+  try {
+    for (const record of await host.namespaceCatalog.listNamespaces()) {
+      names.add(record.namespace);
+    }
+  } catch {
+    // best-effort: fall back to the configured and filesystem namespace sets
+  }
+  return [...names];
+}
+
+/**
+ * Resolve the offline-sync storage for a snapshot, folding pending spills first.
+ * For a root snapshot this also folds every namespace lifecycle ledger the
+ * snapshot will enumerate, so append-only rows in a namespace spill queue are
+ * never omitted (#2033).
+ */
+export function offlineSyncStorageForSnapshot<T extends PendingLifecycleDrain & { dir: string }>(
+  host: PendingImpressionHost &
+    OfflineSyncNamespaceHost & {
+      getStorage(namespace: string): Promise<T>;
+    },
+  namespace: string,
+): Promise<T> {
+  return getOfflineSyncStorage(
+    {
+      config: { memoryDir: host.config.memoryDir },
+      drainPendingRecallImpressions: () => host.drainPendingRecallImpressions(),
+      getStorage: (ns: string) => host.getStorage(ns),
+      listOfflineSyncNamespaces: () => listOfflineSyncNamespaces(host),
+    },
+    namespace,
+  );
+}
+
+const LIFECYCLE_LEDGER_FILE = "memory-lifecycle-ledger.jsonl";
+
+/**
+ * Plaintext filesystem IO for a standalone (CLI) offline-sync lifecycle drain.
+ * A standalone offline cache is plaintext - exactly like its LastRecallStore
+ * impression drain - so spills read/append as UTF-8. `writeSecure` keeps the
+ * atomic temp+rename the pending contract requires (#2033); a pure drain never
+ * spills a new event, but the interface demands an atomic writer.
+ */
+function plaintextLifecyclePendingIo(): LifecyclePendingIo {
+  return {
+    writeSecure: async (filePath, payload) => {
+      await writeFileAtomically(filePath, payload);
+    },
+    readSecure: (filePath) => fs.promises.readFile(filePath, "utf8"),
+  };
+}
+
+/**
+ * Lifecycle ledger paths under a standalone memory dir: the root `state/` ledger
+ * plus every per-namespace `namespaces/<ns>/state/` ledger (#2033). Offline sync
+ * pushes the whole memory dir, so every namespace's ledger can carry pending
+ * spills that must be folded first.
+ */
+async function offlineSyncLifecycleLedgerPaths(memoryDir: string): Promise<string[]> {
+  const paths = [path.join(memoryDir, "state", LIFECYCLE_LEDGER_FILE)];
+  const namespacesBase = path.join(memoryDir, "namespaces");
+  // Symlink/traversal containment (#2033): a symlinked <memoryDir>/namespaces
+  // (or a symlinked child) must not redirect the pre-sync drain - and the
+  // ledger appends/mkdirs it drives - outside memoryDir. Resolve the memory
+  // root and the scan base through realpath, reject a symlinked/escaping/
+  // non-directory base, and skip any symlinked/escaping child, mirroring the
+  // lifecycle-compaction scanner (orchestration/maintenance.ts) and the
+  // memory-store walkers (utils/path-containment). A rejected base is
+  // non-fatal: drain the root ledger only, never through the poisoned link.
+  let memoryDirReal: string;
+  try {
+    memoryDirReal = await realpath(memoryDir);
+    const baseStat = await lstat(namespacesBase);
+    if (baseStat.isSymbolicLink() || !baseStat.isDirectory()) {
+      throw new Error("namespaces base is a symlink or not a directory");
+    }
+    assertPathInsideRoot(memoryDirReal, await realpath(namespacesBase), namespacesBase);
+  } catch (err) {
+    if (!isErrnoCode(err, "ENOENT")) {
+      log.debug(`offline-sync lifecycle drain: namespaces base rejected (non-fatal): ${err}`);
+    }
+    return paths;
+  }
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(namespacesBase, { withFileTypes: true });
+  } catch (err) {
+    if (!isErrnoCode(err, "ENOENT")) {
+      log.debug(`offline-sync lifecycle drain: namespaces dir scan failed (non-fatal): ${err}`);
+    }
+    return paths;
+  }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const childPath = path.join(namespacesBase, entry.name);
+    try {
+      assertPathInsideRoot(memoryDirReal, await realpath(childPath), childPath);
+    } catch (err) {
+      log.debug(`offline-sync lifecycle drain: skipping out-of-root namespace dir ${childPath}: ${err}`);
+      continue;
+    }
+    paths.push(path.join(childPath, "state", LIFECYCLE_LEDGER_FILE));
+  }
+  return paths;
+}
+
+/**
+ * Fold pending memory-lifecycle spills into each active ledger under `memoryDir`
+ * before a standalone (CLI) offline-sync snapshot (#2033). Mirrors the
+ * access-service snapshot entrypoints, which drain lifecycle pending first: the
+ * default sync exclude globs keep `memory-lifecycle-ledger.jsonl.pending.d` out
+ * of the push, so an append-only row (promotion/import/explicit capture) that
+ * spilled while the ledger lock was held would be silently dropped if the local
+ * node were discarded before maintenance folds it. A deferred drain (lock held
+ * by a peer) or a repeatedly failing fold ABORTS via
+ * {@link drainPendingLifecycleForSyncOrThrow} rather than building/pushing a
+ * snapshot that omits durable rows. Fast no-op per ledger with no pending dir.
+ */
+export async function drainPendingLifecycleForOfflineSync(
+  memoryDir: string,
+  drainAtPath: LifecycleDrainAtPath = (ledgerPath) => {
+    const io = plaintextLifecyclePendingIo();
+    const stateDir = path.dirname(ledgerPath);
+    return drainPendingLifecycleLedgerForSync(
+      ledgerPath,
+      io,
+      (payload) => fs.promises.appendFile(ledgerPath, payload),
+      async () => {
+        await fs.promises.mkdir(stateDir, { recursive: true });
+      },
+    );
+  },
+): Promise<void> {
+  for (const ledgerPath of await offlineSyncLifecycleLedgerPaths(memoryDir)) {
+    await drainPendingLifecycleForSyncOrThrow(() => drainAtPath(ledgerPath));
+  }
+}

package/src/offline-sync.test.ts

@@ -297,6 +297,16 @@ test("offline sync includes durable runtime state and excludes only transient sy
     await write(root, "state/memory-projection.sqlite-shm", "projection-shm");
     await write(root, "state/memory-projection.sqlite-wal", "projection-wal");
     await write(root, "state/recall_impressions.jsonl", "impressions");
+    // Rotated archive (issue #1910) must be excluded from the push snapshot
+    // while the active file stays remote-authoritative.
+    await write(root, "state/recall_impressions.jsonl.1", "rotated-impressions");
+    // Node-local lifecycle coordination files must never cross offline sync.
+    await write(root, "state/memory-lifecycle-ledger.jsonl.lock", "lock");
+    await write(
+      root,
+      "state/memory-lifecycle-ledger.jsonl.pending.d/event-1.json",
+      "pending",
+    );
     await write(root, "namespaces/generalist-project-origin-6ebeaa54/state/last_intent.json", "intent");
     await write(root, "namespaces/generalist-project-origin-6ebeaa54/state/entity-mention-index.json", "entities");
     await write(root, "namespaces/generalist-project-origin-6ebeaa54/state/.memory-status-version.log", "version");
@@ -341,6 +351,22 @@ test("offline sync includes durable runtime state and excludes only transient sy
         }),
       /offline sync file content path is excluded: state\/buffer\.json\.tmp-123-456/,
     );
+    await assert.rejects(
+      () =>
+        readOfflineSyncFileContentChunk({
+          root,
+          path: "state/memory-lifecycle-ledger.jsonl.lock",
+        }),
+      /offline sync file content path is excluded: state\/memory-lifecycle-ledger\.jsonl\.lock/,
+    );
+    await assert.rejects(
+      () =>
+        readOfflineSyncFileContentChunk({
+          root,
+          path: "state/memory-lifecycle-ledger.jsonl.pending.d/event-1.json",
+        }),
+      /offline sync file content path is excluded: state\/memory-lifecycle-ledger\.jsonl\.pending\.d\/event-1\.json/,
+    );
     const namespaced = await buildOfflineSyncSnapshotForPaths({
       root,
       sourceId: "remote",
@@ -363,11 +389,12 @@ test("offline sync includes durable runtime state and excludes only transient sy
       }],
     });
 
-    // 18 = the 13 durable local-only files plus the 5 node-local excluded
-    // artifacts, which the corrected apply-side view (#1793 review) now
-    // SEES and deliberately leaves untouched (counted as skipped) instead
-    // of hiding from enumeration entirely.
-    assert.equal(pull.skipped, 18);
+    // 21 = the 13 durable local-only files plus the 8 node-local excluded
+    // artifacts (the 6 prior ones plus the lifecycle lock and pending spill
+    // file), which the corrected apply-side view (#1793 review) now SEES and
+    // deliberately leaves untouched (counted as skipped) instead of hiding
+    // from enumeration entirely.
+    assert.equal(pull.skipped, 21);
     assert.equal(await readUtf8(root, "state/memory-lifecycle-ledger.jsonl"), "ledger");
   } finally {
     await rm(root, { recursive: true, force: true });

package/src/offline-sync.ts

@@ -26,6 +26,7 @@ import {
   type SafeArchiveRoot,
 } from "./transfer/fs-utils.js";
 import { parseFlexibleIsoTimestamp } from "./utils/iso-timestamp.js";
+import { DEFAULT_OFFLINE_SYNC_EXCLUDE_GLOBS } from "./offline-sync-exclude-globs.js";
 
 export const OFFLINE_SYNC_SNAPSHOT_FORMAT = "remnic.offline-sync.snapshot.v1";
 export const OFFLINE_SYNC_CHANGESET_FORMAT = "remnic.offline-sync.changeset.v1";
@@ -198,20 +199,6 @@ const EXCLUDED_FILE_PREFIXES = [
   ".remnic-sync.",
   ".remnic-sync-state.",
 ];
-// Issue #1786: node-local runtime state that each node rebuilds from synced
-// records. Pushing these wastes bandwidth, corrupts the remote's live state
-// dir, and trips the large-file push retry loop on a live SQLite database.
-const DEFAULT_OFFLINE_SYNC_EXCLUDE_GLOBS: readonly string[] = [
-  // Leading `**/` matches zero or more segments, so each pattern covers both
-  // the root `state/` dir AND per-namespace `namespaces/<ns>/state/` dirs
-  // (Cursor review on PR #1793: multi-namespace deployments previously kept
-  // pushing their namespaced live sqlite files).
-  "**/state/*.sqlite",
-  "**/state/*.sqlite-*",
-  "**/state/index_tags.json",
-  "**/state/entity-mention-index.json",
-  "**/state/memory-governance/runs/**",
-];
 
 /**
  * Convert a tiny subset of glob syntax (`*`, `**`, `?`, literal text) into a

package/src/operator-toolkit.ts

@@ -1987,7 +1987,7 @@ function summarizeSecurityMitigations(
     | "recallAuditAnomalyRepeatQueryLimit"
     | "recallAuditAnomalyNamespaceWalkLimit"
     | "recallAuditAnomalyHighCardinalityLimit"
-    | "recallAuditAnomalyRapidFireLimit"
+    | "recallAuditAnomalyRapidFireLimit" | "recallSingleFlightEnabled"
   >,
 ): OperatorDoctorCheck {
   // Resolve access-setup gates once (#1566 Cluster B).