@ekkos/cli 0.2.9 → 0.2.11

package/dist/restore/RestoreOrchestrator.js

@@ -1,12 +1,17 @@
 "use strict";
 /**
- * ekkOS Fast /continue - Restore Orchestrator
+ * ekkOS Fast /continue - Restore Orchestrator (Instance-Aware)
  *
  * Implements the 3-tier restore chain for near-zero context loss:
+ * - Tier -1: Stream log (real-time, has mid-turn content)
  * - Tier 0: Local JSONL cache (~20ms)
  * - Tier 1: Redis hot cache (~150ms)
  * - Tier 2: Supabase cold store (~500ms)
  *
+ * Per ekkOS Onboarding Spec v1.2 FINAL + ADDENDUM:
+ * - All Tier 0 cache paths MUST be: ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.jsonl
+ * - All persisted records MUST include: instanceId, sessionId, sessionName
+ *
  * Falls back through tiers on miss, tracks which tier succeeded.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -44,16 +49,17 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.restoreOrchestrator = exports.RestoreOrchestrator = void 0;
+exports.createRestoreOrchestrator = createRestoreOrchestrator;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const LocalSessionStore_js_1 = require("../cache/LocalSessionStore.js");
 const types_js_1 = require("../cache/types.js");
 const stream_tailer_js_1 = require("../capture/stream-tailer.js");
+const paths_js_1 = require("../utils/paths.js");
 // API configuration
 const MEMORY_API_URL = process.env.EKKOS_API_URL || 'https://api.ekkos.dev';
 const CONFIG_PATH = path.join(os.homedir(), '.ekkos', 'config.json');
-const STREAM_CACHE_DIR = path.join(os.homedir(), '.ekkos', 'cache', 'sessions');
 /**
  * Load auth token from config
  */
