@remnic/core 1.1.2 → 1.1.3

package/dist/{chunk-STGWEHYR.js → chunk-DR7MCMPS.js}

@@ -1,14 +1,21 @@
+import {
+  importCapsule
+} from "./chunk-3KIS4VGT.js";
+import {
+  applyTagFilter,
+  normalizeTags,
+  parseTagMatch
+} from "./chunk-BT7NVCML.js";
+import {
+  decideDisclosureEscalation
+} from "./chunk-H7XKCNR6.js";
 import {
   toRecallExplainJson
-} from "./chunk-ZAIM4TUE.js";
+} from "./chunk-LW2NMHDW.js";
 import {
-  buildProposedActions,
-  buildQualityScore,
-  groupActionsByStatus,
-  listMemoryGovernanceRuns,
-  readMemoryGovernanceRunArtifact,
-  runMemoryGovernance
-} from "./chunk-3OGMS3PE.js";
+  clusterByKey,
+  resolveGitContext
+} from "./chunk-NN3TS5BM.js";
 import {
   getTrustZoneStoreStatus,
   isTrustZoneName,
@@ -18,9 +25,28 @@ import {
   seedTrustZoneDemoDataset,
   summarizeTrustZonePromotionReadiness
 } from "./chunk-EQINRHYR.js";
+import {
+  estimateRecallTokens
+} from "./chunk-USFPPRAF.js";
+import {
+  buildProposedActions,
+  buildQualityScore,
+  groupActionsByStatus,
+  listMemoryGovernanceRuns,
+  readMemoryGovernanceRunArtifact,
+  runMemoryGovernance
+} from "./chunk-LZRYQK6L.js";
 import {
   recordMemoryOutcome
 } from "./chunk-EIR5VLIH.js";
+import {
+  buildGraphSnapshot
+} from "./chunk-PCUKNJAZ.js";
+import {
+  persistExplicitCapture,
+  queueExplicitCaptureForReview,
+  validateExplicitCaptureInput
+} from "./chunk-3FPTCC3Z.js";
 import {
   wrapWorkLayerContext
 } from "./chunk-EEQLFRUM.js";
@@ -28,18 +54,16 @@ import {
   buildProcedurePersistBody,
   normalizeProcedureSteps
 } from "./chunk-QDW3E4RD.js";
-import {
-  persistExplicitCapture,
-  queueExplicitCaptureForReview,
-  validateExplicitCaptureInput
-} from "./chunk-3FPTCC3Z.js";
 import {
   CrossNamespaceBudget
 } from "./chunk-GDFS42HT.js";
 import {
   filterTrajectoriesByLookbackDays,
   readCausalTrajectoryRecords
-} from "./chunk-RBBWYEFJ.js";
+} from "./chunk-G2WADRQ3.js";
+import {
+  defaultCapsulesDir
+} from "./chunk-74EMIVE4.js";
 import {
   canReadNamespace,
   canWriteNamespace,
@@ -52,14 +76,18 @@ import {
   buildBriefing,
   parseBriefingFocus,
   parseBriefingWindow
-} from "./chunk-L7IXWRYE.js";
+} from "./chunk-SS253RXF.js";
 import {
   parseEntityFile
-} from "./chunk-F5VP6YCB.js";
+} from "./chunk-DCE6SQLA.js";
+import {
+  DEFAULT_RECALL_DISCLOSURE,
+  isRecallDisclosure
+} from "./chunk-43EKP2UK.js";
 import {
   inferMemoryStatus,
   toMemoryPathRel
-} from "./chunk-TP4FZJIZ.js";
+} from "./chunk-RULE4VG5.js";
 import {
   normalizeProjectionPreview,
   normalizeProjectionTags
@@ -77,9 +105,15 @@ import {
   AccessIdempotencyStore,
   hashAccessIdempotencyPayload
 } from "./chunk-XKECPATV.js";
+import {
+  exportCapsule
+} from "./chunk-IYY4MCPG.js";
 
 // src/access-service.ts
 import { stat } from "fs/promises";
+import * as nodeFs from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { ZodError } from "zod";
 
 // src/work/storage.ts
 import path from "path";
@@ -747,13 +781,7 @@ async function runProcedureMining(options) {
     causalTrajectoryStoreDir: trajectoryDir
   });
   const recent = filterTrajectoriesByLookbackDays(trajectories, cfg.lookbackDays);
