@remnic/core 9.3.644 → 9.3.646

package/dist/session-identity.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared session-identity / transcript-pathing layer (issue #1496).
+ *
+ * This module is the SINGLE source of truth for turning a `sessionKey` into a
+ * channel identity and a set of deterministic, collision-resistant storage
+ * paths. Every subsystem that previously re-parsed session keys (transcript
+ * pathing, tool-usage pathing, hourly summaries, session auditing, conversation
+ * indexing) MUST route through `parseSessionIdentity()` / `sessionStoragePaths()`
+ * so behavior stays identical across paths (rule #22, #39).
+ *
+ * Two shapes are recognized:
+ *
+ *   1. Legacy `agent:<agentId>:<channelType>:...` keys keep their existing
+ *      readable channel identity:
+ *        - agent:<id>:main                      → type="main",    id="default"
+ *        - agent:<id>:discord:channel:<chanId>  → type="discord", id="<chanId>"
+ *        - agent:<id>:slack:channel:<chanId>    → type="slack",   id="<chanId>"
+ *        - agent:<id>:cron:<jobId>              → type="cron",    id="<jobId>"
+ *        - agent:<id>:<other>[:<id>]            → type="<other>", id="<id?>"
+ *
+ *   2. Arbitrary / non-legacy keys (e.g. `pi-geek:abc123`) become first-class
+ *      from the FIRST write — they NEVER start life under `other/default`:
+ *        channelType = "session"
+ *        channelId   = storagePathHash(sessionKey)   (collision-resistant)
+ *      yielding `transcripts/session/<hash>/YYYY-MM-DD.jsonl`.
+ *
+ * The reserved `"session"` channel type is what makes arbitrary keys isolated
+ * and auditable. Legacy data under `other/default` (and any legacy channel
+ * directory) remains READABLE via `legacyDir` / `alternateDir` candidates.
+ */
+/** Channel type reserved for first-class arbitrary (non-legacy) session keys. */
+declare const SESSION_CHANNEL_TYPE = "session";
+/** Legacy fallback channel identity for un-parseable keys (read-back only). */
+declare const LEGACY_FALLBACK_CHANNEL_TYPE = "other";
+declare const LEGACY_FALLBACK_CHANNEL_ID = "default";
+interface SessionIdentity {
+    /** Channel type — legacy channel type for known shapes, else `"session"`. */
+    channelType: string;
+    /** Channel id — legacy channel id for known shapes, else the key hash. */
+    channelId: string;
+    /** Human-readable, non-authoritative label derived from the raw key. */
+    displayLabel: string;
+    /** The original session key, unchanged. */
+    canonicalSessionKey: string;
+    /** True when the key matched a known legacy `agent:<id>:...` shape. */
+    legacy: boolean;
+}
+interface SessionStoragePaths {
+    /** Channel type (mirrors {@link SessionIdentity.channelType}). */
+    channelType: string;
+    /** Channel id (mirrors {@link SessionIdentity.channelId}). */
+    channelId: string;
+    /** Primary encoded storage subdirectory: `<encodedType>/<encodedId>`. */
+    dir: string;
+    /**
+     * Collision-resistant alternate subdirectory that always embeds the full
+     * session-key hash. Used both as a write-time collision escape hatch and as a
+     * read-back candidate for data written before this layer existed.
+     */
+    alternateDir: string;
+    /**
+     * Un-encoded `<type>/<id>` directory for reading data written by older
+     * builds that did not URL-encode path segments. Undefined when it would be
+     * identical to `dir` or when either segment is path-unsafe.
+     */
+    legacyDir?: string;
+    /**
+     * Ordered, de-duplicated list of READ-BACK-ONLY directories where an older
+     * build may have stranded this key's data. NEW writes never target these —
+     * they exist purely so pre-#1496 transcripts/tool-usage stay discoverable
+     * (and migratable). Populated only for non-legacy keys. Includes:
+     *   1. the shared `other/default` fallback (every arbitrary key landed here);
+     *   2. the directory the OLD `parts.length >= 3` parser would have chosen
+     *      (e.g. `foo:bar:baz` → `baz/default`, `foo:bar:baz:qux` → `baz/qux`).
+     * See {@link legacyParserReadbackDir}.
+     */
+    readbackDirs: string[];
+}
+/**
+ * Parse a session key into a stable channel identity.
+ *
+ * Pure and deterministic — no filesystem access. Same input always yields the
+ * same identity, which is what makes arbitrary keys collision-resistant from
+ * the first write.
+ */
+declare function parseSessionIdentity(sessionKey: string): SessionIdentity;
+/**
+ * Resolve the storage path pieces for a session key. Wraps
+ * {@link parseSessionIdentity} so transcript, tool-usage, and summary writers
+ * share one implementation (rule #22).
+ */
+declare function sessionStoragePaths(sessionKey: string): SessionStoragePaths;
+/**
+ * The shared `other/default` directory every arbitrary key was routed into by
+ * builds predating issue #1496. Exposed so transcript/tool-usage/summary read
+ * paths and the migration scanner all agree on the same fallback location.
+ */
+declare const OTHER_DEFAULT_READBACK_DIR: string;
+/**
+ * Reconstruct the transcript/tool-usage directory the OLD `getTranscriptPath`
+ * parser (pre-#1496) would have produced for a key the NEW parser reclassifies
+ * as a first-class `session/<hash>` identity.
+ *
+ * The OLD parser treated ANY key with `parts.length >= 3` as legacy — it did
+ * NOT require a leading `agent` segment — so an arbitrary key like
+ * `foo:bar:baz` was stored under `baz/default` and `foo:bar:baz:qux` under
+ * `baz/qux`. Those directories must stay readable (and migratable) for existing
+ * installs even though the key now writes to `session/<hash>` (Thread B / codex
+ * review on PR #1504). Path segments are encoded exactly as the old `dir` was
+ * built (`encodeStoragePathSegment`) so the candidate matches the bytes on disk.
+ *
+ * Returns `undefined` when the key has fewer than three colon parts (the old
+ * parser would have used the `other/default` fallback, already covered), when
+ * the channel type is empty, or when the result is unsafe.
+ */
+declare function legacyParserReadbackDir(sessionKey: string): string | undefined;
+
+export { LEGACY_FALLBACK_CHANNEL_ID, LEGACY_FALLBACK_CHANNEL_TYPE, OTHER_DEFAULT_READBACK_DIR, SESSION_CHANNEL_TYPE, type SessionIdentity, type SessionStoragePaths, legacyParserReadbackDir, parseSessionIdentity, sessionStoragePaths };

package/dist/session-identity.js

@@ -0,0 +1,21 @@
+import {
+  LEGACY_FALLBACK_CHANNEL_ID,
+  LEGACY_FALLBACK_CHANNEL_TYPE,
+  OTHER_DEFAULT_READBACK_DIR,
+  SESSION_CHANNEL_TYPE,
+  legacyParserReadbackDir,
+  parseSessionIdentity,
+  sessionStoragePaths
+} from "./chunk-S4DDLTPX.js";
+import "./chunk-FF4KLI5W.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  LEGACY_FALLBACK_CHANNEL_ID,
+  LEGACY_FALLBACK_CHANNEL_TYPE,
+  OTHER_DEFAULT_READBACK_DIR,
+  SESSION_CHANNEL_TYPE,
+  legacyParserReadbackDir,
+  parseSessionIdentity,
+  sessionStoragePaths
+};
+//# sourceMappingURL=session-identity.js.map

package/dist/session-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/session-transcript-migration.d.ts

@@ -0,0 +1,65 @@
+interface SessionMigrationEntryGroup {
+    /** The distinct session key these lines belong to. */
+    sessionKey: string;
+    /** Whether this key is a recognized legacy `agent:<id>:...` shape. */
+    legacy: boolean;
+    /** Destination directory (relative to the transcripts root). */
+    destDir: string;
+    /** Number of JSONL entries that will move. */
+    entryCount: number;
+}
+interface SessionMigrationFilePlan {
+    /** Source file path (relative to transcripts root). */
+    sourceRelPath: string;
+    /** The date-stamped file name (e.g. `2026-06-29.jsonl`). */
+    fileName: string;
+    /** Distinct session groups discovered inside this source file. */
+    groups: SessionMigrationEntryGroup[];
+    /** Lines that could not be parsed as JSON or lacked a sessionKey. */
+    unmovableLines: number;
+    /**
+     * True when EVERY entry in the file already belongs in the source directory
+     * (nothing to do). Such files are skipped.
+     */
+    alreadyHomed: boolean;
+}
+interface SessionMigrationPlan {
+    generatedAt: string;
+    dryRun: boolean;
+    transcriptsDir: string;
+    /** Per-file plans that have at least one entry to move. */
+    files: SessionMigrationFilePlan[];
+    /** Distinct destination session keys across all files. */
+    distinctSessions: number;
+    /** Total entries that will be re-homed. */
+    movedEntries: number;
+}
+interface SessionMigrationResult {
+    plan: SessionMigrationPlan;
+    applied: boolean;
+    filesRewritten: number;
+    filesRemoved: number;
+    errors: string[];
+    manifestPath?: string;
+}
+interface MigrateSessionTranscriptsOptions {
+    /** The memory directory root (transcripts live under `<memoryDir>/transcripts`). */
+    memoryDir: string;
+    /** When true, perform the migration; otherwise produce a dry-run plan only. */
+    apply?: boolean;
+}
+/**
+ * Compute the migration plan without modifying anything.
+ */
+declare function planSessionTranscriptMigration(options: MigrateSessionTranscriptsOptions): Promise<SessionMigrationPlan>;
+/**
+ * Run the migration. Dry-run by default; pass `apply: true` to mutate.
+ */
+declare function migrateSessionTranscripts(options: MigrateSessionTranscriptsOptions): Promise<SessionMigrationResult>;
+/** Best-effort byte-size summary for reporting (used by CLI output). */
+declare function summarizeMigrationSources(memoryDir: string): Promise<{
+    files: number;
+    bytes: number;
+}>;
+
+export { type MigrateSessionTranscriptsOptions, type SessionMigrationEntryGroup, type SessionMigrationFilePlan, type SessionMigrationPlan, type SessionMigrationResult, migrateSessionTranscripts, planSessionTranscriptMigration, summarizeMigrationSources };

package/dist/session-transcript-migration.js

@@ -0,0 +1,16 @@
+import {
+  migrateSessionTranscripts,
+  planSessionTranscriptMigration,
+  summarizeMigrationSources
+} from "./chunk-EVWIEEKZ.js";
+import "./chunk-S4DDLTPX.js";
+import "./chunk-FF4KLI5W.js";
+import "./chunk-6KYMPV2O.js";
+import "./chunk-2ODBA7MQ.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  migrateSessionTranscripts,
+  planSessionTranscriptMigration,
+  summarizeMigrationSources
+};
+//# sourceMappingURL=session-transcript-migration.js.map

