@claude-flow/cli 3.57.1 → 3.58.0

package/dist/src/services/memory-backup.js

@@ -14,7 +14,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { readFileMaybeEncrypted } from '../fs-secure.js';
+import { existingFileIsEncrypted, readFileMaybeEncrypted } from '../fs-secure.js';
 import { loadBetterSqlite3 } from '../memory/shared-sqlite.js';
 import { resolveMemoryRoot } from '../memory/memory-root.js';
 export function defaultMemoryDbPath(cwd = process.cwd()) {
@@ -37,12 +37,18 @@ export async function backupProjectMemoryDbs(cwd, opts = {}) {
     }
     const successful = backups.filter(result => result.backedUp);
     const failed = backups.find(result => !result.backedUp && result.skipped !== 'no-db');
+    // Only report an aggregate `method` when every successful store agrees — a
+    // mixed native/raw-copy result must not collapse to whichever store
+    // happened to be first, the exact false-confidence #4287 is about.
+    const methods = new Set(successful.map(result => result.method));
+    const aggregateMethod = methods.size === 1 ? successful[0]?.method : undefined;
     return {
         ...successful[0],
         backedUp: successful.length > 0 && !failed,
         sizeBytes: successful.reduce((sum, result) => sum + (result.sizeBytes ?? 0), 0),
         rotatedAway: successful.flatMap(result => result.rotatedAway ?? []),
         skipped: failed?.skipped ?? (successful.length === 0 ? 'no-db' : undefined),
+        method: aggregateMethod,
         backups,
     };
 }
@@ -63,88 +69,25 @@ function isSnapshotFor(file, dbPath) {
     return file.startsWith(prefix)
         && /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z\.db$/.test(file.slice(prefix.length));
 }
