atoo-studio 0.0.1 → 0.0.2

package/dist/src/agents/lib/fs-tracking.js

@@ -0,0 +1,109 @@
+/**
+ * Shared file-tracking utilities for all agent types.
+ *
+ * Level 1: LD_PRELOAD — intercepts syscalls for precise before-snapshots
+ * Level 2: inotify — kernel-level fs.watch (started via fsMonitor.watchPid)
+ * Level 3: Tool-result fallback — detects Write/Edit/NotebookEdit from JSONL events
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { fsMonitor } from '../../fs-monitor.js';
+const PRELOAD_SO_PATH = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'preload', 'atoo-studio-preload.so');
+const PRELOAD_SOCKET_PATH = path.join(os.homedir(), '.atoo-studio', 'preload.sock');
+/**
+ * Add LD_PRELOAD environment variables to an env record.
+ * Only adds them if the preload .so exists on disk.
+ */
+export function addPreloadEnv(env, preloadSessionId) {
+    if (fs.existsSync(PRELOAD_SO_PATH)) {
+        env.LD_PRELOAD = PRELOAD_SO_PATH;
+        env.ATOO_SESSION_ID = preloadSessionId;
+        env.ATOO_SOCKET_PATH = PRELOAD_SOCKET_PATH;
+        env.UV_USE_IO_URING = '0';
+    }
+}
+/**
+ * Initialize all three levels of file change detection for an agent session.
+ *
+ * Call this after spawning the CLI process and obtaining the envId/pid.
+ */
+export function initFileTracking(opts) {
+    // Level 2: inotify
+    fsMonitor.watchPid(opts.sessionId, opts.pid, opts.cwd);
+    // Level 1: Register preload session mapping (if preload was enabled)
+    if (opts.preloadSessionId) {
+        fsMonitor.registerSessionMapping(opts.preloadSessionId, opts.sessionId);
+    }
+}
+// ═══════════════════════════════════════════════════════
+// Level 3: Tool-result fallback — detect file changes from JSONL events
+// ═══════════════════════════════════════════════════════
+/**
+ * Tracks pending tool_use blocks and detects completed file-modifying tools.
+ * Create one instance per agent session and call `processEvent()` for each
+ * SessionEvent received from the JSONL watcher.
+ */
+export class ToolResultFileTracker {
+    pendingToolUses = new Map();
+    sessionId;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    /**
+     * Process a SessionEvent. Indexes tool_use blocks from assistant messages
+     * and detects tool_result blocks from user messages, notifying fsMonitor
+     * for Write/Edit/NotebookEdit completions.
+     */
+    processEvent(event) {
+        if (event.type === 'assistant') {
+            this.indexToolUses(event);
+        }
+        else if (event.type === 'user') {
+            this.matchToolResults(event);
+        }
+        else if (event.type === 'result') {
+            // Clean up stale pending tool uses at end of turn
+            this.pendingToolUses.clear();
+        }
+    }
+    indexToolUses(event) {
+        const content = event.message?.content;
+        if (!Array.isArray(content))
+            return;
+        for (const block of content) {
+            if (block.type === 'tool_use' && block.id && block.name) {
+                this.pendingToolUses.set(block.id, {
+                    name: block.name,
+                    input: block.input || {},
+                });
+            }
+        }
+    }
+    matchToolResults(event) {
+        const content = event.message?.content;
+        if (!Array.isArray(content))
+            return;
+        for (const block of content) {
+            if (block.type === 'tool_result' && block.tool_use_id) {
+                const toolUse = this.pendingToolUses.get(block.tool_use_id);
+                if (toolUse && !block.is_error) {
+                    this.notifyIfFileChange(toolUse);
+                    this.pendingToolUses.delete(block.tool_use_id);
+                }
+            }
+        }
+    }
+    notifyIfFileChange(toolUse) {
+        const { name, input } = toolUse;
+        if (name === 'Write' && input.file_path) {
+            fsMonitor.notifyToolChange(this.sessionId, input.file_path, 'Write');
+        }
+        else if (name === 'Edit' && input.file_path) {
+            fsMonitor.notifyToolChange(this.sessionId, input.file_path, 'Edit');
+        }
+        else if (name === 'NotebookEdit' && input.notebook_path) {
+            fsMonitor.notifyToolChange(this.sessionId, input.notebook_path, 'Edit');
+        }
+    }
+}

