@phnx-labs/agents-cli 1.20.36 → 1.20.37

package/dist/commands/sessions-sync.d.ts

@@ -7,6 +7,9 @@ import type { Command } from 'commander';
 interface SyncCmdOptions {
     verbose?: boolean;
     json?: boolean;
+    enable?: boolean;
+    disable?: boolean;
+    status?: boolean;
 }
 export declare function runSessionsSync(options: SyncCmdOptions): Promise<void>;
 export declare function registerSessionsSyncCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-sync.js

@@ -5,9 +5,34 @@
  */
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
-import { isSyncConfigured, SYNC_BUNDLE } from '../lib/session/sync/config.js';
+import { isSyncConfigured, isSyncEnabled, setSyncEnabled, SYNC_BUNDLE, } from '../lib/session/sync/config.js';
 import { syncSessions } from '../lib/session/sync/sync.js';
 export async function runSessionsSync(options) {
+    // Toggle / status actions short-circuit before any network cycle.
+    if (options.disable) {
+        setSyncEnabled(false);
+        console.log(chalk.yellow('Automatic session sync disabled') +
+            chalk.dim(' — the daemon stops pushing/pulling within ~90s. Re-enable: agents sessions sync --enable'));
+        return;
+    }
+    if (options.enable) {
+        setSyncEnabled(true);
+        console.log(chalk.green('Automatic session sync enabled') + chalk.dim(' — the daemon resumes on its next cycle.'));
+        return;
+    }
+    if (options.status) {
+        const enabled = isSyncEnabled();
+        const configured = isSyncConfigured();
+        if (options.json) {
+            console.log(JSON.stringify({ enabled, configured }, null, 2));
+        }
+        else {
+            console.log(`automatic sync: ${enabled ? chalk.green('enabled') : chalk.yellow('disabled')}` +
+                chalk.dim('  ·  ') +
+                `credentials: ${configured ? chalk.green('configured') : chalk.yellow(`missing (${SYNC_BUNDLE})`)}`);
+        }
+        return;
+    }
     if (!isSyncConfigured()) {
         console.error(chalk.red(`Sessions sync is not configured.`) +
             `\nAdd R2 credentials to the '${SYNC_BUNDLE}' bundle:\n` +
@@ -51,7 +76,10 @@ export function registerSessionsSyncCommand(sessionsCmd) {
         .command('sync')
         .description('Sync session transcripts across machines via R2 (CRDT merge). Claude and Codex.')
         .option('-v, --verbose', 'Log each pushed and pulled session')
-        .option('--json', 'Output the sync result as JSON');
+        .option('--json', 'Output the sync result as JSON')
+        .option('--enable', 'Turn ON automatic background sync on this machine (persisted)')
+        .option('--disable', 'Turn OFF automatic background sync on this machine (persisted)')
+        .option('--status', 'Show whether automatic sync is enabled and configured');
     setHelpSections(syncCmd, {
         examples: `
       # One sync cycle (push local changes, pull + merge from other machines)
@@ -59,15 +87,27 @@ export function registerSessionsSyncCommand(sessionsCmd) {
 
       # See exactly what moved
       agents sessions sync --verbose
+
+      # Stop this machine's daemon from auto-syncing (prefer on-demand --host reads)
+      agents sessions sync --disable
+
+      # Check the current switch + credential state
+      agents sessions sync --status
     `,
         notes: `
       - Credentials come from the '${SYNC_BUNDLE}' secrets bundle (R2 S3 API, read+write).
       - Each machine writes only its own prefix; conflicts are impossible by construction.
       - The daemon runs this automatically (~90s); this command forces an immediate cycle.
       - Sessions present locally always win; synced-in copies fill in other machines' sessions.
+      - --disable/--enable persist a machine-local switch (~/.agents/.history) that gates the
+        daemon's automatic sync; a bare 'agents sessions sync' still forces a manual cycle.
+        The AGENTS_SESSIONS_SYNC env var (on/off) overrides the switch for one invocation.
     `,
     });
-    syncCmd.action(async (options) => {
-        await runSessionsSync(options);
+    // `--json` is also declared on the parent `sessions` command, so a bare
+    // `options` arg would miss it (Commander binds the shared flag to the parent).
+    // optsWithGlobals() merges ancestor + local options so --json resolves here.
+    syncCmd.action(async (_options, cmd) => {
+        await runSessionsSync(cmd.optsWithGlobals());
     });
 }

package/dist/commands/sessions.d.ts

@@ -2,6 +2,13 @@ import type { Command } from 'commander';
 import type { SessionAgentId, SessionMeta } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { type PickedSession } from './sessions-picker.js';
+/**
+ * Strip terminal/harness noise from a preview so the column stays a single line
+ * of plain prose: OSC title escapes, CSI/SGR ANSI, and the harness wrapper tags
+ * (`<local-command-stdout>`, `<task-notification>`, `<command-*>`) that leak from
+ * a captured transcript tail. Collapses runs of whitespace.
+ */
+export declare function cleanPreview(text: string): string;
 /**
  * Index live sessions by their full session UUID so a historical `SessionMeta`
  * row (`meta.id`) can be matched to the session that is still running now.

package/dist/commands/sessions.js

@@ -17,6 +17,8 @@ import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
 import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, findExecutable } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
+import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
+import { mapPanesToTargets } from '../lib/tmux/session.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
@@ -39,6 +41,24 @@ import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
+/**
+ * The prioritized harnesses that get a boolean shorthand flag (e.g. `--claude`
+ * === `--agent claude`). The rest stay reachable via `--agent <name>`, which
+ * also carries version pins like `codex@0.116.0`.
+ */
+const AGENT_SHORTHANDS = ['claude', 'codex', 'kimi', 'antigravity', 'grok', 'opencode'];
+/**
+ * Resolve a per-agent shorthand (`--claude`, `--kimi`, …) into `options.agent`.
+ * An explicit `--agent` wins; if two shorthands are passed we take the first and
+ * ignore the rest (commander gives no ordering, so this is a best-effort alias).
+ */
+function applyAgentShorthands(options) {
+    if (options.agent)
+        return;
+    const hit = AGENT_SHORTHANDS.find((name) => options[name] === true);
+    if (hit)
+        options.agent = hit;
+}
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
 const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
 const FIND_VERBS = ['Finding', 'Searching', 'Locating', 'Matching'];
@@ -174,13 +194,28 @@ function formatStartedAt(startedAtMs) {
         return '-';
     return formatRelativeTime(new Date(startedAtMs).toISOString());
 }
+/**
+ * Strip terminal/harness noise from a preview so the column stays a single line
+ * of plain prose: OSC title escapes, CSI/SGR ANSI, and the harness wrapper tags
+ * (`<local-command-stdout>`, `<task-notification>`, `<command-*>`) that leak from
+ * a captured transcript tail. Collapses runs of whitespace.
+ */
+export function cleanPreview(text) {
+    // eslint-disable-next-line no-control-regex
+    return text
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '') // OSC (title) sequences
+        .replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '') // CSI / SGR ANSI
+        .replace(/<\/?(?:local-command-stdout|command-name|command-message|command-args|task-notification|system-reminder)>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 /**
  * Build the live description for an active session: prefer the state engine's
  * preview (the latest turn), then a user label, then the first-prompt topic.
  */
 function buildSessionDescription(s) {
     if (s.context === 'cloud') {
-        return s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
+        return cleanPreview(s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`);
     }
     if (s.context === 'teams') {
         const parts = [s.teamName];
@@ -190,10 +225,10 @@ function buildSessionDescription(s) {
             parts.push(s.label);
         else if (s.topic)
             parts.push(s.topic);
-        return parts.filter(Boolean).join(' · ');
+        return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal or headless: prefer the live preview, then label, then topic.
-    return s.preview || s.label || s.topic || '';
+    return cleanPreview(s.preview || s.label || s.topic || '');
 }
 /** Short human word for a session's activity (falls back to the coarse status). */
 function activityLabel(s) {
@@ -264,20 +299,25 @@ function signalBadges(s) {
     return parts.join(' ');
 }
 /**
- * Compact provenance badge: how to reach the session, not what it's doing.
- * `ssh` flags a remote host; the tmux pane id is the send-keys target the feed
- * would type back into. Local, non-tmux sessions add nothing (the common case).
+ * Compact locator badge: how to JUMP to the session, not what it's doing.
+ * `ssh` flags a remote host. For tmux, prefer the resolved `session:window.pane`
+ * (a real `tmux attach -t <session:window>` target) over the raw `%pane` id. For
+ * a local Ghostty session we know the tab, show `tab N`. Local, unlocatable
+ * sessions add nothing (the common case).
  */
-function provenanceBadge(p) {
-    if (!p)
-        return '';
+function locatorBadge(s) {
+    const p = s.provenance;
     const parts = [];
-    if (p.transport === 'ssh')
+    if (p?.transport === 'ssh')
         parts.push(chalk.red('ssh'));
-    if (p.mux?.kind === 'tmux' && p.mux.pane)
-        parts.push(chalk.green(`tmux ${p.mux.pane}`));
-    else if (p.mux?.kind === 'screen')
+    if (p?.mux?.kind === 'tmux' && (s.tmuxTarget || p.mux.pane)) {
+        parts.push(chalk.green(s.tmuxTarget ?? p.mux.pane));
+    }
+    else if (p?.mux?.kind === 'screen') {
         parts.push(chalk.green('screen'));
+    }
+    if (s.ghosttyTab != null)
+        parts.push(chalk.green(`tab ${s.ghosttyTab}`));
     return parts.join(' ');
 }
 /**
@@ -293,7 +333,7 @@ function printActiveRow(s, indent) {
     const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
     const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
     const fork = s.pidCount && s.pidCount > 1 ? chalk.dim(`×${s.pidCount} `) : '';
-    const badges = (fork ? fork : '') + [signalBadges(s), provenanceBadge(s.provenance)].filter(Boolean).join(' ');
+    const badges = (fork ? fork : '') + [signalBadges(s), locatorBadge(s)].filter(Boolean).join(' ');
     const desc = buildSessionDescription(s) || '-';
     // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
     const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);
@@ -466,6 +506,27 @@ export function mergeLocalFirst(sessions, localMachine) {
     });
     return keys.flatMap((k) => byMachine.get(k));
 }
+/**
+ * `running N · idle N · waiting N · queued N` for a bucket of sessions (zero
+ * buckets omitted). Same bucketing as the grand-total summary so per-group
+ * counts reconcile with the `(total)` beside the header. Empty when nothing.
+ */
+function groupTally(sessions) {
+    const running = sessions.filter(s => s.status === 'running').length;
+    const idle = sessions.filter(s => s.status === 'idle').length;
+    const waiting = sessions.filter(s => s.status === 'input_required').length;
+    const queued = sessions.filter(s => s.status === 'queued').length;
+    const parts = [];
+    if (running)
+        parts.push(`${running} running`);
+    if (idle)
+        parts.push(`${idle} idle`);
+    if (waiting)
+        parts.push(`${waiting} waiting`);
+    if (queued)
+        parts.push(`${queued} queued`);
+    return parts.join(' · ');
+}
 /** Print one machine's workspace tree, indented under its machine header. */
 function renderWorkspaceLayout(layout, base) {
     let first = true;
@@ -478,7 +539,9 @@ function renderWorkspaceLayout(layout, base) {
             : ws.key === '__unknown__'
                 ? chalk.gray.bold('unknown')
                 : chalk.cyan.bold(shortCwd(ws.key));
-        console.log(`${base}${header} ${chalk.gray(`(${ws.total})`)}`);
+        const wsSessions = [...ws.windows.flatMap(w => w.sessions), ...ws.flat];
+        const tally = groupTally(wsSessions);
+        console.log(`${base}${header} ${chalk.gray(`(${ws.total})`)}${tally ? chalk.gray(`  ${tally}`) : ''}`);
         for (const win of ws.windows) {
             // Host is per-process, but every terminal in the same IDE window shares
             // an ancestor — take the first non-empty host as the window's label.
@@ -500,6 +563,43 @@ function printMachineHeader(mg) {
     const here = mg.isLocal ? chalk.cyan('  ← this machine') : '';
     console.log(`${marker}${name} ${chalk.gray(`(${mg.total})`)}${here}`);
 }
+/**
+ * Attach display-only jump locators onto LOCAL sessions: the Ghostty tab number
+ * (one batched read-only osascript, only when a local ghostty session exists)
+ * and the tmux `session:window.pane` target (one `list-panes -a` per socket).
+ * Every step is best-effort and swallowed — a failure just leaves the raw pane
+ * id / no tab number, and the rows render as before. Mutates the sessions.
+ */
+async function enrichLocalLocators(local) {
+    // Ghostty tab numbers.
+    try {
+        const ghostty = local.filter(s => s.host === 'ghostty' && s.provenance?.transport !== 'ssh');
+        if (ghostty.length > 0) {
+            const surfaces = await enumerateGhosttyTabs();
+            for (const [sess, tab] of assignGhosttyTabs(ghostty, surfaces))
+                sess.ghosttyTab = tab;
+        }
+    }
+    catch { /* non-fatal */ }
+    // tmux attach targets, one batched query per distinct socket.
+    try {
+        const tmux = local.filter(s => s.provenance?.mux?.kind === 'tmux' && s.provenance.mux.pane);
+        const sockets = new Set(tmux.map(s => s.provenance.mux.socket));
+        for (const socket of sockets) {
+            const paneMap = await mapPanesToTargets(socket);
+            if (paneMap.size === 0)
+                continue;
+            for (const s of tmux) {
+                if (s.provenance.mux.socket !== socket)
+                    continue;
+                const target = paneMap.get(s.provenance.mux.pane);
+                if (target)
+                    s.tmuxTarget = target;
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+}
 /**
  * Render the unified active-session view, grouped by machine. Local sessions
  * come from `getActiveSessions()`; unless `--local`, sessions from other
@@ -535,6 +635,10 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
             printCrossMachineTip();
         return;
     }
+    // Enrich LOCAL sessions with jump locators (display-only, after the --json /
+    // --waiting gates so scriptable output stays osascript-free). Remote sessions
+    // keep their raw pane id — their tmux/Ghostty live on the other machine.
+    await enrichLocalLocators(sessions.filter(s => !s.machine || s.machine === self));
     const grouped = groupSessionsByMachine(sessions, self);
     let firstMachine = true;
     for (const mg of grouped.machines) {
@@ -544,16 +648,7 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
         printMachineHeader(mg);
         renderWorkspaceLayout(mg.layout, '  ');
     }
-    const runningCount = sessions.filter(s => s.status === 'running').length;
-    const idleCount = sessions.filter(s => s.status === 'idle').length;
-    const queuedCount = sessions.filter(s => s.status === 'queued' || s.status === 'input_required').length;
-    const parts = [];
-    if (runningCount > 0)
-        parts.push(`${runningCount} running`);
-    if (idleCount > 0)
-        parts.push(`${idleCount} idle`);
-    if (queuedCount > 0)
-        parts.push(`${queuedCount} queued`);
+    const parts = groupTally(sessions).split(' · ').filter(Boolean);
     const machineWord = grouped.machines.length === 1 ? 'machine' : 'machines';
     console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}) across ${grouped.machines.length} ${machineWord}.`));
     // Tip only when nothing else could be included and the user didn't opt out.
@@ -569,6 +664,13 @@ function printCrossMachineTip() {
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    // Normalize convenience flags before any routing reads them: per-agent
+    // shorthands fold into --agent, and --device is an alias for --host (both
+    // resolve against the same device registry).
+    applyAgentShorthands(options);
+    if (options.device && options.device.length > 0) {
+        options.host = [...(options.host ?? []), ...options.device];
+    }
     // --host WITHOUT --active keeps the legacy per-host stream (each remote's raw
     // stdout under a `── host ──` banner). With --active, the hosts are folded
     // into the merged machine-grouped view instead (handled below).
@@ -666,9 +768,12 @@ async function sessionsAction(query, options) {
         const scope = {
             agent,
             version,
-            all: pathFilter ? undefined : (wantsOverview ? true : options.all),
+            all: pathFilter ? undefined : options.all,
             cwd: process.cwd(),
-            cwdPrefix: pathFilter,
+            // Default overview scopes to the current repo SUBTREE (prefix match), so a
+            // monorepo shows its sub-projects grouped instead of collapsing to the one
+            // exact-cwd project. `--all` clears the prefix and spans the whole index.
+            cwdPrefix: pathFilter ?? (wantsOverview && !options.all ? process.cwd() : undefined),
             project: options.project,
             since,
             until: options.until,
@@ -819,7 +924,7 @@ function metaSignals(s) {
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
 function flatSessionRow(session, live, showTicket = false, cols = {}) {
     const agentColor = colorAgent(session.agent);
-    const when = formatRelativeTime(session.timestamp);
+    const when = formatRelativeTime(session.lastActivity ?? session.timestamp);
     const project = session.project || '-';
     const tag = teamTag(session);
     const label = session.label;
@@ -858,7 +963,7 @@ function flatSessionRow(session, live, showTicket = false, cols = {}) {
 /** One tree-mode row (grouped under a dir header): id · agent · badges · topic · time. No version/project column. */
 function treeSessionRow(session, live) {
     const agentColor = colorAgent(session.agent);
-    const when = formatRelativeTime(session.timestamp);
+    const when = formatRelativeTime(session.lastActivity ?? session.timestamp);
     const tag = teamTag(session);
     const label = session.label;
     const { glyph, preview } = liveGlyphAndPreview(live);
@@ -928,7 +1033,7 @@ export function buildOverviewGroups(pool, perProjectCap) {
     const groups = [];
     for (const [key, rows] of byKey) {
         const shown = rows.slice(0, cap); // rows are recency-desc (pool was sorted)
-        groups.push({ key, total: rows.length, shown, more: rows.length - shown.length, maxTs: rows[0].timestamp });
+        groups.push({ key, total: rows.length, shown, more: rows.length - shown.length, maxTs: rows[0].lastActivity ?? rows[0].timestamp });
     }
     groups.sort((a, b) => (a.maxTs < b.maxTs ? 1 : a.maxTs > b.maxTs ? -1 : a.key.localeCompare(b.key)));
     return { groups, projectCount: byKey.size };
@@ -960,10 +1065,10 @@ function printSessionOverview(pool, hiddenCount, liveIndex, opts) {
             console.log('  ' + chalk.gray(`· ${g.more} more`));
     }
     console.log();
-    const parts = [chalk.gray('newest first')];
+    const parts = [chalk.gray('newest first (by last activity)')];
     if (hiddenProjects > 0)
-        parts.push(chalk.gray(`+${hiddenProjects} more project${hiddenProjects === 1 ? '' : 's'} · agents sessions --all`));
-    parts.push(chalk.gray('agents sessions <project> to drill in · --flat for the plain list'));
+        parts.push(chalk.gray(`+${hiddenProjects} more project${hiddenProjects === 1 ? '' : 's'}`));
+    parts.push(chalk.gray('agents sessions --all spans every project on disk · <project> to drill in · --flat for the plain list'));
     console.log(parts.join(chalk.gray('  ·  ')));
     if (hiddenCount > 0)
         console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
@@ -1213,7 +1318,7 @@ export function pickerColumnsFor(sessions) {
 }
 export function formatPickerLabel(s, query, cols = {}) {
     const agentColor = colorAgent(s.agent);
-    const when = formatRelativeTime(s.timestamp);
+    const when = formatRelativeTime(s.lastActivity ?? s.timestamp);
     const project = s.project || '-';
     const tag = teamTag(s);
     const label = s.label;
@@ -1785,6 +1890,12 @@ export function registerSessionsCommands(program) {
         .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
         .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
+        .option('--claude', 'Shorthand for --agent claude')
+        .option('--codex', 'Shorthand for --agent codex')
+        .option('--kimi', 'Shorthand for --agent kimi')
+        .option('--antigravity', 'Shorthand for --agent antigravity')
+        .option('--grok', 'Shorthand for --agent grok')
+        .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Include sessions from every directory (not just current project)')
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--project <name>', 'Filter by project name (searches across all directories)')
@@ -1808,7 +1919,8 @@ export function registerSessionsCommands(program) {
         .option('--flat', 'Plain flat table (one row per session) instead of the grouped project overview')
         .option('--no-live', 'Do not enrich the listing with live status/preview for running sessions')
         .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
-        .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)');
+        .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)')
+        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command

package/dist/lib/daemon.js

@@ -343,8 +343,10 @@ export async function runDaemon() {
             return;
         syncing = true;
         try {
-            const { isSyncConfigured } = await import('./session/sync/config.js');
-            if (!isSyncConfigured())
+            const { isSyncConfigured, isSyncEnabled } = await import('./session/sync/config.js');
+            // isSyncEnabled() first: a machine the operator turned off must skip the
+            // keychain read entirely, not just the network cycle.
+            if (!isSyncEnabled() || !isSyncConfigured())
                 return;
             const { syncSessions } = await import('./session/sync/sync.js');
             const r = await syncSessions();

package/dist/lib/devices/resolve-target.d.ts

@@ -0,0 +1,24 @@
+import { type DeviceRegistry } from './registry.js';
+/** A dialable peer: the ssh target, the machine id used to tag its rows, a
+ * display name, and the OS family that picks the remote shell dialect. */
+export interface ResolvedSshTarget {
+    target: string;
+    machine: string;
+    name: string;
+    os?: string;
+}
+/**
+ * Resolve one `--host`/`--device` token to a concrete ssh target through the
+ * registry. Registry hit → the device's real address + platform (so the machine
+ * id, route, and OS all match the auto-discovery sweep). Miss → a literal
+ * `user@host` fallback, its OS taken from the host overlay if enrolled. Returns
+ * undefined only when the token fails the shared ssh-target injection guard.
+ */
+export declare function resolveSshTarget(token: string, reg: DeviceRegistry): ResolvedSshTarget | undefined;
+/**
+ * Resolve an explicit `--host`/`--device` list to dialable targets, reading the
+ * registry once. A token that fails the injection guard is skipped with a
+ * stderr note (never fatal — one bad token must not blank the fan-out). Shared
+ * by every cross-machine fan-out so they can never diverge onto two routes.
+ */
+export declare function resolveExplicitTargets(hosts: string[]): Promise<ResolvedSshTarget[]>;

package/dist/lib/devices/resolve-target.js

@@ -0,0 +1,80 @@
+/**
+ * The one place a `--host` / `--device` token becomes a real ssh target.
+ *
+ * A device and a host are the same thing addressed two ways, so resolution must
+ * go through the device registry — the single source of truth. A token that
+ * names a registered device dials that device's real address (its Tailscale
+ * dnsName/ip + user, via `sshTargetFor`), *identical* to the auto-discovery
+ * sweep and `agents ssh`. Before this module, the explicit `--host` fan-out
+ * instead passed the bare token straight to `ssh`, so `--host yosemite-s0`
+ * dialed whatever `~/.ssh/config`/LAN DNS resolved `yosemite-s0` to — a
+ * different route than the sweep's `yosemite-s0.<tailnet>.ts.net`. That
+ * divergence broke ControlMaster socket reuse (different target → different
+ * `%C` hash → a cold dial every time) and could read a perfectly reachable box
+ * as "unreachable" when only the non-Tailscale route was down.
+ *
+ * A raw `user@host` that matches no registered device falls back to a literal
+ * target so ad-hoc boxes still work.
+ */
+import chalk from 'chalk';
+import { assertValidSshTarget } from '../ssh-exec.js';
+import { normalizeHost } from '../machine-id.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { sshTargetFor } from './connect.js';
+import { loadDevices } from './registry.js';
+/**
+ * Resolve one `--host`/`--device` token to a concrete ssh target through the
+ * registry. Registry hit → the device's real address + platform (so the machine
+ * id, route, and OS all match the auto-discovery sweep). Miss → a literal
+ * `user@host` fallback, its OS taken from the host overlay if enrolled. Returns
+ * undefined only when the token fails the shared ssh-target injection guard.
+ */
+export function resolveSshTarget(token, reg) {
+    try {
+        assertValidSshTarget(token);
+    }
+    catch {
+        return undefined;
+    }
+    const bare = token.split('@').pop() || token;
+    // An explicit `user@host` names an exact account/target — honour it literally.
+    // A bare alias (`yosemite-s0`) resolves through the registry to the device's
+    // real address, so it never diverges from the auto-discovery sweep.
+    const device = token.includes('@')
+        ? undefined
+        : reg[token] ?? Object.values(reg).find((d) => normalizeHost(d.name) === normalizeHost(bare));
+    if (device) {
+        try {
+            return { target: sshTargetFor(device), machine: normalizeHost(device.name), name: device.name, os: device.platform };
+        }
+        catch {
+            // Registered but has no address to dial — fall through to the literal token.
+        }
+    }
+    return { target: token, machine: normalizeHost(bare), name: token, os: resolveRemoteOsSync(token) };
+}
+/**
+ * Resolve an explicit `--host`/`--device` list to dialable targets, reading the
+ * registry once. A token that fails the injection guard is skipped with a
+ * stderr note (never fatal — one bad token must not blank the fan-out). Shared
+ * by every cross-machine fan-out so they can never diverge onto two routes.
+ */
+export async function resolveExplicitTargets(hosts) {
+    let reg;
+    try {
+        reg = await loadDevices();
+    }
+    catch {
+        reg = {};
+    }
+    const out = [];
+    for (const h of hosts) {
+        const resolved = resolveSshTarget(h, reg);
+        if (!resolved) {
+            process.stderr.write(chalk.gray(`  ${h}: not a valid ssh target — skipped\n`));
+            continue;
+        }
+        out.push(resolved);
+    }
+    return out;
+}

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

@@ -66,6 +66,24 @@ export interface ActiveSession {
      * two windows have the same cwd open. Only populated for `terminal` context.
      */
     windowId?: string;
+    /**
+     * Controlling TTY of the agent process (e.g. 'ttys003'), from the `ps -A`
+     * read. macOS/Linux terminal sessions only; '??'/none normalized to undefined.
+     * A disambiguation bridge (and the basis for future terminal addressing).
+     */
+    tty?: string;
+    /**
+     * Ghostty tab index (1-based) the session is shown in, when it can be matched
+     * to a Ghostty surface by working directory (+ title). Transient, populated by
+     * the renderer just before printing — NOT part of the pure discovery path.
+     */
+    ghosttyTab?: number;
+    /**
+     * Resolved tmux attach target (`session:window.pane`) for a tmux-hosted local
+     * session, from the pane id via `mapPanesToTargets`. Transient, renderer-set
+     * (after the --json/--waiting gates) — NOT emitted on the discovery path.
+     */
+    tmuxTarget?: string;
 }
 export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
@@ -80,6 +98,7 @@ export declare function listCloudActive(): ActiveSession[];
 interface ProcRow {
     pid: number;
     ppid: number;
+    tty?: string;
     comm: string;
     kind?: string;
 }

package/dist/lib/session/active.js

@@ -336,6 +336,7 @@ export async function listTerminalsActive() {
             context: 'terminal',
             kind: t.kind,
             host: detectHost(t.pid, procByPid),
+            tty: procByPid.get(t.pid)?.tty,
             pid: t.pid,
             sessionId: t.sessionId ?? sessionIdFromFile(sessionFile),
             cwd: t.cwd ?? undefined,
@@ -406,22 +407,26 @@ async function readProcessTable() {
         return readProcessTableWin32();
     let out;
     try {
-        ({ stdout: out } = await execFileAsync('ps', ['-A', '-o', 'pid=,ppid=,comm='], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
+        ({ stdout: out } = await execFileAsync('ps', ['-A', '-o', 'pid=,ppid=,tty=,comm='], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
     }
     catch {
         return [];
     }
     const rows = [];
     for (const line of out.split('\n')) {
-        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+        // pid ppid tty comm — tty is a single token ('ttys003', 's003', or '??'/'?'
+        // for none); comm stays last so it may contain spaces.
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/);
         if (!m)
             continue;
         const pid = parseInt(m[1], 10);
         const ppid = parseInt(m[2], 10);
         if (!Number.isFinite(pid) || !Number.isFinite(ppid))
             continue;
-        const commRaw = m[3].trim();
-        rows.push({ pid, ppid, comm: commRaw, kind: agentKindFromComm(commRaw) });
+        const ttyRaw = m[3];
+        const tty = ttyRaw === '??' || ttyRaw === '?' || ttyRaw === '-' ? undefined : ttyRaw;
+        const commRaw = m[4].trim();
+        rows.push({ pid, ppid, tty, comm: commRaw, kind: agentKindFromComm(commRaw) });
     }
     return rows;
 }
@@ -684,6 +689,7 @@ export async function listUnattributedActive(attributed) {
             context,
             kind,
             host,
+            tty: procByPid.get(pid)?.tty,
             pid,
             cwd,
             sessionId: entry?.sessionId ?? sessionIdFromFile(sessionFile),

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

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