@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/session/discover.js

@@ -23,6 +23,8 @@ import { extractSessionTopic } from './prompt.js';
 import { parseAntigravity } from './parse.js';
 import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand } from './state.js';
 import { costOfUsage } from '../pricing/index.js';
+import { machineId } from './sync/config.js';
+import { mapBounded } from '../concurrency.js';
 import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
 const HOME = os.homedir();
 // Versions can live under either repo: the user repo (current canonical
@@ -56,28 +58,68 @@ export async function discoverSessions(options) {
     const onProgress = options?.onProgress;
     if (tryClaimScan(process.pid)) {
         try {
-            await Promise.all(agents.map(agent => {
-                switch (agent) {
-                    case 'claude': return scanClaudeIncremental(onProgress);
-                    case 'codex': return scanCodexIncremental(onProgress);
-                    case 'gemini': return scanGeminiIncremental(onProgress);
-                    case 'antigravity': return scanAntigravityIncremental(onProgress);
-                    case 'opencode': return scanOpenCodeIncremental();
-                    case 'openclaw': return scanOpenClawIncremental();
-                    case 'rush': return scanRushIncremental(onProgress);
-                    case 'hermes': return scanHermesIncremental(onProgress);
-                    case 'kimi': return scanKimiIncremental(onProgress);
-                    case 'droid': return scanDroidIncremental(onProgress);
-                }
-            }));
+            // Bounded + staggered instead of a single Promise.all: scanning every
+            // agent's dotfile dir (~/.claude, ~/.codex, ~/.gemini, …) simultaneously
+            // reads to behavioral EDR (CrowdStrike Falcon) as a ransomware-style bulk
+            // file-enumeration sweep. Same dirs, same results — just not all at once.
+            await scanAgentsBounded(agents, agent => dispatchAgentScan(agent, onProgress));
         }
         finally {
             releaseScan(process.pid);
         }
     }
     const sessions = querySessions(buildQueryOptions(options, agents, { includeLimit: true }));
+    for (const s of sessions)
+        s.machine = machineForSessionFile(s.filePath, s.agent);
     return sessions;
 }