package/dist/src/agents/lib/pty-activity-tracker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PTY-based activity status tracker.
+ *
+ * Encapsulates the burst-detection algorithm that determines whether an
+ * agent session is 'open', 'active', or needs 'attention'.
+ *
+ * Terminal-based agent adapters create an instance and feed it PTY data.
+ * Future non-terminal agents can implement their own status logic without
+ * using this class — the Agent interface only requires emitting status events.
+ */
+export type ActivityStatus = 'open' | 'active' | 'attention';
+export declare class PtyActivityTracker {
+    private onStatusChange;
+    private userIsViewing;
+    private currentStatus;
+    private burstStartTime;
+    private burstPromoted;
+    private burstIdleTimer;
+    private preBurstStatus;
+    constructor(onStatusChange: (status: ActivityStatus) => void);
+    /**
+     * Call when PTY produces output.
+     * Only visible content (after ANSI stripping) counts as activity.
+     */
+    onPtyData(data: string): void;
+    /** Called when the user focuses this session's tab. */
+    onFocused(): void;
+    /** Called when the user leaves this session's tab. */
+    onBlurred(): void;
+    /** Get current activity status. */
+    getStatus(): ActivityStatus;
+    /** Clean up timers. */
+    dispose(): void;
+    /** PTY has been silent for BURST_IDLE_MS — the burst is over. */
+    private onBurstIdle;
+    private setStatus;
+}

package/dist/src/agents/lib/pty-activity-tracker.js