-export async function backupMemoryDb(opts = {}) {
-    const dbPath = opts.dbPath ?? defaultMemoryDbPath();
-    if (!dbPath || !fs.existsSync(dbPath))
-        return { backedUp: false, skipped: 'no-db' };
-    let Database;
+/**
+ * A plain file copy of a live WAL-mode SQLite database is not a consistent
+ * snapshot — committed data can live only in the `-wal` sidecar until it's
+ * checkpointed back into the main file. We can't open an RFE1-encrypted
+ * source natively to run a real `wal_checkpoint` probe (it isn't a SQLite
+ * image), so for the raw-copy-fallback path the only signal available is
+ * sidecar presence: a non-empty `-wal` file means there are frames that a
+ * copy of the main file alone would silently drop. Fail closed on that.
+ */
+function hasActiveWal(dbPath) {
     try {
-        const mod = 'better-sqlite3';
-        Database = (await import(mod)).default;
+        return fs.statSync(`${dbPath}-wal`).size > 0;
     }
     catch {
-        return { backedUp: false, skipped: 'better-sqlite3 unavailable' };
+        return false;
     }
-    const destDir = opts.destDir ?? path.join(path.dirname(dbPath), 'backups');
-    try {
-        fs.mkdirSync(destDir, { recursive: true });
-    }
-    catch { /* */ }
-    const destPath = path.join(destDir, `${snapshotPrefix(dbPath)}${fileStamp(opts.timestamp ?? Date.now())}.db`);
-    // WAL-safe online backup: read-only source, consistent snapshot to destPath.
-    let db;
-    try {
-        db = new Database(dbPath, { readonly: true });
-        await db.backup(destPath);
-        db.close();
-    }
-    catch (e) {
-        try {
-            db?.close();
-        }
-        catch { /* */ }
-        // #2798 — under CLAUDE_FLOW_ENCRYPT_AT_REST the source is an RFE1
-        // blob, not native SQLite, so better-sqlite3's online-backup API
-        // throws "file is not a database" and the run was silently recorded
-        // as skipped (users with encryption had ZERO backups behind a green
-        // status). The online-backup API only exists to avoid tearing a live
-        // WAL-mode DB; that concern doesn't apply to the encrypted file (sql.js
-        // rewrites it wholesale per flush), so a plain byte copy is a valid
-        // snapshot. Fall back to it before giving up.
-        try {
-            fs.copyFileSync(dbPath, destPath);
-            const copiedBytes = fs.statSync(destPath).size;
-            if (copiedBytes > 0) {
-                // Fall through to rotation/offsite/return below via a flag path.
-                // (Mirror the success path's tail by re-using the same code.)
-                const keep = typeof opts.keep === 'number' && opts.keep > 0 ? opts.keep : 7;
-                const rotatedAway = [];
-                try {
-                    const snaps = fs.readdirSync(destDir).filter(f => isSnapshotFor(f, dbPath)).sort();
-                    while (snaps.length > keep) {
-                        const old = snaps.shift();
-                        try {
-                            fs.rmSync(path.join(destDir, old), { force: true });
-                            rotatedAway.push(old);
-                        }
-                        catch { /* */ }
-                    }
-                }
-                catch { /* */ }
-                let gcsUri;
-                if (opts.gcs) {
-                    try {
-                        const { execFileSync } = await import('child_process');
-                        const dest = opts.gcs.replace(/\/+$/, '') + '/' + path.basename(destPath);
-                        execFileSync('gcloud', ['storage', 'cp', destPath, dest], { stdio: ['ignore', 'ignore', 'inherit'] });
-                        gcsUri = dest;
-                    }
-                    catch { /* offsite failed — local snapshot stands */ }
-                }
-                if (opts.verbose) {
-                    console.log(`memory DB backed up (byte-copy, encrypted-at-rest) → ${destPath} (${Math.round(copiedBytes / 1024)} KB)`);
-                }
-                return { backedUp: true, path: destPath, sizeBytes: copiedBytes, rotatedAway, gcsUri };
-            }
-        }
-        catch { /* byte-copy also failed — report the original error */ }
-        return { backedUp: false, skipped: `backup failed: ${e?.message ?? e}` };
-    }
-    let sizeBytes = 0;
-    try {
-        sizeBytes = fs.statSync(destPath).size;
-    }
-    catch { /* */ }
+}
+/** Shared tail: rotation + optional GCS offsite + verbose logging + the success receipt. */
+async function finishBackup(destPath, dbPath, destDir, opts, method, sizeBytes) {
     // Rotation — ISO-stamped names sort chronologically, so keep the tail.
     const keep = typeof opts.keep === 'number' && opts.keep > 0 ? opts.keep : 7;
     const rotatedAway = [];
@@ -172,11 +115,96 @@ export async function backupMemoryDb(opts = {}) {
         catch { /* offsite failed — local snapshot stands */ }
     }
     if (opts.verbose) {
-        console.log(`memory DB backed up → ${destPath} (${Math.round(sizeBytes / 1024)} KB)` +
+        const label = method === 'raw-copy-fallback' ? ' (byte-copy, encrypted-at-rest)' : '';
+        console.log(`memory DB backed up${label} → ${destPath} (${Math.round(sizeBytes / 1024)} KB)` +
             (rotatedAway.length ? `, rotated ${rotatedAway.length} old` : '') +
             (gcsUri ? `, offsite ${gcsUri}` : ''));
     }
-    return { backedUp: true, path: destPath, sizeBytes, rotatedAway, gcsUri };
+    return { backedUp: true, path: destPath, sizeBytes, rotatedAway, gcsUri, method };
+}
+export async function backupMemoryDb(opts = {}) {
+    const dbPath = opts.dbPath ?? defaultMemoryDbPath();
+    if (!dbPath || !fs.existsSync(dbPath))
+        return { backedUp: false, skipped: 'no-db' };
+    const destDir = opts.destDir ?? path.join(path.dirname(dbPath), 'backups');
+    try {
+        fs.mkdirSync(destDir, { recursive: true });
+    }
+    catch { /* */ }
+    const destPath = path.join(destDir, `${snapshotPrefix(dbPath)}${fileStamp(opts.timestamp ?? Date.now())}.db`);
+    let Database = opts.Database;
+    let nativeError = null;
+    if (!Database) {
+        try {
+            const mod = 'better-sqlite3';
+            Database = (await import(mod)).default;
+        }
+        catch {
+            nativeError = 'better-sqlite3 unavailable';
+        }
+    }
+    if (!nativeError) {
+        // WAL-safe online backup: read-only source, consistent snapshot to destPath.
+        let db;
+        try {
+            db = new Database(dbPath, { readonly: true });
+            await db.backup(destPath);
+            db.close();
+            let sizeBytes = 0;
+            try {
+                sizeBytes = fs.statSync(destPath).size;
+            }
+            catch { /* */ }
+            return await finishBackup(destPath, dbPath, destDir, opts, 'native-online-backup', sizeBytes);
+        }
+        catch (e) {
+            try {
+                db?.close();
+            }
+            catch { /* */ }
+            try {
+                fs.rmSync(destPath, { force: true });
+            }
+            catch { /* a native backup() that throws mid-write can leave a torn destPath */ }
+            nativeError = e?.message ?? String(e);
+        }
+    }
+    // #2798 — under CLAUDE_FLOW_ENCRYPT_AT_REST the source is an RFE1 blob, not
+    // native SQLite, so better-sqlite3's online-backup API throws "file is not
+    // a database" (or isn't even importable on a WASM-only host). The
+    // online-backup API exists to avoid tearing a live WAL-mode DB; that
+    // concern doesn't apply to the encrypted file (sql.js rewrites it wholesale
+    // per flush), so a plain byte copy IS a valid snapshot there.
+    //
+    // But this fallback must never fire for an ORDINARY (non-encrypted) source
+    // just because the native backup threw — SQLITE_BUSY, a disk error, or any
+    // other native-backup failure on a perfectly normal database must fail
+    // closed, not silently report `backedUp: true` off a raw copy. Positively
+    // verify encryption (4-byte RFE1 magic sniff) before ever taking this path;
+    // "the native backup threw" is never by itself evidence the source is
+    // encrypted.
+    if (existingFileIsEncrypted(dbPath) !== true) {
+        return { backedUp: false, skipped: `native backup failed: ${nativeError}` };
+    }
+    // Even for a confirmed-encrypted source, refuse the raw-copy fallback if
+    // there's an active WAL — a plain copy of the main file alone would miss
+    // uncommitted WAL frames and silently produce an inconsistent snapshot.
+    if (hasActiveWal(dbPath)) {
+        return { backedUp: false, skipped: 'active WAL present — refusing raw-copy fallback (would be inconsistent)' };
+    }
+    try {
+        fs.copyFileSync(dbPath, destPath);
+        const copiedBytes = fs.statSync(destPath).size;
+        if (copiedBytes > 0) {
+            return await finishBackup(destPath, dbPath, destDir, opts, 'raw-copy-fallback', copiedBytes);
+        }
+    }
+    catch { /* byte-copy also failed — report the original native error below */ }
+    try {
+        fs.rmSync(destPath, { force: true });
+    }
+    catch { /* */ }
+    return { backedUp: false, skipped: `native backup failed: ${nativeError}` };
 }
 /** Verify a snapshot without modifying it, including RFE1 images and WASM-only hosts. */
 async function verifiedBackupRows(file, Database) {

package/dist/src/services/policy-ledger-anchor.d.ts

@@ -32,6 +32,8 @@ export type AnchorAssessment = {
 };
 export type AnchorWriter = (file: string, value: unknown) => Promise<void>;
 export type StreamingAnchorWriter = (file: string, value: AtomicJsonSource) => Promise<void>;
+export declare const ANCHOR_LOG_FILE = "ledger-anchors.json";
+export declare const ANCHOR_MIRROR_FILE = "ledger-anchor-head.json";
 export declare const anchorLogPath: (projectRoot: string) => string;
 /**
  * Directory holding per-project trust material (anchor mirror, HMAC key).

package/dist/src/services/policy-ledger-anchor.js

@@ -33,9 +33,9 @@ import { closeSync, constants as fsConstants, fstatSync, existsSync, mkdtempSync
 import { isAbsolute, join, resolve } from 'node:path';
 import { homedir, tmpdir, userInfo } from 'node:os';
 import { AgenticPolicyEngine, canonicalizePolicy } from '@claude-flow/security/policy/index';
-const LOG_FILE = 'ledger-anchors.json';
-const MIRROR_FILE = 'ledger-anchor-head.json';
-export const anchorLogPath = (projectRoot) => join(resolve(projectRoot), '.claude-flow', 'policy', LOG_FILE);
+export const ANCHOR_LOG_FILE = 'ledger-anchors.json';
+export const ANCHOR_MIRROR_FILE = 'ledger-anchor-head.json';
+export const anchorLogPath = (projectRoot) => join(resolve(projectRoot), '.claude-flow', 'policy', ANCHOR_LOG_FILE);
 /**
  * The home directory trust material lives under: $HOME when it is an absolute path, else the account's home. An empty or relative
  * $HOME (an unset variable in a wrapper script, `HOME=. cmd`) would make join() yield a path relative to the working directory and
@@ -71,7 +71,7 @@ export function policyTrustRoot() {
 }
 function mirrorPath(projectRoot) {
     const id = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
-    return join(policyTrustRoot(), id, MIRROR_FILE);
+    return join(policyTrustRoot(), id, ANCHOR_MIRROR_FILE);
 }
 // Duplicated from policy-runtime.ts's RECEIPT_ARCHIVE_FILE rather than
 // imported, to avoid a circular dependency (policy-runtime.ts imports this

package/dist/src/services/policy-runtime.js

@@ -7,17 +7,18 @@ import { AgenticPolicyEngine, POLICY_STATE_VERSION, createLegacyCompatibleState,
 import { isMcpCallerAuthEnabled, decodeTokenEnvelope, publicKeyFromHex, verifyInvocationToken, } from '@claude-flow/security/mcp-caller-identity';
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, ftruncateSync, writeSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { closeSync, constants as fsConstants, existsSync, fstatSync, fsyncSync, ftruncateSync, writeSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { hostname, userInfo } from 'node:os';
 import { syncPolicyProjection } from '../mods/policy-projection.js';
 import { ATOMIC_JSON_WRITER } from './policy-anchor-log.js';
 import { captureArchiveSnapshot, verifyFullPolicyLedger } from './policy-ledger-audit.js';
-import { assessAnchors, policyTrustRoot, recordAnchor } from './policy-ledger-anchor.js';
+import { ANCHOR_LOG_FILE, ANCHOR_MIRROR_FILE, assessAnchors, policyTrustRoot, recordAnchor } from './policy-ledger-anchor.js';
 const POLICY_DIR = join('.claude-flow', 'policy');
 const POLICY_FILE = 'state.json';
 const LOCK_FILE = 'state.lock';
 const RECEIPT_ARCHIVE_FILE = 'receipts.ledger.jsonl';
+const STATE_ANCHOR_FILE = 'state.anchor.json';
 const LOCK_WAIT_MS = 5_000;
 // #3164: without a bound, `state.receipts` grows forever and every
 // transaction's verify/clone/serialize cost is O(all receipts ever issued) —
@@ -362,11 +363,59 @@ async function writeJsonAtomic(file, value) {
         }
     }
 }
+// #3164: a writer killed between creating its temp file and renaming it
+// (SIGKILL from a caller's timeout, OOM) never reaches writeJsonAtomic's
+// cleanup, so a full-size copy of the file stays behind forever (~250 MB each
+// on a mature ledger). Every writer of these files holds the project's
+// state.lock, so while the lock is held no temp file for them can belong to a
+// write in progress. That invariant has known gaps: released versions before
+// the dead-owner fix take over any lock older than 30 s, even a live owner's
+// (a writer suspended mid-write, e.g. a sleeping laptop). So a temp is also
+// kept while its writer pid is alive on this host, and until it is
+// ORPHAN_TEMP_MIN_AGE_MS old; a skipped orphan is removed by a later call.
+const ORPHAN_TEMP_MIN_AGE_MS = 10 * 60_000;
+const ATOMIC_TEMP = /^(.+)\.(\d+)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/;
+const PROJECT_ATOMIC_FILES = new Set([POLICY_FILE, ANCHOR_LOG_FILE]);
+const TRUST_ATOMIC_FILES = new Set([STATE_ANCHOR_FILE, ANCHOR_MIRROR_FILE]);
+function reapOrphanedTemps(dir, files) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const now = Date.now();
+    for (const name of names) {
+        const match = ATOMIC_TEMP.exec(name);
+        if (!match || !files.has(match[1]))
+            continue;
+        const pid = Number(match[2]);
+        if (Number.isSafeInteger(pid) && pid > 0 && isPidAlive(pid))
+            continue;
+        const file = join(dir, name);
+        try {
+            const stat = lstatSync(file);
+            if (!stat.isFile() || now - stat.mtimeMs < ORPHAN_TEMP_MIN_AGE_MS)
+                continue;
+            unlinkSync(file);
+        }
+        catch { /* already gone, or not removable: never fail the caller */ }
+    }
+}
+/** Call only while holding the project's state.lock. */
+function reapOrphanedPolicyTemps(projectRoot) {
+    reapOrphanedTemps(paths(projectRoot).dir, PROJECT_ATOMIC_FILES);
+    try {
+        reapOrphanedTemps(dirname(trustPaths(projectRoot).anchor), TRUST_ATOMIC_FILES);
+    }
+    catch { /* no trust dir yet */ }
+}
 function trustPaths(projectRoot) {
     const trustRoot = policyTrustRoot();
     const projectId = createHash('sha256').update(realpathSync(projectRoot)).digest('hex');
     const dir = join(trustRoot, projectId);
-    return { key: join(dir, 'anchor.key'), anchor: join(dir, 'state.anchor.json') };
+    return { key: join(dir, 'anchor.key'), anchor: join(dir, STATE_ANCHOR_FILE) };
 }
 function trustKey(projectRoot, create) {
     const { key } = trustPaths(projectRoot);
@@ -531,6 +580,7 @@ export async function withPolicyTransaction(projectRoot, operation, options = {}
     mkdirDurably(target.dir);
     const release = await acquireLock(target.lock);
     try {
+        reapOrphanedPolicyTemps(projectRoot);
         const loaded = loadPolicyState(projectRoot);
         const engine = AgenticPolicyEngine.fromState(loaded, {
             signingKey: process.env.CLAUDE_FLOW_POLICY_SIGNING_KEY,
@@ -691,6 +741,7 @@ export async function verifyPolicyLedger(projectRoot = process.cwd(), options =
     // strings, receipt arrays or maps. The descriptor pins path replacements.
     const release = await acquireLock(target.lock);
     try {
+        reapOrphanedPolicyTemps(projectRoot);
         const engine = AgenticPolicyEngine.fromState(loadPolicyState(projectRoot), engineOptions);
         const outcome = reconcileLedger(projectRoot, engine, options);
         if (outcome.persist) {

package/dist/src/services/worker-daemon.js

@@ -1699,6 +1699,10 @@ export class WorkerDaemon extends EventEmitter {
                 rotatedAway: r.rotatedAway?.length ?? 0,
                 gcsUri: r.gcsUri,
                 skipped: r.skipped,
+                // Which method actually completed (per-store detail is in `backups`);
+                // migration tooling should require 'native-online-backup', not a
+                // blanket `backedUp: true` — see #4287.
+                method: r.method,
             };
         }
         catch (error) {

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

@@ -639,19 +639,19 @@ The `@claude-flow/codex` package now includes built-in dual-mode orchestration:
 
 ```bash
 # List available collaboration templates
-npx claude-flow-codex dual templates
+npx @claude-flow/codex dual templates
 
 # Run a feature development swarm
-npx claude-flow-codex dual run --template feature --task "Add user authentication"
+npx @claude-flow/codex dual run --template feature --task "Add user authentication"
 
 # Run a security audit swarm
-npx claude-flow-codex dual run --template security --task "src/auth/"
+npx @claude-flow/codex dual run --template security --task "src/auth/"
 
 # Run a refactoring swarm
-npx claude-flow-codex dual run --template refactor --task "src/legacy/"
+npx @claude-flow/codex dual run --template refactor --task "src/legacy/"
 
 # Check collaboration status
-npx claude-flow-codex dual status
+npx @claude-flow/codex dual status
 ```
 
 ### Codex Loop Runner
@@ -660,15 +660,15 @@ Codex does not expose Claude Code's `ScheduleWakeup`, so `@claude-flow/codex` pr
 
 ```bash
 # Run Codex repeatedly until it creates .codex/loop/default.complete or reaches 10 iterations
-npx claude-flow-codex loop run "Fix failing tests and create the completion marker when done"
+npx @claude-flow/codex loop run "Fix failing tests and create the completion marker when done"
 
 # Use command mode for recurring Ruflo workers or custom scripts
-npx claude-flow-codex loop run --name testgaps --interval 270 --max-iterations 0 \
+npx @claude-flow/codex loop run --name testgaps --interval 270 --max-iterations 0 \
   --command "npx claude-flow hooks worker dispatch --trigger testgaps"
 
 # Inspect or stop a loop from another terminal
-npx claude-flow-codex loop status --name testgaps
-npx claude-flow-codex loop stop --name testgaps
+npx @claude-flow/codex loop status --name testgaps
+npx @claude-flow/codex loop stop --name testgaps
 ```
 
 Loop state is stored in `.codex/loop/<name>.json`; `loop stop` writes `.codex/loop/<name>.stop`, which the runner observes between iterations.
@@ -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"}

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

@@ -0,0 +1,115 @@
+import { Command, InvalidArgumentError } from 'commander';
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { emitKeypressEvents } from 'node:readline';
+import { ActivityViewer } from './viewer.js';
+import { sanitize } from './sanitize.js';
+export function createActivityCommand() {
+    return new Command('activity')
+        .description('Inspect helpers from an existing Codex session (read-only)')
+        .requiredOption('--session-file <file>', 'Parent CLI rollout JSONL file')
+        .requiredOption('--sessions-dir <directory>', 'Directory containing parent and helper rollouts')
+        .option('--agent <id>', 'Open a particular helper thread ID')
+        .option('--once', 'Print one bounded snapshot and exit (no interactive terminal needed)')
+        .option('--interval <seconds>', 'Refresh interval, 0.2 to 60 seconds', interval, 2)
+        .action(async (options) => {
+        try {
+            const root = await realpath(path.resolve(options.sessionsDir));
+            // Canonicalize the directory only. A selected file through a symlink is rejected.
+            const file = path.resolve(root, path.relative(path.resolve(options.sessionsDir), path.resolve(options.sessionFile)));
+            const viewer = new ActivityViewer(root, file);
+            await viewer.refresh();
+            if (viewer.list.error)
+                throw new Error(viewer.list.error);
+            if (options.agent) {
+                if (!viewer.list.helpers.some(item => item.id === options.agent))
+                    throw new Error('Agent is not an attributable helper of this session.');
+                viewer.selected = options.agent;
+                viewer.detail = true;
+                await viewer.refresh();
+            }
+            if (options.once)
+                console.log(viewer.render(100, 200));
+            else
+                await runTerminal(viewer, options.interval * 1000);
+        }
+        catch (error) {
+            console.error(`Activity viewer: ${sanitize(error instanceof Error ? error.message : 'Unable to read session.', 300)}`);
+            process.exitCode = 1;
+        }
+    });
+}
+function interval(value) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0.2 || parsed > 60)
+        throw new InvalidArgumentError('Choose 0.2 to 60 seconds.');
+    return parsed;
+}
+async function runTerminal(viewer, intervalMs) {
+    const input = process.stdin;
+    const output = process.stdout;
+    if (!input.isTTY || !output.isTTY)
+        throw new Error('Use --once when input or output is not a terminal.');
+    const wasRaw = input.isRaw;
+    let stopped = false;
+    let busy = false;
+    let finish = () => { };
+    const done = new Promise(resolve => { finish = resolve; });
+    const draw = () => {
+        if (!stopped)
+            output.write(`\x1b[H\x1b[2J${viewer.render(output.columns || 80, output.rows || 24)}`);
+    };
+    const close = () => { stopped = true; finish(); };
+    const update = async () => {
+        if (busy || stopped)
+            return;
+        busy = true;
+        try {
+            await viewer.refresh();
+            draw();
+        }
+        catch {
+            close();
+            process.exitCode = 1;
+        }
+        finally {
+            busy = false;
+        }
+    };
+    const keypress = (text, key) => {
+        if (key?.name === 'q' || key?.ctrl && key.name === 'c') {
+            close();
+            return;
+        }
+        viewer.key(text === 'G' ? 'G' : key?.name ?? text);
+        draw();
+        if (key?.name === 'return')
+            void update();
+    };
+    emitKeypressEvents(input);
+    const timer = setInterval(() => { void update(); }, intervalMs);
+    try {
+        input.setRawMode(true);
+        input.resume();
+        input.on('keypress', keypress);
+        output.on('resize', draw);
+        process.on('SIGINT', close);
+        process.on('SIGTERM', close);
+        output.write('\x1b[?1049h\x1b[?25l');
+        draw();
+        await done;
+    }
+    finally {
+        stopped = true;
+        clearInterval(timer);
+        input.off('keypress', keypress);
+        output.off('resize', draw);
+        process.off('SIGINT', close);
+        process.off('SIGTERM', close);
+        input.setRawMode(wasRaw);
+        // This command owns stdin. A resumed stream would keep Node alive after q.
+        input.pause();
+        output.write('\x1b[?25h\x1b[?1049l');
+    }
+}
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/activity/cli.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,14 @@
+import type { FileHandle } from 'node:fs/promises';
+import { type SessionIdentity } from './types.js';
+export declare const MAX_LINE: number;
+/** Only regular files whose resolved path stays inside the selected directory. */
+export declare function openSession(root: string, file: string): Promise<FileHandle>;
+export declare function readIdentity(root: string, file: string): Promise<SessionIdentity | null>;
+export interface SessionList {
+    root: SessionIdentity | null;
+    helpers: SessionIdentity[];
+    partial: boolean;
+    error: string;
+}
+export declare function listSessions(root: string, rootFile: string, expectedId?: string): Promise<SessionList>;
+//# sourceMappingURL=files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/activity/files.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAU,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAG1D,eAAO,MAAM,QAAQ,QAAY,CAAC;AAGlC,kFAAkF;AAClF,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBjF;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAyB9F;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAsD5G"}