@claude-flow/cli 3.57.2 → 3.58.1

package/dist/src/memory/memory-initializer.js

@@ -10,6 +10,7 @@ import { createRequire } from 'node:module';
 import { readFileMaybeEncrypted, writeDbImagePreservingFormat, writeFileRestricted } from '../fs-secure.js';
 import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
 import { validateIdentifier } from '../mcp-tools/validate-input.js';
+import { resolveModelCacheDir } from './model-cache-dir.js';
 /**
  * ADR-323 — typed memory provenance. Distinguishes WHO/WHAT wrote a memory
  * entry (a user's stated claim vs an agent's own output vs a tool result vs
@@ -2009,6 +2010,8 @@ export async function applyTemporalDecay(dbPath) {
         };
     }
 }
+/** ADR-454: minimum interval before a 'retryable' degraded state re-attempts real init. */
+const MODEL_INIT_RETRY_INTERVAL_MS = 60_000;
 /**
  * State of the LOCAL embedding chain only (transformers.js / agentic-flow /
  * ruvector ONNX / hash). #3375: the AgentDB bridge's result is cached
@@ -2058,8 +2061,15 @@ export async function loadEmbeddingModel(options) {
  */
 async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now()) {
     if (embeddingModelState?.loaded) {
-        return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+        const isRetryableDue = embeddingModelState.degradedReason === 'retryable' &&
+            Date.now() - (embeddingModelState.lastAttemptAt ?? 0) >= MODEL_INIT_RETRY_INTERVAL_MS;
+        if (!isRetryableDue) {
+            return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+        }
+        // Fall through to re-attempt real initialization — the retryable
+        // failure (e.g. EACCES on the model cache dir) may now be fixed.
     }
+    let sawRetryableFailure = false;
     try {
         // ADR-094: prefer @huggingface/transformers (clears protobufjs <7.5.5
         // critical RCE chain), fall back to legacy @xenova/transformers.
@@ -2068,6 +2078,7 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
         // @claude-flow/embeddings/src/transformers-loader.ts.
         let transformersSource = null;
         let pipelineFn = null;
+        let transformersModule = null;
         {
             const tryLoad = async (specifier) => {
                 try {
@@ -2081,12 +2092,14 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
             if (hf && typeof hf.pipeline === 'function') {
                 pipelineFn = hf.pipeline;
                 transformersSource = '@huggingface/transformers';
+                transformersModule = hf;
             }
             else {
                 const xen = await tryLoad('@xenova/transformers');
                 if (xen && typeof xen.pipeline === 'function') {
                     pipelineFn = xen.pipeline;
                     transformersSource = '@xenova/transformers';
+                    transformersModule = xen;
                 }
             }
         }
@@ -2103,6 +2116,14 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
                 if (verbose) {
                     console.log(`Loading ONNX embedding model via ${transformersSource} (all-MiniLM-L6-v2)...`);
                 }
+                // ADR-454: route model downloads to a user-writable cache dir —
+                // the package-relative default is root-owned under a system-prefix
+                // global install, which throws EACCES for the runtime user.
+                const cacheDir = resolveModelCacheDir();
+                fs.mkdirSync(cacheDir, { recursive: true });
+                const env = transformersModule?.env;
+                if (env)
+                    env.cacheDir = cacheDir;
                 const embedder = await pipelineFn('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
                 embeddingModelState = {
                     loaded: true,
@@ -2118,6 +2139,10 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
                 };
             }
             catch (err) {
+                // ADR-454: a real backend was importable and callable — this failure
+                // (EACCES, ENOSPC, transient network error, etc.) is environmental,
+                // not a missing dependency, so it must not be memoized permanently.
+                sawRetryableFailure = true;
                 if (verbose) {
                     console.warn(`${transformersSource} pipeline init failed (${err instanceof Error ? err.message : String(err)}); ` +
                         'falling through to ruvector ONNX / agentic-flow / hash fallback.');
@@ -2186,12 +2211,18 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
         }
         // No agentic-flow root-entry fallback: no published root exports
         // `embeddings`, and importing it runs its CLI main() in 3.0.0-alpha.x.
-        // No ONNX model available - use fallback
+        // No ONNX model available - use fallback.
+        // ADR-454: mark whether this is a permanent (no backend importable at
+        // all) or retryable (a backend existed but init failed for an
+        // environmental reason) degraded state, so a later call can re-attempt
+        // real initialization once the condition is fixed.
         embeddingModelState = {
             loaded: true,
             model: null, // Will use simple hash-based fallback
             tokenizer: null,
-            dimensions: 128 // Smaller fallback dimensions
+            dimensions: 128, // Smaller fallback dimensions
+            degradedReason: sawRetryableFailure ? 'retryable' : 'permanent',
+            lastAttemptAt: Date.now()
         };
         return {
             success: true,
@@ -2257,7 +2288,15 @@ export async function generateLocalEmbedding(text) {
     // loadEmbeddingModel(), which is bridge-first — when the bridge answered
     // there, no local model was ever loaded and this function always returned
     // the hash fallback.
-    if (!embeddingModelState?.loaded) {
+    //
+    // ADR-454: also re-attempt when the memoized state is a 'retryable'
+    // degraded fallback whose retry interval has elapsed — otherwise this
+    // guard short-circuits past loadLocalEmbeddingChain()'s own retry check
+    // and the fix (e.g. a now-writable cache dir) never gets exercised.
+    const shouldRetryLoad = !embeddingModelState?.loaded ||
+        (embeddingModelState.degradedReason === 'retryable' &&
+            Date.now() - (embeddingModelState.lastAttemptAt ?? 0) >= MODEL_INIT_RETRY_INTERVAL_MS);
+    if (shouldRetryLoad) {
         await loadLocalEmbeddingChain();
     }
     // #2461: loadEmbeddingModel() can leave embeddingModelState null when an

package/dist/src/memory/memory-peek.d.ts

@@ -0,0 +1,28 @@
+export type MemoryRootSource = 'path' | 'CLAUDE_FLOW_DB_PATH' | 'CLAUDE_FLOW_MEMORY_PATH' | 'config' | 'default';
+export interface MemoryPeekStore {
+    role: 'cli' | 'mcp';
+    path: string;
+    exists: boolean;
+    rows: number | null;
+    lastWrite: string | null;
+    sizeBytes: number | null;
+    walBytes: number | null;
+    encrypted?: boolean;
+}
+export interface MemoryPeekResult {
+    cwd: string;
+    root: {
+        path: string;
+        source: MemoryRootSource;
+    };
+    stores: MemoryPeekStore[];
+    sharedKeys: number | null;
+}
+/**
+ * Resolve the route and report both stores, read-only. Never creates,
+ * initializes, or migrates anything, on an empty project or any other.
+ */
+export declare function memoryPeek(opts?: {
+    path?: string;
+}): Promise<MemoryPeekResult>;
+//# sourceMappingURL=memory-peek.d.ts.map

package/dist/src/memory/memory-peek.js

@@ -0,0 +1,222 @@
+/**
+ * #3508: read-only memory route/peek.
+ *
+ * A health check needs to know which memory store files a cwd resolves to,
+ * and what is in them, without changing anything to find out. `memory stats`
+ * (even after #3463/#3448) still calls `ensureInitialized()` when no explicit
+ * path is given, and answers for one file per call. This module reports
+ * BOTH files — the sql.js `memory.db` the CLI writes and its native
+ * `agentdb-memory.db` sibling the MCP/bridge path writes — in one read-only
+ * pass, and says which resolution rule picked the root.
+ *
+ * Contract (do not relax without re-reading #3508):
+ *   - never creates, initializes, or migrates anything;
+ *   - never opens a file that does not exist (`existsSync` gated before any
+ *     open attempt, for both engines);
+ *   - every open is `readonly`/`fileMustExist` (native) or a one-shot byte
+ *     buffer handed to sql.js, which is never written back to disk;
+ *   - `rows: null` means "could not read" and is never a count of 0, so an
+ *     empty store and an unreadable one never look the same;
+ *   - an encrypted-at-rest `memory.db` reports `encrypted: true` and
+ *     `rows: null`, but its size is still reported.
+ */
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { getMemoryRoot, resolveDbPath } from './memory-initializer.js';
+import { siblingAgentDbPath } from './memory-bridge.js';
+import { isEncryptedBlob } from '../encryption/vault.js';
+// Mirrors the `ACTIVE_MEMORY_ROW_SQL` convention in memory-initializer.ts:
+// legacy rows with a NULL status predate soft-delete semantics and count.
+const ACTIVE_ROW_SQL = `(status = 'active' OR status IS NULL)`;
+const ENCRYPTION_SNIFF_LEN = 64; // RFE1 magic(4)+iv(12)+tag(16); 64 gives headroom.
+function safeStatSize(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return null;
+    }
+}
+function readHeaderBytes(filePath, len) {
+    const fd = openSync(filePath, 'r');
+    try {
+        const buf = Buffer.alloc(len);
+        const bytesRead = readSync(fd, buf, 0, len, 0);
+        return buf.subarray(0, bytesRead);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function latestMillis(values) {
+    let latest = -Infinity;
+    for (const raw of values) {
+        const millis = typeof raw === 'number' ? raw : Number(raw);
+        if (Number.isFinite(millis))
+            latest = Math.max(latest, millis);
+    }
+    return latest;
+}
+/** sql.js is read as a one-shot in-memory byte buffer — nothing is ever
+ * written back, so reading this file has no on-disk side effect. */
+async function probeSqlJsStore(dbPath) {
+    try {
+        if (isEncryptedBlob(readHeaderBytes(dbPath, ENCRYPTION_SNIFF_LEN))) {
+            return { rows: null, lastWrite: null, keys: null, encrypted: true };
+        }
+    }
+    catch {
+        /* header read failed (permissions/race) — fall through to the open attempt */
+    }
+    try {
+        const initSqlJs = (await import('sql.js')).default ?? (await import('sql.js'));
+        const SQL = await (typeof initSqlJs === 'function' ? initSqlJs() : initSqlJs.default());
+        const buf = readFileSync(dbPath);
+        const db = new SQL.Database(new Uint8Array(buf));
+        try {
+            const tables = db.exec("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_entries'");
+            if (!tables.length)
+                return { rows: null, lastWrite: null, keys: null };
+            const result = db.exec(`SELECT namespace, key, created_at, updated_at FROM memory_entries WHERE ${ACTIVE_ROW_SQL}`);
+            const values = result[0]?.values ?? [];
+            const keys = new Set();
+            let last = -Infinity;
+            for (const [namespace, key, createdAt, updatedAt] of values) {
+                keys.add(`${String(namespace)}\u0000${String(key)}`);
+                last = Math.max(last, latestMillis([createdAt, updatedAt]));
+            }
+            return {
+                rows: values.length,
+                lastWrite: Number.isFinite(last) ? new Date(last).toISOString() : null,
+                keys,
+            };
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch {
+        return { rows: null, lastWrite: null, keys: null };
+    }
+}
+/** better-sqlite3 is an optional native dependency — absence must degrade
+ * to "could not read", never throw. Opened `readonly`/`fileMustExist`, same
+ * as `countSiblingStoreRows` in sibling-store.ts. */
+async function probeNativeStore(dbPath) {
+    try {
+        const require = (await import('node:module')).createRequire(import.meta.url);
+        const Database = require('better-sqlite3');
+        const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+        try {
+            const table = db
+                .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memory_entries'")
+                .get();
+            if (!table)
+                return { rows: null, lastWrite: null, keys: null };
+            const rows = db
+                .prepare(`SELECT namespace, key, created_at, updated_at FROM memory_entries WHERE ${ACTIVE_ROW_SQL}`)
+                .all();
+            const keys = new Set();
+            let last = -Infinity;
+            for (const row of rows) {
+                keys.add(`${String(row.namespace)}\u0000${String(row.key)}`);
+                last = Math.max(last, latestMillis([row.created_at, row.updated_at]));
+            }
+            return {
+                rows: rows.length,
+                lastWrite: Number.isFinite(last) ? new Date(last).toISOString() : null,
+                keys,
+            };
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch {
+        return { rows: null, lastWrite: null, keys: null };
+    }
+}
+/** Same precedence `getMemoryRoot()`/`resolveDbPath()` already own — this
+ * only *labels* which rule decided, it never re-derives the path itself. */
+function decideSource(cliFlag) {
+    if (cliFlag && cliFlag.trim().length > 0)
+        return 'path';
+    if (process.env.CLAUDE_FLOW_DB_PATH && process.env.CLAUDE_FLOW_DB_PATH.trim().length > 0) {
+        return 'CLAUDE_FLOW_DB_PATH';
+    }
+    if (process.env.CLAUDE_FLOW_MEMORY_PATH && process.env.CLAUDE_FLOW_MEMORY_PATH.trim().length > 0) {
+        return 'CLAUDE_FLOW_MEMORY_PATH';
+    }
+    const configCandidates = [
+        path.resolve(process.cwd(), 'claude-flow.config.json'),
+        path.resolve(process.cwd(), '.claude-flow', 'config.json'),
+    ];
+    for (const configPath of configCandidates) {
+        if (!existsSync(configPath))
+            continue;
+        try {
+            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+            const fromConfig = raw?.memory?.persistPath ?? raw?.memory?.path;
+            if (typeof fromConfig === 'string' && fromConfig.trim().length > 0)
+                return 'config';
+        }
+        catch {
+            /* malformed config — getMemoryRoot() falls through to default too */
+        }
+    }
+    return 'default';
+}
+async function describeStore(role, storePath, probe) {
+    if (!existsSync(storePath)) {
+        return {
+            store: { role, path: storePath, exists: false, rows: null, lastWrite: null, sizeBytes: null, walBytes: null },
+            keys: null,
+        };
+    }
+    const result = await probe(storePath);
+    const sizeBytes = safeStatSize(storePath);
+    const walBytes = safeStatSize(`${storePath}-wal`) ?? 0;
+    return {
+        store: {
+            role,
+            path: storePath,
+            exists: true,
+            rows: result.rows,
+            lastWrite: result.lastWrite,
+            sizeBytes,
+            walBytes,
+            ...(result.encrypted ? { encrypted: true } : {}),
+        },
+        keys: result.keys,
+    };
+}
+/**
+ * Resolve the route and report both stores, read-only. Never creates,
+ * initializes, or migrates anything, on an empty project or any other.
+ */
+export async function memoryPeek(opts) {
+    const cliFlag = opts?.path;
+    const cliPath = resolveDbPath(cliFlag);
+    const mcpPath = siblingAgentDbPath(cliPath);
+    const root = { path: cliFlag ? path.dirname(cliPath) : getMemoryRoot(), source: decideSource(cliFlag) };
+    const cliDescribed = await describeStore('cli', cliPath, probeSqlJsStore);
+    const stores = [cliDescribed.store];
+    let mcpKeys = null;
+    if (mcpPath) {
+        const mcpDescribed = await describeStore('mcp', mcpPath, probeNativeStore);
+        stores.push(mcpDescribed.store);
+        mcpKeys = mcpDescribed.keys;
+    }
+    const cliKeys = cliDescribed.keys;
+    const sharedKeys = cliKeys && mcpKeys
+        ? [...cliKeys].filter((key) => mcpKeys.has(key)).length
+        : null;
+    return { cwd: process.cwd(), root, stores, sharedKeys };
+}
+//# sourceMappingURL=memory-peek.js.map

package/dist/src/memory/model-cache-dir.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve a writable cache directory for ONNX model downloads.
+ *
+ * ADR-454: duplicated intentionally from
+ * `@claude-flow/embeddings/src/transformers-loader.ts`'s
+ * `resolveModelCacheDir()` rather than imported, since `@claude-flow/cli`
+ * has no dependency on `@claude-flow/embeddings` (see the circular
+ * optional-dep note in `memory-initializer.ts`).
+ */
+export declare function resolveModelCacheDir(): string;
+//# sourceMappingURL=model-cache-dir.d.ts.map

package/dist/src/memory/model-cache-dir.js

@@ -0,0 +1,17 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+/**
+ * Resolve a writable cache directory for ONNX model downloads.
+ *
+ * ADR-454: duplicated intentionally from
+ * `@claude-flow/embeddings/src/transformers-loader.ts`'s
+ * `resolveModelCacheDir()` rather than imported, since `@claude-flow/cli`
+ * has no dependency on `@claude-flow/embeddings` (see the circular
+ * optional-dep note in `memory-initializer.ts`).
+ */
+export function resolveModelCacheDir() {
+    return (process.env.TRANSFORMERS_CACHE ||
+        process.env.HF_HOME ||
+        path.join(os.homedir(), '.cache', 'ruflo', 'models'));
+}
+//# sourceMappingURL=model-cache-dir.js.map

package/dist/src/parser.js

@@ -184,8 +184,9 @@ export class CommandParser {
         let commandSlotAvailable = true;
         while (i < args.length) {
             const arg = args[i];
-            // Check for end of flags marker
-            if (arg === '--') {
+            // Check for end of flags marker. Only the first "--" changes parser
+            // state; a later literal "--" is an ordinary positional (#4310).
+            if (parsingFlags && arg === '--') {
                 parsingFlags = false;
                 i++;
                 continue;

package/dist/src/ruvector/task-embedder.js

@@ -19,6 +19,8 @@
  *
  * @module task-embedder
  */
+import * as fs from 'node:fs';
+import { resolveModelCacheDir } from '../memory/model-cache-dir.js';
 // ============================================================================
 // FNV-1a-32 hash (matches scripts/gen-seed-corpus.mjs + router-trajectory.ts)
 // ============================================================================
@@ -38,18 +40,48 @@ function cacheKey(task) {
 // same function (xenova's pipeline returns a callable that accepts either),
 // so we don't pay the ONNX model-load cost twice.
 let _extractorPromise = null;
+/**
+ * ADR-454: distinguishes a null-extractor result caused by a genuinely
+ * missing dependency (permanent — nothing changes without a reinstall) from
+ * one caused by an environmental/fixable failure during `pipeline(...)`
+ * init, such as EACCES on the model cache dir (retryable).
+ */
+let _extractorDegradedReason = null;
+let _extractorLastAttemptAt = 0;
+const EXTRACTOR_RETRY_INTERVAL_MS = 60_000;
 function loadExtractor() {
-    if (_extractorPromise !== null)
-        return _extractorPromise;
+    if (_extractorPromise !== null) {
+        const isRetryableDue = _extractorDegradedReason === 'retryable' &&
+            Date.now() - _extractorLastAttemptAt >= EXTRACTOR_RETRY_INTERVAL_MS;
+        if (!isRetryableDue)
+            return _extractorPromise;
+        // Fall through to re-attempt — the retryable failure may now be fixed.
+    }
+    _extractorLastAttemptAt = Date.now();
     _extractorPromise = (async () => {
+        let packageImportable = false;
         try {
             const specifier = '@xenova/transformers';
             const mod = await import(/* @vite-ignore */ specifier).catch(() => null);
-            if (!mod || typeof mod.pipeline !== 'function')
+            if (!mod || typeof mod.pipeline !== 'function') {
+                _extractorDegradedReason = 'permanent';
                 return null;
-            return await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true });
+            }
+            packageImportable = true;
+            // ADR-454: route model downloads to a user-writable cache dir — the
+            // package-relative default is root-owned under a system-prefix
+            // global install, which throws EACCES for the runtime user.
+            const cacheDir = resolveModelCacheDir();
+            fs.mkdirSync(cacheDir, { recursive: true });
+            const env = mod.env;
+            if (env)
+                env.cacheDir = cacheDir;
+            const extractor = await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true });
+            _extractorDegradedReason = null;
+            return extractor;
         }
         catch {
+            _extractorDegradedReason = packageImportable ? 'retryable' : 'permanent';
             return null;
         }
     })();
@@ -233,5 +265,7 @@ export function __resetTaskEmbedderForTests() {
     _hits = 0;
     _misses = 0;
     _extractorPromise = null;
+    _extractorDegradedReason = null;
+    _extractorLastAttemptAt = 0;
 }
 //# sourceMappingURL=task-embedder.js.map

package/node_modules/@claude-flow/codex/README.md

@@ -1042,6 +1042,84 @@ npx claude-flow memory optimize --rebuild-index
 
 ---
 
+## Inspect an existing Codex session
+
+The `activity` command lets you pick a helper and read its assignment, recorded
+state, public progress messages, and tool calls/results. It reads local rollout
+files without starting model sessions or sending commands to agents.
+
+From a checkout containing this change:
+
+```bash
+npm install --prefix v3/@claude-flow/codex --workspaces=false --ignore-scripts --legacy-peer-deps --package-lock=false
+npm run build --prefix v3/@claude-flow/codex
+node v3/@claude-flow/codex/dist/cli.js activity \
+  --session-file /path/to/sessions/parent-rollout.jsonl \
+  --sessions-dir /path/to/sessions
+```
+
+Choose the parent rollout explicitly. Only helpers whose recorded parent chain
+leads back to that session appear. The selected directory must contain both the
+parent and helper files; use the smallest directory that contains them all.
+
+Use **j/k** or the arrow keys to select a helper, then **Enter** to open it.
+In the detail view, **j/k** scroll, **Space** moves down a page, **g** goes to the
+top, **G** follows the latest activity, and **b** or **Escape** returns to the list.
+Press **q** to quit; the Codex session keeps running.
+
+Use `--agent <thread-id>` to open a specific helper, `--once` to print a snapshot
+without an interactive terminal, or `--interval <seconds>` to change the refresh
+interval (default: 2 seconds; range: 0.2–60).
+
+These screenshots use made-up session records:
+
+![Agent picker with a parser-review helper](docs/images/activity-picker.png)
+
+![Helper assignment, public progress, command and result](docs/images/activity-detail.png)
+
+### What the viewer can read
+
+The parser supports CLI rollout files with a `session_meta` header, helper ancestry
+in `source.subagent.thread_spawn.parent_thread_id`, and an own-thread marker
+(`payload.thread_id`) before helper activity. Public message, function/custom tool
+call and result records, and supported task/item events are shown. Formats without
+these attribution fields may produce an empty list or unavailable activity.
+
+Copied parent history, reasoning, and system/developer messages are excluded.
+Ambiguous identities and paths through symlinks are rejected. The viewer strips
+terminal controls and masks common credential patterns before shortening previews.
+Masking cannot catch every secret in arbitrary command output: check the visible
+content before sharing a screenshot.
+
+State is the last **recorded** state, not a heartbeat. Discovery stops after 4,000
+entries or eight directory levels; ancestry is limited to 64 links. Each detail
+refresh reads at most 1 MiB, lines are limited to 64 KiB, previews to 2,400 characters,
+and history to 80 events. The metadata header must include its terminating newline
+within the first 64 KiB; an oversized or incomplete header excludes that file.
+The screen labels incomplete scans, omitted records and logs that are still being
+read. Missing data stays unavailable.
+
+### Check the viewer locally
+
+```bash
+cd v3/@claude-flow/codex
+npm test -- --run tests/activity-files.test.ts tests/activity-parser.test.ts tests/activity-viewer.test.ts
+cd ../../..
+node scripts/smoke-codex-activity.mjs
+```
+
+The Node smoke check runs the built CLI against synthetic files and checks the
+picker, detail output, history isolation, invalid input and read-only access.
+The screenshots above were captured from the interactive viewer using synthetic
+records; screenshot generation is not part of CI.
+
+### Release integration
+
+Ship the viewer in `@claude-flow/codex` with the next coordinated Ruflo release.
+At release, bump the package version and exported `VERSION` together, update the
+bundled dependency pins and lockfile, and include the built package in the release
+train.
+
 ## Related Packages
 
 | Package | Description |

package/node_modules/@claude-flow/codex/dist/activity/cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createActivityCommand(): Command;
+//# sourceMappingURL=cli.d.ts.map

package/node_modules/@claude-flow/codex/dist/activity/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/activity/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAwB,MAAM,WAAW,CAAC;AAO1D,wBAAgB,qBAAqB,IAAI,OAAO,CA6B/C"}