package/dist/session-transcript-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/storage.js

@@ -9,7 +9,7 @@ import {
   parseEntityFile,
   serializeEntityFile,
   stripAttributesSuffix
-} from "./chunk-GYITUZFT.js";
+} from "./chunk-A4BTPHIN.js";
 import "./chunk-M7XQSUBB.js";
 import "./chunk-5UZXUTVO.js";
 import "./chunk-J6A3CX5N.js";

package/dist/summarizer.js

@@ -1,9 +1,10 @@
 import {
   HourlySummarizer
-} from "./chunk-Y2XKJJEI.js";
+} from "./chunk-IMWFHBG2.js";
 import "./chunk-XJNBEDFE.js";
 import "./chunk-XZ4WBBB5.js";
 import "./chunk-H3HDXD3U.js";
+import "./chunk-S4DDLTPX.js";
 import "./chunk-A3BS64GV.js";
 import "./chunk-B5XMS73R.js";
 import "./chunk-7SI52C65.js";

package/dist/transcript.d.ts

@@ -26,13 +26,17 @@ declare class TranscriptManager {
     private static readonly CHARS_PER_TOKEN;
     constructor(config: PluginConfig);
     /**
-     * Parse a sessionKey to extract channel type and ID.
+     * Resolve the storage path pieces for a sessionKey via the shared
+     * {@link sessionStoragePaths} helper (issue #1496, rule #22).
      *
-     * SessionKey patterns:
-     *   - agent:<agent-id>:main → type="main", id="default"
-     *   - agent:<agent-id>:discord:channel:<channel-id> → type="discord", id="<channel-id>"
-     *   - agent:<agent-id>:cron:<job-id> → type="cron", id="<job-id>"
-     *   - agent:<agent-id>:slack:channel:<channel-id> → type="slack", id="<channel-id>"
+     * Legacy `agent:<id>:...` shapes keep their existing readable channel paths.
+     * Arbitrary / non-legacy keys (e.g. `pi-geek:abc123`) route to
+     * `transcripts/session/<hash>/YYYY-MM-DD.jsonl` from the FIRST write — they
+     * never start life in `other/default`. For those keys a list of
+     * read-back-only `readbackDirs` is returned so data written by older builds
+     * (under `other/default`, or under an old `parts.length >= 3` directory such
+     * as `baz/default`) stays discoverable until migrated. New writes never
+     * target read-back dirs. See `session-identity.ts`.
      *
      * @returns Object with raw channel identifiers and encoded storage path pieces.
      */
@@ -43,6 +47,7 @@ declare class TranscriptManager {
         channelId: string;
         alternateDir: string;
         legacyDir?: string;
+        readbackDirs: string[];
     };
     /**
      * Initialize the transcript manager by ensuring directories exist.
@@ -59,6 +64,7 @@ declare class TranscriptManager {
         file: string;
         alternateDir: string;
         legacyDir?: string;
+        readbackDirs: string[];
     };
     private selectStorageDirForWrite;
     private directorySessionStatus;

package/dist/transcript.js

@@ -1,6 +1,7 @@
 import {
   TranscriptManager
-} from "./chunk-IHG27THY.js";
+} from "./chunk-JLOJ5RJ7.js";
+import "./chunk-S4DDLTPX.js";
 import "./chunk-KFY3SGN7.js";
 import "./chunk-FF4KLI5W.js";
 import "./chunk-2ODBA7MQ.js";

package/dist/transfer/backup.js

@@ -1,8 +1,8 @@
 import {
   backupMemoryDir
-} from "../chunk-BXLOS5AJ.js";
+} from "../chunk-OWHERGF2.js";
 import "../chunk-765K3SAT.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-UVYI6VIX.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";

package/dist/transfer/capsule-export.js

@@ -1,9 +1,9 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-VDX2J7OX.js";
+} from "../chunk-BUKK5SWA.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-UVYI6VIX.js";
 import "../chunk-J4EB7DNW.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";

package/dist/transfer/capsule-import.js

@@ -1,9 +1,9 @@
 import {
   importCapsule
-} from "../chunk-DGNQRNLL.js";
+} from "../chunk-NT5TINK5.js";
 import "../chunk-ALEPI75L.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-DQEMWVMT.js";
+import "../chunk-UVYI6VIX.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";

package/dist/transfer/import-sqlite.js

@@ -1,8 +1,8 @@
 import {
   importSqlite
-} from "../chunk-AGNBY3VG.js";
-import "../chunk-Z734BLO3.js";
+} from "../chunk-APJQ6UEA.js";
 import "../chunk-G4IAEX6D.js";
+import "../chunk-Z734BLO3.js";
 import "../chunk-6KYMPV2O.js";
 import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";

package/dist/transfer/types.d.ts

@@ -313,13 +313,13 @@ declare const CapsuleBlockSchema: z.ZodObject<{
         peerProfiles: boolean;
     }>;
 }, "strip", z.ZodTypeAny, {
+    schemaVersion: string;
     includes: {
         procedural: boolean;
         taxonomy: boolean;
         identityAnchors: boolean;
         peerProfiles: boolean;
     };
-    schemaVersion: string;
     id: string;
     description: string;
     version: string;
@@ -334,13 +334,13 @@ declare const CapsuleBlockSchema: z.ZodObject<{
         directAnswerEnabled: boolean;
     };
 }, {
+    schemaVersion: string;
     includes: {
         procedural: boolean;
         taxonomy: boolean;
         identityAnchors: boolean;
         peerProfiles: boolean;
     };
-    schemaVersion: string;
     id: string;
     description: string;
     version: string;
@@ -464,13 +464,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
             peerProfiles: boolean;
         }>;
     }, "strip", z.ZodTypeAny, {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
@@ -485,13 +485,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
             directAnswerEnabled: boolean;
         };
     }, {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
@@ -518,13 +518,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
     pluginVersion: string;
     includesTranscripts: boolean;
     capsule: {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
@@ -551,13 +551,13 @@ declare const ExportManifestV2Schema: z.ZodObject<{
     pluginVersion: string;
     includesTranscripts: boolean;
     capsule: {
+        schemaVersion: string;
         includes: {
             procedural: boolean;
             taxonomy: boolean;
             identityAnchors: boolean;
             peerProfiles: boolean;
         };
-        schemaVersion: string;
         id: string;
         description: string;
         version: string;
@@ -683,13 +683,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
                 peerProfiles: boolean;
             }>;
         }, "strip", z.ZodTypeAny, {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -704,13 +704,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
                 directAnswerEnabled: boolean;
             };
         }, {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -737,13 +737,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -770,13 +770,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -815,13 +815,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;
@@ -854,13 +854,13 @@ declare const ExportBundleV2Schema: z.ZodObject<{
         pluginVersion: string;
         includesTranscripts: boolean;
         capsule: {
+            schemaVersion: string;
             includes: {
                 procedural: boolean;
                 taxonomy: boolean;
                 identityAnchors: boolean;
                 peerProfiles: boolean;
             };
-            schemaVersion: string;
             id: string;
             description: string;
             version: string;

package/dist/verified-recall.js

@@ -1,8 +1,8 @@
 import {
   searchVerifiedEpisodes
-} from "./chunk-4HYLRROV.js";
+} from "./chunk-UMKPSD35.js";
 import "./chunk-HQ6NIBL6.js";
-import "./chunk-GYITUZFT.js";
+import "./chunk-A4BTPHIN.js";
 import "./chunk-M7XQSUBB.js";
 import "./chunk-5UZXUTVO.js";
 import "./chunk-J6A3CX5N.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.3.644",
+  "version": "9.3.646",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",

package/src/cli.ts

@@ -202,6 +202,10 @@ import {
   type SessionRepairApplyResult,
   type SessionRepairPlan,
 } from "./session-integrity.js";
+import {
+  migrateSessionTranscripts,
+  planSessionTranscriptMigration,
+} from "./session-transcript-migration.js";
 import type { TierMigrationCycleSummary, TierMigrationStatusSnapshot } from "./recall-state.js";
 import {
   readRuntimePolicySnapshot as readPolicyRuntimeSnapshot,
@@ -8650,6 +8654,81 @@ export function registerCli(
           }
         });
 
+      // ── Sessions subcommand (issue #1496) ───────────────────────────────
+      const sessionsCmd = cmd
+        .command("sessions")
+        .description("Inspect and migrate session transcript storage");
+
+      sessionsCmd
+        .command("migrate-transcripts")
+        .description(
+          "Split conflated other/default transcripts into first-class session/<hash> dirs",
+        )
+        .option("--dry-run", "Report the migration plan without moving files (default)")
+        .option("--apply", "Apply the migration (move files; default is dry-run)")
+        .action(async (...args: unknown[]) => {
+          const options = (args[0] ?? {}) as Record<string, unknown>;
+          const dryRunFlag = options.dryRun === true;
+          const applyFlag = options.apply === true;
+
+          // Rule #51: reject contradictory flags rather than silently picking one.
+          if (dryRunFlag && applyFlag) {
+            console.error("Cannot pass both --dry-run and --apply. Choose one.");
+            process.exit(1);
+          }
+
+          // Safe default: dry-run when neither flag is given.
+          const apply = applyFlag;
+          const memoryDir = orchestrator.config.memoryDir;
+
+          if (!apply) {
+            const plan = await planSessionTranscriptMigration({ memoryDir });
+            console.log("=== Session Transcript Migration (DRY RUN) ===\n");
+            if (!dryRunFlag && !applyFlag) {
+              console.log("No flag given — defaulting to --dry-run. Pass --apply to migrate.\n");
+            }
+            console.log(`transcripts dir: ${plan.transcriptsDir}`);
+            console.log(`files to migrate: ${plan.files.length}`);
+            console.log(`distinct sessions: ${plan.distinctSessions}`);
+            console.log(`entries to move: ${plan.movedEntries}`);
+            if (plan.files.length > 0) {
+              console.log("\nPlanned splits:");
+              for (const file of plan.files) {
+                console.log(`- ${file.sourceRelPath}`);
+                for (const group of file.groups) {
+                  console.log(
+                    `    ${group.entryCount} entr${group.entryCount === 1 ? "y" : "ies"} → ${group.destDir} (${group.legacy ? "legacy" : "session"})`,
+                  );
+                }
+                if (file.unmovableLines > 0) {
+                  console.log(`    ${file.unmovableLines} unmovable line(s) retained in source`);
+                }
+              }
+            }
+            console.log("\nDRY RUN — no files changed.");
+            return;
+          }
+
+          const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+          console.log("=== Session Transcript Migration (APPLY) ===\n");
+          console.log(`files rewritten: ${result.filesRewritten}`);
+          console.log(`files removed: ${result.filesRemoved}`);
+          console.log(`distinct sessions: ${result.plan.distinctSessions}`);
+          console.log(`entries moved: ${result.plan.movedEntries}`);
+          if (result.manifestPath) {
+            console.log(`manifest: ${result.manifestPath}`);
+          }
+          if (result.errors.length > 0) {
+            console.log("\nErrors:");
+            for (const err of result.errors) {
+              console.log(`- ${err}`);
+            }
+            process.exitCode = 1;
+            return;
+          }
+          console.log("\nOK");
+        });
+
       // Checkpoint command
       cmd
         .command("checkpoint")

package/src/index.ts

@@ -324,6 +324,24 @@ export { MeilisearchBackend } from "./search/meilisearch-backend.js";
 export { buildEntityRecallSection } from "./entity-retrieval.js";
 export { resolvePrincipal } from "./namespaces/principal.js";
 
+// ---------------------------------------------------------------------------
+// Session identity / transcript pathing (issue #1496)
+// ---------------------------------------------------------------------------
+
+// Shared, deterministic session-key → storage-path resolution. Exported so
+// downstream consumers (the @remnic/bench adapter + its tests, host adapters)
+// resolve transcript directories through the SAME layer the core writer uses
+// instead of hard-coding `other/default` (rule #20, #22, #26).
+export {
+  SESSION_CHANNEL_TYPE,
+  parseSessionIdentity,
+  sessionStoragePaths,
+  legacyParserReadbackDir,
+  type SessionIdentity,
+  type SessionStoragePaths,
+} from "./session-identity.js";
+export { storagePathHash } from "./storage-paths.js";
+
 // ---------------------------------------------------------------------------
 // Trust zones
 // ---------------------------------------------------------------------------