@remnic/core 1.1.31 → 9.3.516

package/src/training-export/converter.ts

@@ -9,9 +9,11 @@
  * The `input` field is empty string (synthesis is left to adapters).
  */
 
-import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 
+import { parseStrictCliDate } from "./date-parse.js";
 import type { TrainingExportOptions, TrainingExportRecord } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -85,6 +87,10 @@ async function safeRealpath(p: string): Promise<string | null> {
   }
 }
 
+function isContainedPath(real: string, containmentRoot: string): boolean {
+  return real === containmentRoot || real.startsWith(containmentRoot + path.sep);
+}
+
 /**
  * Recursively collect `.md` files under `dir`, returning deterministic,
  * lexicographically-sorted absolute paths.
@@ -157,7 +163,7 @@ async function collectMarkdownFiles(
 
         const real = await safeRealpath(full);
         if (!real) continue;
-        if (real !== containmentRoot && !real.startsWith(containmentRoot + path.sep)) {
+        if (!isContainedPath(real, containmentRoot)) {
           continue;
         }
         files.push(full);
@@ -172,6 +178,27 @@ async function collectMarkdownFiles(
   return files.sort((a, b) => a.localeCompare(b));
 }
 
+export async function readContainedMarkdownFile(
+  filePath: string,
+  containmentRoot: string,
+): Promise<string | null> {
+  let handle: Awaited<ReturnType<typeof open>> | null = null;
+  try {
+    handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const st = await handle.stat();
+    if (!st.isFile() || st.nlink > 1) return null;
+
+    const real = await safeRealpath(filePath);
+    if (!real || !isContainedPath(real, containmentRoot)) return null;
+
+    return await handle.readFile("utf-8");
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Build instruction from category + tags
 // ---------------------------------------------------------------------------
@@ -214,8 +241,11 @@ function buildInstruction(category: string, tags: string[]): string {
 
 function parseIsoDate(isoStr: string): Date | null {
   if (!isoStr) return null;
-  const d = new Date(isoStr);
-  return Number.isFinite(d.getTime()) ? d : null;
+  try {
+    return parseStrictCliDate(isoStr, "memory created timestamp");
+  } catch {
+    return null;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -254,12 +284,8 @@ export async function convertMemoriesToRecords(
   const records: TrainingExportRecord[] = [];
 
   for (const filePath of allFiles) {
-    let raw: string;
-    try {
-      raw = await readFile(filePath, "utf-8");
-    } catch {
-      continue; // skip unreadable files
-    }
+    const raw = await readContainedMarkdownFile(filePath, containmentRoot);
+    if (raw === null) continue; // skip unreadable files
 
     const parsed = parseFrontmatter(raw);
     if (!parsed) continue; // skip malformed files

package/src/training-export/registry.test.ts

@@ -71,6 +71,23 @@ describe("TrainingExportAdapter registry", () => {
     );
   });
 
+  it("rejects malformed adapters without mutating the registry", () => {
+    assert.throws(
+      () => registerTrainingExportAdapter({ name: "no-format" } as unknown as TrainingExportAdapter),
+      /formatRecords must be a function/,
+    );
+    assert.throws(
+      () => registerTrainingExportAdapter({
+        name: "bad-ext",
+        formatRecords: () => "",
+        fileExtension: "",
+      } as unknown as TrainingExportAdapter),
+      /fileExtension must be a non-empty extension/,
+    );
+
+    assert.deepEqual(listTrainingExportAdapters(), []);
+  });
+
   it("trims adapter name on lookup", () => {
     registerTrainingExportAdapter(makeAdapter("axolotl"));
     assert.ok(getTrainingExportAdapter("  axolotl  "));

package/src/training-export/registry.ts

@@ -16,12 +16,30 @@ const adapters = new Map<string, TrainingExportAdapter>();
  * listing valid actions (CLAUDE.md rule #51).
  */
 export function registerTrainingExportAdapter(adapter: TrainingExportAdapter): void {
-  if (!adapter || typeof adapter.name !== "string" || adapter.name.trim().length === 0) {
+  if (!adapter || typeof adapter !== "object" || Array.isArray(adapter)) {
+    throw new Error(
+      "registerTrainingExportAdapter: adapter must be an object with name, fileExtension, and formatRecords.",
+    );
+  }
+  if (typeof adapter.name !== "string" || adapter.name.trim().length === 0) {
     throw new Error(
       "registerTrainingExportAdapter: adapter.name must be a non-empty string. " +
         "Provide a unique adapter name (e.g. 'weclone', 'axolotl', 'mlx').",
     );
   }
+  if (typeof adapter.formatRecords !== "function") {
+    throw new Error(
+      "registerTrainingExportAdapter: adapter.formatRecords must be a function.",
+    );
+  }
+  if (
+    typeof adapter.fileExtension !== "string" ||
+    !/^\.[A-Za-z0-9][A-Za-z0-9._-]*$/.test(adapter.fileExtension.trim())
+  ) {
+    throw new Error(
+      "registerTrainingExportAdapter: adapter.fileExtension must be a non-empty extension like '.jsonl'.",
+    );
+  }
 
   const key = adapter.name.trim();
 

package/src/transcript.ts

@@ -659,7 +659,7 @@ export class TranscriptManager {
               const entryTime = new Date(entry.timestamp);
 
               // Check if entry is within time range
-              if (entryTime >= start && entryTime <= end) {
+              if (entryTime >= start && entryTime < end) {
                 // Filter by sessionKey if provided
                 if (!sessionKey || entry.sessionKey === sessionKey) {
                   entries.push(entry);
@@ -739,7 +739,7 @@ export class TranscriptManager {
           try {
             const entry = JSON.parse(line) as TranscriptEntry;
             const ts = new Date(entry.timestamp);
-            if (ts >= start && ts <= end && entry.sessionKey === sessionKey) {
+            if (ts >= start && ts < end && entry.sessionKey === sessionKey) {
               entries.push(entry);
             }
           } catch {

package/src/transfer/backup.ts

@@ -3,7 +3,7 @@ import { mkdir, readdir, rm, unlink, writeFile } from "node:fs/promises";
 import { gzipSync } from "node:zlib";
 import { exportMarkdownBundle } from "./export-md.js";
 import { encryptCapsuleFile } from "./capsule-crypto.js";
-import { isTransferPathExcluded } from "./exclusions.js";
+import { computeTransferOutputRel, isTransferPathExcluded } from "./exclusions.js";
 
 export interface BackupOptions {
   memoryDir: string;
@@ -43,13 +43,14 @@ export async function backupMemoryDir(opts: BackupOptions): Promise<string> {
     const { readFile } = await import("node:fs/promises");
 
     const memoryDirAbs = path.resolve(opts.memoryDir);
+    const outputRelPosix = computeTransferOutputRel(memoryDirAbs, outDirAbs);
     const filesAbs = await listFilesRecursive(memoryDirAbs);
     const includeTranscripts = opts.includeTranscripts === true;
 
     const records: Array<{ path: string; content: string }> = [];
     for (const abs of filesAbs) {
       const relPosix = toPosixRelPath(abs, memoryDirAbs);
-      if (isTransferPathExcluded(relPosix, { includeTranscripts })) continue;
+      if (isTransferPathExcluded(relPosix, { includeTranscripts, outputRelPosix })) continue;
       const content = await readFile(abs, "utf-8");
       records.push({ path: relPosix, content });
     }
@@ -67,11 +68,21 @@ export async function backupMemoryDir(opts: BackupOptions): Promise<string> {
     await writeFile(tempGzPath, gz);
 
     // Encrypt and remove plaintext.
-    const { encPath } = await encryptCapsuleFile({
-      sourceGzPath: tempGzPath,
-      memoryDir: opts.memoryDir,
-    });
-    await unlink(tempGzPath);
+    let encPath: string;
+    try {
+      ({ encPath } = await encryptCapsuleFile({
+        sourceGzPath: tempGzPath,
+        memoryDir: opts.memoryDir,
+      }));
+      await unlink(tempGzPath);
+    } catch (error) {
+      try {
+        await unlink(tempGzPath);
+      } catch {
+        // Best-effort cleanup: do not leave a plaintext backup after failed encryption.
+      }
+      throw error;
+    }
 
     if (opts.retentionDays && opts.retentionDays > 0) {
       await enforceRetention(outDirAbs, opts.retentionDays);

package/src/transfer/capsule-crypto.ts

@@ -61,6 +61,13 @@ import path from "node:path";
 import { open, seal } from "../secure-store/cipher.js";
 import * as keyring from "../secure-store/keyring.js";
 import { readHeader, secureStoreDir } from "../secure-store/header.js";
+import {
+  deriveKey,
+  KDF_SALT_LENGTH,
+  type Argon2idParams,
+  type KdfAlgorithm,
+  type ScryptParams,
+} from "../secure-store/kdf.js";
 
 // ---------------------------------------------------------------------------
 // On-disk magic
@@ -125,9 +132,17 @@ export interface DecryptCapsuleOptions {
 
   /**
    * Absolute path to the memory directory whose secure-store keyring will
-   * be queried for the master key.
+   * be queried for the master key when no passphrase is supplied. Required
+   * for v1 archives, optional for v2 passphrase-based restores.
    */
-  memoryDir: string;
+  memoryDir?: string;
+
+  /**
+   * Original secure-store passphrase. For format-v2 archives this is used
+   * with the embedded KDF params to restore on a machine that does not have
+   * the source memory directory's unlocked keyring entry.
+   */
+  passphrase?: string;
 
   /**
    * Destination path for the decrypted output. If omitted, defaults to
@@ -235,14 +250,13 @@ export async function encryptCapsuleFile(
  * decryption. Throws with a clear message on:
  *   - non-enc file / wrong magic
  *   - unsupported format version
- *   - locked/uninitialized secure-store (when keyring is not unlocked and no passphrase)
+   *   - locked/uninitialized secure-store (when keyring is not unlocked and no passphrase)
  *   - wrong key / tampered ciphertext (AES-GCM auth failure)
  *
- * Format v2 archives carry embedded KDF params. If a `passphrase` is
- * provided in `opts.memoryDir`-less scenarios, the key is re-derived from
- * the passphrase + embedded KDF params (cross-machine restore). If the
- * keyring is unlocked the keyring key is used directly (faster, no
- * passphrase prompt needed).
+   * Format v2 archives carry embedded KDF params. If a `passphrase` is
+   * provided, the key is re-derived from the passphrase + embedded KDF params
+   * for cross-machine restore. Without a passphrase, an unlocked keyring key
+   * from `memoryDir` is used directly.
  */
 export async function decryptCapsuleFile(
   opts: DecryptCapsuleOptions,
@@ -273,7 +287,14 @@ export async function decryptCapsuleFile(
   }
 
   // Resolve the decryption key and the envelope offset.
-  const { key, envelopeOffset } = resolveKeyAndOffset(buf, version, opts.memoryDir, "decryptCapsuleFile", opts.encPath);
+  const { key, envelopeOffset } = resolveKeyAndOffset(
+    buf,
+    version,
+    opts.memoryDir,
+    "decryptCapsuleFile",
+    opts.encPath,
+    opts.passphrase,
+  );
 
   // The sealed envelope starts at `envelopeOffset`.
   const envelope = buf.subarray(envelopeOffset);
@@ -312,7 +333,8 @@ export async function decryptCapsuleFile(
  */
 export async function decryptCapsuleFileInMemory(
   encPath: string,
-  memoryDir: string,
+  memoryDir?: string,
+  options: { passphrase?: string } = {},
 ): Promise<Buffer> {
   const buf = await readFile(encPath);
 
@@ -335,7 +357,14 @@ export async function decryptCapsuleFileInMemory(
     );
   }
 
-  const { key, envelopeOffset } = resolveKeyAndOffset(buf, version, memoryDir, "decryptCapsuleFileInMemory", encPath);
+  const { key, envelopeOffset } = resolveKeyAndOffset(
+    buf,
+    version,
+    memoryDir,
+    "decryptCapsuleFileInMemory",
+    encPath,
+    options.passphrase,
+  );
   const envelope = buf.subarray(envelopeOffset);
 
   const basename = path.basename(encPath);
@@ -370,6 +399,12 @@ interface KdfSection {
   salt: Buffer;
 }
 
+interface ParsedKdfSection {
+  algorithm: KdfAlgorithm;
+  params: ScryptParams | Argon2idParams;
+  salt: Buffer;
+}
+
 /**
  * Read the KDF params + canonical salt from the secure-store header and
  * return both a compact JSON representation (for embedding in the archive)
@@ -419,14 +454,20 @@ async function loadKdfSection(memoryDir: string): Promise<KdfSection> {
  * Rule 51: never silently default when the user's intent is clear but the
  * precondition (unlocked keyring) is not met.
  */
-function getKeyOrThrow(memoryDir: string, action: string): Buffer {
+function getKeyOrThrow(memoryDir: string | undefined, action: string): Buffer {
+  if (!memoryDir) {
+    throw new Error(
+      `Secure-store memoryDir is required — cannot ${action} without either an unlocked keyring or a format-v2 passphrase.`,
+    );
+  }
   const storeId = secureStoreDir(memoryDir);
   const key = keyring.getKey(storeId);
   if (key === null) {
     throw new Error(
       `Secure-store is locked or not initialized — cannot ${action}. ` +
-        `Run \`remnic secure-store unlock\` first, or \`remnic secure-store init\` ` +
-        `if the store has never been initialized.`,
+        `Run \`remnic secure-store unlock\` first, provide the original passphrase for ` +
+        `a format-v2 archive restore, or run \`remnic secure-store init\` if the store ` +
+        `has never been initialized.`,
     );
   }
   return key;
@@ -437,11 +478,9 @@ function getKeyOrThrow(memoryDir: string, action: string): Buffer {
  * within `buf`, handling both format v1 (no KDF section) and format v2
  * (embedded KDF params for cross-machine restore).
  *
- * For v2 archives: the keyring is tried first (fast path, no re-derivation).
- * If the keyring is locked/unavailable and the archive carries KDF params,
- * the caller must supply a passphrase separately (not yet wired to the
- * public API — this is the foundation). For now, locked keyring still
- * throws the same clear error as v1.
+ * For v2 archives: a caller-supplied passphrase is derived against the
+ * embedded KDF section for cross-machine restore. Without a passphrase, the
+ * keyring is used as the fast local path.
  *
  * The KDF-params section serves two roles:
  *   1. Documents what algorithm was used so cross-machine tooling knows
@@ -453,9 +492,10 @@ function getKeyOrThrow(memoryDir: string, action: string): Buffer {
 function resolveKeyAndOffset(
   buf: Buffer,
   version: number,
-  memoryDir: string,
+  memoryDir: string | undefined,
   caller: string,
   encPath: string,
+  passphrase?: string,
 ): { key: Buffer; envelopeOffset: number } {
   if (version === 1) {
     // v1: envelope starts immediately after magic (11) + version (1).
@@ -477,9 +517,53 @@ function resolveKeyAndOffset(
       `${caller}: file too short for format v2 KDF params section (expected ${kdfLen} bytes): ${encPath}`,
     );
   }
+  if (kdfLen <= 0) {
+    throw new Error(`${caller}: format v2 KDF params section is empty: ${encPath}`);
+  }
+  const kdfJson = buf.subarray(kdfJsonOffset, kdfJsonOffset + kdfLen).toString("utf-8");
+  const kdf = parseEmbeddedKdfSection(kdfJson, caller, encPath);
   const envelopeOffset = kdfJsonOffset + kdfLen;
 
-  // Prefer the in-memory keyring key (no re-derivation needed).
+  if (passphrase !== undefined) {
+    if (passphrase.length === 0) {
+      throw new Error(`${caller}: passphrase must not be empty for format v2 archive restore`);
+    }
+    const key = deriveKey(kdf.algorithm, passphrase, kdf.salt, kdf.params);
+    return { key, envelopeOffset };
+  }
+
   const key = getKeyOrThrow(memoryDir, "decrypt capsule");
   return { key, envelopeOffset };
 }
+
+function parseEmbeddedKdfSection(json: string, caller: string, encPath: string): ParsedKdfSection {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (cause) {
+    throw new Error(`${caller}: format v2 KDF params are not valid JSON: ${encPath}`, { cause: cause as Error });
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${caller}: format v2 KDF params must be a JSON object: ${encPath}`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  const algorithm = obj.algorithm;
+  if (algorithm !== "scrypt" && algorithm !== "argon2id") {
+    throw new Error(`${caller}: unsupported format v2 KDF algorithm ${String(algorithm)}: ${encPath}`);
+  }
+  if (typeof obj.params !== "object" || obj.params === null || Array.isArray(obj.params)) {
+    throw new Error(`${caller}: format v2 KDF params.params must be an object: ${encPath}`);
+  }
+  if (typeof obj.salt !== "string" || !/^[0-9a-fA-F]+$/.test(obj.salt) || obj.salt.length % 2 !== 0) {
+    throw new Error(`${caller}: format v2 KDF salt must be an even-length hex string: ${encPath}`);
+  }
+  const salt = Buffer.from(obj.salt, "hex");
+  if (salt.length !== KDF_SALT_LENGTH) {
+    throw new Error(`${caller}: format v2 KDF salt decoded to ${salt.length} bytes, expected ${KDF_SALT_LENGTH}: ${encPath}`);
+  }
+  return {
+    algorithm,
+    params: obj.params as ScryptParams | Argon2idParams,
+    salt,
+  };
+}

package/src/transfer/capsule-encrypt.test.ts

@@ -22,7 +22,7 @@
 
 import assert from "node:assert/strict";
 import test from "node:test";
-import { mkdtemp, rm, writeFile, readFile, mkdir, stat } from "node:fs/promises";
+import { mkdtemp, rm, writeFile, readFile, mkdir, stat, readdir } from "node:fs/promises";
 import path from "node:path";
 import { tmpdir } from "node:os";
 import { gzipSync, gunzipSync } from "node:zlib";
@@ -231,12 +231,6 @@ test("exportCapsule with encrypt=true + importCapsule roundtrip restores all fil
     );
     assert.equal(exportResult.encryptedArchivePath, exportResult.archivePath);
 
-    // Cross-machine restore scenario: the destination machine uses the same
-    // passphrase as the source. For this unit test, we simply pass srcDir as
-    // the memoryDir for the import — the key was registered there and is still
-    // in the keyring. In production, the operator runs `secure-store init` +
-    // `unlock` on the destination with the same passphrase; the recorded KDF
-    // derives the same key because the salt is embedded in the sealed envelope.
     const importResult = await importCapsule({
       archivePath: exportResult.archivePath,
       root: dstDir,
@@ -260,6 +254,77 @@ test("exportCapsule with encrypt=true + importCapsule roundtrip restores all fil
   }
 });
 
+test("encrypted format-v2 capsule restores from passphrase without source keyring", async () => {
+  const srcDir = await makeTempDir();
+  const dstDir = await makeTempDir();
+  const outDir = await makeTempDir();
+  try {
+    await makeMemoryDir(srcDir);
+    await initAndUnlockStore(srcDir);
+
+    const exportResult = await exportCapsule({
+      name: "test-capsule-passphrase",
+      root: srcDir,
+      outDir,
+      pluginVersion: "0.0.0-test",
+      encrypt: true,
+      memoryDir: srcDir,
+      now: 1_700_000_000_500,
+    });
+
+    keyring.lockAll();
+
+    const importResult = await importCapsule({
+      archivePath: exportResult.archivePath,
+      root: dstDir,
+      mode: "skip",
+      passphrase: TEST_PASSPHRASE,
+    });
+
+    assert.equal(importResult.imported.length, 2);
+    assert.equal(importResult.skipped.length, 0);
+
+    const aContent = await readFile(path.join(dstDir, "facts", "a.md"), "utf-8");
+    assert.ok(aContent.includes("Fact A content."));
+    const bContent = await readFile(path.join(dstDir, "facts", "b.md"), "utf-8");
+    assert.ok(bContent.includes("Fact B content."));
+  } finally {
+    keyring.lockAll();
+    await rm(srcDir, { recursive: true, force: true });
+    await rm(dstDir, { recursive: true, force: true });
+    await rm(outDir, { recursive: true, force: true });
+  }
+});
+
+test("exportCapsule with encrypt=true removes plaintext archive when encryption fails", async () => {
+  const srcDir = await makeTempDir();
+  const outDir = await makeTempDir();
+  try {
+    await makeMemoryDir(srcDir);
+
+    await assert.rejects(
+      async () =>
+        exportCapsule({
+          name: "locked-capsule",
+          root: srcDir,
+          outDir,
+          pluginVersion: "0.0.0-test",
+          encrypt: true,
+          memoryDir: srcDir,
+          now: 1_700_000_000_700,
+        }),
+      /Secure-store is locked/,
+    );
+
+    const files = await readdir(outDir);
+    assert.equal(files.some((name) => name.endsWith(".capsule.json.gz")), false);
+  } finally {
+    keyring.lockAll();
+    await rm(srcDir, { recursive: true, force: true });
+    await rm(outDir, { recursive: true, force: true });
+  }
+});
+
 // ─── Test 3: import without unlocked store → clear error ─────────────────────
 
 test("importCapsule with encrypted archive and locked store throws clear error", async () => {
@@ -439,6 +504,8 @@ test("backupMemoryDir with encrypt=true and locked store throws clear error", as
       /Secure-store is locked/,
       "should surface locked error when store not unlocked",
     );
+    const files = await readdir(backupDir);
+    assert.equal(files.some((name) => name.endsWith(".backup.json.gz")), false);
   } finally {
     keyring.lockAll();
     await rm(memDir, { recursive: true, force: true });
@@ -647,6 +714,38 @@ test("backupMemoryDir excludes .secure-store and .capsules directories from encr
   }
 });
 
+test("backupMemoryDir excludes nested encrypted backup output directory", async () => {
+  const memDir = await makeTempDir();
+  try {
+    await makeMemoryDir(memDir);
+    await initAndUnlockStore(memDir);
+
+    const backupDir = path.join(memDir, "backups");
+    await mkdir(backupDir, { recursive: true });
+    await writeFile(path.join(backupDir, "old.backup.json.gz.enc"), Buffer.from("old backup"));
+
+    const encPath = await backupMemoryDir({
+      memoryDir: memDir,
+      outDir: backupDir,
+      pluginVersion: "0.0.0-test",
+      encrypt: true,
+    });
+
+    const { gzPath } = await decryptCapsuleFile({ encPath, memoryDir: memDir });
+    const gz = await readFile(gzPath);
+    const bundle = JSON.parse(gunzipSync(gz).toString("utf-8")) as {
+      records: Array<{ path: string }>;
+    };
+    const paths = bundle.records.map((record) => record.path);
+
+    assert.equal(paths.some((entry) => entry === "backups" || entry.startsWith("backups/")), false);
+    assert.equal(paths.some((entry) => entry.startsWith("facts/")), true);
+  } finally {
+    keyring.lockAll();
+    await rm(memDir, { recursive: true, force: true });
+  }
+});
+
 // ─── Test 12: exportCapsule includeTranscripts=true includes all dirs (Cursor) ─
 
 test("exportCapsule with includeTranscripts=true includes transcripts and peers dirs without dropping other dirs", async () => {

package/src/transfer/capsule-export.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { gzipSync } from "node:zlib";
 import { CAPSULE_SCHEMA_VERSION, EXPORT_FORMAT } from "./constants.js";
@@ -151,6 +151,13 @@ export async function exportCapsule(
   opts: ExportCapsuleOptions,
 ): Promise<ExportCapsuleResult> {
   validateName(opts.name);
+  if (opts.encrypt === true && !opts.memoryDir) {
+    throw new Error(
+      "exportCapsule: 'memoryDir' is required when 'encrypt' is true so the " +
+        "secure-store key can be retrieved.",
+    );
+  }
+  const encryptionMemoryDir = opts.encrypt === true ? opts.memoryDir : undefined;
   const sinceMs = parseSince(opts.since);
   const includeKinds = normalizeIncludeKinds(opts.includeKinds);
   const peerFilter = normalizePeerIds(opts.peerIds);
@@ -245,20 +252,22 @@ export async function exportCapsule(
   // Per gotcha #54: write the encrypted file before removing the plaintext so
   // a crash mid-encrypt does not destroy the only copy.
   if (opts.encrypt === true) {
-    if (!opts.memoryDir) {
-      throw new Error(
-        "exportCapsule: 'memoryDir' is required when 'encrypt' is true so the " +
-          "secure-store key can be retrieved.",
-      );
+    try {
+      const { encPath } = await encryptCapsuleFile({
+        sourceGzPath: archivePath,
+        memoryDir: encryptionMemoryDir!,
+      });
+      // Remove the plaintext only after the encrypted file was written successfully.
+      await unlink(archivePath);
+      return { archivePath: encPath, manifestPath, manifest, encryptedArchivePath: encPath };
+    } catch (error) {
+      try {
+        await unlink(archivePath);
+      } catch {
+        // Best-effort cleanup: do not leave a plaintext capsule after a failed encrypted export.
+      }
+      throw error;
     }
-    const { encPath } = await encryptCapsuleFile({
-      sourceGzPath: archivePath,
-      memoryDir: opts.memoryDir,
-    });
-    // Remove the plaintext only after the encrypted file was written successfully.
-    const { unlink } = await import("node:fs/promises");
-    await unlink(archivePath);
-    return { archivePath: encPath, manifestPath, manifest, encryptedArchivePath: encPath };
   }
 
   return { archivePath, manifestPath, manifest, encryptedArchivePath: null };

package/src/transfer/capsule-import.ts

@@ -84,6 +84,12 @@ export interface ImportCapsuleOptions {
    * When provided and the archive is NOT encrypted, the value is ignored.
    */
   memoryDir?: string;
+  /**
+   * Original secure-store passphrase for encrypted format-v2 archives. When
+   * supplied, the importer derives the archive key from the embedded KDF
+   * header, enabling restore without the source machine's unlocked keyring.
+   */
+  passphrase?: string;
 }
 
 export interface ImportCapsuleSkippedRecord {
@@ -167,14 +173,17 @@ export async function importCapsule(
   const encrypted = await isEncryptedCapsuleFile(archiveAbs);
   let raw: Buffer;
   if (encrypted) {
-    if (!opts.memoryDir) {
+    if (!opts.memoryDir && !opts.passphrase) {
       throw new Error(
         `importCapsule: archive is encrypted but 'memoryDir' was not provided. ` +
           `Pass the memory directory so the secure-store key can be retrieved, ` +
+          `provide the original passphrase for a format-v2 archive restore, ` +
           `or run \`remnic secure-store unlock\` before importing.`,
       );
     }
-    raw = await decryptCapsuleFileInMemory(archiveAbs, opts.memoryDir);
+    raw = await decryptCapsuleFileInMemory(archiveAbs, opts.memoryDir, {
+      passphrase: opts.passphrase,
+    });
   } else {
     raw = await readFile(archiveAbs);
   }

package/src/transfer/exclusions.ts

@@ -31,6 +31,13 @@ export function isTransferPathExcluded(relPosix: string, options: TransferPathEx
   if (outputRelPosix !== null) {
     if (outputRelPosix === ".") return true;
     if (relPosix === outputRelPosix || relPosix.startsWith(`${outputRelPosix}/`)) return true;
+    if (
+      relPosix === `${outputRelPosix}-wal` ||
+      relPosix === `${outputRelPosix}-shm` ||
+      relPosix === `${outputRelPosix}-journal`
+    ) {
+      return true;
+    }
   }
 
   return false;