@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/session/active.js

@@ -31,7 +31,16 @@ import { extractSessionTopic } from './prompt.js';
 import { readSessionTail } from './tail.js';
 import { inferSessionState } from './state.js';
 import { detectProvenance } from './provenance.js';
+import { mapBounded } from '../concurrency.js';
 const execFileAsync = promisify(execFile);
+/**
+ * Per-PID `lsof` probes run bounded and staggered rather than as one parallel
+ * fan-out: a simultaneous system-wide `lsof` burst reads to behavioral EDR
+ * (CrowdStrike Falcon) as lateral-movement recon. Results are identical — the
+ * cwds are just gathered at a bounded spawn rate instead of a single burst.
+ */
+export const LSOF_CONCURRENCY = 4;
+const LSOF_STAGGER_MS = 10;
 const HOME = os.homedir();
 const LIVE_TERMINALS_FILE = path.join(getTerminalsDir(), 'live-terminals.json');
 /**
@@ -49,6 +58,19 @@ const AGENT_CLI_NAMES = {
     opencode: 'opencode',
     droid: 'droid',
 };
+/**
+ * Resolve an agent kind from a process's reported executable. `comm` may be an
+ * absolute path (shim-launched agents), and Windows image names carry an
+ * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
+ */
+function agentKindFromComm(commRaw) {
+    const base = path.basename(commRaw);
+    const stripped = base.replace(/\.exe$/i, '');
+    // Windows image names compare case-insensitively; POSIX comms stay exact —
+    // macOS's Claude desktop app process is named 'Claude' and must NOT match.
+    const key = stripped === base ? base : stripped.toLowerCase();
+    return AGENT_CLI_NAMES[key];
+}
 function isPidAlive(pid) {
     if (!pid || pid < 1)
         return false;
@@ -314,6 +336,7 @@ export async function listTerminalsActive() {
             context: 'terminal',
             kind: t.kind,
             host: detectHost(t.pid, procByPid),
+            tty: procByPid.get(t.pid)?.tty,
             pid: t.pid,
             sessionId: t.sessionId ?? sessionIdFromFile(sessionFile),
             cwd: t.cwd ?? undefined,
@@ -355,14 +378,14 @@ export function listCloudActive() {
  * and a terminal-app is preferred over the multiplexer inside it.
  */
 const HOST_MATCHERS = [
-    // IDE renderers (Electron helper processes)
-    { host: 'code', tokens: ['Code Helper', 'Code - Insiders Helper'] },
-    { host: 'cursor', tokens: ['Cursor Helper'] },
-    { host: 'codium', tokens: ['VSCodium Helper'] },
-    { host: 'windsurf', tokens: ['Windsurf Helper'] },
+    // IDE renderers (Electron helper processes on macOS, image names on Windows)
+    { host: 'code', tokens: ['Code Helper', 'Code - Insiders Helper', 'Code.exe'] },
+    { host: 'cursor', tokens: ['Cursor Helper', 'Cursor.exe'] },
+    { host: 'codium', tokens: ['VSCodium Helper', 'VSCodium.exe'] },
+    { host: 'windsurf', tokens: ['Windsurf Helper', 'Windsurf.exe'] },
     // Native terminal apps
     { host: 'iterm', tokens: ['iTerm2', 'iTermServer', 'iTerm'] },
-    { host: 'terminal', tokens: ['Terminal.app', '/Applications/Utilities/Terminal.app'] },
+    { host: 'terminal', tokens: ['Terminal.app', '/Applications/Utilities/Terminal.app', 'WindowsTerminal.exe'] },
     { host: 'warp', tokens: ['Warp.app', 'stable_'] },
     { host: 'alacritty', tokens: ['alacritty', 'Alacritty'] },
     { host: 'kitty', tokens: ['kitty'] },
@@ -380,25 +403,64 @@ const HOST_MATCHERS = [
  * matching against AGENT_CLI_NAMES.
  */
 async function readProcessTable() {
+    if (process.platform === 'win32')
+        return readProcessTableWin32();
     let out;
     try {
-        ({ stdout: out } = await execFileAsync('ps', ['-A', '-o', 'pid=,ppid=,comm='], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
+        ({ stdout: out } = await execFileAsync('ps', ['-A', '-o', 'pid=,ppid=,tty=,comm='], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
     }
     catch {
         return [];
     }
     const rows = [];
     for (const line of out.split('\n')) {
-        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+        // pid ppid tty comm — tty is a single token ('ttys003', 's003', or '??'/'?'
+        // for none); comm stays last so it may contain spaces.
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
+        if (!m)
+            continue;
+        const pid = parseInt(m[1], 10);
+        const ppid = parseInt(m[2], 10);
+        if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+            continue;
+        const ttyRaw = m[3];
+        const tty = ttyRaw === '??' || ttyRaw === '?' || ttyRaw === '-' ? undefined : ttyRaw;
+        const commRaw = m[4].trim();
+        rows.push({ pid, ppid, tty, comm: commRaw, kind: agentKindFromComm(commRaw) });
+    }
+    return rows;
+}
+/**
+ * Windows process table in one CIM query (`wmic` is removed on current
+ * Windows 11, so PowerShell is the stable interface). Same pid/ppid/comm
+ * shape as the POSIX `ps` snapshot; `Name` is the image name (`claude.exe`).
+ */
+async function readProcessTableWin32() {
+    let out;
+    try {
+        ({ stdout: out } = await execFileAsync('powershell.exe', [
+            '-NoProfile', '-NonInteractive', '-Command',
+            'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name | ConvertTo-Csv -NoTypeInformation',
+        ], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, windowsHide: true }));
+    }
+    catch {
+        return [];
+    }
+    return parseWin32ProcessCsv(out);
+}
+/** Parse `ConvertTo-Csv` output of Win32_Process rows. Exported for tests. */
+export function parseWin32ProcessCsv(out) {
+    const rows = [];
+    for (const line of out.split(/\r?\n/)) {
+        const m = line.trim().match(/^"(\d+)","(\d+)","(.*)"$/);
         if (!m)
             continue;
         const pid = parseInt(m[1], 10);
         const ppid = parseInt(m[2], 10);
         if (!Number.isFinite(pid) || !Number.isFinite(ppid))
             continue;
-        const commRaw = m[3].trim();
-        const kind = AGENT_CLI_NAMES[path.basename(commRaw)];
-        rows.push({ pid, ppid, comm: commRaw, kind });
+        const comm = m[3].replace(/""/g, '"');
+        rows.push({ pid, ppid, comm, kind: agentKindFromComm(comm) });
     }
     return rows;
 }
@@ -418,12 +480,25 @@ function hasAttributedAncestor(pid, ppidMap, attributed) {
     }
     return false;
 }
+/**
+ * Resolve every candidate PID's cwd, bounded and staggered so the probes no
+ * longer fan out as one simultaneous system-wide `lsof` burst (a behavioral-EDR
+ * recon trigger). Order matches the input `pids`. The `probe` seam is injectable
+ * for testing the bound; production always uses the real `lsof`-backed probe.
+ */
+export function resolveCwds(pids, probe = getCwdForPid) {
+    return mapBounded(pids, probe, { concurrency: LSOF_CONCURRENCY, staggerMs: LSOF_STAGGER_MS });
+}
 /**
  * Resolve a process's current working directory via `lsof`. The `-a` flag
  * ANDs the filters; without it macOS treats `-p` and `-d` as a union and
  * returns the cwd of every process on the system.
  */
 async function getCwdForPid(pid) {
+    // No lsof on Windows and no cheap foreign-process cwd API; the pid registry
+    // written by `ag run` supplies the cwd for registry-launched agents instead.
+    if (process.platform === 'win32')
+        return undefined;
     let out;
     try {
         const res = await execFileAsync('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
@@ -470,6 +545,99 @@ const UI_HOSTS = new Set([
     'iterm', 'terminal', 'warp', 'alacritty', 'kitty', 'hyper', 'wezterm', 'ghostty',
     'tmux', 'screen',
 ]);
+/**
+ * Find the launch registry entry recorded by a WRAPPER of this process. The
+ * shim delegate records the pid it spawned, but on Windows the `.cmd` shell
+ * path makes that a cmd.exe intermediary whose child is the real agent binary
+ * — so the agent pid itself has no entry and the wrapper one ancestor up does.
+ * The nearest entry wins, and only if its agent matches the candidate's kind:
+ * a claude session shelling out to codex must not hand codex its identity.
+ */
+export function readAncestorSessionEntry(pid, ppidMap, kind, readEntry = readPidSessionEntry) {
+    let cur = ppidMap.get(pid);
+    const seen = new Set();
+    while (cur && cur > 1 && !seen.has(cur)) {
+        const entry = readEntry(cur);
+        if (entry)
+            return entry.agent === kind ? entry : undefined;
+        seen.add(cur);
+        cur = ppidMap.get(cur);
+    }
+    return undefined;
+}
+/**
+ * Collapse agent processes spawned by another live agent process of the same
+ * kind onto their nearest kept ancestor. Claude runs subagents, forks, and
+ * even its bundled ripgrep as child `claude` processes — on POSIX those
+ * children resolve to the parent's cwd and collapse in dedupeBySession, but
+ * where no cwd can be recovered (Windows has no lsof) every fork would print
+ * as its own headless row. Two exceptions keep their own row: a candidate with
+ * its own registry entry — on its pid OR on a wrapper ancestor strictly below
+ * the pid it would fold into (the shim's entry lands on the cmd.exe
+ * intermediary on Windows) — and a child of a *different* agent kind (claude
+ * shelling out to codex is a real second session, not a fork).
+ * Returns the kept roots plus, per root pid, how many descendants folded in.
+ */
+export function foldSubordinateAgents(candidates, ppidMap, readEntry) {
+    const kindByPid = new Map(candidates.map(c => [c.pid, c.kind]));
+    const nearestSameKindAncestor = (pid, kind) => {
+        let cur = ppidMap.get(pid);
+        const seen = new Set();
+        while (cur && cur > 1 && !seen.has(cur)) {
+            if (kindByPid.get(cur) === kind)
+                return cur;
+            seen.add(cur);
+            cur = ppidMap.get(cur);
+        }
+        return undefined;
+    };
+    // Own launch identity: a matching-kind registry entry on the candidate or on
+    // any wrapper between it and the pid it would fold into (exclusive). Entries
+    // above the fold target belong to that ancestor's session, not this one.
+    const hasOwnSession = (c, stopPid) => {
+        if (readEntry(c.pid)?.agent === c.kind)
+            return true;
+        let cur = ppidMap.get(c.pid);
+        const seen = new Set();
+        while (cur && cur > 1 && cur !== stopPid && !seen.has(cur)) {
+            if (readEntry(cur)?.agent === c.kind)
+                return true;
+            seen.add(cur);
+            cur = ppidMap.get(cur);
+        }
+        return false;
+    };
+    const keptPids = new Set();
+    for (const c of candidates) {
+        const foldTarget = nearestSameKindAncestor(c.pid, c.kind);
+        if (foldTarget === undefined || hasOwnSession(c, foldTarget)) {
+            keptPids.add(c.pid);
+        }
+    }
+    const kept = [];
+    const foldedByRoot = new Map();
+    for (const c of candidates) {
+        if (keptPids.has(c.pid)) {
+            kept.push(c);
+            continue;
+        }
+        // Walk up through folded intermediates to the nearest kept same-kind pid.
+        let cur = nearestSameKindAncestor(c.pid, c.kind);
+        const seen = new Set();
+        while (cur !== undefined && !keptPids.has(cur) && !seen.has(cur)) {
+            seen.add(cur);
+            cur = nearestSameKindAncestor(cur, c.kind);
+        }
+        // A fold target must itself be a kept row (a ppid cycle from pid reuse
+        // can orphan the whole chain) — otherwise keep the row rather than drop it.
+        if (cur === undefined || !keptPids.has(cur)) {
+            kept.push(c);
+            continue;
+        }
+        foldedByRoot.set(cur, (foldedByRoot.get(cur) ?? 0) + 1);
+    }
+    return { kept, foldedByRoot };
+}
 /**
  * Agent processes not attributed to a team or the runtime registry.
  * Classified by walking the ppid chain: any recognised UI ancestor (IDE
@@ -495,16 +663,22 @@ export async function listUnattributedActive(attributed) {
             continue;
         candidates.push({ pid, kind });
     }
-    // Run lsof probes in parallel so N spawns take one round-trip, not N.
-    const cwds = await Promise.all(candidates.map(c => getCwdForPid(c.pid)));
+    // Forks/subagents of a live agent process collapse onto their root before
+    // the cwd probes — fewer spawns, and one session stays one row even when
+    // cwd-based dedupe is unavailable (Windows).
+    const { kept, foldedByRoot } = foldSubordinateAgents(candidates, ppidMap, readPidSessionEntry);
+    // Bounded + staggered lsof probes: same cwds, but a trickle of spawns instead
+    // of one simultaneous system-wide burst that behavioral EDR flags as recon.
+    const cwds = await resolveCwds(kept.map(c => c.pid));
     const out = [];
-    for (let i = 0; i < candidates.length; i++) {
-        const { pid, kind } = candidates[i];
-        // The per-pid registry (written by `ag run`) gives the EXACT session id this
-        // pid was launched with — so N agents in one cwd resolve to N distinct
-        // sessions instead of all collapsing onto the newest .jsonl. Absent (agent
-        // not launched via `ag run`, or one that takes no session id) → heuristic.
-        const entry = readPidSessionEntry(pid);
+    for (let i = 0; i < kept.length; i++) {
+        const { pid, kind } = kept[i];
+        // The per-pid registry (written by `ag run` and the shim delegate) gives
+        // the EXACT session id this pid was launched with — so N agents in one cwd
+        // resolve to N distinct sessions instead of all collapsing onto the newest
+        // .jsonl. The shim's entry may sit on a wrapper ancestor (Windows .cmd
+        // path). Absent entirely (direct launch outside agents-cli) → heuristic.
+        const entry = readPidSessionEntry(pid) ?? readAncestorSessionEntry(pid, ppidMap, kind);
         const cwd = cwds[i] ?? entry?.cwd ?? undefined;
         const sessionFile = findSessionFileForKind(kind, cwd, entry?.sessionId);
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
@@ -515,11 +689,13 @@ export async function listUnattributedActive(attributed) {
             context,
             kind,
             host,
+            tty: procByPid.get(pid)?.tty,
             pid,
             cwd,
             sessionId: entry?.sessionId ?? sessionIdFromFile(sessionFile),
             topic,
             sessionFile,
+            pidCount: 1 + (foldedByRoot.get(pid) ?? 0),
         }, state, sessionFile));
     }
     // Housekeeping: drop registry files for pids that have since died.
@@ -581,10 +757,11 @@ function dedupeBySession(sessions) {
         }
         const existing = byKey.get(key);
         if (existing) {
-            existing.pidCount = (existing.pidCount ?? 1) + 1;
+            // Carry pre-folded fork counts (headless rows arrive with pidCount set).
+            existing.pidCount = (existing.pidCount ?? 1) + (s.pidCount ?? 1);
         }
         else {
-            s.pidCount = 1;
+            s.pidCount = s.pidCount ?? 1;
             byKey.set(key, s);
             out.push(s);
         }

package/dist/lib/session/db.d.ts

@@ -16,6 +16,7 @@ export interface SessionRow {
     version: string | null;
     account: string | null;
     timestamp: string;
+    last_activity: string | null;
     project: string | null;
     cwd: string | null;
     git_branch: string | null;
@@ -144,7 +145,7 @@ export declare function syncTopics(topicMap: Map<string, string>): number;
  * session hasn't been scanned yet — the caller degrades to no live state.
  */
 export declare function latestSessionFileForCwd(agent: SessionAgentId, cwd: string): string | undefined;
-/** Query sessions from the database, applying filters and ordering by timestamp descending. */
+/** Query sessions from the database, applying filters and ordering by last-activity descending (default). */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */
 export declare function countSessions(options?: QueryOptions): number;

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 7;
+const SCHEMA_VERSION = 8;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -46,6 +46,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   version TEXT,
   account TEXT,
   timestamp TEXT NOT NULL,
+  last_activity TEXT,
   project TEXT,
   cwd TEXT,
   git_branch TEXT,
@@ -176,6 +177,17 @@ function migrateSchema(db, fromVersion) {
             db.exec(`ALTER TABLE sessions ADD COLUMN ticket_id TEXT`);
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 8) {
+        // v7 → v8: the listing now sorts and labels by last-activity (last message
+        // time) instead of creation time. Add the column, seed it to `timestamp` so
+        // no row sorts as NULL before the rescan lands, then force a full rescan so
+        // every session gets its true last_activity (from lastTsMs) repopulated.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'last_activity'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN last_activity TEXT`);
+        db.exec(`UPDATE sessions SET last_activity = timestamp WHERE last_activity IS NULL`);
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -202,6 +214,11 @@ export function getDB() {
         migrateSchema(db, currentVersion);
         db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES ('schema_version', ?)`).run(String(SCHEMA_VERSION));
     }
+    // Index last_activity only after the column is guaranteed to exist — fresh DBs
+    // get it from CREATE TABLE above, existing pre-v8 DBs from the migration just
+    // run. It must NOT live in SCHEMA (executed before migration) or an existing
+    // DB would fail the index build on a column it doesn't have yet.
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_sessions_last_activity ON sessions(last_activity DESC)`);
     // One-shot cleanup of the pre-SQLite JSONL indexes. Safe — nothing reads
     // them anymore. Guarded by a meta flag so we only try once.
     const cleaned = db.prepare(`SELECT value FROM meta WHERE key = 'legacy_indexes_removed'`).get();
@@ -383,13 +400,13 @@ export function recordScans(entries) {
 }
 const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
-    id, short_id, agent, version, account, timestamp,
+    id, short_id, agent, version, account, timestamp, last_activity,
     project, cwd, git_branch, topic, label, message_count, token_count,
     cost_usd, duration_ms,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
     pr_url, pr_number, worktree_slug, ticket_id
   ) VALUES (
-    @id, @short_id, @agent, @version, @account, @timestamp,
+    @id, @short_id, @agent, @version, @account, @timestamp, @last_activity,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @cost_usd, @duration_ms,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
@@ -401,6 +418,7 @@ const upsertSessionStmt = (db) => db.prepare(`
     version = excluded.version,
     account = excluded.account,
     timestamp = excluded.timestamp,
+    last_activity = excluded.last_activity,
     project = excluded.project,
     cwd = excluded.cwd,
     git_branch = excluded.git_branch,
@@ -447,6 +465,7 @@ export function upsertSession(meta, content, scan) {
         version: meta.version ?? null,
         account: meta.account ?? null,
         timestamp: meta.timestamp,
+        last_activity: resolveLastActivity(meta, scan),
         project: meta.project ?? null,
         cwd: meta.cwd ?? null,
         git_branch: meta.gitBranch ?? null,
@@ -526,6 +545,7 @@ export function upsertSessionsBatch(entries) {
                 version: meta.version ?? null,
                 account: meta.account ?? null,
                 timestamp: meta.timestamp,
+                last_activity: resolveLastActivity(meta, scan),
                 project: meta.project ?? null,
                 cwd: meta.cwd ?? null,
                 git_branch: meta.gitBranch ?? null,
@@ -641,6 +661,7 @@ function rowToMeta(row) {
         shortId: row.short_id,
         agent: row.agent,
         timestamp: row.timestamp,
+        lastActivity: row.last_activity ?? undefined,
         project: row.project ?? undefined,
         cwd: row.cwd ?? undefined,
         filePath: row.file_path,
@@ -660,6 +681,21 @@ function rowToMeta(row) {
         ticketId: row.ticket_id ?? undefined,
     };
 }
+/**
+ * The recency signal used to sort and label the listing: last-message time when
+ * a parser computed it (`meta.lastActivity` from `lastTsMs`), else the file's
+ * mtime (its last write), else creation time. Guarded on `filePath` so synthetic
+ * / cloud rows (no local file) fall to their creation timestamp rather than a
+ * bogus scan-time mtime. Always an ISO string, so it sorts lexicographically
+ * against `timestamp` and feeds `formatRelativeTime` unchanged.
+ */
+function resolveLastActivity(meta, scan) {
+    if (meta.lastActivity)
+        return meta.lastActivity;
+    if (scan?.fileMtimeMs && meta.filePath)
+        return new Date(scan.fileMtimeMs).toISOString();
+    return meta.timestamp;
+}
 /**
  * Newest indexed session file for an agent working in `cwd`. Lets the live
  * `--active` scanner locate a Codex transcript (whose files are date-partitioned,
@@ -741,7 +777,7 @@ function buildSessionWhere(options) {
     const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
     return { clause, params };
 }
-/** Query sessions from the database, applying filters and ordering by timestamp descending. */
+/** Query sessions from the database, applying filters and ordering by last-activity descending (default). */
 export function querySessions(options = {}) {
     const db = getDB();
     const { clause, params } = buildSessionWhere(options);
@@ -757,7 +793,7 @@ export function querySessions(options = {}) {
         ? 'ORDER BY cost_usd IS NULL, cost_usd DESC, timestamp DESC'
         : options.sortBy === 'duration'
             ? 'ORDER BY duration_ms IS NULL, duration_ms DESC, timestamp DESC'
-            : 'ORDER BY timestamp DESC';
+            : 'ORDER BY IFNULL(last_activity, timestamp) DESC, timestamp DESC';
     const sql = `SELECT * FROM sessions ${clause} ${orderClause} ${limitClause}`;
     const rows = db.prepare(sql).all(...params);
     // Belt-and-suspenders: drop rows whose JSONL no longer exists on disk. The

package/dist/lib/session/discover.d.ts

@@ -50,6 +50,8 @@ interface ClaudeSessionScan {
     costUsd?: number;
     /** Wall-clock duration in ms between the first and last timestamped event. */
     durationMs?: number;
+    /** ISO time of the last timestamped event — the session's last activity. */
+    lastActivity?: string;
     /**
      * Value of the JSONL `entrypoint` field on the first event that carries it.
      * 'cli' for real interactive sessions, 'sdk-cli' for team-spawned ones.
@@ -74,6 +76,22 @@ interface ClaudeSessionScan {
  * TTL, no external lock files needed.
  */
 export declare function discoverSessions(options?: DiscoverOptions): Promise<SessionMeta[]>;
+/**
+ * How many agents' dotfile dirs we scan at once, and the minimum spacing between
+ * successive scan starts. A small bound + stagger turns a simultaneous bulk
+ * multi-dotfile sweep (a behavioral-EDR file-enumeration trigger) into a trickle.
+ */
+export declare const DOTFILE_SCAN_CONCURRENCY = 2;
+/** Run each agent's incremental scan, bounded + staggered. Order is irrelevant (each scan writes its own rows). */
+export declare function scanAgentsBounded<T>(items: readonly T[], run: (item: T) => Promise<void>): Promise<void[]>;
+/**
+ * The machine a discovered session originated on. Cross-machine sync mirrors a
+ * remote transcript to backups/<agent>/<machine>/<subdir>/… (see mirrorPath in
+ * sync/agents.ts); every other transcript is a live-home file on this box. So:
+ * when the path sits under the agent's backups root, the first segment below it
+ * is the origin machine id; otherwise it's the local machine.
+ */
+export declare function machineForSessionFile(filePath: string, agent: string): string;
 /**
  * Count sessions in scope without running an incremental scan. Assumes the DB
  * is already fresh (typically true because `discoverSessions` ran first this
@@ -105,8 +123,29 @@ export declare function getAgentSessionDirs(agent: string, subdir: string): stri
  * recent startedAt.
  */
 export declare function buildClaudeLabelMap(): Map<string, string | null>;
+/**
+ * Base64url-decode a JWT and return its `email` claim, if present. Split out so
+ * the decode is a single, testable step — and so it only runs when someone
+ * actually reads the Codex account (see the lazy resolution below).
+ */
+export declare function decodeJwtEmail(idToken: string): string | undefined;
+/** Test seam: how many times getCodexAccount has actually resolved (decoded) since the last reset. */
+export declare function __codexAccountResolveCountForTest(): number;
+/** Test seam: clear the memoized account + resolve counter so laziness can be observed from a clean slate. */
+export declare function __resetCodexAccountCacheForTest(): void;
 /** Parse the lines of a Codex `session_index.jsonl` into a session id -> title map. */
 export declare function parseCodexThreadNameIndex(raw: string): Map<string, string>;
+/**
+ * Stream-parse a single Codex JSONL file to extract session metadata.
+ *
+ * `resolveAccount` is a lazy thunk (not a resolved string): the JWT decode it
+ * performs is deferred until we know this file is a real session worth building
+ * metadata for, and only then — never during the file walk / stat phase.
+ */
+export declare function readCodexMeta(filePath: string, resolveAccount?: () => string | undefined, currentVersion?: string): Promise<{
+    meta: SessionMeta;
+    content: string;
+} | null>;
 /** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
 export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessionScan>;
 /** Read up to maxLines non-empty lines from the beginning of a file. */