@@ -0,0 +1,105 @@
+/**
+ * PTY-based activity status tracker.
+ *
+ * Encapsulates the burst-detection algorithm that determines whether an
+ * agent session is 'open', 'active', or needs 'attention'.
+ *
+ * Terminal-based agent adapters create an instance and feed it PTY data.
+ * Future non-terminal agents can implement their own status logic without
+ * using this class — the Agent interface only requires emitting status events.
+ */
+const BURST_IDLE_MS = 1000; // 1s of PTY silence = burst ended
+const BURST_PROMOTE_MS = 3000; // 3s of sustained output = real work (not a re-render)
+// Strip standard CSI escape sequences, keep visible characters (including Unicode)
+const ANSI_RE = /\x1b\[[0-9;]*[a-zA-Z]/g;
+export class PtyActivityTracker {
+    onStatusChange;
+    userIsViewing = false;
+    currentStatus = 'open';
+    burstStartTime = null;
+    burstPromoted = false;
+    burstIdleTimer = null;
+    preBurstStatus = 'open';
+    constructor(onStatusChange) {
+        this.onStatusChange = onStatusChange;
+    }
+    /**
+     * Call when PTY produces output.
+     * Only visible content (after ANSI stripping) counts as activity.
+     */
+    onPtyData(data) {
+        const stripped = data.replace(ANSI_RE, '').replace(/[\r\n]+/g, ' ').trim();
+        if (!stripped)
+            return;
+        const now = Date.now();
+        // New burst: record pre-burst status and start time
+        if (this.burstStartTime === null) {
+            this.preBurstStatus = this.currentStatus;
+            this.burstStartTime = now;
+            this.burstPromoted = false;
+        }
+        // Check if burst should be promoted (sustained output >= BURST_PROMOTE_MS)
+        if (!this.burstPromoted && (now - this.burstStartTime) >= BURST_PROMOTE_MS) {
+            this.burstPromoted = true;
+        }
+        // Set active instantly for responsive UX
+        this.setStatus('active');
+        // Reset the idle timer — burst continues as long as data keeps flowing
+        if (this.burstIdleTimer)
+            clearTimeout(this.burstIdleTimer);
+        this.burstIdleTimer = setTimeout(() => this.onBurstIdle(), BURST_IDLE_MS);
+    }
+    /** Called when the user focuses this session's tab. */
+    onFocused() {
+        this.userIsViewing = true;
+        if (this.currentStatus === 'attention') {
+            this.setStatus('open');
+        }
+    }
+    /** Called when the user leaves this session's tab. */
+    onBlurred() {
+        this.userIsViewing = false;
+    }
+    /** Get current activity status. */
+    getStatus() {
+        return this.currentStatus;
+    }
+    /** Clean up timers. */
+    dispose() {
+        if (this.burstIdleTimer) {
+            clearTimeout(this.burstIdleTimer);
+            this.burstIdleTimer = null;
+        }
+    }
+    /** PTY has been silent for BURST_IDLE_MS — the burst is over. */
+    onBurstIdle() {
+        const wasPromoted = this.burstPromoted;
+        // Clear burst tracking
+        this.burstStartTime = null;
+        this.burstPromoted = false;
+        this.burstIdleTimer = null;
+        if (wasPromoted) {
+            if (this.userIsViewing) {
+                this.setStatus('open');
+            }
+            else {
+                this.setStatus('attention');
+            }
+        }
+        else {
+            // Short burst (re-render, keystroke echo) — revert, but respect viewing state
+            if (this.userIsViewing) {
+                this.setStatus('open');
+            }
+            else {
+                this.setStatus(this.preBurstStatus);
+            }
+        }
+    }
+    setStatus(status) {
+        if (status !== this.currentStatus) {
+            this.currentStatus = status;
+            this.onStatusChange(status);
+        }
+    }
+}

package/dist/src/agents/lib/session-id-utils.d.ts

@@ -0,0 +1,46 @@
+export type LinkType = 'chain' | 'fork';
+/**
+ * Strip any prefix (agent_, sess_) and dashes to get raw hex from a session ID.
+ */
+export declare function toRawHex(sessionId: string): string;
+/**
+ * Generate a parent-linked UUID with a chain/fork discriminator.
+ *
+ * Layout: {parent's last 16 hex}{c|f}{random 15 hex} = 32 hex total
+ *
+ * @param parentSessionId - The parent session ID (any format: agent_xxx, sess_xxx, bare UUID)
+ * @param linkType - 'chain' for continuation sessions, 'fork' for branched sessions
+ * @returns A UUID-formatted string with embedded parent link and discriminator
+ */
+export declare function buildLinkedUuid(parentSessionId: string, linkType: LinkType): string;
+/**
+ * Parse the link type from a session ID by inspecting the discriminator at hex position 16.
+ *
+ * @returns 'chain', 'fork', or null if no discriminator is present (root/old-format session)
+ */
+export declare function parseLinkType(sessionId: string): LinkType | null;
+/**
+ * Get the parent link portion (first 16 hex chars) from a session ID.
+ * This corresponds to the parent's last 16 hex chars.
+ */
+export declare function getParentLink(sessionId: string): string;
+/**
+ * Walk a session chain backward from a starting session ID.
+ * Returns all chain-linked session IDs in order from oldest to newest (starting session last).
+ *
+ * Only follows 'chain' links (discriminator 'c'). Fork links are ignored.
+ *
+ * @param sessionId - The session to start walking from
+ * @param allSessionIds - All known session IDs to search through
+ * @returns Array of session IDs forming the chain, oldest first
+ */
+export declare function walkChain(sessionId: string, allSessionIds: string[]): string[];
+/**
+ * Resolve the chain head (most recent session) for a given session ID.
+ * Walks the full chain (backward then forward) and returns the last entry.
+ *
+ * @param sessionId - Any session in the chain
+ * @param allSessionIds - All known session IDs to search through
+ * @returns The most recent session UUID in the chain
+ */
+export declare function resolveChainHead(sessionId: string, allSessionIds: string[]): string;

package/dist/src/agents/lib/session-id-utils.js

@@ -0,0 +1,147 @@
+/**
+ * Session ID utilities for parent-linked UUIDs with chain/fork discrimination.
+ *
+ * Session ID schema:
+ *   {last 16 hex of parent}{discriminator}{random 15 hex} = 32 hex, formatted as UUID
+ *
+ * Discriminator at hex position 16:
+ *   'c' = chain link (continuation session, replaces compaction)
+ *   'f' = fork (branched session)
+ *
+ * Root sessions (no parent) have no discriminator — they're standard UUIDs.
+ */
+import crypto from 'crypto';
+const DISCRIMINATOR = {
+    chain: 'c',
+    fork: 'f',
+};
+/**
+ * Strip any prefix (agent_, sess_) and dashes to get raw hex from a session ID.
+ */
+export function toRawHex(sessionId) {
+    return sessionId.replace(/^(agent_|sess_)/, '').replace(/-/g, '');
+}
+/**
+ * Format 32 hex chars as a UUID string (8-4-4-4-12).
+ */
+function formatAsUuid(hex) {
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join('-');
+}
+/**
+ * Generate a parent-linked UUID with a chain/fork discriminator.
+ *
+ * Layout: {parent's last 16 hex}{c|f}{random 15 hex} = 32 hex total
+ *
+ * @param parentSessionId - The parent session ID (any format: agent_xxx, sess_xxx, bare UUID)
+ * @param linkType - 'chain' for continuation sessions, 'fork' for branched sessions
+ * @returns A UUID-formatted string with embedded parent link and discriminator
+ */
+export function buildLinkedUuid(parentSessionId, linkType) {
+    const parentRaw = toRawHex(parentSessionId);
+    const last16 = parentRaw.slice(-16);
+    const disc = DISCRIMINATOR[linkType];
+    const randomHex = crypto.randomBytes(8).toString('hex').slice(0, 15); // 15 hex chars
+    const newHex = last16 + disc + randomHex;
+    return formatAsUuid(newHex);
+}
+/**
+ * Parse the link type from a session ID by inspecting the discriminator at hex position 16.
+ *
+ * @returns 'chain', 'fork', or null if no discriminator is present (root/old-format session)
+ */
+export function parseLinkType(sessionId) {
+    const hex = toRawHex(sessionId);
+    if (hex.length < 32)
+        return null;
+    const disc = hex[16];
+    if (disc === 'c')
+        return 'chain';
+    if (disc === 'f')
+        return 'fork';
+    return null;
+}
+/**
+ * Get the parent link portion (first 16 hex chars) from a session ID.
+ * This corresponds to the parent's last 16 hex chars.
+ */
+export function getParentLink(sessionId) {
+    return toRawHex(sessionId).slice(0, 16);
+}
+/**
+ * Walk a session chain backward from a starting session ID.
+ * Returns all chain-linked session IDs in order from oldest to newest (starting session last).
+ *
+ * Only follows 'chain' links (discriminator 'c'). Fork links are ignored.
+ *
+ * @param sessionId - The session to start walking from
+ * @param allSessionIds - All known session IDs to search through
+ * @returns Array of session IDs forming the chain, oldest first
+ */
+export function walkChain(sessionId, allSessionIds) {
+    // Build lookup: last16 hex → session ID
+    const last16Map = new Map();
+    for (const id of allSessionIds) {
+        const hex = toRawHex(id);
+        if (hex.length >= 16) {
+            last16Map.set(hex.slice(-16), id);
+        }
+    }
+    const chain = [sessionId];
+    let current = sessionId;
+    // Walk backward: current's first16 = parent's last16, but only if it's a chain link
+    while (true) {
+        const linkType = parseLinkType(current);
+        if (linkType !== 'chain')
+            break;
+        const parentLink = getParentLink(current);
+        const parentId = last16Map.get(parentLink);
+        if (!parentId || parentId === current || chain.includes(parentId))
+            break;
+        chain.unshift(parentId);
+        current = parentId;
+    }
+    return chain;
+}
+/**
+ * Resolve the chain head (most recent session) for a given session ID.
+ * Walks the full chain (backward then forward) and returns the last entry.
+ *
+ * @param sessionId - Any session in the chain
+ * @param allSessionIds - All known session IDs to search through
+ * @returns The most recent session UUID in the chain
+ */
+export function resolveChainHead(sessionId, allSessionIds) {
+    // First walk backward to find the chain root
+    const backwardChain = walkChain(sessionId, allSessionIds);
+    const root = backwardChain[0];
+    // Build forward lookup: parent's last16 hex → child session IDs (chain links only)
+    const childrenOf = new Map();
+    for (const id of allSessionIds) {
+        if (parseLinkType(id) !== 'chain')
+            continue;
+        const parentLink = getParentLink(id);
+        const children = childrenOf.get(parentLink) || [];
+        children.push(id);
+        childrenOf.set(parentLink, children);
+    }
+    // Walk forward from root, following chain children
+    let current = root;
+    const visited = new Set([current]);
+    while (true) {
+        const currentLast16 = toRawHex(current).slice(-16);
+        const children = childrenOf.get(currentLast16) || [];
+        // Filter to unvisited chain children
+        const next = children.find(c => !visited.has(c));
+        if (!next)
+            break;
+        visited.add(next);
+        current = next;
+    }
+    return current;
+}

package/dist/src/agents/lib/session-precreate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Pre-create a Claude Code session JSONL file with a minimal seed conversation.
+ * Claude Code requires at least a user+assistant message pair to accept --resume.
+ *
+ * @returns The generated session UUID
+ */
+export declare function precreateClaudeSession(cwd: string, initialMessage?: string): string;
+/**
+ * Pre-create a Codex session JSONL file by cloning the header (session_meta +
+ * developer prompt) from the most recent real Codex session and replacing the UUID.
+ * Codex requires the real developer prompt (permissions, sandbox config) to accept resume.
+ *
+ * @returns The generated session UUID
+ */
+export declare function precreateCodexSession(cwd: string): string;
+/** Find the most recently modified Codex session JSONL file. */
+export declare function findMostRecentCodexSession(): string | null;

package/dist/src/agents/lib/session-precreate.js

@@ -0,0 +1,177 @@
+/**
+ * Pre-create session files with minimal seed content so the CLI accepts --resume.
+ * The CLI is then started with --resume <uuid>, adopting our pre-created UUID.
+ * This eliminates hook-based or filesystem-based session UUID discovery.
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { v4 as uuidv4 } from 'uuid';
+const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
+const CODEX_SESSIONS_DIR = path.join(os.homedir(), '.codex', 'sessions');
+/**
+ * Pre-create a Claude Code session JSONL file with a minimal seed conversation.
+ * Claude Code requires at least a user+assistant message pair to accept --resume.
+ *
+ * @returns The generated session UUID
+ */
+export function precreateClaudeSession(cwd, initialMessage) {
+    const uuid = uuidv4();
+    const resolvedCwd = path.resolve(cwd);
+    let dirHash = resolvedCwd.replace(/[^a-zA-Z0-9]/g, '-');
+    if (dirHash.length > 200) {
+        const suffix = crypto.createHash('sha256').update(resolvedCwd).digest('hex').slice(0, 12);
+        dirHash = `${dirHash.slice(0, 200)}-${suffix}`;
+    }
+    const projectDir = path.join(CLAUDE_PROJECTS_DIR, dirHash);
+    const now = new Date().toISOString();
+    const userUuid = uuidv4();
+    const assistantUuid = uuidv4();
+    let greeting = 'Hello from Atoo Studio — Agentic Development Environment!';
+    if (initialMessage) {
+        greeting += '\n\n' + initialMessage;
+    }
+    const userEvent = JSON.stringify({
+        parentUuid: null,
+        isSidechain: false,
+        userType: 'external',
+        cwd: resolvedCwd,
+        sessionId: uuid,
+        type: 'user',
+        message: { role: 'user', content: greeting },
+        uuid: userUuid,
+        timestamp: now,
+        permissionMode: 'bypassPermissions',
+    });
+    const assistantEvent = JSON.stringify({
+        parentUuid: userUuid,
+        isSidechain: false,
+        userType: 'external',
+        cwd: resolvedCwd,
+        sessionId: uuid,
+        type: 'assistant',
+        message: {
+            role: 'assistant',
+            content: [{ type: 'text', text: 'Hello! How can I help you today?' }],
+            model: 'claude-sonnet-4-6',
+            stop_reason: 'end_turn',
+        },
+        uuid: assistantUuid,
+        timestamp: now,
+    });
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(path.join(projectDir, `${uuid}.jsonl`), userEvent + '\n' + assistantEvent + '\n', { mode: 0o600 });
+    return uuid;
+}
+/**
+ * Pre-create a Codex session JSONL file by cloning the header (session_meta +
+ * developer prompt) from the most recent real Codex session and replacing the UUID.
+ * Codex requires the real developer prompt (permissions, sandbox config) to accept resume.
+ *
+ * @returns The generated session UUID
+ */
+export function precreateCodexSession(cwd) {
+    const uuid = uuidv4();
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(now.getUTCDate()).padStart(2, '0');
+    const timestamp = now.toISOString().replace(/:/g, '-').replace(/\.\d+Z$/, '');
+    const dateDir = path.join(CODEX_SESSIONS_DIR, String(year), month, day);
+    fs.mkdirSync(dateDir, { recursive: true });
+    const filename = `rollout-${timestamp}-${uuid}.jsonl`;
+    const targetPath = path.join(dateDir, filename);
+    // Find the most recent real Codex session to clone its header from
+    const donorFile = findMostRecentCodexSession();
+    if (donorFile) {
+        // Read the first 2 lines (session_meta + developer prompt) from the donor
+        const content = fs.readFileSync(donorFile, 'utf-8');
+        const lines = content.split('\n').filter(l => l.trim());
+        const headerLines = lines.slice(0, 2);
+        // Replace the donor's UUID and cwd with our new values in both lines
+        const donorUuid = extractCodexUuid(headerLines[0]);
+        const resolvedCwd = path.resolve(cwd);
+        const newHeader = headerLines
+            .map(line => {
+            if (donorUuid)
+                line = line.replace(new RegExp(donorUuid, 'g'), uuid);
+            // Update cwd in session_meta payload
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed?.type === 'session_meta' && parsed?.payload?.cwd) {
+                    parsed.payload.cwd = resolvedCwd;
+                    return JSON.stringify(parsed);
+                }
+            }
+            catch { }
+            return line;
+        })
+            .join('\n') + '\n';
+        fs.writeFileSync(targetPath, newHeader, { mode: 0o600 });
+    }
+    else {
+        // No donor session found — write minimal session_meta (may not resume, but won't crash)
+        const sessionMeta = JSON.stringify({
+            timestamp: now.toISOString(),
+            type: 'session_meta',
+            payload: {
+                id: uuid,
+                timestamp: now.toISOString(),
+                cwd: path.resolve(cwd),
+                originator: 'codex_cli_rs',
+                source: 'cli',
+                model_provider: 'openai',
+                git: {},
+            },
+        });
+        fs.writeFileSync(targetPath, sessionMeta + '\n', { mode: 0o600 });
+    }
+    return uuid;
+}
+/** Find the most recently modified Codex session JSONL file. */
+export function findMostRecentCodexSession() {
+    try {
+        let best = null;
+        // Walk ~/.codex/sessions/YYYY/MM/DD/ directories (most recent first)
+        const years = fs.readdirSync(CODEX_SESSIONS_DIR).sort().reverse();
+        for (const year of years.slice(0, 2)) {
+            const yearDir = path.join(CODEX_SESSIONS_DIR, year);
+            const months = fs.readdirSync(yearDir).sort().reverse();
+            for (const month of months.slice(0, 2)) {
+                const monthDir = path.join(yearDir, month);
+                const days = fs.readdirSync(monthDir).sort().reverse();
+                for (const day of days.slice(0, 3)) {
+                    const dayDir = path.join(monthDir, day);
+                    const files = fs.readdirSync(dayDir).filter(f => f.endsWith('.jsonl'));
+                    for (const f of files) {
+                        const filePath = path.join(dayDir, f);
+                        try {
+                            const stat = fs.statSync(filePath);
+                            if (!best || stat.mtimeMs > best.mtime) {
+                                best = { path: filePath, mtime: stat.mtimeMs };
+                            }
+                        }
+                        catch { }
+                    }
+                }
+                if (best)
+                    return best.path; // Found recent files, no need to keep searching
+            }
+        }
+        return best?.path ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Extract the session UUID from a Codex session_meta JSON line. */
+function extractCodexUuid(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return parsed?.payload?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}