-  const clusters = /* @__PURE__ */ new Map();
-  for (const t of recent) {
-    const key = clusterKey(t);
-    const arr = clusters.get(key) ?? [];
-    arr.push(t);
-    clusters.set(key, arr);
-  }
+  const clusters = clusterByKey(recent, clusterKey);
   let clustersProcessed = 0;
   let proceduresWritten = 0;
   for (const [key, group] of clusters) {
@@ -906,8 +934,21 @@ function formatProcedureStatsText(report) {
 }
 
 // src/access-service.ts
+import * as nodePath from "path";
 var EngramAccessInputError = class extends Error {
 };
+var cachedPackageVersion = null;
+async function getPackageVersion() {
+  if (cachedPackageVersion !== null) return cachedPackageVersion;
+  try {
+    const raw = await nodeFs.readFile(new URL("../package.json", import.meta.url), "utf-8");
+    const parsed = JSON.parse(raw);
+    cachedPackageVersion = typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : "unknown";
+  } catch {
+    cachedPackageVersion = "unknown";
+  }
+  return cachedPackageVersion;
+}
 function normalizeTrustZoneInputError(error) {
   const message = error instanceof Error ? error.message : null;
   if (!message) {
@@ -1020,6 +1061,23 @@ function compareBrowseMemory(sort, left, right) {
       return rightUpdated.localeCompare(leftUpdated) || rightCreated.localeCompare(leftCreated) || left.frontmatter.id.localeCompare(right.frontmatter.id);
   }
 }
+function shapeMemorySummary(memory, baseDir, disclosure, rawExcerpts) {
+  const includeFullContent = disclosure === "section" || disclosure === "raw";
+  return {
+    id: memory.frontmatter.id,
+    path: memory.path,
+    category: memory.frontmatter.category,
+    status: inferMemoryStatus(memory.frontmatter, toMemoryPathRel(baseDir, memory.path)),
+    created: memory.frontmatter.created,
+    updated: memory.frontmatter.updated,
+    tags: normalizeProjectionTags(memory.frontmatter.tags),
+    entityRef: memory.frontmatter.entityRef,
+    preview: normalizeProjectionPreview(memory.content),
+    ...disclosure !== void 0 ? { disclosure } : {},
+    ...includeFullContent ? { content: memory.content } : {},
+    ...disclosure === "raw" && rawExcerpts !== void 0 ? { rawExcerpts } : {}
+  };
+}
 var EngramAccessService = class {
   constructor(orchestrator) {
     this.orchestrator = orchestrator;
@@ -1127,29 +1185,90 @@ var EngramAccessService = class {
       graph
     } : void 0;
   }
-  async serializeRecallResults(snapshot) {
+  async serializeRecallResults(snapshot, disclosure, rawContext = null) {
     if (!snapshot) return [];
     const namespace = snapshot.namespace ? this.resolveNamespace(snapshot.namespace) : this.orchestrator.config.defaultNamespace;
     const storage = await this.orchestrator.getStorage(namespace);
     const storageDir = storage.dir;
     const results = [];
     const seen = /* @__PURE__ */ new Set();
+    const rawExcerptsResult = await this.fetchRawExcerpts(
+      disclosure,
+      rawContext ? { ...rawContext, namespace } : null
+    );
+    const rawExcerpts = rawExcerptsResult ?? void 0;
     for (const memoryPath of snapshot.resultPaths ?? []) {
       if (!memoryPath || seen.has(memoryPath)) continue;
       const memory = await storage.readMemoryByPath(memoryPath);
       if (!memory) continue;
       seen.add(memoryPath);
-      results.push(this.serializeMemorySummary(memory, storageDir));
+      results.push(
+        this.serializeMemorySummary(
+          memory,
+          storageDir,
+          disclosure,
+          // Attach the (possibly empty) raw excerpts to the first raw
+          // result; subsequent results do not duplicate the array.
+          results.length === 0 ? rawExcerpts : void 0
+        )
+      );
     }
     if (results.length > 0) return results;
     for (const memoryId of snapshot.memoryIds) {
       const memory = await storage.getMemoryById(memoryId);
       if (!memory || seen.has(memory.path)) continue;
       seen.add(memory.path);
-      results.push(this.serializeMemorySummary(memory, storageDir));
+      results.push(
+        this.serializeMemorySummary(
+          memory,
+          storageDir,
+          disclosure,
+          results.length === 0 ? rawExcerpts : void 0
+        )
+      );
     }
     return results;
   }
+  /**
+   * Fetch raw transcript excerpts from the LCM archive for `disclosure ===
+   * "raw"` recalls (issue #677 PR 2/4).  Returns `null` for non-raw recall
+   * depths, an empty array when LCM is disabled / not initialized / has no
+   * matches, and an array of LCM-side excerpts otherwise.  Errors are
+   * swallowed and treated as "no excerpts" so a failing LCM never breaks
+   * the recall response.
+   *
+   * Namespace handling: LCM archival prefixes non-default-namespace
+   * sessions with `${namespace}:${sessionKey}` (see `observe()` around
+   * line 2498), so the lookup must mirror that prefix or raw recalls in
+   * non-default namespaces miss their own excerpts.
+   */
+  async fetchRawExcerpts(disclosure, context) {
+    if (disclosure !== "raw") return null;
+    if (!context || !context.query) return [];
+    if (!context.sessionKey) return [];
+    const lcm = this.orchestrator.lcmEngine;
+    if (!lcm || !lcm.enabled) return [];
+    try {
+      const lcmSessionKey = context.namespace && context.namespace !== this.orchestrator.config.defaultNamespace ? `${context.namespace}:${context.sessionKey}` : context.sessionKey;
+      const rows = await lcm.searchContextFull(
+        context.query,
+        // Cap the excerpt fanout so recall responses stay bounded.  Five
+        // matches is enough to anchor the model in the raw transcript
+        // without ballooning token spend; raw is meant as the escape
+        // hatch, not the default.
+        5,
+        lcmSessionKey
+      );
+      return rows.map((r) => ({
+        turnIndex: r.turn_index,
+        role: r.role,
+        content: r.content,
+        sessionId: r.session_id
+      }));
+    } catch {
+      return [];
+    }
+  }
   async handleIdempotentWrite(options) {
     if (options.skip === true) {
       return options.execute();
@@ -1205,8 +1324,8 @@ var EngramAccessService = class {
   async withIdempotencyLock(key, fn) {
     const previous = this.idempotencyLocks.get(key) ?? Promise.resolve();
     let release;
-    const current = new Promise((resolve) => {
-      release = resolve;
+    const current = new Promise((resolve2) => {
+      release = resolve2;
     });
     const queued = previous.then(() => current, () => current);
     this.idempotencyLocks.set(key, queued);
@@ -1350,17 +1469,81 @@ var EngramAccessService = class {
       defaultBranch: ctx.defaultBranch
     });
   }
+  /**
+   * Auto-resolve and attach a coding context for a session when one is not
+   * already present. Resolves from `projectTag` (highest priority after
+   * explicit `codingContext`), then from `cwd` via git detection.
+   *
+   * This is a no-op when:
+   *   - `sessionKey` is missing
+   *   - the session already has a coding context attached
+   *   - codingMode.projectScope is disabled (CLAUDE.md #30)
+   *   - neither `cwd` nor `projectTag` is provided
+   *
+   * Never throws — git resolution failures are silently ignored because not
+   * being in a repo is a normal runtime state.
+   */
+  async maybeAttachCodingContext(sessionKey, options) {
+    if (!sessionKey) return;
+    if (!this.orchestrator.config.codingMode?.projectScope) return;
+    if (this.orchestrator.getCodingContextForSession(sessionKey)) return;
+    if (typeof options.projectTag === "string" && options.projectTag.trim().length > 0) {
+      const tag = options.projectTag.trim();
+      this.orchestrator.setCodingContextForSession(sessionKey, {
+        projectId: `tag:${tag}`,
+        branch: null,
+        rootPath: `tag:${tag}`,
+        defaultBranch: null
+      });
+      return;
+    }
+    if (typeof options.cwd === "string" && options.cwd.trim().length > 0) {
+      try {
+        const gitCtx = await resolveGitContext(options.cwd);
+        if (gitCtx) {
+          this.setCodingContext({
+            sessionKey,
+            codingContext: {
+              projectId: gitCtx.projectId,
+              branch: gitCtx.branch,
+              rootPath: gitCtx.rootPath,
+              defaultBranch: gitCtx.defaultBranch
+            }
+          });
+        }
+      } catch {
+      }
+    }
+  }
   async recall(request) {
     const query = request.query.trim();
     if (query.length === 0) {
       throw new EngramAccessInputError("query is required");
     }
+    const callerProvidedDisclosure = request.disclosure !== void 0 && request.disclosure !== null;
+    const requestedDisclosure = (() => {
+      if (!callerProvidedDisclosure) {
+        return DEFAULT_RECALL_DISCLOSURE;
+      }
+      if (!isRecallDisclosure(request.disclosure)) {
+        throw new EngramAccessInputError(
+          `disclosure must be one of: chunk, section, raw (got: ${String(request.disclosure)})`
+        );
+      }
+      return request.disclosure;
+    })();
     if (request.codingContext !== void 0 && request.sessionKey) {
       this.setCodingContext({
         sessionKey: request.sessionKey,
         codingContext: request.codingContext
       });
     }
+    if (request.codingContext === void 0 && request.sessionKey) {
+      await this.maybeAttachCodingContext(request.sessionKey, {
+        cwd: request.cwd,
+        projectTag: request.projectTag
+      });
+    }
     const namespaceOverride = this.resolveRecallNamespace(request.namespace, request.sessionKey);
     const namespace = namespaceOverride ?? this.orchestrator.config.defaultNamespace;
     const mode = this.normalizeRecallMode(request.mode);
@@ -1421,16 +1604,77 @@ var EngramAccessService = class {
       this.budget.gc();
     }
     const topK = Number.isFinite(request.topK) ? Math.max(0, Math.floor(request.topK ?? 0)) : void 0;
+    let asOf;
+    if (request.asOf !== void 0 && request.asOf !== null) {
+      if (typeof request.asOf !== "string" || request.asOf.trim().length === 0) {
+        throw new EngramAccessInputError(
+          "asOf must be a non-empty ISO 8601 timestamp string"
+        );
+      }
+      const parsed = Date.parse(request.asOf);
+      if (!Number.isFinite(parsed)) {
+        throw new EngramAccessInputError(
+          `asOf must be a parseable ISO 8601 timestamp (got: "${request.asOf}")`
+        );
+      }
+      asOf = request.asOf;
+    }
     const recallOptions = {
       namespace: namespaceOverride,
       topK,
-      mode
+      mode,
+      ...asOf !== void 0 ? { asOf } : {},
+      ...request.includeLowConfidence === true ? { includeLowConfidence: true } : {}
     };
     const startedAt = Date.now();
     const context = await this.orchestrator.recall(query, request.sessionKey, recallOptions);
     const snapshot = request.sessionKey ? this.orchestrator.lastRecall.get(request.sessionKey) : null;
     const effectiveNamespace = snapshot?.namespace ? this.resolveNamespace(snapshot.namespace) : namespace;
-    const results = await this.serializeRecallResults(snapshot);
+    const resultsReturned = snapshot?.memoryIds?.length ?? 0;
+    const appliedTopK = snapshot?.budgetsApplied?.appliedTopK;
+    const configMaxResults = typeof this.orchestrator.config.qmdMaxResults === "number" && Number.isFinite(this.orchestrator.config.qmdMaxResults) && this.orchestrator.config.qmdMaxResults > 0 ? this.orchestrator.config.qmdMaxResults : 0;
+    const topKDenominator = typeof appliedTopK === "number" && Number.isFinite(appliedTopK) && appliedTopK > 0 ? Math.max(appliedTopK, resultsReturned) : typeof topK === "number" && topK > 0 ? Math.max(topK, resultsReturned) : Math.max(configMaxResults, resultsReturned, 1);
+    const topKConfidence = snapshot && topKDenominator > 0 ? Math.min(1, resultsReturned / topKDenominator) : void 0;
+    const escalationDecision = decideDisclosureEscalation({
+      mode: this.orchestrator.config.recallDisclosureEscalation,
+      threshold: this.orchestrator.config.recallDisclosureEscalationThreshold,
+      originalDisclosure: requestedDisclosure,
+      callerProvidedDisclosure,
+      topKConfidence
+    });
+    const disclosure = escalationDecision.effective;
+    let results = await this.serializeRecallResults(snapshot, disclosure, {
+      query,
+      sessionKey: request.sessionKey
+    });
+    const filterTags = normalizeTags(request.tags);
+    let tagMatchMode;
+    try {
+      tagMatchMode = parseTagMatch(request.tagMatch);
+    } catch (err) {
+      throw new EngramAccessInputError(
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+    let effectiveContext = context;
+    if (filterTags && filterTags.length > 0) {
+      const beforeIds = results.map((r) => r.id);
+      const { results: admitted } = applyTagFilter(results, {
+        tags: filterTags,
+        tagMatch: tagMatchMode
+      });
+      results = admitted;
+      const admittedIds = new Set(results.map((r) => r.id));
+      const droppedAny = beforeIds.some((id) => !admittedIds.has(id));
+      if (droppedAny) {
+        effectiveContext = results.map((r) => {
+          const content = typeof r.content === "string" ? r.content ?? "" : "";
+          const preview = typeof r.preview === "string" ? r.preview ?? "" : "";
+          return content || preview;
+        }).filter((s) => s.length > 0).join("\n\n");
+      }
+    }
+    const filteredMemoryIds = filterTags && filterTags.length > 0 ? results.map((r) => r.id) : snapshot?.memoryIds ?? [];
     const debug = await this.buildRecallDebug(
       snapshot,
       effectiveNamespace,
@@ -1451,8 +1695,13 @@ var EngramAccessService = class {
           trigger: "access-surface",
           queryText: query,
           candidateMemoryIds: snapshot?.memoryIds ?? [],
-          summary: context.slice(0, 200) || null,
-          injectedChars: context.length,
+          // Audit must reflect what was actually injected, not what
+          // recall produced before the tag filter. Using `context`
+          // (pre-filter) overstates injectedChars and can leak content
+          // from excluded memories into the audit summary (cursor
+          // Medium on PR #712).
+          summary: effectiveContext.slice(0, 200) || null,
+          injectedChars: effectiveContext.length,
           toggleState: "enabled",
           latencyMs: Date.now() - startedAt,
           plannerMode: snapshot?.plannerMode ?? mode,
@@ -1471,15 +1720,16 @@ var EngramAccessService = class {
       query,
       sessionKey: request.sessionKey,
       namespace: effectiveNamespace,
-      context,
-      count: snapshot?.memoryIds.length ?? results.length,
-      memoryIds: snapshot?.memoryIds ?? [],
+      context: effectiveContext,
+      count: filterTags && filterTags.length > 0 ? results.length : snapshot?.memoryIds.length ?? results.length,
+      memoryIds: filteredMemoryIds,
       results,
       recordedAt: snapshot?.recordedAt,
       traceId: snapshot?.traceId,
       plannerMode: snapshot?.plannerMode ?? mode,
       fallbackUsed: snapshot?.fallbackUsed ?? false,
       sourcesUsed: snapshot?.sourcesUsed ?? [],
+      disclosure,
       budgetsApplied: snapshot?.budgetsApplied,
       auditAnomalies,
       budgetWarning: budgetDecision.reason === "warn-over-soft" ? budgetDecision : void 0,
@@ -1551,6 +1801,11 @@ var EngramAccessService = class {
     if (query.trim().length === 0) {
       throw new Error("recallXray: query is required and must be non-empty");
     }
+    if (request.disclosure !== void 0 && !isRecallDisclosure(request.disclosure)) {
+      throw new EngramAccessInputError(
+        `recallXray: disclosure must be one of: chunk, section, raw (got: ${String(request.disclosure)})`
+      );
+    }
     const namespacesEnabled = this.orchestrator.config.namespacesEnabled;
     const requestedNamespace = request.namespace?.trim() ? this.resolveNamespace(request.namespace) : void 0;
     const authenticatedPrincipal = request.authenticatedPrincipal?.trim();
@@ -1579,8 +1834,8 @@ var EngramAccessService = class {
     const previousQueue = this.xrayQueue;
     let release = () => {
     };
-    this.xrayQueue = new Promise((resolve) => {
-      release = resolve;
+    this.xrayQueue = new Promise((resolve2) => {
+      release = resolve2;
     });
     await previousQueue;
     try {
@@ -1601,11 +1856,98 @@ var EngramAccessService = class {
         // (CLAUDE.md rule 42).
         ...authenticatedPrincipal ? { principalOverride: authenticatedPrincipal } : {}
       });
-      const snapshot = this.orchestrator.getLastXraySnapshot();
-      if (!snapshot) return { snapshotFound: false };
-      if (requestedNamespace && snapshot.namespace !== requestedNamespace) {
+      const rawSnapshot = this.orchestrator.getLastXraySnapshot();
+      if (!rawSnapshot) return { snapshotFound: false };
+      if (requestedNamespace && rawSnapshot.namespace !== requestedNamespace) {
         return { snapshotFound: false };
       }
+      let snapshot = rawSnapshot;
+      const xrayFilterTags = normalizeTags(request.tags);
+      let xrayTagMatch;
+      try {
+        xrayTagMatch = parseTagMatch(request.tagMatch);
+      } catch (err) {
+        throw new EngramAccessInputError(
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+      if (xrayFilterTags && xrayFilterTags.length > 0) {
+        const namespace = snapshot.namespace ? this.resolveNamespace(snapshot.namespace) : this.orchestrator.config.defaultNamespace;
+        const tagsByIndex = await Promise.all(
+          snapshot.results.map(async (result) => {
+            try {
+              const storage = await this.orchestrator.getStorage(namespace);
+              const memory = await storage.readMemoryByPath(result.path);
+              const t = memory?.frontmatter?.tags;
+              return Array.isArray(t) ? normalizeProjectionTags(t) : [];
+            } catch {
+              return [];
+            }
+          })
+        );
+        const tagged = snapshot.results.map((result, index) => ({
+          result,
+          tags: tagsByIndex[index] ?? []
+        }));
+        const { results: admittedTagged, trace } = applyTagFilter(tagged, {
+          tags: xrayFilterTags,
+          tagMatch: xrayTagMatch
+        });
+        const admittedResults = admittedTagged.map((entry) => entry.result);
+        const filters = trace ? [...snapshot.filters, trace] : snapshot.filters;
+        snapshot = { ...snapshot, results: admittedResults, filters };
+      }
+      if (request.disclosure !== void 0) {
+        const disclosure = request.disclosure;
+        const namespace = snapshot.namespace ? this.resolveNamespace(snapshot.namespace) : this.orchestrator.config.defaultNamespace;
+        const trimmedSessionKey = request.sessionKey?.trim() || void 0;
+        const rawExcerpts = disclosure === "raw" ? await this.fetchRawExcerpts(disclosure, {
+          query,
+          ...trimmedSessionKey ? { sessionKey: trimmedSessionKey } : {},
+          namespace
+        }) : null;
+        const rawExcerptText = rawExcerpts && rawExcerpts.length > 0 ? rawExcerpts.map((e) => e.content).join("\n") : "";
+        const memoryByIndex = await Promise.all(
+          snapshot.results.map(async (result) => {
+            try {
+              const storage = await this.orchestrator.getStorage(namespace);
+              return await storage.readMemoryByPath(result.path);
+            } catch {
+              return null;
+            }
+          })
+        );
+        const firstReadableIndex = memoryByIndex.findIndex((m) => m !== null);
+        const baseDir = (await this.orchestrator.getStorage(namespace)).dir;
+        const decorated = snapshot.results.map((result, index) => {
+          const memory = memoryByIndex[index];
+          if (!memory) {
+            return { ...result, disclosure };
+          }
+          const shaped = shapeMemorySummary(
+            memory,
+            baseDir,
+            disclosure,
+            disclosure === "raw" && index === firstReadableIndex && rawExcerpts && rawExcerpts.length > 0 ? rawExcerpts : void 0
+          );
+          return {
+            ...result,
+            disclosure,
+            estimatedTokens: estimateRecallTokens(JSON.stringify(shaped))
+          };
+        });
+        if (disclosure === "raw" && firstReadableIndex === -1 && rawExcerptText.length > 0 && decorated.length > 0) {
+          decorated[0] = {
+            ...decorated[0],
+            disclosure,
+            estimatedTokens: estimateRecallTokens(rawExcerptText)
+          };
+        }
+        return {
+          snapshotFound: true,
+          snapshot: { ...snapshot, results: decorated }
+        };
+      }
       return { snapshotFound: true, snapshot };
     } finally {
       release();
@@ -2074,6 +2416,10 @@ var EngramAccessService = class {
     };
   }
   async governanceRun(request, principal) {
+    const deepSleep = this.orchestrator.config.dreamsPhases.deepSleep;
+    if (deepSleep.enabled === false && deepSleep.enabledExplicitlySet === true) {
+      throw new Error("memory governance is disabled by dreams.phases.deepSleep.enabled=false");
+    }
     const resolvedNamespace = this.resolveWritableNamespace(
       request.namespace,
       void 0,
@@ -2130,6 +2476,66 @@ var EngramAccessService = class {
       skippedReason: result.skippedReason
     };
   }
+  async liveConnectorsRun(request = {}, principal) {
+    this.resolveWritableNamespace(
+      void 0,
+      void 0,
+      request.authenticatedPrincipal ?? principal
+    );
+    return this.orchestrator.runLiveConnectors({
+      force: request.force === true
+    });
+  }
+  /**
+   * Run the pattern-reinforcement maintenance job (issue #687 PR 2/4).
+   *
+   * Cluster duplicate non-procedural memories and reinforce the
+   * canonical (most-recent) member.  Gated on
+   * `patternReinforcementEnabled` — when disabled, returns
+   * `{ ran: false, skippedReason: "disabled" }` so the cron payload
+   * surface in CI logs cleanly.
+   *
+   * Resolves the namespace via the same writable path used by
+   * `procedureMiningRun` so cross-tenant writes are impossible
+   * (CLAUDE.md rule 42).
+   *
+   * Delegates the run to `orchestrator.runPatternReinforcement` so
+   * the cadence floor (`patternReinforcementCadenceMs`) is enforced
+   * uniformly across cron + MCP paths (PR #730 review feedback,
+   * Codex P2).  Accepts `force: true` for ad-hoc operator runs that
+   * must bypass the cadence floor — mirrors the pattern used by
+   * other maintenance MCP tools.
+   */
+  async patternReinforcementRun(request = {}, principal) {
+    const resolvedNamespace = this.resolveWritableNamespace(
+      request.namespace,
+      void 0,
+      request.authenticatedPrincipal ?? principal
+    );
+    const outcome = await this.orchestrator.runPatternReinforcement({
+      namespace: resolvedNamespace,
+      force: request.force === true
+    });
+    if (!outcome.ran) {
+      return {
+        namespace: resolvedNamespace,
+        ran: false,
+        skippedReason: outcome.skippedReason,
+        clustersFound: 0,
+        canonicalsUpdated: 0,
+        duplicatesSuperseded: 0
+      };
+    }
+    const result = outcome.result;
+    return {
+      namespace: resolvedNamespace,
+      ran: true,
+      clustersFound: result.clustersFound,
+      canonicalsUpdated: result.canonicalsUpdated,
+      duplicatesSuperseded: result.duplicatesSuperseded,
+      result
+    };
+  }
   /**
    * Procedural memory stats (issue #567 PR 5/5). Read-only — resolves the
    * namespace via the same path used by `recallExplain` / `trustZoneStatus`
@@ -2320,18 +2726,8 @@ var EngramAccessService = class {
       frontmatter: memory.frontmatter
     };
   }
-  serializeMemorySummary(memory, baseDir) {
-    return {
-      id: memory.frontmatter.id,
-      path: memory.path,
-      category: memory.frontmatter.category,
-      status: inferMemoryStatus(memory.frontmatter, toMemoryPathRel(baseDir, memory.path)),
-      created: memory.frontmatter.created,
-      updated: memory.frontmatter.updated,
-      tags: normalizeProjectionTags(memory.frontmatter.tags),
-      entityRef: memory.frontmatter.entityRef,
-      preview: normalizeProjectionPreview(memory.content)
-    };
+  serializeMemorySummary(memory, baseDir, disclosure, rawExcerpts) {
+    return shapeMemorySummary(memory, baseDir, disclosure, rawExcerpts);
   }
   async observe(request) {
     if (!request.sessionKey || typeof request.sessionKey !== "string" || request.sessionKey.trim().length === 0) {
@@ -2353,6 +2749,10 @@ var EngramAccessService = class {
       request.sessionKey,
       request.authenticatedPrincipal
     );
+    await this.maybeAttachCodingContext(request.sessionKey, {
+      cwd: request.cwd,
+      projectTag: request.projectTag
+    });
     const lcmSessionKey = namespace !== this.orchestrator.config.defaultNamespace ? `${namespace}:${request.sessionKey}` : request.sessionKey;
     let lcmArchived = false;
     if (this.orchestrator.lcmEngine && this.orchestrator.lcmEngine.enabled) {
@@ -2540,6 +2940,14 @@ var EngramAccessService = class {
     if (!anchor) return { found: false, message: "No identity anchor found yet. Use identity_anchor_update to create one." };
     return { found: true, anchor };
   }
+  /**
+   * @deprecated since issue #679 PR 5/5 — the identity-anchor model is
+   * superseded by the peer registry. Use `peerSet({ id: "self", ... })` or
+   * `remnic peer set self` to update the self peer's identity kernel, and
+   * `remnic peer migrate` to seed `peers/self/identity.md` from existing
+   * legacy anchor data. This method continues to function for backward
+   * compatibility but will be removed in a future major version.
+   */
   async identityAnchorUpdate(request) {
     if (!this.orchestrator.config.identityContinuityEnabled) {
       return { enabled: false, reason: "Identity continuity is disabled." };
@@ -2934,6 +3342,80 @@ ${next}`);
     const explanation = await this.orchestrator.explainLastGraphRecall({ namespace });
     return { explanation };
   }
+  /**
+   * Read-only graph snapshot for the admin pane (issue #691 PR 2/5).
+   *
+   * Reads adjacency from the JSONL edge store written by `GraphIndex` and
+   * resolves node metadata via the namespaced storage manager.  Namespace
+   * resolution mirrors the read-side path used by `recall` /
+   * `procedureStats`, so multi-principal deployments can't leak edges from
+   * a peer namespace (CLAUDE.md rule 42).
+   */
+  async graphSnapshot(request, authenticatedPrincipal) {
+    const namespace = this.resolveReadableNamespace(
+      request.namespace,
+      authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(namespace);
+    const cfg = this.orchestrator.config;
+    let namespaceRootReal;
+    try {
+      namespaceRootReal = await nodeFs.realpath(storage.dir);
+    } catch {
+      namespaceRootReal = nodePath.resolve(storage.dir);
+    }
+    const namespaceRootWithSep = namespaceRootReal.endsWith(nodePath.sep) ? namespaceRootReal : namespaceRootReal + nodePath.sep;
+    const loadNode = async (relPath) => {
+      if (nodePath.isAbsolute(relPath)) {
+        log.warn(
+          `graphSnapshot: rejected absolute edge endpoint (len=${relPath.length}) outside namespace root`
+        );
+        return null;
+      }
+      const candidate = nodePath.resolve(namespaceRootReal, relPath);
+      if (candidate !== namespaceRootReal && !candidate.startsWith(namespaceRootWithSep)) {
+        log.warn(
+          `graphSnapshot: rejected traversing edge endpoint (len=${relPath.length}) outside namespace root`
+        );
+        return null;
+      }
+      let canonical;
+      try {
+        canonical = await nodeFs.realpath(candidate);
+      } catch {
+        canonical = candidate;
+      }
+      if (canonical !== namespaceRootReal && !canonical.startsWith(namespaceRootWithSep)) {
+        log.warn(
+          `graphSnapshot: rejected symlinked edge endpoint (len=${relPath.length}) that resolved outside namespace root`
+        );
+        return null;
+      }
+      const memory = await storage.readMemoryByPath(canonical);
+      if (!memory) return null;
+      const fm = memory.frontmatter;
+      return {
+        category: fm.category ?? "unknown",
+        label: fm.id ?? nodePath.basename(canonical, nodePath.extname(canonical)),
+        updated: fm.updated
+      };
+    };
+    return buildGraphSnapshot({
+      memoryDir: namespaceRootReal,
+      graphConfig: {
+        entityGraphEnabled: cfg.entityGraphEnabled === true,
+        timeGraphEnabled: cfg.timeGraphEnabled === true,
+        causalGraphEnabled: cfg.causalGraphEnabled === true
+      },
+      request: {
+        limit: request.limit,
+        since: request.since,
+        focusNodeId: request.focusNodeId,
+        categories: request.categories
+      },
+      loadNode
+    });
+  }
   async memoryFeedback(request) {
     if (!this.orchestrator.config.feedbackEnabled) {
       return {
@@ -2995,17 +3477,17 @@ ${next}`);
     const storage = await this.orchestrator.getStorage(resolvedNs);
     const storageDir = storage.dir;
     const { writeFile: writeFile2, mkdir: mkdir2 } = await import("fs/promises");
-    const { join, resolve } = await import("path");
+    const { join: join2, resolve: resolve2 } = await import("path");
     const safeKey = request.sessionKey.replace(/[^a-zA-Z0-9_-]/g, "_");
     if (!safeKey) throw new EngramAccessInputError("sessionKey is required");
-    const checkpointDir = join(storageDir, "checkpoints", safeKey);
-    const resolved = resolve(checkpointDir);
-    if (!resolved.startsWith(resolve(storageDir))) {
+    const checkpointDir = join2(storageDir, "checkpoints", safeKey);
+    const resolved = resolve2(checkpointDir);
+    if (!resolved.startsWith(resolve2(storageDir))) {
       throw new EngramAccessInputError("Invalid sessionKey");
     }
     await mkdir2(checkpointDir, { recursive: true });
     const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const filePath = join(checkpointDir, `checkpoint-${ts}.md`);
+    const filePath = join2(checkpointDir, `checkpoint-${ts}.md`);
     await writeFile2(filePath, request.context, "utf-8");
     return { saved: true };
   }
@@ -3040,8 +3522,8 @@ ${next}`);
     );
     const memoryIds = [];
     for (const entry of request.entries) {
-      const basename = entry.path.split("/").pop() ?? entry.path;
-      const id = basename.endsWith(".md") ? basename.slice(0, -3) : basename;
+      const basename2 = entry.path.split("/").pop() ?? entry.path;
+      const id = basename2.endsWith(".md") ? basename2.slice(0, -3) : basename2;
       if (id.length > 0) {
         memoryIds.push(id);
       }
@@ -3059,10 +3541,196 @@ ${next}`);
     }
     return { submitted: memoryIds.length, matched: matchedIds.length };
   }
+  // ── Operator Console state (issue #688 PR 2/3) ────────────────────────────
+  /**
+   * Gather a point-in-time `ConsoleStateSnapshot` from the orchestrator.
+   *
+   * Principal-aware: `resolveReadableNamespace` enforces ACL before the
+   * snapshot is gathered, so callers cannot read a namespace they don't
+   * have read access to (CLAUDE.md rule 42).  The resolved namespace's
+   * storage directory is forwarded as `config.memoryDir` so the ledger-
+   * tail reader in `gatherConsoleState` scans the correct namespace root
+   * rather than the global root.  Read-only — never mutates orchestrator state.
+   */
+  async consoleState(namespace, principal) {
+    const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const { gatherConsoleState } = await import("./state-NCHQ4TRG.js");
+    const orchestratorProxy = Object.create(this.orchestrator, {
+      config: {
+        value: { ...this.orchestrator.config, memoryDir: storage.dir },
+        enumerable: true,
+        configurable: true
+      }
+    });
+    return gatherConsoleState(orchestratorProxy);
+  }
+  // ── Peer Registry surfaces (issue #679 PR 4/5) ────────────────────────────
+  /**
+   * List all registered peers. Returns the array of `Peer` objects in
+   * deterministic alphabetical order (mirroring `listPeers` storage semantics).
+   */
+  async peerList() {
+    const { listPeers } = await import("./peers-6OSQ3NK6.js");
+    const peers = await listPeers(this.orchestrator.config.memoryDir);
+    return { peers };
+  }
+  /**
+   * Get a single peer by id. Returns `{ found: false }` when the peer does
+   * not exist rather than throwing, matching the `memoryGet` / `entityGet`
+   * pattern used throughout the service.
+   */
+  async peerGet(peerId) {
+    const peers = await import("./peers-6OSQ3NK6.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const peer = await peers.readPeer(this.orchestrator.config.memoryDir, peerId);
+    if (!peer) return { found: false };
+    return { found: true, peer };
+  }
+  /**
+   * Upsert a peer. Writes `peers/{id}/identity.md`. On first write the
+   * `createdAt` timestamp is set to now; on subsequent writes only
+   * `displayName` and `notes` are mutated (kind and createdAt are immutable
+   * once set, per the storage contract).
+   *
+   * Returns `{ created: true }` on first write, `{ created: false }` on update.
+   */
+  async peerSet(input) {
+    const peers = await import("./peers-6OSQ3NK6.js");
+    const validateId = peers.assertValidPeerId;
+    const { id } = input;
+    try {
+      validateId(id);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const memoryDir = this.orchestrator.config.memoryDir;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const existing = await peers.readPeer(memoryDir, id);
+    const ALLOWED_KINDS = /* @__PURE__ */ new Set(["self", "human", "agent", "integration"]);
+    if (!existing) {
+      const kind = input.kind ?? "human";
+      if (!ALLOWED_KINDS.has(kind)) {
+        throw new EngramAccessInputError(
+          `peer kind must be one of ${[...ALLOWED_KINDS].join(", ")}`
+        );
+      }
+      const newPeer = {
+        id,
+        kind,
+        displayName: input.displayName ?? id,
+        createdAt: now,
+        updatedAt: now,
+        ...typeof input.notes === "string" ? { notes: input.notes } : {}
+      };
+      await peers.writePeer(memoryDir, newPeer);
+      return { ok: true, created: true, peer: newPeer };
+    }
+    const updated = {
+      id: existing.id,
+      kind: existing.kind,
+      createdAt: existing.createdAt,
+      updatedAt: now,
+      displayName: input.displayName !== void 0 ? input.displayName : existing.displayName,
+      ...input.notes !== void 0 ? { notes: input.notes } : existing.notes !== void 0 ? { notes: existing.notes } : {}
+    };
+    await peers.writePeer(memoryDir, updated);
+    return { ok: true, created: false, peer: updated };
+  }
+  /**
+   * Delete a peer by removing `peers/{id}/identity.md`. If the file does not
+   * exist the call is a no-op (idempotent). The peer directory itself
+   * (`peers/{id}/`) is intentionally left in place — profile and interaction
+   * log data are not destroyed.
+   */
+  async peerDelete(peerId) {
+    const peers = await import("./peers-6OSQ3NK6.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const deleted = await peers.deletePeer(this.orchestrator.config.memoryDir, peerId);
+    return { ok: true, deleted };
+  }
+  /**
+   * Destructively purge the entire peer directory for a given peerId —
+   * `identity.md`, `profile.md`, `interactions.log.md`, and any other
+   * files in `peers/{id}/`. Requires `confirm: "yes"` to prevent
+   * accidental invocation.
+   *
+   * This is the DESTRUCTIVE counterpart to `peerDelete`, which only
+   * removes `identity.md`. All companion files are permanently removed.
+   *
+   * Returns `{ ok: true, purged: true }` when the directory existed and
+   * was removed; `{ ok: true, purged: false }` when the directory did
+   * not exist (idempotent no-op).
+   */
+  async peerForget(peerId, opts) {
+    const peers = await import("./peers-6OSQ3NK6.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    if (opts.confirm !== "yes") {
+      throw new EngramAccessInputError(
+        "peerForget requires confirm: 'yes' to prevent accidental data loss"
+      );
+    }
+    const result = await peers.forgetPeer(this.orchestrator.config.memoryDir, peerId, {
+      confirm: "yes"
+    });
+    return { ok: true, purged: result.purged };
+  }
+  /**
+   * Get the evolving cognitive profile for a peer. Returns `{ found: false }`
+   * when no profile file exists yet (profile is written by the async reasoner,
+   * PR 2/5). The peer identity itself need not exist for a profile to exist,
+   * but in practice the reasoner only writes profiles for registered peers.
+   */
+  async peerProfileGet(peerId) {
+    const peers = await import("./peers-6OSQ3NK6.js");
+    const validateId = peers.assertValidPeerId;
+    try {
+      validateId(peerId);
+    } catch (err) {
+      throw new EngramAccessInputError(err.message);
+    }
+    const profile = await peers.readPeerProfile(this.orchestrator.config.memoryDir, peerId);
+    if (!profile) return { found: false };
+    return { found: true, profile };
+  }
   // ── Contradiction Review (issue #520) ──────────────────────────────────────
   get memoryDir() {
     return this.orchestrator.config.memoryDir;
   }
+  /**
+   * Resolve the storage directory for a given namespace.  Used by the SSE
+   * graph-event handler to subscribe to the correct per-namespace bus rather
+   * than the global root (CLAUDE.md rule 42 — read/write paths must resolve
+   * through the same namespace layer).
+   *
+   * `principal` must be the transport-bound request principal (from
+   * `resolveRequestPrincipal`).  When namespaces are enabled, an absent
+   * principal causes `resolveReadableNamespace` to throw an auth error,
+   * matching the behaviour of every other authenticated read path.
+   *
+   * Falls back to `this.memoryDir` when namespaces are disabled or the
+   * namespace is absent, matching the behaviour of every other read path.
+   */
+  async getMemoryDirForNamespace(namespace, principal) {
+    const resolved = this.resolveReadableNamespace(namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolved);
+    return storage.dir;
+  }
   get storageRef() {
     return this.orchestrator.storage;
   }
@@ -3087,6 +3755,257 @@ ${next}`);
       };
     };
   }
+  /**
+   * Import a capsule archive into the orchestrator's memory directory.
+   *
+   * Delegates directly to the standalone {@link importCapsuleFn} function.
+   * The `root` parameter defaults to the orchestrator's `memoryDir` when
+   * omitted, so callers that only have access to the service do not need to
+   * thread the config value through.
+   *
+   * `versioning` defaults to the orchestrator's page-versioning config so
+   * `mode: "overwrite"` automatically snapshots prior content without the
+   * caller having to construct the config object.
+   */
+  async capsuleImport(opts) {
+    const { namespace, principal, root: explicitRoot, memoryDir: explicitMemoryDir, ...importOptions } = opts;
+    const resolvedNamespace = this.resolveWritableNamespace(namespace, void 0, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const root = explicitRoot ?? storage.dir;
+    const memoryDir = explicitMemoryDir ?? this.orchestrator.config.memoryDir;
+    const versioning = importOptions.versioning ?? {
+      enabled: this.orchestrator.config.versioningEnabled,
+      maxVersionsPerPage: this.orchestrator.config.versioningMaxPerPage,
+      sidecarDir: this.orchestrator.config.versioningSidecarDir
+    };
+    await this.validateCapsuleImportArchivePath(importOptions.archivePath);
+    try {
+      return await importCapsule({ ...importOptions, root, memoryDir, versioning });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (this.isCapsuleImportArchiveInputError(err, message)) {
+        throw new EngramAccessInputError(`capsule import failed: ${message}`);
+      }
+      throw err;
+    }
+  }
+  async validateCapsuleImportArchivePath(archivePath) {
+    let archiveStat;
+    try {
+      archiveStat = await stat(archivePath);
+    } catch (err) {
+      if (!this.isCapsuleImportPathInputFsError(err)) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      throw new EngramAccessInputError(`capsule import failed: archive is not readable: ${message}`);
+    }
+    if (!archiveStat.isFile()) {
+      throw new EngramAccessInputError("capsule import failed: archivePath must point to a file");
+    }
+    try {
+      await nodeFs.access(archivePath, fsConstants.R_OK);
+    } catch (err) {
+      if (!this.isCapsuleImportPathInputFsError(err)) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      throw new EngramAccessInputError(`capsule import failed: archive is not readable: ${message}`);
+    }
+  }
+  isCapsuleImportPathInputFsError(err) {
+    const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+    return code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM" || code === "ELOOP";
+  }
+  isCapsuleImportArchiveInputError(err, message) {
+    if (err instanceof ZodError) return true;
+    const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+    if (typeof code === "string" && code.startsWith("Z_")) return true;
+    return message.startsWith("importCapsule: archive") || message.startsWith("importCapsule: bundle") || message.startsWith("importCapsule: manifest") || message.startsWith("importCapsule: record") || /incorrect header check|invalid stored block lengths|not in gzip format|unexpected end of file/i.test(message);
+  }
+  /**
+   * Export a capsule archive from the orchestrator's memory directory.
+   *
+   * HTTP and future MCP surfaces use this rather than calling the transfer
+   * helper directly so namespace ACL checks stay consistent with the archive
+   * write side effect. The exporter still owns archive construction and
+   * validation.
+   */
+  async capsuleExport(opts) {
+    const { namespace, principal, root: explicitRoot, memoryDir: explicitMemoryDir, ...exportOptions } = opts;
+    const resolvedNamespace = this.resolveWritableNamespace(namespace, void 0, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const root = explicitRoot ?? storage.dir;
+    const memoryDir = explicitMemoryDir ?? this.orchestrator.config.memoryDir;
+    const pluginVersion = exportOptions.pluginVersion ?? await getPackageVersion();
+    return exportCapsule({
+      ...exportOptions,
+      pluginVersion,
+      root,
+      memoryDir: exportOptions.encrypt === true ? memoryDir : void 0
+    });
+  }
+  /**
+   * List capsule archives in the namespace-scoped capsule store.
+   *
+   * MCP uses this access-layer method instead of reading arbitrary paths so
+   * capsule discovery remains bound to the same namespace ACLs as export and
+   * import.
+   */
+  async capsuleList(options) {
+    const resolvedNamespace = this.resolveReadableNamespace(options?.namespace, options?.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const capsulesDir = defaultCapsulesDir(storage.dir);
+    let dirEntries;
+    try {
+      const capsulesDirStat = await nodeFs.lstat(capsulesDir);
+      if (capsulesDirStat.isSymbolicLink()) {
+        throw new EngramAccessInputError("capsule list failed: capsule store directory must not be a symlink");
+      }
+      if (!capsulesDirStat.isDirectory()) {
+        throw new EngramAccessInputError("capsule list failed: capsule store path must be a directory");
+      }
+      dirEntries = await nodeFs.readdir(capsulesDir, { withFileTypes: true });
+    } catch (err) {
+      const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+      if (code === "ENOENT") {
+        return { namespace: resolvedNamespace, capsulesDir, capsules: [] };
+      }
+      throw err;
+    }
+    const archiveNames = dirEntries.filter(
+      (entry) => entry.isFile() && (entry.name.endsWith(".capsule.json.gz") || entry.name.endsWith(".capsule.json.gz.enc"))
+    ).map((entry) => entry.name).sort();
+    const capsules = [];
+    for (const archiveName of archiveNames) {
+      const archivePath = nodePath.join(capsulesDir, archiveName);
+      const id = archiveName.replace(/\.capsule\.json\.gz\.enc$/, "").replace(/\.capsule\.json\.gz$/, "");
+      const manifestPath = nodePath.join(capsulesDir, `${id}.manifest.json`);
+      let createdAt = null;
+      let pluginVersion = null;
+      let fileCount = null;
+      let description = null;
+      let manifestPathOrNull = manifestPath;
+      try {
+        const manifestStat = await nodeFs.lstat(manifestPath);
+        if (manifestStat.isSymbolicLink() || !manifestStat.isFile()) {
+          capsules.push({
+            id,
+            archivePath,
+            manifestPath: manifestPathOrNull,
+            createdAt,
+            pluginVersion,
+            fileCount,
+            description
+          });
+          continue;
+        }
+        const raw = await nodeFs.readFile(manifestPath, "utf-8");
+        const sidecar = JSON.parse(raw);
+        createdAt = typeof sidecar.createdAt === "string" ? sidecar.createdAt : null;
+        pluginVersion = typeof sidecar.pluginVersion === "string" ? sidecar.pluginVersion : null;
+        fileCount = Array.isArray(sidecar.files) ? sidecar.files.length : null;
+        const capsule = sidecar.capsule;
+        description = capsule && typeof capsule.description === "string" ? capsule.description : null;
+      } catch (err) {
+        const code = typeof err === "object" && err !== null && "code" in err ? err.code : void 0;
+        if (code === "ENOENT") {
+          manifestPathOrNull = null;
+        }
+      }
+      capsules.push({
+        id,
+        archivePath,
+        manifestPath: manifestPathOrNull,
+        createdAt,
+        pluginVersion,
+        fileCount,
+        description
+      });
+    }
+    return { namespace: resolvedNamespace, capsulesDir, capsules };
+  }
+  // ── Dreams pipeline telemetry surfaces (issue #678 PR 3+4) ──────────────
+  /**
+   * Return per-phase Dreams telemetry for the last N hours (default 24).
+   */
+  async dreamsStatus(options) {
+    const { getDreamsStatus, normalizeDreamsStatusWindowHours } = await import("./dreams-ledger-LR2NBAZE.js");
+    let windowHours;
+    try {
+      windowHours = normalizeDreamsStatusWindowHours(options?.windowHours);
+    } catch (error) {
+      throw new EngramAccessInputError(error instanceof Error ? error.message : String(error));
+    }
+    const resolvedNamespace = this.resolveReadableNamespace(options?.namespace, options?.principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    return getDreamsStatus(storage.dir, windowHours);
+  }
+  /**
+   * Manually invoke a single Dreams phase pass (PR 4/4).
+   *
+   * Deep-sleep delegates to memory governance (shadow → dry-run, apply → live).
+   * Light-sleep and REM scan the observation ledger and memory corpus
+   * respectively, returning the same telemetry shape as a scheduled run.
+   */
+  async dreamsRun(options) {
+    const { runDreamsPhase } = await import("./dreams-ledger-LR2NBAZE.js");
+    const validPhases = ["lightSleep", "rem", "deepSleep"];
+    if (!validPhases.includes(options.phase)) {
+      throw new EngramAccessInputError(
+        `Invalid phase: ${String(options.phase)}. Must be one of: ${validPhases.join(", ")}`
+      );
+    }
+    const deepSleep = this.orchestrator.config.dreamsPhases.deepSleep;
+    if (options.phase === "deepSleep" && deepSleep.enabled === false && deepSleep.enabledExplicitlySet === true) {
+      throw new EngramAccessInputError(
+        "memory governance is disabled by dreams.phases.deepSleep.enabled=false"
+      );
+    }
+    const dryRun = options.dryRun === true;
+    const resolvedNamespace = this.resolveWritableNamespace(
+      options.namespace,
+      void 0,
+      options.authenticatedPrincipal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const memoryDir = storage.dir;
+    const phaseRunner = dryRun || options.phase === "deepSleep" ? void 0 : async (_opts) => {
+      if (_opts.phase === "lightSleep") {
+        const result3 = await this.orchestrator.runLifecyclePolicyNow(storage);
+        return {
+          itemsProcessed: result3.memoriesAssessed,
+          notes: `scored ${result3.memoriesAssessed} memories`
+        };
+      }
+      const result2 = await this.orchestrator.runSemanticConsolidationNow({
+        dryRun: false,
+        storage
+      });
+      const itemsProcessed = result2.clusters.reduce(
+        (sum, cluster) => sum + cluster.memories.length,
+        0
+      );
+      return {
+        itemsProcessed,
+        notes: `REM consolidation found ${result2.clustersFound} clusters`
+      };
+    };
+    const governanceRunner = options.phase === "deepSleep" ? async (_opts) => {
+      return this.orchestrator.runDeepSleepGovernanceNow({
+        storage,
+        dryRun: _opts.dryRun
+      });
+    } : void 0;
+    const result = await runDreamsPhase(
+      { memoryDir, phase: options.phase, dryRun },
+      governanceRunner,
+      phaseRunner
+    );
+    return {
+      phase: result.phase,
+      dryRun: result.dryRun,
+      durationMs: result.durationMs,
+      itemsProcessed: result.itemsProcessed,
+      notes: result.notes
+    };
+  }
 };
 
 export {
@@ -3095,6 +4014,7 @@ export {
   formatProcedureStatsText,
   EngramAccessInputError,
   ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
+  shapeMemorySummary,
   EngramAccessService
 };
-//# sourceMappingURL=chunk-STGWEHYR.js.map
+//# sourceMappingURL=chunk-DR7MCMPS.js.map