+/**
+ * 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 const DOTFILE_SCAN_CONCURRENCY = 2;
+const DOTFILE_SCAN_STAGGER_MS = 15;
+/** Run each agent's incremental scan, bounded + staggered. Order is irrelevant (each scan writes its own rows). */
+export function scanAgentsBounded(items, run) {
+    return mapBounded(items, run, {
+        concurrency: DOTFILE_SCAN_CONCURRENCY,
+        staggerMs: DOTFILE_SCAN_STAGGER_MS,
+    });
+}
+/** Dispatch a single agent's incremental dotfile scan. */
+function dispatchAgentScan(agent, onProgress) {
+    switch (agent) {
+        case 'claude': return scanClaudeIncremental(onProgress);
+        case 'codex': return scanCodexIncremental(onProgress);
+        case 'gemini': return scanGeminiIncremental(onProgress);
+        case 'antigravity': return scanAntigravityIncremental(onProgress);
+        case 'opencode': return scanOpenCodeIncremental();
+        case 'openclaw': return scanOpenClawIncremental();
+        case 'rush': return scanRushIncremental(onProgress);
+        case 'hermes': return scanHermesIncremental(onProgress);
+        case 'kimi': return scanKimiIncremental(onProgress);
+        case 'droid': return scanDroidIncremental(onProgress);
+        default: return Promise.resolve();
+    }
+}
+let _localMachineId;
+/**
+ * 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 function machineForSessionFile(filePath, agent) {
+    const base = path.join(getHistoryDir(), 'backups', agent) + path.sep;
+    if (filePath.startsWith(base)) {
+        const seg = filePath.slice(base.length).split(path.sep)[0];
+        if (seg)
+            return seg;
+    }
+    return (_localMachineId ??= machineId());
+}
 /**
  * Count sessions in scope without running an incremental scan. Assumes the DB
  * is already fresh (typically true because `discoverSessions` ran first this
@@ -417,6 +459,7 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             shortId: sessionId.slice(0, 8),
             agent: 'claude',
             timestamp: scan.timestamp,
+            lastActivity: scan.lastActivity,
             project: cwd ? path.basename(cwd) : undefined,
             cwd,
             filePath,
@@ -443,6 +486,7 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             shortId: sessionId.slice(0, 8),
             agent: 'claude',
             timestamp: stat ? stat.mtime.toISOString() : new Date().toISOString(),
+            lastActivity: scan.lastActivity,
             filePath,
             account,
             label,
@@ -464,10 +508,37 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
 // Codex account info
 // ---------------------------------------------------------------------------
 let cachedCodexAccount;
-/** Extract the Codex account email from the JWT id_token in auth.json. */
+/** Number of times the auth.json JWT was actually base64-decoded. Test seam for the lazy-decode contract. */
+let codexAccountResolveCount = 0;
+/**
+ * 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 function decodeJwtEmail(idToken) {
+    const parts = idToken.split('.');
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
+        return typeof payload.email === 'string' ? payload.email : undefined;
+    }
+    catch {
+        return undefined; // malformed JWT
+    }
+}
+/**
+ * Extract the Codex account email from the JWT id_token in auth.json.
+ *
+ * Memoized and resolved LAZILY: the credential-harvesting-shaped JWT decode
+ * (base64-decoding ~/.codex/auth.json) only runs when the account is actually
+ * needed to build a session's metadata — never eagerly during the bulk scan.
+ * A scan with no changed Codex files never touches the auth file.
+ */
 function getCodexAccount() {
     if (cachedCodexAccount !== undefined)
         return cachedCodexAccount || undefined;
+    codexAccountResolveCount++;
     const candidates = [path.join(HOME, '.codex', 'auth.json')];
     for (const root of VERSIONS_ROOTS) {
         const versionsBase = path.join(root, 'versions', 'codex');
@@ -487,27 +558,35 @@ function getCodexAccount() {
             const data = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
             const idToken = data.tokens?.id_token;
             if (idToken) {
-                const parts = idToken.split('.');
-                if (parts.length >= 2) {
-                    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8'));
-                    if (payload.email) {
-                        cachedCodexAccount = payload.email;
-                        return payload.email;
-                    }
+                const email = decodeJwtEmail(idToken);
+                if (email) {
+                    cachedCodexAccount = email;
+                    return email;
                 }
             }
         }
-        catch { /* auth file or JWT malformed */ }
+        catch { /* auth file malformed */ }
     }
     cachedCodexAccount = '';
     return undefined;
 }
+/** Test seam: how many times getCodexAccount has actually resolved (decoded) since the last reset. */
+export function __codexAccountResolveCountForTest() {
+    return codexAccountResolveCount;
+}
+/** Test seam: clear the memoized account + resolve counter so laziness can be observed from a clean slate. */
+export function __resetCodexAccountCacheForTest() {
+    cachedCodexAccount = undefined;
+    codexAccountResolveCount = 0;
+}
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------
 /** Incrementally re-scan changed Codex session files and upsert into the DB. */
 async function scanCodexIncremental(onProgress) {
-    const account = getCodexAccount();
+    // Lazy: getCodexAccount (the auth.json JWT decode) is only resolved by
+    // readCodexMeta when a changed session actually needs it — never eagerly here,
+    // so a no-op scan (changed.length === 0) never touches the credential file.
     const currentVersion = await getCurrentAgentVersion('codex');
     const filePaths = [];
     for (const sessionsDir of getAgentSessionDirs('codex', 'sessions')) {
@@ -532,7 +611,7 @@ async function scanCodexIncremental(onProgress) {
     let parsed = 0;
     for (const { filePath, scan } of changed) {
         try {
-            const result = await readCodexMeta(filePath, account, currentVersion);
+            const result = await readCodexMeta(filePath, getCodexAccount, currentVersion);
             if (result && !seen.has(result.meta.id)) {
                 seen.add(result.meta.id);
                 // Prefer the Codex-generated title over the first-prompt fallback.
@@ -596,8 +675,14 @@ function readCodexThreadNames() {
     }
     return titles;
 }
-/** Stream-parse a single Codex JSONL file to extract session metadata. */
-async function readCodexMeta(filePath, account, currentVersion) {
+/**
+ * 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 async function readCodexMeta(filePath, resolveAccount, currentVersion) {
     const scan = await scanCodexSession(filePath);
     const sessionId = scan.sessionId || '';
     if (!sessionId)
@@ -610,6 +695,7 @@ async function readCodexMeta(filePath, account, currentVersion) {
         // Codex `session_meta` only carries the start time; use file mtime when
         // it's newer so long-running sessions register as recently active.
         timestamp: pickLatestCodexTimestamp(scan.timestamp, filePath),
+        lastActivity: scan.lastActivity,
         project: cwd ? path.basename(cwd) : undefined,
         cwd,
         filePath,
@@ -620,7 +706,7 @@ async function readCodexMeta(filePath, account, currentVersion) {
         tokenCount: scan.tokenCount,
         costUsd: scan.costUsd,
         durationMs: scan.durationMs,
-        account,
+        account: resolveAccount?.(),
         prUrl: scan.prUrl,
         prNumber: scan.prNumber,
         worktreeSlug: scan.worktreeSlug,
@@ -804,6 +890,7 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
         shortId: sessionId.slice(0, 8),
         agent: 'gemini',
         timestamp: startTime || (stat ? stat.mtime.toISOString() : new Date().toISOString()),
+        lastActivity: lastTsMs !== undefined ? new Date(lastTsMs).toISOString() : undefined,
         project,
         cwd,
         filePath,
@@ -1010,6 +1097,7 @@ async function scanOpenCodeIncremental() {
         s.directory,
         s.version,
         s.time_created,
+        s.time_updated,
         COALESCE(stats.message_count, 0),
         stats.token_count,
         COALESCE(stats.has_token_data, 0)
@@ -1042,20 +1130,26 @@ async function scanOpenCodeIncremental() {
         for (const line of out.split('\n')) {
             if (!line.trim())
                 continue;
-            const [id, title, directory, version, timeCreatedStr, messageCountStr, tokenCountStr, hasTokenDataStr] = line.split('|||');
+            const [id, title, directory, version, timeCreatedStr, timeUpdatedStr, messageCountStr, tokenCountStr, hasTokenDataStr] = line.split('|||');
             if (!id)
                 continue;
             const timeCreated = parseInt(timeCreatedStr, 10);
+            const timeUpdated = parseInt(timeUpdatedStr, 10);
             const messageCount = parseInt(messageCountStr, 10);
             const tokenCount = parseInt(tokenCountStr, 10);
             const hasTokenData = hasTokenDataStr === '1';
             const timestamp = isNaN(timeCreated) ? new Date().toISOString() : new Date(timeCreated).toISOString();
+            // OpenCode is one shared DB, not one file per session — its row carries a
+            // per-session updated time. Set lastActivity explicitly (falling back to
+            // creation, never the whole-DB mtime the ScanStamp would otherwise supply).
+            const lastActivity = Number.isNaN(timeUpdated) ? timestamp : new Date(timeUpdated).toISOString();
             const topic = title || undefined;
             const meta = {
                 id,
                 shortId: id.replace(/^ses_/, '').slice(0, 8),
                 agent: 'opencode',
                 timestamp,
+                lastActivity,
                 project: directory ? path.basename(directory) : undefined,
                 cwd: directory ? normalizeCwd(directory) : undefined,
                 filePath: `${OPENCODE_DB}#${id}`,
@@ -1488,6 +1582,7 @@ async function readDroidMeta(filePath, currentVersion) {
         shortId: sessionId.slice(0, 8),
         agent: 'droid',
         timestamp: scan.timestamp || (stat ? stat.mtime.toISOString() : new Date().toISOString()),
+        lastActivity: scan.lastActivity,
         project: cwd ? path.basename(cwd) : undefined,
         cwd,
         filePath,
@@ -1609,6 +1704,7 @@ async function scanDroidSession(filePath) {
         model,
         messageCount,
         durationMs,
+        lastActivity: lastTsMs !== undefined ? new Date(lastTsMs).toISOString() : undefined,
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
     };
 }
@@ -1794,6 +1890,7 @@ export async function scanClaudeSession(filePath) {
         tokenCount: sawTokenCount ? tokenCount : undefined,
         costUsd: sawCost ? costUsd : undefined,
         durationMs,
+        lastActivity: lastTsMs !== undefined ? new Date(lastTsMs).toISOString() : undefined,
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
         prUrl,
         prNumber,
@@ -1937,6 +2034,7 @@ async function scanCodexSession(filePath) {
         tokenCount,
         costUsd,
         durationMs,
+        lastActivity: lastTsMs !== undefined ? new Date(lastTsMs).toISOString() : undefined,
         contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
         prUrl,
         prNumber,

package/dist/lib/session/ghostty-tabs.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Best-effort Ghostty tab-number detection for `agents sessions --active`.
+ *
+ * Ghostty (macOS) exposes read-only AppleScript: every tab has an `index` and a
+ * `name` (title); every surface a `working directory`. It exposes NO per-tab env
+ * var and NO tty/pid on a surface — so a session is matched to its tab by
+ * `working directory` (with title as a tiebreak). This is display sugar only:
+ * one bounded, non-fatal osascript call, run by the renderer, never on the
+ * discovery / --json / --waiting path. Any failure (Ghostty not running,
+ * Automation permission denied, timeout) degrades silently to no tab number.
+ */
+import type { ActiveSession } from './active.js';
+/** One Ghostty surface (terminal), flattened from window -> tab -> surface. */
+export interface GhosttySurface {
+    windowIndex: number;
+    tabIndex: number;
+    cwd: string;
+    title: string;
+}
+/**
+ * Enumerate every Ghostty surface (window/tab/cwd/title) via one read-only
+ * osascript call. Returns [] on ANY failure — Ghostty not running, Automation
+ * permission not granted, timeout, or a parse miss. Never throws, never prompts.
+ */
+export declare function enumerateGhosttyTabs(timeoutMs?: number): Promise<GhosttySurface[]>;
+/**
+ * Assign a Ghostty tab number to each `host === 'ghostty'` session by matching
+ * its cwd to a surface's working directory; ties (same cwd) are broken by title
+ * containment against the session's label/topic/kind. Deliberately conservative:
+ * a session that can't be uniquely resolved gets NO number — a wrong jump target
+ * is worse than none. Pure and unit-tested.
+ */
+export declare function assignGhosttyTabs(sessions: ActiveSession[], surfaces: GhosttySurface[]): Map<ActiveSession, number>;

package/dist/lib/session/ghostty-tabs.js

@@ -0,0 +1,126 @@
+/**
+ * Best-effort Ghostty tab-number detection for `agents sessions --active`.
+ *
+ * Ghostty (macOS) exposes read-only AppleScript: every tab has an `index` and a
+ * `name` (title); every surface a `working directory`. It exposes NO per-tab env
+ * var and NO tty/pid on a surface — so a session is matched to its tab by
+ * `working directory` (with title as a tiebreak). This is display sugar only:
+ * one bounded, non-fatal osascript call, run by the renderer, never on the
+ * discovery / --json / --waiting path. Any failure (Ghostty not running,
+ * Automation permission denied, timeout) degrades silently to no tab number.
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+// Field delimiter: ASCII Unit Separator (0x1F). AppleScript's `tab` keyword does
+// not resolve to a tab byte via `osascript -e`, but `character id 31` does — and
+// 0x1F never appears in a cwd or a tab title, so parsing is unambiguous.
+const ENUM_SCRIPT = `tell application "Ghostty"
+  set fd to (character id 31)
+  set out to ""
+  set wi to 0
+  repeat with w in windows
+    set wi to wi + 1
+    repeat with t in tabs of w
+      set ti to index of t
+      repeat with s in terminals of t
+        set out to out & wi & fd & ti & fd & (working directory of s) & fd & (name of s) & linefeed
+      end repeat
+    end repeat
+  end repeat
+  return out
+end tell`;
+/**
+ * Enumerate every Ghostty surface (window/tab/cwd/title) via one read-only
+ * osascript call. Returns [] on ANY failure — Ghostty not running, Automation
+ * permission not granted, timeout, or a parse miss. Never throws, never prompts.
+ */
+export async function enumerateGhosttyTabs(timeoutMs = 1500) {
+    if (process.platform !== 'darwin')
+        return [];
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync('osascript', ['-e', ENUM_SCRIPT], {
+            timeout: timeoutMs,
+            killSignal: 'SIGKILL',
+            maxBuffer: 1024 * 1024,
+            encoding: 'utf8',
+        }));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of stdout.split('\n')) {
+        if (!line)
+            continue;
+        const f = line.split('\u001f');
+        if (f.length < 4)
+            continue;
+        const windowIndex = parseInt(f[0], 10);
+        const tabIndex = parseInt(f[1], 10);
+        if (!Number.isFinite(windowIndex) || !Number.isFinite(tabIndex))
+            continue;
+        out.push({ windowIndex, tabIndex, cwd: f[2], title: f[3] });
+    }
+    return out;
+}
+/** Trailing-slash-insensitive cwd key. */
+function cwdKey(p) {
+    return (p ?? '').replace(/\/+$/, '');
+}
+/**
+ * Normalize a tab title / hint for containment matching: drop a leading run of
+ * non-alphanumerics (Ghostty prefixes the title with a spinner glyph like `⠐ `
+ * or `✳ ` while the agent runs) and lowercase. Without this, a title that starts
+ * with the session's exact topic still fails a substring test.
+ */
+function normText(s) {
+    return s.replace(/^[^\p{L}\p{N}]+/u, '').toLowerCase().trim();
+}
+/**
+ * Assign a Ghostty tab number to each `host === 'ghostty'` session by matching
+ * its cwd to a surface's working directory; ties (same cwd) are broken by title
+ * containment against the session's label/topic/kind. Deliberately conservative:
+ * a session that can't be uniquely resolved gets NO number — a wrong jump target
+ * is worse than none. Pure and unit-tested.
+ */
+export function assignGhosttyTabs(sessions, surfaces) {
+    const result = new Map();
+    if (surfaces.length === 0)
+        return result;
+    const byCwd = new Map();
+    for (const s of surfaces) {
+        const k = cwdKey(s.cwd);
+        const bucket = byCwd.get(k);
+        if (bucket)
+            bucket.push(s);
+        else
+            byCwd.set(k, [s]);
+    }
+    for (const sess of sessions) {
+        if (sess.host !== 'ghostty')
+            continue;
+        const candidates = byCwd.get(cwdKey(sess.cwd));
+        if (!candidates || candidates.length === 0)
+            continue;
+        if (candidates.length === 1) {
+            result.set(sess, candidates[0].tabIndex);
+            continue;
+        }
+        // Tie: break by title containment (glyph-stripped, lowercased). Hints are
+        // what the session knows about itself; a good hint is >=8 chars so short
+        // fragments don't cause spurious matches.
+        const hints = [sess.label, sess.topic, sess.preview]
+            .filter((h) => !!h && normText(h).length >= 8)
+            .map(normText);
+        const matches = candidates.filter(c => {
+            const title = normText(c.title);
+            return title.length >= 8 && hints.some(h => title.includes(h) || h.includes(title));
+        });
+        // Only assign when the tiebreak is unambiguous (exactly one title match).
+        if (matches.length === 1)
+            result.set(sess, matches[0].tabIndex);
+    }
+    return result;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Session → Terminal-Engine injection adapter.
+ *
+ * The Terminal Engine owns the injection primitive (`injectIntoTerminal`,
+ * src/lib/terminal/inject.ts). This thin adapter maps a session's provenance
+ * `ReplyRail` (the addressable terminal the feed already derives — provenance.ts:47)
+ * to the engine's `InjectTarget`, so a caller can go session → keystrokes in one
+ * hop. Kept on the session side because `ReplyRail` is a session concept; the
+ * engine stays agnostic of how a target was discovered.
+ */
+import type { ReplyRail } from './provenance.js';
+import type { InjectTarget } from '../terminal/inject.js';
+/**
+ * Map a session's `ReplyRail` to an engine `InjectTarget`. Today only tmux rails
+ * are externally addressable (provenance.ts:143-149); a null rail yields null and
+ * the caller must supply a target another way (a pty id, a macOS window).
+ */
+export declare function injectTargetFromReplyRail(rail: ReplyRail): InjectTarget | null;

package/dist/lib/session/inject.js

@@ -0,0 +1,21 @@
+/**
+ * Session → Terminal-Engine injection adapter.
+ *
+ * The Terminal Engine owns the injection primitive (`injectIntoTerminal`,
+ * src/lib/terminal/inject.ts). This thin adapter maps a session's provenance
+ * `ReplyRail` (the addressable terminal the feed already derives — provenance.ts:47)
+ * to the engine's `InjectTarget`, so a caller can go session → keystrokes in one
+ * hop. Kept on the session side because `ReplyRail` is a session concept; the
+ * engine stays agnostic of how a target was discovered.
+ */
+/**
+ * Map a session's `ReplyRail` to an engine `InjectTarget`. Today only tmux rails
+ * are externally addressable (provenance.ts:143-149); a null rail yields null and
+ * the caller must supply a target another way (a pty id, a macOS window).
+ */
+export function injectTargetFromReplyRail(rail) {
+    if (rail && rail.rail === 'tmux') {
+        return { backend: 'tmux', pane: rail.target, socket: rail.socket };
+    }
+    return null;
+}

package/dist/lib/session/parse.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
+import Database from '../sqlite.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
  * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
@@ -875,19 +876,28 @@ const ANTIGRAVITY_TOOL_MAP = {
  * request step and a completion step that share the id).
  */
 export function parseAntigravity(dbPath) {
+    // Read the raw BLOB payloads through the node/bun SQLite wrapper (not the
+    // `sqlite3` CLI) so this works on every OS — the CLI is absent on Windows.
     let rows;
+    let db;
     try {
-        rows = execFileSync('sqlite3', ['-separator', '\t', dbPath, 'SELECT idx, step_type, quote(step_payload) FROM steps ORDER BY idx;'], {
-            encoding: 'utf-8',
-            timeout: 10000,
-            maxBuffer: 64 * 1024 * 1024,
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
+        db = new Database(dbPath);
+        rows = db
+            .prepare('SELECT idx, step_type, step_payload FROM steps ORDER BY idx;')
+            .all();
     }
     catch {
-        /* DB not accessible, sqlite3 missing, or query failed */
+        /* DB not accessible, sqlite module unavailable, or query failed */
         return [];
     }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            /* best-effort close */
+        }
+    }
     // Single timestamp for the whole session: the steps table carries no per-step
     // time column, so fall back to the DB file's mtime for a stable, sortable value.
     let timestamp = new Date().toISOString();
@@ -899,20 +909,13 @@ export function parseAntigravity(dbPath) {
     }
     const events = [];
     const seenCallIds = new Set();
-    for (const line of rows.split('\n')) {
-        if (!line.trim())
-            continue;
-        const tab1 = line.indexOf('\t');
-        if (tab1 === -1)
-            continue;
-        const tab2 = line.indexOf('\t', tab1 + 1);
-        if (tab2 === -1)
-            continue;
-        const hex = line.slice(tab2 + 1).trim();
-        // sqlite3 quote() renders a BLOB as X'...'; anything else (NULL) is skipped.
-        if (!hex.startsWith("X'") || !hex.endsWith("'"))
+    for (const row of rows) {
+        const payload = row.step_payload;
+        // Both node:sqlite and bun:sqlite return a BLOB as a Uint8Array (Buffer is
+        // a subclass). NULL / non-blob payloads are skipped.
+        if (!(payload instanceof Uint8Array))
             continue;
-        const bytes = Uint8Array.from(Buffer.from(hex.slice(2, -1), 'hex'));
+        const bytes = payload;
         let fields;
         try {
             fields = decodeProtoMessage(bytes);

package/dist/lib/session/pid-registry.d.ts

@@ -13,6 +13,7 @@ export interface PidSessionEntry {
     tmuxPane?: string;
     startedAtMs: number;
 }
+export declare function extractSessionIdArg(args: string[]): string | undefined;
 /** Record a launched agent process. Never throws — the registry is an optimization. */
 export declare function writePidSessionEntry(entry: PidSessionEntry): void;
 /** Look up a live pid's recorded session. Returns undefined if absent/corrupt. */

package/dist/lib/session/pid-registry.js

@@ -19,6 +19,30 @@
 import fs from 'fs';
 import path from 'path';
 import { getTerminalsDir } from '../state.js';
+/**
+ * Pull an explicit `--session-id <uuid>` (or `--session-id=<uuid>`) out of a
+ * raw agent arg vector. The transparent shim forwards args untouched, but when
+ * a launcher (Claude Code background jobs, IDE harnesses) already names the
+ * session, recording it gives the same exact pid -> session mapping `ag run`
+ * gets from generating the id itself.
+ */
+const SESSION_ID_VALUE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function extractSessionIdArg(args) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--session-id') {
+            const v = args[i + 1];
+            if (v && SESSION_ID_VALUE_RE.test(v))
+                return v;
+        }
+        else if (a.startsWith('--session-id=')) {
+            const v = a.slice('--session-id='.length);
+            if (SESSION_ID_VALUE_RE.test(v))
+                return v;
+        }
+    }
+    return undefined;
+}
 function pidRegistryDir() {
     return path.join(getTerminalsDir(), 'by-pid');
 }

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

@@ -13,11 +13,16 @@ export interface MuxLocation {
     /** screen session name from $STY, e.g. '12345.pts-0.host'. */
     session?: string;
 }
-/** How the feed can type back into a session, derived from rails that exist today. */
+/** How the feed can type back into a session, derived from env rails that exist today. */
 export type ReplyRail = {
     rail: 'tmux';
     target: string;
     socket?: string;
+}
+/** iTerm2 split addressed by its session UUID (the part of $ITERM_SESSION_ID after ':'). */
+ | {
+    rail: 'iterm';
+    session: string;
 } | null;
 export interface SessionProvenance {
     /** Machine the process runs on — os.hostname(). Drives HOSTS grouping. */
@@ -34,7 +39,14 @@ export interface SessionProvenance {
     reply: ReplyRail;
 }
 /** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
-export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY"];
+export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY", "ITERM_SESSION_ID"];
+/**
+ * Extract the iTerm2 session UUID from `$ITERM_SESSION_ID`, whose value is
+ * `w<window>t<tab>p<pane>:<UUID>` — the `:`-suffix is exactly what iTerm2's
+ * `id of session` returns, so it's the address for `tell session id …`. Returns
+ * undefined for an empty/absent value; tolerates a bare value with no `:`.
+ */
+export declare function parseItermSession(value?: string): string | undefined;
 /** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
 export declare function parseProcEnviron(buf: string): Record<string, string>;
 /**