@phnx-labs/agents-cli 1.20.35 → 1.20.36

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

@@ -74,6 +74,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 +121,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. */

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
@@ -464,10 +506,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 +556,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 +609,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 +673,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)
@@ -620,7 +703,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,

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>;
 /**

package/dist/lib/session/provenance.js

@@ -15,9 +15,22 @@
  * (gone, or owned by another uid) yields `undefined`, never a guess.
  *
  * `reply` is a read-only hint, not a send channel: it reports whether a rail
- * that can type back into this session exists today (tmux pane => addressable;
- * inherited/ignored stdin => null). The feed uses it to decide whether to show
- * a Send box. Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ * that can type back into this session exists today and, if so, the exact
+ * address to type into. Two env-derived rails, in precedence order:
+ *
+ *   - tmux  — `$TMUX_PANE` (+ `$TMUX` socket): `tmux send-keys -t <pane>`. Works
+ *             inside ANY host app (a tmux pane can live under iTerm/Ghostty/VS
+ *             Code), so it wins whenever present.
+ *   - iterm — `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:<UUID>`): the exact iTerm2
+ *             split, addressable by its session UUID via `tell session id …`
+ *             (focus-safe, no `activate`). Used when there's no tmux above it.
+ *
+ * Both are inherited env vars, so the split the agent lives in is recovered with
+ * zero cooperation from the agent. Inherited/ignored stdin with neither rail =>
+ * null (not env-addressable — resolution may still find an IDE rail off disk,
+ * see src/lib/terminal/resolve.ts). The feed uses `reply` to decide whether to
+ * show a Send box; the resolver turns it into a concrete inject target (Gap 2,
+ * src/lib/terminal/inject.ts).
  */
 import * as os from 'os';
 import { execFile } from 'child_process';
@@ -32,7 +45,20 @@ export const PROVENANCE_ENV_KEYS = [
     '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 function parseItermSession(value) {
+    if (!value)
+        return undefined;
+    const uuid = value.includes(':') ? value.slice(value.lastIndexOf(':') + 1) : value;
+    return uuid.trim() || undefined;
+}
 /** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
 export function parseProcEnviron(buf) {
     const env = {};
@@ -99,13 +125,18 @@ export function deriveProvenance(env, hostname) {
     else if (env.STY) {
         mux = { kind: 'screen', session: env.STY };
     }
-    // A tmux pane is the one rail that lets an external process type into an
-    // already-running interactive agent (`tmux send-keys -t <pane>`). Everything
-    // else (inherited stdin from `agents run`, ignored stdin from teams) is not
-    // externally addressable without relaunching under a pty/tmux rail.
+    // Env-addressable rails, in precedence order. A tmux pane wins because it can
+    // live inside any host app (`tmux send-keys -t <pane>` reaches it regardless of
+    // whether iTerm/Ghostty/VS Code is above it). Absent tmux, an iTerm2 split is
+    // addressable by its session UUID. Everything else (inherited stdin from
+    // `agents run`, ignored stdin from teams, a plain VS Code integrated terminal)
+    // is not env-addressable — the resolver may still find an IDE rail off disk.
+    const itermSession = parseItermSession(env.ITERM_SESSION_ID);
     const reply = mux?.kind === 'tmux' && mux.pane
         ? { rail: 'tmux', target: mux.pane, socket: mux.socket }
-        : null;
+        : itermSession
+            ? { rail: 'iterm', session: itermSession }
+            : null;
     return {
         host: hostname,
         transport: ssh ? 'ssh' : 'local',

package/dist/lib/session/remote-active.js

@@ -19,6 +19,8 @@ import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { loadDevices } from '../devices/registry.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { machineId, normalizeHost } from './sync/config.js';
 /** Per-host SSH budget. Slightly above SSH_OPTS' ConnectTimeout=10 so a
  * reachable-but-slow remote still answers before we give up. */
@@ -29,8 +31,16 @@ const REMOTE_TIMEOUT_MS = 12_000;
  * on an unknown option. A remote new enough to fan out reads it and stays local.
  */
 export const NO_FANOUT_ENV = 'AGENTS_SESSIONS_LOCAL';
