@remnic/core 1.1.31 → 9.3.516

package/src/orchestrator.ts

@@ -71,7 +71,10 @@ import { extractTopics } from "./topics.js";
 import { TranscriptManager } from "./transcript.js";
 import { HourlySummarizer } from "./summarizer.js";
 import { LocalLlmClient } from "./local-llm.js";
-import { FallbackLlmClient } from "./fallback-llm.js";
+import {
+  FallbackLlmClient,
+  fallbackLlmRuntimeContextFromConfig,
+} from "./fallback-llm.js";
 import {
   ensureDaySummaryCron,
   ensureNightlyGovernanceCron,
@@ -287,6 +290,7 @@ import {
   type ConversationQmdRuntime,
 } from "./conversation-index/backend.js";
 import { NamespaceStorageRouter } from "./namespaces/storage.js";
+import { namespaceIdentityFromToken } from "./namespaces/identity.js";
 import {
   canReadNamespace,
   defaultNamespaceForPrincipal,
@@ -676,6 +680,56 @@ async function raceRecallAbort<T>(
 
 /** Maximum age (ms) before a compaction-reset signal file is considered stale and removed. */
 const COMPACTION_SIGNAL_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
+const DEFAULT_QMD_STARTUP_COLLECTION_CHECK_TIMEOUT_MS = 10_000;
+
+type SearchCollectionState = "present" | "missing" | "unknown" | "skipped";
+
+function qmdStartupCollectionCheckTimeoutMs(): number {
+  const raw =
+    process.env.REMNIC_QMD_STARTUP_COLLECTION_CHECK_TIMEOUT_MS ??
+    process.env.ENGRAM_QMD_STARTUP_COLLECTION_CHECK_TIMEOUT_MS;
+  if (raw === undefined) return DEFAULT_QMD_STARTUP_COLLECTION_CHECK_TIMEOUT_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 1_000
+    ? Math.floor(parsed)
+    : DEFAULT_QMD_STARTUP_COLLECTION_CHECK_TIMEOUT_MS;
+}
+
+async function qmdStartupCollectionCheckWithTimeout(
+  promise: Promise<SearchCollectionState>,
+  controller: AbortController,
+  label: string,
+): Promise<SearchCollectionState> {
+  const timeoutMs = qmdStartupCollectionCheckTimeoutMs();
+  let timer: NodeJS.Timeout | undefined;
+  let settled = false;
+
+  const timeoutPromise = new Promise<SearchCollectionState>((resolve) => {
+    timer = setTimeout(() => {
+      if (settled) return;
+      controller.abort();
+      log.warn(
+        `QMD startup collection check for ${label} timed out after ${timeoutMs}ms; keeping search enabled fail-open`,
+      );
+      resolve("unknown");
+    }, timeoutMs);
+    timer.unref?.();
+  });
+
+  const checkedPromise = promise
+    .catch((err): SearchCollectionState => {
+      log.warn(
+        `QMD startup collection check for ${label} failed; keeping search enabled fail-open: ${err}`,
+      );
+      return "unknown";
+    })
+    .finally(() => {
+      settled = true;
+      if (timer) clearTimeout(timer);
+    });
+
+  return await Promise.race([checkedPromise, timeoutPromise]);
+}
 
 /** Default workspace directory when no per-agent or config workspace is available. */
 export function defaultWorkspaceDir(): string {
@@ -2014,9 +2068,10 @@ export class Orchestrator {
       : this.localLlm;
     // Initialize gateway fast LLM for fast-tier ops when modelSource is "gateway"
     this._fastGatewayLlm = config.modelSource === "gateway"
-      ? new FallbackLlmClient(config.gatewayConfig, {
-          workspaceDir: config.workspaceDir,
-        })
+      ? new FallbackLlmClient(
+          config.gatewayConfig,
+          fallbackLlmRuntimeContextFromConfig(config),
+        )
       : null;
     if (config.modelSource === "gateway") {
       log.debug(
@@ -2448,14 +2503,22 @@ export class Orchestrator {
             ? this.configuredNamespaces()
             : [this.config.defaultNamespace];
           const states = await Promise.all(
-            namespaces.map(async (namespace) => ({
-              namespace,
-              state: this.config.namespacesEnabled
-                ? await this.namespaceSearchRouter.ensureNamespaceCollection(
-                    namespace,
-                  )
-                : await this.qmd.ensureCollection(this.config.memoryDir),
-            })),
+            namespaces.map(async (namespace) => {
+              const collectionCheckAbort = new AbortController();
+              const state = await qmdStartupCollectionCheckWithTimeout(
+                this.config.namespacesEnabled
+                  ? this.namespaceSearchRouter.ensureNamespaceCollection(
+                      namespace,
+                      { signal: collectionCheckAbort.signal },
+                    )
+                  : this.qmd.ensureCollection(this.config.memoryDir, {
+                      signal: collectionCheckAbort.signal,
+                    }),
+                collectionCheckAbort,
+                namespace,
+              );
+              return { namespace, state };
+            }),
           );
           const defaultState =
             states.find(
@@ -2795,8 +2858,8 @@ export class Orchestrator {
       namespaces.map(async (namespace) => ({
         namespace,
         state: this.config.namespacesEnabled
-          ? await this.namespaceSearchRouter.ensureNamespaceCollection(namespace)
-          : await this.qmd.ensureCollection(this.config.memoryDir),
+          ? await this.namespaceSearchRouter.ensureNamespaceCollection(namespace, { signal })
+          : await this.qmd.ensureCollection(this.config.memoryDir, { signal }),
       })),
     );
 
@@ -3337,9 +3400,10 @@ export class Orchestrator {
           ? this.config.fastGatewayAgentId
           : this.config.gatewayAgentId || undefined)
       : undefined;
-    const llm = new FallbackLlmClient(this.config.gatewayConfig, {
-      workspaceDir: this.config.workspaceDir,
-    });
+    const llm = new FallbackLlmClient(
+      this.config.gatewayConfig,
+      fallbackLlmRuntimeContextFromConfig(this.config),
+    );
     if (!llm.isAvailable(gatewayAgentId) && !(modelSetting === "fast" && this.fastLlm && !useGateway)) {
       log.warn(
         "[semantic-consolidation] no LLM available — skipping synthesis",
@@ -3584,9 +3648,10 @@ export class Orchestrator {
     if (this.config.peerProfileReasonerEnabled) {
       try {
         const { runPeerProfileReasoner } = await import("./peers/index.js");
-        const llm = new FallbackLlmClient(this.config.gatewayConfig, {
-          workspaceDir: this.config.workspaceDir,
-        });
+        const llm = new FallbackLlmClient(
+          this.config.gatewayConfig,
+          fallbackLlmRuntimeContextFromConfig(this.config),
+        );
         const peerResult = await runPeerProfileReasoner({
           memoryDir: targetStorage.dir,
           enabled: true,
@@ -4627,6 +4692,12 @@ export class Orchestrator {
     }
     const chunks = await this.buildConversationIndexChunks(sessionKey, hours);
     await writeConversationChunks(this.conversationIndexDir, chunks);
+    const retentionCutoffMs =
+      Number.isFinite(this.config.conversationIndexRetentionDays) &&
+      this.config.conversationIndexRetentionDays > 0
+        ? Date.now() -
+          this.config.conversationIndexRetentionDays * 24 * 60 * 60 * 1000
+        : undefined;
     await cleanupConversationChunks(
       this.conversationIndexDir,
       this.config.conversationIndexRetentionDays,
@@ -4638,6 +4709,7 @@ export class Orchestrator {
     if (this.conversationIndexBackend) {
       const result = await this.conversationIndexBackend.update(chunks, {
         embed: shouldEmbed,
+        ...(retentionCutoffMs !== undefined ? { retentionCutoffMs } : {}),
       });
       embedded = result.embedded;
     }
@@ -4814,7 +4886,7 @@ export class Orchestrator {
     if (this.config.secureStoreEnabled && !this.storage.isSecureStoreUnlocked()) {
       const lockedMsg =
         "[secure-store locked] Memory store is encrypted and locked. " +
-        "Run `remnic secure-store unlock` then restart the daemon to decrypt.";
+        "Unlock the secure-store inside this daemon process, or restart the daemon through a secure-store aware launcher that installs the key.";
       log.warn("recall blocked: secure-store is locked");
       return lockedMsg;
     }
@@ -6900,6 +6972,7 @@ export class Orchestrator {
       const section = await buildEntityRecallSection({
         config: this.config,
         storage: profileStorage,
+        namespaceStorage: (namespace) => this.getStorage(namespace),
         query: retrievalQuery,
         recallNamespaces,
         recentTurns,
@@ -7851,6 +7924,7 @@ export class Orchestrator {
                   temporalResults,
                   this.config.parallelAgentWeights,
                   qmdFetchLimit + lifecycleHeadroom,
+                  this.config.memoryDir,
                 );
               }
             } catch (err) {
@@ -10362,9 +10436,18 @@ export class Orchestrator {
 
   async ingestReplayBatch(
     turns: ReplayTurn[],
-    options: { deadlineMs?: number; archiveLcm?: boolean } = {},
+    options: {
+      deadlineMs?: number;
+      archiveLcm?: boolean;
+      abortSignal?: AbortSignal;
+    } = {},
   ): Promise<void> {
     if (!Array.isArray(turns) || turns.length === 0) return;
+    if (options.abortSignal?.aborted) {
+      throw options.abortSignal.reason instanceof Error
+        ? options.abortSignal.reason
+        : new Error("ingestReplayBatch aborted");
+    }
     if (shouldSkipImplicitExtraction(this.config)) {
       log.debug(
         "ingestReplayBatch: skipping implicit extraction because captureMode=explicit",
@@ -10398,6 +10481,11 @@ export class Orchestrator {
     }> = [];
     for (const [key, sessionTurns] of bySession.entries()) {
       if (sessionTurns.length === 0) continue;
+      if (options.abortSignal?.aborted) {
+        throw options.abortSignal.reason instanceof Error
+          ? options.abortSignal.reason
+          : new Error("ingestReplayBatch aborted");
+      }
       if (options.archiveLcm !== false && this.lcmEngine?.enabled) {
         await this.lcmEngine.observeMessages(
           key,
@@ -10437,6 +10525,7 @@ export class Orchestrator {
               skipUserTurnThreshold: true,
               bufferKey,
               extractionDeadlineMs: options.deadlineMs,
+              abortSignal: options.abortSignal,
               onTaskSettled: (err) => (err ? reject(err) : resolve()),
             }).catch(reject);
           }),
@@ -10540,6 +10629,7 @@ export class Orchestrator {
         parts: turn.parts,
         rawContent: turn.rawContent,
         sourceFormat: turn.sourceFormat,
+        importProvenance: turn.importProvenance,
       });
     }
     if (sessionTurns.length === 0) return;
@@ -12163,9 +12253,10 @@ export class Orchestrator {
           judgeCandidates,
           this.config,
           this.localLlm,
-          new FallbackLlmClient(this.config.gatewayConfig, {
-            workspaceDir: this.config.workspaceDir,
-          }),
+          new FallbackLlmClient(
+            this.config.gatewayConfig,
+            fallbackLlmRuntimeContextFromConfig(this.config),
+          ),
           this.judgeVerdictCache,
           this.judgeDeferCounts,
           judgeTelemetryHandler,
@@ -16327,7 +16418,8 @@ export class Orchestrator {
   private namespaceFromPath(p: string): string {
     if (!this.config.namespacesEnabled) return this.config.defaultNamespace;
     const m = p.match(/[\\/]+namespaces[\\/]+([^\\/]+)(?:[\\/]|$)/);
-    return m && m[1] ? m[1] : this.config.defaultNamespace;
+    if (!m?.[1]) return this.config.defaultNamespace;
+    return namespaceIdentityFromToken(m[1]) ?? m[1];
   }
 
   private namespaceFromStorageDir(storageDir: string): string {
@@ -16337,7 +16429,8 @@ export class Orchestrator {
     if (resolvedStorageDir === resolvedMemoryDir)
       return this.config.defaultNamespace;
     const m = resolvedStorageDir.match(/[\\/]namespaces[\\/]([^\\/]+)$/);
-    return m && m[1] ? m[1] : this.config.defaultNamespace;
+    if (!m?.[1]) return this.config.defaultNamespace;
+    return namespaceIdentityFromToken(m[1]) ?? m[1];
   }
 
   private async readAllMemoriesForNamespaces(

package/src/page-versioning.ts

@@ -126,18 +126,44 @@ async function readManifest(
   pagePath: string,
 ): Promise<VersionHistory> {
   const mp = manifestPath(memoryDir, sidecar, pagePath);
+  if (!(await fileExists(mp))) {
+    return { pagePath, versions: [], currentVersion: "0" };
+  }
   try {
     const raw = await readFile(mp, "utf-8");
     const parsed: unknown = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null) {
-      return { pagePath, versions: [], currentVersion: "0" };
+      throw new Error("manifest root must be an object");
     }
     const obj = parsed as Record<string, unknown>;
-    const versions = Array.isArray(obj.versions) ? (obj.versions as PageVersion[]) : [];
-    const currentVersion = typeof obj.currentVersion === "string" ? obj.currentVersion : "0";
+    if (!Array.isArray(obj.versions)) {
+      throw new Error("manifest versions must be an array");
+    }
+    const versions = obj.versions.map((entry, index) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        throw new Error(`manifest version ${index} must be an object`);
+      }
+      const version = entry as Record<string, unknown>;
+      if (
+        typeof version.versionId !== "string" ||
+        !/^\d+$/.test(version.versionId) ||
+        typeof version.timestamp !== "string" ||
+        typeof version.contentHash !== "string" ||
+        typeof version.sizeBytes !== "number" ||
+        !Number.isFinite(version.sizeBytes) ||
+        !["write", "consolidation", "revert", "manual"].includes(String(version.trigger))
+      ) {
+        throw new Error(`manifest version ${index} has invalid shape`);
+      }
+      return version as unknown as PageVersion;
+    });
+    if (typeof obj.currentVersion !== "string" || !/^\d+$/.test(obj.currentVersion)) {
+      throw new Error("manifest currentVersion must be a numeric string");
+    }
+    const currentVersion = obj.currentVersion;
     return { pagePath: typeof obj.pagePath === "string" ? obj.pagePath : pagePath, versions, currentVersion };
-  } catch {
-    return { pagePath, versions: [], currentVersion: "0" };
+  } catch (error) {
+    throw new Error(`page-versioning: invalid manifest ${mp}: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
 

package/src/peers/peers.test.ts

@@ -18,6 +18,7 @@ import {
   listPeers,
   PEER_ID_PATTERN,
   readInteractionLogRaw,
+  readPeerInteractionLog,
   readPeer,
   readPeerProfile,
   writePeer,
@@ -274,6 +275,75 @@ test("appendInteractionLog creates peer directory on demand", async () => {
   assert.ok(raw.includes("no identity yet"));
 });
 
+test("appendInteractionLog rejects non-canonical timestamps", async () => {
+  const dir = await makeTempDir();
+
+  await assert.rejects(
+    appendInteractionLog(dir, "self", {
+      timestamp: "zzzz",
+      kind: "peer_profile_reasoner_run",
+      summary: "bad marker",
+    }),
+    /canonical ISO-8601 timestamp/,
+  );
+});
+
+test("readPeerInteractionLog skips malformed timestamp lines before timestamp filtering", async () => {
+  const dir = await makeTempDir();
+  const peerDir = path.join(dir, "peers", "self");
+  await fs.mkdir(peerDir, { recursive: true });
+  await fs.writeFile(
+    path.join(peerDir, "interactions.log.md"),
+    [
+      "- [zzzz] (peer_profile_reasoner_run) bad marker",
+      "- [2026-04-25T00:00:01.000Z] (message) good marker",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  const entries = await readPeerInteractionLog(dir, "self", {
+    afterTimestamp: "2026-04-25T00:00:00.000Z",
+  });
+
+  assert.deepEqual(
+    entries.map((entry) => entry.summary),
+    ["good marker"],
+  );
+});
+
+test("readPeerInteractionLog preserves valid non-canonical ISO timestamps", async () => {
+  const dir = await makeTempDir();
+  const peerDir = path.join(dir, "peers", "self");
+  await fs.mkdir(peerDir, { recursive: true });
+  await fs.writeFile(
+    path.join(peerDir, "interactions.log.md"),
+    [
+      "- [2026-04-25T00:00:00Z] (message) no millisecond marker",
+      "- [2026-04-25T01:00:00+01:00] (message) offset marker for same instant",
+      "- [2026-04-25T00:00:01.000Z] (message) newer marker",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+
+  const allEntries = await readPeerInteractionLog(dir, "self");
+
+  assert.deepEqual(
+    allEntries.map((entry) => entry.timestamp),
+    ["2026-04-25T00:00:00Z", "2026-04-25T01:00:00+01:00", "2026-04-25T00:00:01.000Z"],
+  );
+
+  const filteredEntries = await readPeerInteractionLog(dir, "self", {
+    afterTimestamp: "2026-04-25T00:00:00.000Z",
+  });
+
+  assert.deepEqual(
+    filteredEntries.map((entry) => entry.timestamp),
+    ["2026-04-25T00:00:01.000Z"],
+  );
+});
+
 test("readInteractionLogRaw returns empty string when log does not exist", async () => {
   const dir = await makeTempDir();
   const raw = await readInteractionLogRaw(dir, "self");

package/src/peers/storage.ts

@@ -851,6 +851,25 @@ function sanitizeLogField(value: string): string {
   return value.replace(/[\r\n\t]+/g, " ").trim();
 }
 
+function isCanonicalIsoTimestamp(value: string): boolean {
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === value;
+}
+
+function parseIsoTimestampMs(value: string): number | null {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)) {
+    return null;
+  }
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function assertCanonicalIsoTimestamp(value: string, field: string): void {
+  if (!isCanonicalIsoTimestamp(value)) {
+    throw new Error(`${field} must be a canonical ISO-8601 timestamp`);
+  }
+}
+
 function formatLogEntry(entry: PeerInteractionLogEntry): string {
   // One line per entry. We use a leading bullet so the file remains
   // readable as ordinary markdown. Order: timestamp, kind, optional
@@ -899,6 +918,7 @@ export async function appendInteractionLog(
   if (typeof entry.timestamp !== "string" || entry.timestamp.trim() === "") {
     throw new Error("interaction entry must have a non-whitespace timestamp");
   }
+  assertCanonicalIsoTimestamp(entry.timestamp.trim(), "interaction entry timestamp");
   if (typeof entry.kind !== "string" || entry.kind.trim() === "") {
     throw new Error("interaction entry must have a non-whitespace kind");
   }
@@ -1245,6 +1265,7 @@ function parseLogLine(line: string): PeerInteractionLogEntry | null {
   if (tsClose === -1) return null;
   const timestamp = line.slice(3, tsClose).trim();
   if (timestamp === "") return null;
+  if (parseIsoTimestampMs(timestamp) === null) return null;
   // Skip optional whitespace between `]` and `(`.
   let cursor = tsClose + 1;
   while (cursor < line.length && line[cursor] === " ") cursor += 1;
@@ -1308,8 +1329,9 @@ function parseLogLine(line: string): PeerInteractionLogEntry | null {
  *
  * `options.limit` (when > 0) restricts the result to the most recent
  * N entries. `options.afterTimestamp` (ISO-8601) filters out entries
- * with `timestamp < afterTimestamp` (string compare is safe for
- * canonical ISO-8601 form). Both filters are applied in order:
+ * with `timestamp <= afterTimestamp`, comparing parsed instants so
+ * legacy valid ISO-8601 forms like `Z` without milliseconds or
+ * offset timestamps keep working. Both filters are applied in order:
  * timestamp first, then limit.
  *
  * Order: oldest → newest, matching the append-only on-disk order so
@@ -1337,7 +1359,14 @@ export async function readPeerInteractionLog(
   let filtered = entries;
   if (typeof options.afterTimestamp === "string" && options.afterTimestamp.length > 0) {
     const cutoff = options.afterTimestamp;
-    filtered = filtered.filter((e) => e.timestamp > cutoff);
+    const cutoffMs = parseIsoTimestampMs(cutoff);
+    if (cutoffMs === null) {
+      throw new Error("afterTimestamp must be an ISO-8601 timestamp");
+    }
+    filtered = filtered.filter((e) => {
+      const entryMs = parseIsoTimestampMs(e.timestamp);
+      return entryMs !== null && entryMs > cutoffMs;
+    });
   }
   // Gotcha #27: guard slice(-n) against n === 0 — `slice(-0)` returns
   // the entire array. Treat 0 and negatives as "no limit applied".

package/src/plugin-entry-resolver.test.ts

@@ -0,0 +1,60 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { resolvePluginEntry } from "./plugin-entry-resolver.js";
+
+function resolve(raw: unknown): Record<string, unknown> | undefined {
+  return resolvePluginEntry(raw, {
+    candidateIds: ["openclaw-remnic", "openclaw-engram"],
+    preferredId: "openclaw-remnic",
+    getEntries(candidate) {
+      const plugins = candidate["plugins"];
+      if (!plugins || typeof plugins !== "object" || Array.isArray(plugins)) {
+        return undefined;
+      }
+      const entries = (plugins as Record<string, unknown>)["entries"];
+      return entries && typeof entries === "object" && !Array.isArray(entries)
+        ? (entries as Record<string, unknown>)
+        : undefined;
+    },
+    getSlotId(candidate) {
+      const plugins = candidate["plugins"];
+      if (!plugins || typeof plugins !== "object" || Array.isArray(plugins)) {
+        return undefined;
+      }
+      const slots = (plugins as Record<string, unknown>)["slots"];
+      if (!slots || typeof slots !== "object" || Array.isArray(slots)) {
+        return undefined;
+      }
+      const slotId = (slots as Record<string, unknown>)["memory"];
+      return typeof slotId === "string" ? slotId : undefined;
+    },
+  });
+}
+
+test("resolvePluginEntry returns undefined for a foreign string memory slot", () => {
+  const entry = resolve({
+    plugins: {
+      slots: { memory: "other-memory-plugin" },
+      entries: {
+        "openclaw-remnic": { config: { memoryDir: "/tmp/remnic" } },
+        "openclaw-engram": { config: { memoryDir: "/tmp/engram" } },
+      },
+    },
+  });
+
+  assert.equal(entry, undefined);
+});
+
+test("resolvePluginEntry falls back to preferred id when memory slot is absent", () => {
+  const entry = resolve({
+    plugins: {
+      entries: {
+        "openclaw-remnic": { config: { memoryDir: "/tmp/remnic" } },
+        "openclaw-engram": { config: { memoryDir: "/tmp/engram" } },
+      },
+    },
+  });
+
+  assert.deepEqual(entry, { config: { memoryDir: "/tmp/remnic" } });
+});

package/src/plugin-entry-resolver.ts

@@ -0,0 +1,48 @@
+export interface PluginEntryResolverOptions {
+  candidateIds: readonly string[];
+  preferredId?: string;
+  getEntries(raw: Record<string, unknown>): Record<string, unknown> | undefined;
+  getSlotId?: (raw: Record<string, unknown>) => string | undefined;
+}
+
+function uniqueDefined(values: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const value of values) {
+    if (value === undefined || seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
+  }
+  return out;
+}
+
+export function resolvePluginEntry(
+  raw: unknown,
+  options: PluginEntryResolverOptions,
+): Record<string, unknown> | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const root = raw as Record<string, unknown>;
+  const entries = options.getEntries(root);
+  if (!entries) return undefined;
+
+  const allowedIds = new Set(options.candidateIds);
+  const slotId = options.getSlotId?.(root);
+  if (typeof slotId === "string" && !allowedIds.has(slotId)) {
+    return undefined;
+  }
+  const activeId = typeof slotId === "string" ? slotId : undefined;
+  const ownId =
+    !activeId &&
+    typeof options.preferredId === "string" &&
+    allowedIds.has(options.preferredId)
+      ? options.preferredId
+      : undefined;
+
+  for (const id of uniqueDefined([activeId, ownId, ...options.candidateIds])) {
+    const entry = entries[id];
+    if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+      return entry as Record<string, unknown>;
+    }
+  }
+  return undefined;
+}

package/src/plugin-id.test.ts

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+
+import {
+  LEGACY_PLUGIN_ID,
+  PLUGIN_ID,
+  resolveRemnicPluginEntry,
+} from "./plugin-id.js";
+
+test("plugin-id compatibility subpath exposes canonical ids and resolver", () => {
+  assert.equal(PLUGIN_ID, "openclaw-remnic");
+  assert.equal(LEGACY_PLUGIN_ID, "openclaw-engram");
+
+  const entry = resolveRemnicPluginEntry(
+    {
+      plugins: {
+        entries: {
+          "openclaw-remnic": { config: { memoryDir: "/tmp/remnic" } },
+          "openclaw-engram": { config: { memoryDir: "/tmp/engram" } },
+        },
+      },
+    },
+    LEGACY_PLUGIN_ID,
+  );
+
+  assert.deepEqual(entry, { config: { memoryDir: "/tmp/engram" } });
+});
+
+test("package exports preserve plugin-id compatibility subpaths", async () => {
+  const packageJsonUrl = new URL("../package.json", import.meta.url);
+  const pkg = JSON.parse(await readFile(packageJsonUrl, "utf8")) as {
+    exports?: Record<string, unknown>;
+  };
+
+  assert.ok(pkg.exports?.["./plugin-id"]);
+  assert.ok(pkg.exports?.["./plugin-id.js"]);
+});