@phnx-labs/agents-cli 1.20.36 → 1.20.37

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.

package/dist/lib/session/discover.js

@@ -459,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,
@@ -485,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,
@@ -693,6 +695,7 @@ export async function readCodexMeta(filePath, resolveAccount, 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,
@@ -887,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,
@@ -1093,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)
@@ -1125,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}`,
@@ -1571,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,
@@ -1692,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,
     };
 }
@@ -1877,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,
@@ -2020,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/relative-time.js

@@ -21,8 +21,12 @@ export function formatRelativeTime(isoTimestamp) {
         return `${diffHrs} hour${diffHrs === 1 ? '' : 's'} ago`;
     if (diffDays < 7)
         return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
-    // Older: show date
+    // Older: show the date. Append a 2-digit year for anything outside the current
+    // year so "Jun 28" is never ambiguous across years (e.g. "Jun 28 '25").
     const d = new Date(then);
     const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-    return `${months[d.getMonth()]} ${d.getDate()}`;
+    const label = `${months[d.getMonth()]} ${d.getDate()}`;
+    return d.getFullYear() === new Date(now).getFullYear()
+        ? label
+        : `${label} '${String(d.getFullYear()).slice(-2)}`;
 }

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

@@ -18,9 +18,9 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
+import { resolveExplicitTargets } from '../devices/resolve-target.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. */
@@ -108,19 +108,9 @@ export async function gatherRemoteActive(hosts) {
     const self = machineId();
     const targets = [];
     if (hosts && hosts.length > 0) {
-        for (const h of hosts) {
-            try {
-                assertValidSshTarget(h);
-            }
-            catch {
-                process.stderr.write(chalk.gray(`  ${h}: not a valid ssh target — skipped\n`));
-                continue;
-            }
-            const bareHost = h.split('@').pop() || 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) });
-        }
+        // Resolve each token through the device registry so an explicit --host/--device
+        // dials the exact same address (and machine id) as the auto-discovery sweep.
+        targets.push(...await resolveExplicitTargets(hosts));
     }
     else {
         let reg;

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

@@ -17,9 +17,9 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
+import { resolveExplicitTargets } from '../devices/resolve-target.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';
 import { NO_FANOUT_ENV } from './remote-active.js';
 import { terminalWidth } from './width.js';
@@ -112,17 +112,9 @@ export async function gatherRemoteList(forwardedArgs, hosts) {
     const self = machineId();
     const targets = [];
     if (hosts && hosts.length > 0) {
-        for (const h of hosts) {
-            try {
-                assertValidSshTarget(h);
-            }
-            catch {
-                process.stderr.write(chalk.gray(`  ${h}: not a valid ssh target — skipped\n`));
-                continue;
-            }
-            const bareHost = h.split('@').pop() || h;
-            targets.push({ target: h, machine: normalizeHost(bareHost), name: h, os: resolveRemoteOsSync(h) });
-        }
+        // Resolve each token through the device registry so an explicit --host/--device
+        // dials the exact same address (and machine id) as the auto-discovery sweep.
+        targets.push(...await resolveExplicitTargets(hosts));
     }
     else {
         let reg;

package/dist/lib/session/remote.js

@@ -63,10 +63,12 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
     const out = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === '--host' || a === '-H') {
+        if (a === '--host' || a === '-H' || a === '--device') {
             // Commander's `<target...>` variadic accepts both `--host a --host b` and
             // `--host a b` — consume every consecutive token that is a known host so
             // the variadic form doesn't leak the extra hosts into the remote argv.
+            // `--device` is an alias for `--host` (its values are merged into the same
+            // host set), so strip it the same way — else the peer would re-fan-out.
             // Fall back to consuming the single next token when we have no host set
             // (e.g. malformed input) so the flag value never leaks either way.
             if (hosts.size > 0) {
@@ -78,7 +80,7 @@ export function buildForwardedArgs(argv, hosts = new Set()) {
             }
             continue;
         }
-        if (a.startsWith('--host=') || a.startsWith('-H='))
+        if (a.startsWith('--host=') || a.startsWith('-H=') || a.startsWith('--device='))
             continue;
         if (/^-H.+/.test(a))
             continue; // glued short form: -Hyosemite-s1

package/dist/lib/session/sync/config.d.ts

@@ -5,6 +5,19 @@
  */
 /** Secrets bundle holding the R2 credentials. */
 export declare const SYNC_BUNDLE = "r2.backups";
+/** Env var that overrides the persisted enable flag (on/off/true/false/1/0/yes/no). */
+export declare const SYNC_ENABLED_ENV = "AGENTS_SESSIONS_SYNC";
+/** Durable, machine-local path holding the sync enable flag. */
+export declare function syncStateFilePath(): string;
+/**
+ * Whether automatic session sync is enabled on this machine. Defaults to true;
+ * an unrecognized env value falls through to the file; an absent/unreadable file
+ * falls through to the default. Read fresh every call (no memoization) so a
+ * `--disable` takes effect on the daemon's next ~90s cycle without a restart.
+ */
+export declare function isSyncEnabled(): boolean;
+/** Persist the machine-local sync enable flag (durable across cache wipes). */
+export declare function setSyncEnabled(enabled: boolean): void;
 export interface R2Config {
     accountId: string;
     bucket: string;

package/dist/lib/session/sync/config.js

@@ -3,9 +3,65 @@
  * machine's stable identity. Credentials come from the `r2.backups` secrets
  * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
  */
+import * as fs from 'fs';
+import * as path from 'path';
 import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+import { getHistoryDir } from '../../state.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
+// ── Enable / disable switch ─────────────────────────────────────────────────
+// Whether the daemon's automatic cross-machine sync (and `agents sync
+// --sessions`) may run on THIS machine. Independent of credential presence
+// (isSyncConfigured): a machine can hold valid R2 creds yet still opt out of the
+// background push/pull — e.g. when on-demand `agents sessions --host` is
+// preferred over the ad-hoc R2 mirror. Manual `agents sessions sync` is an
+// explicit user action and is deliberately NOT gated by this switch.
+//
+// Resolution order: the AGENTS_SESSIONS_SYNC env var (a recognized on/off value
+// wins outright, for ad-hoc overrides and tests), then a durable machine-local
+// flag file, then the default (enabled). The flag lives in the durable
+// ~/.agents/.history tree — NOT .cache — so a cache wipe can never silently
+// re-enable a sync the operator turned off.
+/** Env var that overrides the persisted enable flag (on/off/true/false/1/0/yes/no). */
+export const SYNC_ENABLED_ENV = 'AGENTS_SESSIONS_SYNC';
+const SYNC_ENABLED_FILE = 'sessions-sync.json';
+const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disabled']);
+const ON_VALUES = new Set(['1', 'on', 'true', 'yes', 'enabled']);
+/** Durable, machine-local path holding the sync enable flag. */
+export function syncStateFilePath() {
+    return path.join(getHistoryDir(), SYNC_ENABLED_FILE);
+}
+/**
+ * Whether automatic session sync is enabled on this machine. Defaults to true;
+ * an unrecognized env value falls through to the file; an absent/unreadable file
+ * falls through to the default. Read fresh every call (no memoization) so a
+ * `--disable` takes effect on the daemon's next ~90s cycle without a restart.
+ */
+export function isSyncEnabled() {
+    const envRaw = process.env[SYNC_ENABLED_ENV]?.trim().toLowerCase();
+    if (envRaw) {
+        if (OFF_VALUES.has(envRaw))
+            return false;
+        if (ON_VALUES.has(envRaw))
+            return true;
+        // Unrecognized value: ignore and consult the persisted flag.
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(syncStateFilePath(), 'utf-8'));
+        if (parsed && typeof parsed.enabled === 'boolean')
+            return parsed.enabled;
+    }
+    catch {
+        // Absent or unreadable → default enabled.
+    }
+    return true;
+}
+/** Persist the machine-local sync enable flag (durable across cache wipes). */
+export function setSyncEnabled(enabled) {
+    const p = syncStateFilePath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify({ enabled }, null, 2) + '\n', 'utf-8');
+}
 /**
  * Resolve R2 credentials from the `r2.backups` bundle. Throws a clear,
  * actionable error if the bundle or any key is missing — sync cannot proceed

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

@@ -46,6 +46,12 @@ export interface SessionMeta {
     shortId: string;
     agent: SessionAgentId;
     timestamp: string;
+    /**
+     * Last-activity time (ISO): the last message timestamp when a parser computed
+     * it, else file mtime, else `timestamp`. This is the recency signal the
+     * listing sorts and labels by; `timestamp` stays the creation time.
+     */
+    lastActivity?: string;
     project?: string;
     cwd?: string;
     filePath: string;

package/dist/lib/sync-umbrella.js

@@ -111,10 +111,10 @@ export async function runUmbrellaSync(args) {
         }
     }
     if (plan.fetchSessions) {
-        // Gate exactly like the daemon: a missing r2.backups bundle is a clean no-op,
-        // not an error that fails the whole sync.
-        const { isSyncConfigured } = await import('./session/sync/config.js');
-        if (isSyncConfigured()) {
+        // Gate exactly like the daemon: an off switch or a missing r2.backups bundle
+        // is a clean no-op, not an error that fails the whole sync.
+        const { isSyncConfigured, isSyncEnabled } = await import('./session/sync/config.js');
+        if (isSyncEnabled() && isSyncConfigured()) {
             const { syncSessions } = await import('./session/sync/sync.js');
             const r = await syncSessions();
             result.sessions = { ran: true, pushed: r.pushed, pulled: r.pulled, merged: r.merged };

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

@@ -70,6 +70,16 @@ export declare function killSession(name: string, socket?: string): Promise<bool
  * meta files. Wipes the socket so the next `new` starts from a clean slate.
  */
 export declare function killAll(socket?: string): Promise<number>;
+/**
+ * Map every pane id (`%N`) on a socket to its `session:window.pane` attach
+ * target, in one batched `tmux list-panes -a` call. `%116 -> main:2.0` is a
+ * valid `tmux attach -t main:2` / `tmux select-window -t main:2` target — a
+ * human jump target, unlike the bare `%pane` send-keys id. Because it walks
+ * every pane (not just one-per-session), it also surfaces multiple agents that
+ * share a session across windows. Best-effort: returns an empty map on any
+ * failure (tmux gone, foreign socket) so callers fall back to the raw pane id.
+ */
+export declare function mapPanesToTargets(socket?: string): Promise<Map<string, string>>;
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)