@@ -70,19 +76,31 @@ function loadAuthToken() {
     return '';
 }
 /**
- * RestoreOrchestrator - Tiered restore for /continue
+ * RestoreOrchestrator - Tiered restore for /continue (Instance-Aware)
  */
 class RestoreOrchestrator {
-    constructor() {
-        this.localStore = new LocalSessionStore_js_1.LocalSessionStore();
+    constructor(instanceId) {
+        this.instanceId = (0, paths_js_1.normalizeInstanceId)(instanceId || process.env.EKKOS_INSTANCE_ID);
+        this.localStore = (0, LocalSessionStore_js_1.createLocalSessionStore)(this.instanceId);
         this.authToken = loadAuthToken();
     }
+    /**
+     * Get the current instance ID
+     */
+    getInstanceId() {
+        return this.instanceId;
+    }
     /**
      * Main restore function - attempts tiers in order
      */
     async restore(options = {}) {
         const startTime = Date.now();
         const lastN = options.last_n || 10;
+        // Use provided instanceId or fall back to constructor instanceId
+        const instanceId = options.instance_id || this.instanceId;
+        if (instanceId !== this.instanceId) {
+            this.localStore.setInstanceId(instanceId);
+        }
         // Resolve session
         let sessionId = options.session_id;
         let sessionName = options.session_name;
@@ -105,7 +123,7 @@ class RestoreOrchestrator {
             };
         }
         // Try Tier -1: Stream log (has mid-turn content, most recent data)
-        const streamResult = await this.restoreFromStreamLog(sessionId, sessionName || '', lastN);
+        const streamResult = await this.restoreFromStreamLog(instanceId, sessionId, sessionName || '', lastN);
         if (streamResult.success && streamResult.data) {
             return {
                 ...streamResult,
@@ -113,7 +131,7 @@ class RestoreOrchestrator {
             };
         }
         // Try Tier 0: Local cache
-        const localResult = await this.restoreFromLocal(sessionId, sessionName || '', lastN);
+        const localResult = await this.restoreFromLocal(instanceId, sessionId, sessionName || '', lastN);
         if (localResult.success && localResult.data) {
             return {
                 ...localResult,
@@ -121,7 +139,7 @@ class RestoreOrchestrator {
             };
         }
         // Try Tier 1: Redis
-        const redisResult = await this.restoreFromRedis(sessionName || sessionId, lastN);
+        const redisResult = await this.restoreFromRedis(sessionName || sessionId, lastN, instanceId);
         if (redisResult.success && redisResult.data) {
             return {
                 ...redisResult,
@@ -129,7 +147,7 @@ class RestoreOrchestrator {
             };
         }
         // Try Tier 2: Supabase
-        const supabaseResult = await this.restoreFromSupabase(sessionId, lastN);
+        const supabaseResult = await this.restoreFromSupabase(sessionId, lastN, instanceId);
         if (supabaseResult.success && supabaseResult.data) {
             return {
                 ...supabaseResult,
@@ -147,12 +165,14 @@ class RestoreOrchestrator {
      * Tier -1: Restore from stream log (has mid-turn content)
      * This is checked FIRST because stream logs have the most recent data,
      * including in-progress turns that haven't been sealed yet.
+     *
+     * Checks instance-scoped path first, then legacy path as fallback.
      */
-    async restoreFromStreamLog(sessionId, sessionName, lastN) {
+    async restoreFromStreamLog(instanceId, sessionId, sessionName, lastN) {
         const startTime = Date.now();
-        // Find stream log file
-        const streamLogPath = path.join(STREAM_CACHE_DIR, `${sessionId}.stream.jsonl`);
-        if (!fs.existsSync(streamLogPath)) {
+        // Find stream log file (instance-scoped first, then legacy)
+        const streamLogFile = (0, paths_js_1.findStreamLogFile)(instanceId, sessionId);
+        if (!streamLogFile) {
             return {
                 success: false,
                 error: 'No stream log found',
@@ -161,7 +181,7 @@ class RestoreOrchestrator {
             };
         }
         try {
-            const { turns: streamTurns, latestTurnId } = await (0, stream_tailer_js_1.reconstructTurnFromEvents)(streamLogPath);
+            const { turns: streamTurns, latestTurnId } = await (0, stream_tailer_js_1.reconstructTurnFromEvents)(streamLogFile.path);
             if (streamTurns.size === 0) {
                 return {
                     success: false,
@@ -193,6 +213,9 @@ class RestoreOrchestrator {
                     tools_used: turn.tools.filter(t => t.kind === 'tool_use').map(t => t.name || 'unknown'),
                     files_referenced: [],
                     is_complete: turn.status === 'complete',
+                    instance_id: streamLogFile.isLegacy ? paths_js_1.DEFAULT_INSTANCE_ID : instanceId,
+                    session_id: sessionId,
+                    session_name: sessionName,
                 });
             }
             // Sort by turn_id
@@ -213,6 +236,7 @@ class RestoreOrchestrator {
             const payload = {
                 session_id: sessionId,
                 session_name: sessionName || 'unknown',
+                instance_id: streamLogFile.isLegacy ? paths_js_1.DEFAULT_INSTANCE_ID : instanceId,
                 source: 'stream',
                 restored_turns: restoredTurns,
                 latest: {
@@ -257,7 +281,7 @@ class RestoreOrchestrator {
     /**
      * Tier 0: Restore from local JSONL cache
      */
-    async restoreFromLocal(sessionId, sessionName, lastN) {
+    async restoreFromLocal(instanceId, sessionId, sessionName, lastN) {
         const startTime = Date.now();
         const turnsResult = this.localStore.getLastTurns(sessionId, lastN);
         if (!turnsResult.success || !turnsResult.data || turnsResult.data.length === 0) {
@@ -272,6 +296,9 @@ class RestoreOrchestrator {
         const allTurns = turnsResult.data.map((t) => ({
             ...t,
             is_complete: (0, types_js_1.isValidAssistantResponse)(t.assistant_response),
+            instance_id: t.instance_id || instanceId,
+            session_id: t.session_id || sessionId,
+            session_name: t.session_name || sessionName,
         }));
         // Separate complete turns from incomplete (pending) turns
         const completeTurns = allTurns.filter((t) => t.is_complete);
@@ -304,6 +331,7 @@ class RestoreOrchestrator {
         const payload = {
             session_id: sessionId,
             session_name: sessionName || this.localStore.getSessionName(sessionId) || 'unknown',
+            instance_id: meta?.instance_id || instanceId,
             source: 'local',
             restored_turns: turns,
             latest: {
@@ -337,7 +365,7 @@ class RestoreOrchestrator {
     /**
      * Tier 1: Restore from Redis via API
      */
-    async restoreFromRedis(sessionName, lastN) {
+    async restoreFromRedis(sessionName, lastN, instanceId) {
         const startTime = Date.now();
         if (!this.authToken) {
             return {
@@ -375,6 +403,9 @@ class RestoreOrchestrator {
                     tools_used: t.agent?.tools_used || [],
                     files_referenced: t.user?.files_referenced || [],
                     is_complete: (0, types_js_1.isValidAssistantResponse)(t.agent?.response),
+                    instance_id: t.instance_id || instanceId,
+                    session_id: data.session_id || sessionName,
+                    session_name: data.session_name || sessionName,
                 }));
                 // Separate complete turns from pending
                 const completeTurns = allTurns.filter((t) => t.is_complete);
@@ -395,6 +426,7 @@ class RestoreOrchestrator {
                 const payload = {
                     session_id: data.session_id || sessionName,
                     session_name: data.session_name || sessionName,
+                    instance_id: data.instance_id || instanceId,
                     source: 'redis',
                     restored_turns: turns,
                     latest: {
@@ -444,7 +476,7 @@ class RestoreOrchestrator {
     /**
      * Tier 2: Restore from Supabase via API
      */
-    async restoreFromSupabase(sessionId, lastN) {
+    async restoreFromSupabase(sessionId, lastN, instanceId) {
         const startTime = Date.now();
         if (!this.authToken) {
             return {
@@ -483,6 +515,9 @@ class RestoreOrchestrator {
                     tools_used: [],
                     files_referenced: c.metadata?.file_changes?.map((f) => f.path) || [],
                     is_complete: (0, types_js_1.isValidAssistantResponse)(c.assistant_response),
+                    instance_id: c.metadata?.instance_id || instanceId,
+                    session_id: sessionId,
+                    session_name: data.session_name || 'unknown',
                 }));
                 // Separate complete turns from pending
                 const completeTurns = allTurns.filter((t) => t.is_complete);
@@ -503,6 +538,7 @@ class RestoreOrchestrator {
                 const payload = {
                     session_id: sessionId,
                     session_name: data.session_name || 'unknown',
+                    instance_id: instanceId,
                     source: 'supabase',
                     restored_turns: turns,
                     latest: {
@@ -560,6 +596,7 @@ class RestoreOrchestrator {
             '<system-reminder>',
             'CONTEXT RESTORED (ekkOS /continue)',
             `Session: ${payload.session_name} (${payload.session_id})`,
+            `Instance: ${payload.instance_id || paths_js_1.DEFAULT_INSTANCE_ID}`,
             `Source: ${payload.source}${isStreamRestore ? ' (real-time stream)' : ''}`,
             isInProgress ? `Status: IN_PROGRESS (mid-turn restore)` : `Turns restored: ${payload.restored_turns.length}`,
             '',
@@ -570,7 +607,7 @@ class RestoreOrchestrator {
             if (openLoops && openLoops.length > 0) {
                 lines.push('## Open Loops (machine-derived)');
                 for (const loop of openLoops) {
-                    lines.push(`- ⚠️ ${loop.detail}`);
+                    lines.push(`- Warning: ${loop.detail}`);
                 }
                 lines.push('');
             }
@@ -585,7 +622,7 @@ class RestoreOrchestrator {
             // Special instruction for mid-turn resume
             lines.push('INSTRUCTION: Continue from the exact point shown above.');
             lines.push('Do not recap. Do not restart. Continue the sentence/action if mid-sentence.');
-            lines.push('Start your response with: "✓ Continuing -"');
+            lines.push('Start your response with: "Continuing -"');
         }
         else {
             // Standard restore format
@@ -598,7 +635,7 @@ class RestoreOrchestrator {
                 lines.push('\n[...truncated...]');
             }
             lines.push('');
-            lines.push('## Recent Turns (older → newer)');
+            lines.push('## Recent Turns (older to newer)');
             // Add turn summaries (skip last one since it's shown in detail above)
             const turnsToShow = payload.restored_turns.slice(0, -1);
             for (let i = 0; i < turnsToShow.length; i++) {
@@ -611,7 +648,7 @@ class RestoreOrchestrator {
             lines.push('');
             lines.push('INSTRUCTION: Resume seamlessly where you left off.');
             lines.push('Do not ask "what were we doing?"');
-            lines.push('Start your response with: "✓ Continuing -"');
+            lines.push('Start your response with: "Continuing -"');
         }
         lines.push('</system-reminder>');
         return lines.join('\n');
@@ -625,9 +662,14 @@ class RestoreOrchestrator {
             local_sessions: stats.session_count,
             local_turns: stats.total_turns,
             local_size_bytes: stats.cache_size_bytes,
+            instance_id: stats.instance_id,
         };
     }
 }
 exports.RestoreOrchestrator = RestoreOrchestrator;
-// Export singleton instance
+// Export factory function
+function createRestoreOrchestrator(instanceId) {
+    return new RestoreOrchestrator(instanceId);
+}
+// Export default instance using EKKOS_INSTANCE_ID from env
 exports.restoreOrchestrator = new RestoreOrchestrator();

package/dist/utils/paths.d.ts

@@ -0,0 +1,125 @@
+/**
+ * ekkOS Path Utilities - Instance-Aware Path Resolution
+ *
+ * Per ekkOS Onboarding Spec v1.2 FINAL + ADDENDUM:
+ * - All Tier 0 cache paths MUST be: ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.jsonl
+ * - All persisted records MUST include: instanceId, sessionId, sessionName
+ *
+ * This module provides canonical path helpers for the entire CLI.
+ */
+export declare const DEFAULT_INSTANCE_ID = "default";
+/**
+ * Normalize instanceId - use 'default' if empty/undefined
+ */
+export declare function normalizeInstanceId(instanceId?: string | null): string;
+/**
+ * Get the base ekkOS config directory
+ * ~/.ekkos on Unix, %USERPROFILE%\.ekkos on Windows
+ */
+export declare function getConfigDir(): string;
+/**
+ * Get the cache directory
+ * ~/.ekkos/cache
+ */
+export declare function getCacheDir(): string;
+/**
+ * Get the sessions cache directory
+ * ~/.ekkos/cache/sessions
+ */
+export declare function getSessionsDir(): string;
+/**
+ * Get the instance-scoped sessions directory
+ * ~/.ekkos/cache/sessions/{instanceId}
+ */
+export declare function getInstanceSessionsDir(instanceId?: string | null): string;
+/**
+ * Get the path to a session's turns JSONL file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.jsonl
+ */
+export declare function getTurnsPath(instanceId: string | null | undefined, sessionId: string): string;
+/**
+ * Get the path to a session's metadata file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.meta.json
+ */
+export declare function getMetaPath(instanceId: string | null | undefined, sessionId: string): string;
+/**
+ * Get the path to a session's stream log file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.stream.jsonl
+ */
+export declare function getStreamLogPath(instanceId: string | null | undefined, sessionId: string): string;
+/**
+ * Get the path to a session's state file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.state.json
+ */
+export declare function getStreamStatePath(instanceId: string | null | undefined, sessionId: string): string;
+/**
+ * Get the path to the session index file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/index.json
+ */
+export declare function getIndexPath(instanceId?: string | null): string;
+/**
+ * Get the instances directory
+ * ~/.ekkos/instances
+ */
+export declare function getInstancesDir(): string;
+/**
+ * Get the path to an instance file
+ * ~/.ekkos/instances/{instanceId}.json
+ */
+export declare function getInstanceFilePath(instanceId: string): string;
+/**
+ * Legacy path for backward compatibility (read-only fallback)
+ * ~/.ekkos/cache/sessions/{sessionId}.jsonl
+ */
+export declare function getLegacyTurnsPath(sessionId: string): string;
+/**
+ * Legacy metadata path for backward compatibility (read-only fallback)
+ * ~/.ekkos/cache/sessions/{sessionId}.meta.json
+ */
+export declare function getLegacyMetaPath(sessionId: string): string;
+/**
+ * Legacy stream log path for backward compatibility (read-only fallback)
+ * ~/.ekkos/cache/sessions/{sessionId}.stream.jsonl
+ */
+export declare function getLegacyStreamLogPath(sessionId: string): string;
+/**
+ * Ensure a directory exists (mkdirp)
+ */
+export declare function ensureDir(dirPath: string): void;
+/**
+ * Ensure the instance sessions directory exists
+ */
+export declare function ensureInstanceDir(instanceId?: string | null): string;
+/**
+ * Ensure the base ekkOS directories exist
+ */
+export declare function ensureBaseDirs(): void;
+/**
+ * List all instance directories under sessions cache
+ * Returns array of instanceIds
+ */
+export declare function listInstanceIds(): string[];
+/**
+ * Check if a file exists at the instance-scoped path
+ * If not, check legacy path and return which one exists (if any)
+ */
+export declare function findTurnsFile(instanceId: string | null | undefined, sessionId: string): {
+    path: string;
+    isLegacy: boolean;
+} | null;
+/**
+ * Check if a meta file exists at the instance-scoped path
+ * If not, check legacy path and return which one exists (if any)
+ */
+export declare function findMetaFile(instanceId: string | null | undefined, sessionId: string): {
+    path: string;
+    isLegacy: boolean;
+} | null;
+/**
+ * Check if a stream log exists at the instance-scoped path
+ * If not, check legacy path and return which one exists (if any)
+ */
+export declare function findStreamLogFile(instanceId: string | null | undefined, sessionId: string): {
+    path: string;
+    isLegacy: boolean;
+} | null;

package/dist/utils/paths.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * ekkOS Path Utilities - Instance-Aware Path Resolution
+ *
+ * Per ekkOS Onboarding Spec v1.2 FINAL + ADDENDUM:
+ * - All Tier 0 cache paths MUST be: ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.jsonl
+ * - All persisted records MUST include: instanceId, sessionId, sessionName
+ *
+ * This module provides canonical path helpers for the entire CLI.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INSTANCE_ID = void 0;
+exports.normalizeInstanceId = normalizeInstanceId;
+exports.getConfigDir = getConfigDir;
+exports.getCacheDir = getCacheDir;
+exports.getSessionsDir = getSessionsDir;
+exports.getInstanceSessionsDir = getInstanceSessionsDir;
+exports.getTurnsPath = getTurnsPath;
+exports.getMetaPath = getMetaPath;
+exports.getStreamLogPath = getStreamLogPath;
+exports.getStreamStatePath = getStreamStatePath;
+exports.getIndexPath = getIndexPath;
+exports.getInstancesDir = getInstancesDir;
+exports.getInstanceFilePath = getInstanceFilePath;
+exports.getLegacyTurnsPath = getLegacyTurnsPath;
+exports.getLegacyMetaPath = getLegacyMetaPath;
+exports.getLegacyStreamLogPath = getLegacyStreamLogPath;
+exports.ensureDir = ensureDir;
+exports.ensureInstanceDir = ensureInstanceDir;
+exports.ensureBaseDirs = ensureBaseDirs;
+exports.listInstanceIds = listInstanceIds;
+exports.findTurnsFile = findTurnsFile;
+exports.findMetaFile = findMetaFile;
+exports.findStreamLogFile = findStreamLogFile;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const fs = __importStar(require("fs"));
+// Base directories
+const HOME = os.homedir();
+const EKKOS_DIR = path.join(HOME, '.ekkos');
+const CACHE_DIR = path.join(EKKOS_DIR, 'cache');
+const SESSIONS_DIR = path.join(CACHE_DIR, 'sessions');
+const INSTANCES_DIR = path.join(EKKOS_DIR, 'instances');
+// Default instanceId when none provided (backward compatibility)
+exports.DEFAULT_INSTANCE_ID = 'default';
+/**
+ * Normalize instanceId - use 'default' if empty/undefined
+ */
+function normalizeInstanceId(instanceId) {
+    if (!instanceId || instanceId.trim() === '') {
+        return exports.DEFAULT_INSTANCE_ID;
+    }
+    return instanceId.trim();
+}
+/**
+ * Get the base ekkOS config directory
+ * ~/.ekkos on Unix, %USERPROFILE%\.ekkos on Windows
+ */
+function getConfigDir() {
+    return EKKOS_DIR;
+}
+/**
+ * Get the cache directory
+ * ~/.ekkos/cache
+ */
+function getCacheDir() {
+    return CACHE_DIR;
+}
+/**
+ * Get the sessions cache directory
+ * ~/.ekkos/cache/sessions
+ */
+function getSessionsDir() {
+    return SESSIONS_DIR;
+}
+/**
+ * Get the instance-scoped sessions directory
+ * ~/.ekkos/cache/sessions/{instanceId}
+ */
+function getInstanceSessionsDir(instanceId) {
+    const normalizedId = normalizeInstanceId(instanceId);
+    return path.join(SESSIONS_DIR, normalizedId);
+}
+/**
+ * Get the path to a session's turns JSONL file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.jsonl
+ */
+function getTurnsPath(instanceId, sessionId) {
+    const instanceDir = getInstanceSessionsDir(instanceId);
+    return path.join(instanceDir, `${sessionId}.jsonl`);
+}
+/**
+ * Get the path to a session's metadata file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.meta.json
+ */
+function getMetaPath(instanceId, sessionId) {
+    const instanceDir = getInstanceSessionsDir(instanceId);
+    return path.join(instanceDir, `${sessionId}.meta.json`);
+}
+/**
+ * Get the path to a session's stream log file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.stream.jsonl
+ */
+function getStreamLogPath(instanceId, sessionId) {
+    const instanceDir = getInstanceSessionsDir(instanceId);
+    return path.join(instanceDir, `${sessionId}.stream.jsonl`);
+}
+/**
+ * Get the path to a session's state file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/{sessionId}.state.json
+ */
+function getStreamStatePath(instanceId, sessionId) {
+    const instanceDir = getInstanceSessionsDir(instanceId);
+    return path.join(instanceDir, `${sessionId}.state.json`);
+}
+/**
+ * Get the path to the session index file (instance-scoped)
+ * ~/.ekkos/cache/sessions/{instanceId}/index.json
+ */
+function getIndexPath(instanceId) {
+    const instanceDir = getInstanceSessionsDir(instanceId);
+    return path.join(instanceDir, 'index.json');
+}
+/**
+ * Get the instances directory
+ * ~/.ekkos/instances
+ */
+function getInstancesDir() {
+    return INSTANCES_DIR;
+}
+/**
+ * Get the path to an instance file
+ * ~/.ekkos/instances/{instanceId}.json
+ */
+function getInstanceFilePath(instanceId) {
+    return path.join(INSTANCES_DIR, `${instanceId}.json`);
+}
+/**
+ * Legacy path for backward compatibility (read-only fallback)
+ * ~/.ekkos/cache/sessions/{sessionId}.jsonl
+ */
+function getLegacyTurnsPath(sessionId) {
+    return path.join(SESSIONS_DIR, `${sessionId}.jsonl`);
+}
+/**
+ * Legacy metadata path for backward compatibility (read-only fallback)
+ * ~/.ekkos/cache/sessions/{sessionId}.meta.json
+ */
+function getLegacyMetaPath(sessionId) {
+    return path.join(SESSIONS_DIR, `${sessionId}.meta.json`);
+}
+/**
+ * Legacy stream log path for backward compatibility (read-only fallback)
+ * ~/.ekkos/cache/sessions/{sessionId}.stream.jsonl
+ */
+function getLegacyStreamLogPath(sessionId) {
+    return path.join(SESSIONS_DIR, `${sessionId}.stream.jsonl`);
+}
+/**
+ * Ensure a directory exists (mkdirp)
+ */
+function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Ensure the instance sessions directory exists
+ */
+function ensureInstanceDir(instanceId) {
+    const instanceDir = getInstanceSessionsDir(instanceId);
+    ensureDir(instanceDir);
+    return instanceDir;
+}
+/**
+ * Ensure the base ekkOS directories exist
+ */
+function ensureBaseDirs() {
+    ensureDir(EKKOS_DIR);
+    ensureDir(CACHE_DIR);
+    ensureDir(SESSIONS_DIR);
+    ensureDir(INSTANCES_DIR);
+}
+/**
+ * List all instance directories under sessions cache
+ * Returns array of instanceIds
+ */
+function listInstanceIds() {
+    ensureDir(SESSIONS_DIR);
+    try {
+        const entries = fs.readdirSync(SESSIONS_DIR, { withFileTypes: true });
+        return entries
+            .filter(e => e.isDirectory())
+            .map(e => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check if a file exists at the instance-scoped path
+ * If not, check legacy path and return which one exists (if any)
+ */
+function findTurnsFile(instanceId, sessionId) {
+    // Try instance-scoped path first
+    const instancePath = getTurnsPath(instanceId, sessionId);
+    if (fs.existsSync(instancePath)) {
+        return { path: instancePath, isLegacy: false };
+    }
+    // Try legacy path as fallback (read-only)
+    const legacyPath = getLegacyTurnsPath(sessionId);
+    if (fs.existsSync(legacyPath)) {
+        return { path: legacyPath, isLegacy: true };
+    }
+    return null;
+}
+/**
+ * Check if a meta file exists at the instance-scoped path
+ * If not, check legacy path and return which one exists (if any)
+ */
+function findMetaFile(instanceId, sessionId) {
+    // Try instance-scoped path first
+    const instancePath = getMetaPath(instanceId, sessionId);
+    if (fs.existsSync(instancePath)) {
+        return { path: instancePath, isLegacy: false };
+    }
+    // Try legacy path as fallback (read-only)
+    const legacyPath = getLegacyMetaPath(sessionId);
+    if (fs.existsSync(legacyPath)) {
+        return { path: legacyPath, isLegacy: true };
+    }
+    return null;
+}
+/**
+ * Check if a stream log exists at the instance-scoped path
+ * If not, check legacy path and return which one exists (if any)
+ */
+function findStreamLogFile(instanceId, sessionId) {
+    // Try instance-scoped path first
+    const instancePath = getStreamLogPath(instanceId, sessionId);
+    if (fs.existsSync(instancePath)) {
+        return { path: instancePath, isLegacy: false };
+    }
+    // Try legacy path as fallback (read-only)
+    const legacyPath = getLegacyStreamLogPath(sessionId);
+    if (fs.existsSync(legacyPath)) {
+        return { path: legacyPath, isLegacy: true };
+    }
+    return null;
+}