-/** The command run on each peer: answer for itself, as JSON, without recursing. */
-function remoteActiveCommand() {
+/** The command run on each peer: answer for itself, as JSON, without recursing.
+ * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
+ * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`. */
+function remoteActiveCommand(os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({
+            args: ['sessions', '--active', '--json'],
+            env: { [NO_FANOUT_ENV]: '1' },
+        });
+    }
     const inner = `${NO_FANOUT_ENV}=1 agents sessions --active --json`;
     return `bash -lc ${shellQuote(inner)}`;
 }
@@ -80,8 +90,8 @@ function sshCapture(target, remoteCmd, timeoutMs) {
         child.on('close', (code) => done(code));
     });
 }
-async function fetchByTarget(target, machine, display) {
-    const { code, stdout } = await sshCapture(target, remoteActiveCommand(), REMOTE_TIMEOUT_MS);
+async function fetchByTarget(target, machine, display, os) {
+    const { code, stdout } = await sshCapture(target, remoteActiveCommand(os), REMOTE_TIMEOUT_MS);
     if (code !== 0) {
         process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
         return [];
@@ -107,7 +117,9 @@ export async function gatherRemoteActive(hosts) {
                 continue;
             }
             const bareHost = h.split('@').pop() || h;
-            targets.push({ target: h, machine: normalizeHost(bareHost), name: h });
+            // Resolve the OS by the name the user passed (a bare alias like `win-mini`
+            // matches a device-registry entry; a raw `user@host` falls back to POSIX).
+            targets.push({ target: h, machine: normalizeHost(bareHost), name: h, os: resolveRemoteOsSync(h) });
         }
     }
     else {
@@ -129,13 +141,13 @@ export async function gatherRemoteActive(hosts) {
             if (d.platform !== 'windows' && d.platform !== 'linux' && d.platform !== 'macos')
                 continue;
             try {
-                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name });
+                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
             }
             catch {
                 // No address on the profile — nothing to dial; skip silently.
             }
         }
     }
-    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name)));
+    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name, t.os)));
     return { sessions: results.flat(), deviceCount: targets.length };
 }

package/dist/lib/session/remote-list.d.ts

@@ -0,0 +1,51 @@
+import type { SessionMeta } from './types.js';
+/**
+ * The command run on each peer: answer for itself, as JSON, without recursing.
+ * `forwardedArgs` carry the caller's own query/filters (already including the
+ * leading `sessions` and a `--json`) so each peer returns a comparable slice.
+ * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
+ * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
+ */
+export declare function remoteListCommand(forwardedArgs: string[], os?: string): string;
+/**
+ * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
+ * with `machine`. Defensive against version skew / partial output: non-JSON or
+ * a non-array yields `[]`, and non-object entries are dropped rather than
+ * throwing. The `machine` we dialed always wins over any value the peer set on
+ * its own rows, so grouping keys off the computer we asked. Exported for unit
+ * testing without a live tailnet.
+ */
+export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
+export interface RemoteListResult {
+    sessions: SessionMeta[];
+    /** How many peer machines we attempted to reach (drives the empty-fleet tip). */
+    deviceCount: number;
+}
+/**
+ * Gather listing sessions from other machines. With an explicit `hosts` list
+ * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * online devices from `ag devices`, excluding this machine and any without an
+ * address. `forwardedArgs` are the caller's own sessions args (query + filters,
+ * already `--json`) so every peer returns the same slice this machine asked for.
+ */
+export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[]): Promise<RemoteListResult>;
+/** Resolve a peer's SSH target (and OS) from the device registry by its
+ * normalized machine id — the same id the fan-out tags rows with. Returns
+ * undefined when no registered device with an address matches. */
+export declare function resolvePeerTarget(machine: string): Promise<{
+    target: string;
+    os?: string;
+} | undefined>;
+/**
+ * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
+ * stdio). `args` is the full arg vector after the binary — callers pass e.g.
+ * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
+ * picked session lives on another machine: its transcript and agent binary are
+ * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
+ * not via a local `--host` hop, which would discover locally and dead-end for a
+ * session that exists only on the peer. Resolves 'no-target' when the machine
+ * isn't a dialable registered device; the caller surfaces a clear message.
+ */
+export declare function runOnPeer(args: string[], machine: string, opts?: {
+    tty?: boolean;
+}): Promise<'ok' | 'no-target'>;