@phnx-labs/agents-cli 1.20.36 → 1.20.38

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';
@@ -37,8 +39,27 @@ import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
+import { registerGoCommand } from './go.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 +195,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 +226,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 +300,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 +334,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 +507,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 +540,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 +564,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 +636,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 +649,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 +665,16 @@ function printCrossMachineTip() {
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    // Explicit --query is interchangeable with the positional; it's how you search
+    // for text that collides with a subcommand name (e.g. `sessions --query go`).
+    query = query ?? options.query;
+    // 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 +772,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 +928,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 +967,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 +1037,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 +1069,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 +1322,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;
@@ -1260,7 +1369,7 @@ const PICKER_TIPS = [
 export function formatPickerTip(sessions) {
     return chalk.gray(PICKER_TIPS[sessions.length % PICKER_TIPS.length]);
 }
-export async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0) {
+export async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0, enterHint) {
     if (hiddenCount > 0) {
         console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
     }
@@ -1280,6 +1389,7 @@ export async function pickSessionInteractive(sessions, message = 'Search session
             labelFor: (s, query) => formatPickerLabel(s, query, cols),
             pageSize: PICKER_RECENT_COUNT,
             initialSearch,
+            enterHint,
         });
     }
     catch (err) {
@@ -1783,8 +1893,15 @@ export function registerSessionsCommands(program) {
     const sessionsCmd = program
         .command('sessions')
         .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
+        .option('--query <text>', 'Search text — use when the term collides with a subcommand name (e.g. "go")')
         .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 +1925,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
@@ -1855,6 +1973,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsSyncCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
+    registerGoCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {

package/dist/index.js

@@ -483,7 +483,7 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     const { confirm } = await import('@inquirer/prompts');
     const { AGENTS } = await import('./lib/agents.js');
     const { getGlobalDefault, listInstalledVersions } = await import('./lib/versions.js');
-    const { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } = await import('./lib/shims.js');
+    const { addShimsToPath, adoptShadowingLauncher, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } = await import('./lib/shims.js');
     const installedAgents = listAgentsWithInstalledVersions();
     if (installedAgents.length === 0) {
         return;
@@ -519,87 +519,78 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
         return;
     }
     const defaultAgents = installedAgents.filter((agent) => getGlobalDefault(agent));
+    // Auto-adopt any harness launcher that shadows our shim. PATH-order repair
+    // (below) cannot win against `~/.local/bin` — it's prepended in .zshenv for
+    // every shell while our prepend only lands in .zshrc — so for symlink
+    // launchers we *become* the launcher instead. Detection keys on the launcher
+    // symlink EXISTING (via adoptShadowingLauncher's own fallback), not on this
+    // shell's PATH order, so it also heals the GUI/non-interactive shadow an
+    // interactive run can't see. Reversible; only ever rewrites a symlink.
+    for (const agent of defaultAgents) {
+        const result = adoptShadowingLauncher(agent);
+        if (result.adopted) {
+            console.log(chalk.green(`Adopted ${AGENTS[agent].cliCommand} launcher (${result.launcher}) — version management now wins regardless of PATH order.`));
+        }
+    }
+    // Recompute AFTER adoption so anything we just took over drops out. What
+    // remains is a real binary we deliberately don't touch (adoption is
+    // symlink-only) — those get an honest one-time note, never a looping prompt.
     const shadowed = defaultAgents
         .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))
         .filter((item) => Boolean(item.shadowedBy));
-    // Shell aliases that call the same command with extra flags are intentional
-    // customization and don't break shim integration — `addShimsToPath` cannot
-    // touch them, so they don't belong in the repair prompt. We previously
-    // computed an `aliased` list here and inserted it into `affected`, which
-    // contradicted the comment below and surfaced false positives (e.g. an
-    // earlier `alias codex=...` cancelled by a later `unalias codex` was
-    // reported because the detector did a static rc-file regex).
-    if (shadowed.length === 0 && isShimsInPath()) {
+    // After adoption, the only things left are (a) real-binary shadows we won't
+    // touch, and (b) a genuinely missing PATH entry. Nothing else needs the user.
+    const pathMissing = !isShimsInPath();
+    if (shadowed.length === 0 && !pathMissing) {
         return;
     }
-    // Suppress repeated prompts within the same shell. A successful rc-file
-    // edit doesn't reload the parent shell, so the next invocation sees the
-    // same PATH and re-fires detection. The sentinel survives only as long as
-    // the parent shell process — once the user opens a new terminal, the
-    // PPID changes and the prompt is allowed again.
+    // Suppress repeated notices within the same shell. A successful rc-file edit
+    // doesn't reload the parent shell, so the next invocation re-fires detection.
+    // The sentinel survives only as long as the parent shell process — a new
+    // terminal (new PPID) is allowed to surface it again.
     const sentinelPath = path.join(os.tmpdir(), `agents-shim-prompted-${process.ppid}`);
     if (fs.existsSync(sentinelPath)) {
         return;
     }
-    const affected = [];
-    for (const { agent, shadowedBy } of shadowed) {
-        affected.push(`${AGENTS[agent].cliCommand} -> ${shadowedBy}`);
-    }
-    if (affected.length === 0) {
-        // Pure PATH-not-loaded case: rc may already have the shim block, but the
-        // running shell hasn't sourced it. Don't list agents here — they aren't
-        // broken; only the PATH is stale. The prompt + post-message handle it.
-        affected.push('PATH entry missing');
-    }
-    const shouldRepair = await confirm({
-        message: `Repair shim integration now? ${affected.join(', ')}`,
-        default: true,
-    });
-    if (!shouldRepair) {
-        console.log(chalk.yellow('Shim integration still needs attention.'));
-        console.log(chalk.gray(getPathSetupInstructions()));
-        try {
-            fs.writeFileSync(sentinelPath, '1');
-        }
-        catch { /* best-effort */ }
-        return;
-    }
-    const pathResult = addShimsToPath();
-    if (!pathResult.success) {
-        console.log(chalk.yellow('Could not repair shim PATH setup automatically.'));
-        console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
-        // Write the sentinel even on failure — otherwise an unwritable rc file
-        // re-prompts every invocation in the same shell. The user opens a new
-        // terminal (new PPID) to retry.
-        try {
-            fs.writeFileSync(sentinelPath, '1');
-        }
-        catch { /* best-effort */ }
-        return;
+    // Real-binary shadows: adoption is symlink-only (we never rename a real native
+    // binary), and `addShimsToPath` provably can't outrank an early-PATH dir like
+    // ~/.local/bin across zsh's whole sourcing chain. So DON'T offer a "Repair?"
+    // prompt here — that was the infinite-loop bug (Yes was always a no-op).
+    // Inform once and point at the real levers.
+    if (shadowed.length > 0) {
+        const targets = shadowed
+            .map(({ agent, shadowedBy }) => `  ${AGENTS[agent].cliCommand}: ${shadowedBy}`)
+            .join('\n');
+        console.log(chalk.yellow('These agent commands run a native binary instead of the version-managed shim:'));
+        console.log(chalk.gray(targets));
+        console.log(chalk.gray(`It's a real binary (not a symlink), so agents-cli won't move it. To hand it to agents-cli, remove/reorder it, or put ${getShimsDir()} earlier in PATH.`));
     }
-    // When the rc file already has the canonical shim block, `addShimsToPath`
-    // is a no-op — re-emitting produced byte-identical content. In this branch
-    // the user clicked "Yes" but nothing changed on disk, AND the underlying
-    // cause (a real binary shadow, or a stale shell PATH) is unaffected by
-    // this command. Be honest about it and point at the actual action.
-    if (pathResult.alreadyPresent) {
-        if (shadowed.length > 0) {
-            const targets = shadowed
-                .map(({ agent, shadowedBy }) => `  ${AGENTS[agent].cliCommand}: ${shadowedBy}`)
-                .join('\n');
-            console.log(chalk.yellow('Repair could not change anything — the shim is shadowed by another binary on PATH:'));
-            console.log(chalk.gray(targets));
-            console.log(chalk.gray(`Fix it by removing or reordering that binary, or making sure ${getShimsDir()} appears earlier in PATH than its parent dir.`));
+    // Genuinely-missing PATH entry is the one thing addShimsToPath actually fixes,
+    // so it's the only case that still earns an interactive prompt.
+    if (pathMissing) {
+        const shouldRepair = await confirm({
+            message: 'Add the agents-cli shims directory to your PATH now?',
+            default: true,
+        });
+        if (!shouldRepair) {
+            console.log(chalk.gray(getPathSetupInstructions()));
         }
         else {
-            console.log(chalk.yellow(`Shim PATH entry is already in ~/${pathResult.rcFile} — this shell just needs to reload it.`));
-            console.log(chalk.gray(`Run: source ~/${pathResult.rcFile}   (or open a new terminal)`));
+            const pathResult = addShimsToPath();
+            if (!pathResult.success) {
+                console.log(chalk.yellow('Could not update PATH automatically.'));
+                console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
+            }
+            else if (pathResult.alreadyPresent) {
+                console.log(chalk.yellow(`Shim PATH entry is already in ~/${pathResult.rcFile} — this shell just needs to reload it.`));
+                console.log(chalk.gray(`Run: source ~/${pathResult.rcFile}   (or open a new terminal)`));
+            }
+            else {
+                console.log(chalk.green(`Added shims to PATH in ~/${pathResult.rcFile}`));
+                console.log(chalk.gray(getPathSetupInstructions()));
+            }
         }
     }
-    else {
-        console.log(chalk.green(`Repaired shim PATH setup in ~/${pathResult.rcFile}`));
-        console.log(chalk.gray(getPathSetupInstructions()));
-    }
     try {
         fs.writeFileSync(sentinelPath, '1');
     }

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;
+}