@ekkos/cli 0.2.8 → 0.2.10

package/dist/cache/LocalSessionStore.d.ts

@@ -1,39 +1,41 @@
 /**
- * ekkOS Fast /continue - Local Session Store
+ * ekkOS Fast /continue - Local Session Store (Instance-Aware)
  *
  * Tier 0 of the 3-tier restore chain.
  * Provides ultra-low latency (<20ms) turn storage using append-only JSONL files.
  *
+ * 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
+ * - Backward compatibility: missing instanceId treated as 'default'
+ *
  * Features:
+ * - Instance-scoped storage (prevents multi-session cross-talk)
  * - Atomic writes (write to .tmp, rename)
  * - Crash recovery (handle partial JSONL lines)
  * - ACK-based safe pruning
  * - Multi-session support with LRU eviction
+ * - Legacy path fallback for reads (backward compatibility)
  */
 import { Turn, SessionMeta, LocalCacheConfig, SessionListEntry, CacheResult } from './types.js';
 /**
- * LocalSessionStore - Fast local cache for conversation turns
+ * LocalSessionStore - Fast local cache for conversation turns (Instance-Aware)
  */
 export declare class LocalSessionStore {
     private config;
-    private sessionsDir;
-    private indexPath;
+    private instanceId;
     private indexCache;
     private indexCacheTime;
     private readonly INDEX_CACHE_TTL;
-    constructor(config?: Partial<LocalCacheConfig>);
-    /**
-     * Ensure cache directories exist
-     */
-    private ensureDirectories;
+    constructor(config?: Partial<LocalCacheConfig>, instanceId?: string);
     /**
-     * Get the JSONL file path for a session
+     * Get the current instance ID
      */
-    private getTurnsPath;
+    getInstanceId(): string;
     /**
-     * Get the metadata file path for a session
+     * Set the instance ID (useful for switching contexts)
      */
-    private getMetaPath;
+    setInstanceId(instanceId: string): void;
     /**
      * Read the session index (with caching)
      */
@@ -47,21 +49,24 @@ export declare class LocalSessionStore {
      */
     private updateIndexEntry;
     /**
-     * Read session metadata
+     * Read session metadata (checks instance path, then legacy path)
      */
     getSessionMeta(sessionId: string): SessionMeta | null;
     /**
-     * Write session metadata atomically
+     * Write session metadata atomically (always to instance-scoped path)
      */
     private writeSessionMeta;
     /**
      * Append a turn to the session's JSONL file
      * This is the hot path - must be fast
+     *
+     * Per v1.2 ADDENDUM: All records include instanceId, sessionId, sessionName
      */
     appendTurn(sessionId: string, sessionName: string, turn: Turn, projectPath?: string): CacheResult<void>;
     /**
      * Get the last N turns from a session
      * Handles crash recovery (partial lines)
+     * Checks instance path first, then legacy path as read-only fallback
      */
     getLastTurns(sessionId: string, n?: number): CacheResult<Turn[]>;
     /**
@@ -89,19 +94,25 @@ export declare class LocalSessionStore {
      */
     prune(sessionId: string): CacheResult<number>;
     /**
-     * List all sessions, sorted by last active (newest first)
+     * List all sessions for current instance, sorted by last active (newest first)
      */
     listSessions(): SessionListEntry[];
     /**
-     * Get session ID from session name
+     * List all sessions across ALL instances (for global queries)
+     */
+    listAllSessions(): Array<SessionListEntry & {
+        instance_id: string;
+    }>;
+    /**
+     * Get session ID from session name (searches current instance)
      */
     getSessionId(sessionName: string): string | null;
     /**
-     * Get session name from session ID
+     * Get session name from session ID (searches current instance)
      */
     getSessionName(sessionId: string): string | null;
     /**
-     * Check if a session exists in local cache
+     * Check if a session exists in local cache (current instance or legacy)
      */
     hasSession(sessionIdOrName: string): boolean;
     /**
@@ -114,16 +125,18 @@ export declare class LocalSessionStore {
      */
     evictOldSessions(): number;
     /**
-     * Get cache statistics
+     * Get cache statistics for current instance
      */
     getStats(): {
         session_count: number;
         total_turns: number;
         cache_size_bytes: number;
+        instance_id: string;
     };
     /**
-     * Clear all local cache (use with caution)
+     * Clear all local cache for current instance (use with caution)
      */
     clearAll(): void;
 }
+export declare function createLocalSessionStore(instanceId?: string): LocalSessionStore;
 export declare const localCache: LocalSessionStore;

package/dist/cache/LocalSessionStore.js

@@ -1,15 +1,22 @@
 "use strict";
 /**
- * ekkOS Fast /continue - Local Session Store
+ * ekkOS Fast /continue - Local Session Store (Instance-Aware)
  *
  * Tier 0 of the 3-tier restore chain.
  * Provides ultra-low latency (<20ms) turn storage using append-only JSONL files.
  *
+ * 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
+ * - Backward compatibility: missing instanceId treated as 'default'
+ *
  * Features:
+ * - Instance-scoped storage (prevents multi-session cross-talk)
  * - Atomic writes (write to .tmp, rename)
  * - Crash recovery (handle partial JSONL lines)
  * - ACK-based safe pruning
  * - Multi-session support with LRU eviction
+ * - Legacy path fallback for reads (backward compatibility)
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -46,9 +53,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.localCache = exports.LocalSessionStore = void 0;
+exports.createLocalSessionStore = createLocalSessionStore;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
+const paths_js_1 = require("../utils/paths.js");
 // Default configuration
 const DEFAULT_CONFIG = {
     cache_dir: path.join(os.homedir(), '.ekkos', 'cache'),
@@ -58,40 +67,31 @@ const DEFAULT_CONFIG = {
     flush_interval_ms: 5000,
 };
 /**
- * LocalSessionStore - Fast local cache for conversation turns
+ * LocalSessionStore - Fast local cache for conversation turns (Instance-Aware)
  */
 class LocalSessionStore {
-    constructor(config = {}) {
+    constructor(config = {}, instanceId) {
         this.indexCache = null;
         this.indexCacheTime = 0;
         this.INDEX_CACHE_TTL = 1000; // 1 second
         this.config = { ...DEFAULT_CONFIG, ...config };
-        this.sessionsDir = path.join(this.config.cache_dir, 'sessions');
-        this.indexPath = path.join(this.sessionsDir, 'index.json');
-        this.ensureDirectories();
+        this.instanceId = (0, paths_js_1.normalizeInstanceId)(instanceId || process.env.EKKOS_INSTANCE_ID);
+        (0, paths_js_1.ensureBaseDirs)();
+        (0, paths_js_1.ensureInstanceDir)(this.instanceId);
     }
     /**
-     * Ensure cache directories exist
+     * Get the current instance ID
      */
-    ensureDirectories() {
-        try {
-            fs.mkdirSync(this.sessionsDir, { recursive: true });
-        }
-        catch (err) {
-            // Directory might already exist
-        }
+    getInstanceId() {
+        return this.instanceId;
     }
     /**
-     * Get the JSONL file path for a session
+     * Set the instance ID (useful for switching contexts)
      */
-    getTurnsPath(sessionId) {
-        return path.join(this.sessionsDir, `${sessionId}.jsonl`);
-    }
-    /**
-     * Get the metadata file path for a session
-     */
-    getMetaPath(sessionId) {
-        return path.join(this.sessionsDir, `${sessionId}.meta.json`);
+    setInstanceId(instanceId) {
+        this.instanceId = (0, paths_js_1.normalizeInstanceId)(instanceId);
+        this.indexCache = null; // Clear cache when switching instances
+        (0, paths_js_1.ensureInstanceDir)(this.instanceId);
     }
     // ═══════════════════════════════════════════════════════════════════════════
     // INDEX OPERATIONS
@@ -104,9 +104,10 @@ class LocalSessionStore {
         if (this.indexCache && now - this.indexCacheTime < this.INDEX_CACHE_TTL) {
             return this.indexCache;
         }
+        const indexPath = (0, paths_js_1.getIndexPath)(this.instanceId);
         try {
-            if (fs.existsSync(this.indexPath)) {
-                const content = fs.readFileSync(this.indexPath, 'utf-8');
+            if (fs.existsSync(indexPath)) {
+                const content = fs.readFileSync(indexPath, 'utf-8');
                 this.indexCache = JSON.parse(content);
                 this.indexCacheTime = now;
                 return this.indexCache;
@@ -124,10 +125,11 @@ class LocalSessionStore {
      * Write the session index atomically
      */
     writeIndex(index) {
-        const tmpPath = `${this.indexPath}.tmp`;
+        const indexPath = (0, paths_js_1.getIndexPath)(this.instanceId);
+        const tmpPath = `${indexPath}.tmp`;
         try {
             fs.writeFileSync(tmpPath, JSON.stringify(index, null, 2), 'utf-8');
-            fs.renameSync(tmpPath, this.indexPath);
+            fs.renameSync(tmpPath, indexPath);
             this.indexCache = index;
             this.indexCacheTime = Date.now();
         }
@@ -154,26 +156,52 @@ class LocalSessionStore {
     // SESSION METADATA
     // ═══════════════════════════════════════════════════════════════════════════
     /**
-     * Read session metadata
+     * Read session metadata (checks instance path, then legacy path)
      */
     getSessionMeta(sessionId) {
-        const metaPath = this.getMetaPath(sessionId);
+        // Try instance-scoped path first
+        const metaPath = (0, paths_js_1.getMetaPath)(this.instanceId, sessionId);
         try {
             if (fs.existsSync(metaPath)) {
                 const content = fs.readFileSync(metaPath, 'utf-8');
-                return JSON.parse(content);
+                const meta = JSON.parse(content);
+                // Ensure instance_id is set
+                if (!meta.instance_id) {
+                    meta.instance_id = this.instanceId;
+                }
+                return meta;
             }
         }
         catch (err) {
             console.error('[LocalSessionStore] Meta read error:', err);
         }
+        // Try legacy path (read-only fallback)
+        const legacyPath = (0, paths_js_1.getLegacyMetaPath)(sessionId);
+        try {
+            if (fs.existsSync(legacyPath)) {
+                const content = fs.readFileSync(legacyPath, 'utf-8');
+                const meta = JSON.parse(content);
+                // Mark as default instance for legacy data
+                if (!meta.instance_id) {
+                    meta.instance_id = paths_js_1.DEFAULT_INSTANCE_ID;
+                }
+                return meta;
+            }
+        }
+        catch {
+            // Ignore legacy read errors
+        }
         return null;
     }
     /**
-     * Write session metadata atomically
+     * Write session metadata atomically (always to instance-scoped path)
      */
     writeSessionMeta(meta) {
-        const metaPath = this.getMetaPath(meta.session_id);
+        // Ensure instance_id is set
+        if (!meta.instance_id) {
+            meta.instance_id = this.instanceId;
+        }
+        const metaPath = (0, paths_js_1.getMetaPath)(this.instanceId, meta.session_id);
         const tmpPath = `${metaPath}.tmp`;
         try {
             fs.writeFileSync(tmpPath, JSON.stringify(meta, null, 2), 'utf-8');
@@ -195,13 +223,24 @@ class LocalSessionStore {
     /**
      * Append a turn to the session's JSONL file
      * This is the hot path - must be fast
+     *
+     * Per v1.2 ADDENDUM: All records include instanceId, sessionId, sessionName
      */
     appendTurn(sessionId, sessionName, turn, projectPath) {
         const startTime = Date.now();
-        const turnsPath = this.getTurnsPath(sessionId);
+        // Ensure instance directory exists
+        (0, paths_js_1.ensureInstanceDir)(this.instanceId);
+        const turnsPath = (0, paths_js_1.getTurnsPath)(this.instanceId, sessionId);
         try {
+            // Add instance namespacing fields to turn
+            const enrichedTurn = {
+                ...turn,
+                instance_id: this.instanceId,
+                session_id: sessionId,
+                session_name: sessionName,
+            };
             // Append turn as JSONL line (atomic append on most filesystems)
-            const line = JSON.stringify(turn) + '\n';
+            const line = JSON.stringify(enrichedTurn) + '\n';
             fs.appendFileSync(turnsPath, line, 'utf-8');
             // Update metadata
             let meta = this.getSessionMeta(sessionId);
@@ -209,6 +248,7 @@ class LocalSessionStore {
                 meta = {
                     session_id: sessionId,
                     session_name: sessionName,
+                    instance_id: this.instanceId,
                     acked_turn_id: 0,
                     last_flush_ts: new Date().toISOString(),
                     turn_count: 0,
@@ -218,12 +258,14 @@ class LocalSessionStore {
             }
             meta.turn_count = turn.turn_id;
             meta.last_flush_ts = new Date().toISOString();
+            meta.instance_id = this.instanceId;
             if (projectPath)
                 meta.project_path = projectPath;
             this.writeSessionMeta(meta);
             // Update index
             this.updateIndexEntry(sessionName, {
                 session_id: sessionId,
+                instance_id: this.instanceId,
                 last_active_ts: new Date().toISOString(),
                 last_turn_id: turn.turn_id,
                 acked_turn_id: meta.acked_turn_id,
@@ -247,11 +289,17 @@ class LocalSessionStore {
     /**
      * Get the last N turns from a session
      * Handles crash recovery (partial lines)
+     * Checks instance path first, then legacy path as read-only fallback
      */
     getLastTurns(sessionId, n = 10) {
         const startTime = Date.now();
-        const turnsPath = this.getTurnsPath(sessionId);
-        try {
+        // Try instance-scoped path first
+        let turnsPath = (0, paths_js_1.getTurnsPath)(this.instanceId, sessionId);
+        let isLegacy = false;
+        if (!fs.existsSync(turnsPath)) {
+            // Try legacy path as fallback
+            turnsPath = (0, paths_js_1.getLegacyTurnsPath)(sessionId);
+            isLegacy = true;
             if (!fs.existsSync(turnsPath)) {
                 return {
                     success: false,
@@ -260,6 +308,8 @@ class LocalSessionStore {
                     latency_ms: Date.now() - startTime,
                 };
             }
+        }
+        try {
             const content = fs.readFileSync(turnsPath, 'utf-8');
             const lines = content.trim().split('\n').filter(Boolean);
             const turns = [];
@@ -267,6 +317,13 @@ class LocalSessionStore {
             for (const line of lines) {
                 try {
                     const turn = JSON.parse(line);
+                    // Ensure instance fields are present (for legacy data)
+                    if (!turn.instance_id) {
+                        turn.instance_id = isLegacy ? paths_js_1.DEFAULT_INSTANCE_ID : this.instanceId;
+                    }
+                    if (!turn.session_id) {
+                        turn.session_id = sessionId;
+                    }
                     turns.push(turn);
                 }
                 catch {
@@ -312,8 +369,11 @@ class LocalSessionStore {
      */
     updateTurnResponse(sessionId, turnId, response, toolsUsed, filesReferenced) {
         const startTime = Date.now();
-        const turnsPath = this.getTurnsPath(sessionId);
-        try {
+        // Try instance-scoped path first
+        let turnsPath = (0, paths_js_1.getTurnsPath)(this.instanceId, sessionId);
+        if (!fs.existsSync(turnsPath)) {
+            // Try legacy path
+            turnsPath = (0, paths_js_1.getLegacyTurnsPath)(sessionId);
             if (!fs.existsSync(turnsPath)) {
                 return {
                     success: false,
@@ -322,6 +382,8 @@ class LocalSessionStore {
                     latency_ms: Date.now() - startTime,
                 };
             }
+        }
+        try {
             const content = fs.readFileSync(turnsPath, 'utf-8');
             const lines = content.trim().split('\n').filter(Boolean);
             const turns = [];
@@ -348,11 +410,20 @@ class LocalSessionStore {
                 turns[turnIndex].tools_used = toolsUsed;
             if (filesReferenced)
                 turns[turnIndex].files_referenced = filesReferenced;
-            // Rewrite the file atomically
+            // Ensure instance fields
+            if (!turns[turnIndex].instance_id) {
+                turns[turnIndex].instance_id = this.instanceId;
+            }
+            if (!turns[turnIndex].session_id) {
+                turns[turnIndex].session_id = sessionId;
+            }
+            // Rewrite the file atomically (always to instance-scoped path)
+            const instanceTurnsPath = (0, paths_js_1.getTurnsPath)(this.instanceId, sessionId);
+            (0, paths_js_1.ensureInstanceDir)(this.instanceId);
             const newContent = turns.map((t) => JSON.stringify(t)).join('\n') + '\n';
-            const tmpPath = `${turnsPath}.tmp`;
+            const tmpPath = `${instanceTurnsPath}.tmp`;
             fs.writeFileSync(tmpPath, newContent, 'utf-8');
-            fs.renameSync(tmpPath, turnsPath);
+            fs.renameSync(tmpPath, instanceTurnsPath);
             return {
                 success: true,
                 source: 'local',
@@ -390,12 +461,14 @@ class LocalSessionStore {
             if (ackedTurnId > meta.acked_turn_id) {
                 meta.acked_turn_id = ackedTurnId;
                 meta.last_flush_ts = new Date().toISOString();
+                meta.instance_id = this.instanceId;
                 this.writeSessionMeta(meta);
                 // Update index too
                 const index = this.readIndex();
                 const sessionName = Object.keys(index).find((name) => index[name].session_id === sessionId);
                 if (sessionName) {
                     index[sessionName].acked_turn_id = ackedTurnId;
+                    index[sessionName].instance_id = this.instanceId;
                     this.writeIndex(index);
                 }
             }
@@ -435,6 +508,7 @@ class LocalSessionStore {
             if (ackedTurnId > currentSupabaseAck) {
                 meta.supabase_acked_turn_id = ackedTurnId;
                 meta.last_flush_ts = new Date().toISOString();
+                meta.instance_id = this.instanceId;
                 this.writeSessionMeta(meta);
             }
             return {
@@ -459,7 +533,7 @@ class LocalSessionStore {
      */
     prune(sessionId) {
         const startTime = Date.now();
-        const turnsPath = this.getTurnsPath(sessionId);
+        const turnsPath = (0, paths_js_1.getTurnsPath)(this.instanceId, sessionId);
         try {
             const meta = this.getSessionMeta(sessionId);
             if (!meta) {
@@ -532,7 +606,7 @@ class LocalSessionStore {
     // SESSION MANAGEMENT
     // ═══════════════════════════════════════════════════════════════════════════
     /**
-     * List all sessions, sorted by last active (newest first)
+     * List all sessions for current instance, sorted by last active (newest first)
      */
     listSessions() {
         const index = this.readIndex();
@@ -553,14 +627,47 @@ class LocalSessionStore {
         return entries;
     }
     /**
-     * Get session ID from session name
+     * List all sessions across ALL instances (for global queries)
+     */
+    listAllSessions() {
+        const allEntries = [];
+        const instanceIds = (0, paths_js_1.listInstanceIds)();
+        for (const instId of instanceIds) {
+            const indexPath = (0, paths_js_1.getIndexPath)(instId);
+            try {
+                if (fs.existsSync(indexPath)) {
+                    const content = fs.readFileSync(indexPath, 'utf-8');
+                    const index = JSON.parse(content);
+                    for (const [sessionName, entry] of Object.entries(index)) {
+                        allEntries.push({
+                            session_name: sessionName,
+                            session_id: entry.session_id,
+                            instance_id: instId,
+                            last_active_ts: entry.last_active_ts,
+                            turn_count: entry.last_turn_id,
+                            project_path: entry.project_path,
+                            is_current: false,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Ignore errors for individual instances
+            }
+        }
+        // Sort by last active (newest first)
+        allEntries.sort((a, b) => new Date(b.last_active_ts).getTime() - new Date(a.last_active_ts).getTime());
+        return allEntries;
+    }
+    /**
+     * Get session ID from session name (searches current instance)
      */
     getSessionId(sessionName) {
         const index = this.readIndex();
         return index[sessionName]?.session_id || null;
     }
     /**
-     * Get session name from session ID
+     * Get session name from session ID (searches current instance)
      */
     getSessionName(sessionId) {
         const index = this.readIndex();
@@ -572,7 +679,7 @@ class LocalSessionStore {
         return null;
     }
     /**
-     * Check if a session exists in local cache
+     * Check if a session exists in local cache (current instance or legacy)
      */
     hasSession(sessionIdOrName) {
         const index = this.readIndex();
@@ -584,6 +691,10 @@ class LocalSessionStore {
             if (entry.session_id === sessionIdOrName)
                 return true;
         }
+        // Check legacy paths
+        const legacyTurns = (0, paths_js_1.getLegacyTurnsPath)(sessionIdOrName);
+        if (fs.existsSync(legacyTurns))
+            return true;
         return false;
     }
     /**
@@ -592,9 +703,9 @@ class LocalSessionStore {
     deleteSession(sessionId) {
         const startTime = Date.now();
         try {
-            // Remove files
-            const turnsPath = this.getTurnsPath(sessionId);
-            const metaPath = this.getMetaPath(sessionId);
+            // Remove instance-scoped files
+            const turnsPath = (0, paths_js_1.getTurnsPath)(this.instanceId, sessionId);
+            const metaPath = (0, paths_js_1.getMetaPath)(this.instanceId, sessionId);
             if (fs.existsSync(turnsPath))
                 fs.unlinkSync(turnsPath);
             if (fs.existsSync(metaPath))
@@ -648,7 +759,7 @@ class LocalSessionStore {
     // UTILITIES
     // ═══════════════════════════════════════════════════════════════════════════
     /**
-     * Get cache statistics
+     * Get cache statistics for current instance
      */
     getStats() {
         const sessions = this.listSessions();
@@ -656,7 +767,7 @@ class LocalSessionStore {
         let cacheSize = 0;
         for (const session of sessions) {
             totalTurns += session.turn_count;
-            const turnsPath = this.getTurnsPath(session.session_id);
+            const turnsPath = (0, paths_js_1.getTurnsPath)(this.instanceId, session.session_id);
             try {
                 const stats = fs.statSync(turnsPath);
                 cacheSize += stats.size;
@@ -669,10 +780,11 @@ class LocalSessionStore {
             session_count: sessions.length,
             total_turns: totalTurns,
             cache_size_bytes: cacheSize,
+            instance_id: this.instanceId,
         };
     }
     /**
-     * Clear all local cache (use with caution)
+     * Clear all local cache for current instance (use with caution)
      */
     clearAll() {
         const sessions = this.listSessions();
@@ -684,5 +796,9 @@ class LocalSessionStore {
     }
 }
 exports.LocalSessionStore = LocalSessionStore;
-// Export singleton instance
+// Export factory function instead of singleton (to support instance-scoped usage)
+function createLocalSessionStore(instanceId) {
+    return new LocalSessionStore({}, instanceId);
+}
+// Export default instance using EKKOS_INSTANCE_ID from env
 exports.localCache = new LocalSessionStore();

package/dist/cache/capture.d.ts

@@ -1,24 +1,32 @@
 #!/usr/bin/env node
 /**
- * ekkOS Fast Capture & Restore - CLI for local cache operations
+ * ekkOS Fast Capture & Restore - CLI for local cache operations (Instance-Aware)
  *
- * Capture Commands:
+ * 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
+ *
+ * Capture Commands (NEW format with instanceId):
+ *   capture user <instance_id> <session_id> <session_name> <turn_id> <query> [project_path]
+ *   capture response <instance_id> <session_id> <turn_id> <response> [tools] [files]
+ *
+ * Capture Commands (LEGACY format - backward compatible, uses default instanceId):
  *   capture user <session_id> <session_name> <turn_id> <query> [project_path]
  *   capture response <session_id> <turn_id> <response> [tools] [files]
  *
  * Restore Commands:
- *   capture restore [session_name] [--json|--markdown|--n=N]
+ *   capture restore [session_name] [--json|--markdown|--n=N] [--instance=ID]
  *
- * ACK & Sync Commands (Phase 5):
- *   capture ack <session_id> <turn_id>     - Update ACK cursor after Redis success
- *   capture sync [session_id]              - Sync unACKed turns to Redis
- *   capture prune <session_id>             - Remove safely ACKed turns
- *   capture cleanup                        - Prune all + evict old sessions
+ * ACK & Sync Commands:
+ *   capture ack <session_id> <turn_id> [--instance=ID]
+ *   capture sync [session_id] [--instance=ID]
+ *   capture prune <session_id> [--instance=ID]
+ *   capture cleanup [--instance=ID]
  *
  * Query Commands:
- *   capture list                           - List all cached sessions
- *   capture get <session_id> [n]           - Get last N turns
- *   capture stats                          - Cache statistics
+ *   capture list [--instance=ID|--all]
+ *   capture get <session_id> [n] [--instance=ID]
+ *   capture stats [--instance=ID]
  *
  * This is a lightweight script designed for hook integration.
  * Writes to local JSONL cache with minimal latency.