@phnx-labs/agents-cli 1.20.29 → 1.20.31

package/dist/lib/session/state.js

@@ -0,0 +1,221 @@
+/**
+ * Session state inference.
+ *
+ * Turns a chronological slice of normalized `SessionEvent`s (typically the tail
+ * of a transcript) plus lightweight context (file mtime, cwd, branch, whether
+ * the owning process is alive) into a `SessionState`: is the agent working,
+ * waiting on the user, or idle — and did it open a PR, is it in a worktree, is
+ * it tied to a tracker ticket. Pure functions, no I/O, so the whole thing is
+ * unit-testable and shared by both the live `--active` path and the incremental
+ * scanner (which persists the durable signals to the index).
+ *
+ * Structural signals are preferred over prose heuristics: Claude's
+ * `ExitPlanMode` / `AskUserQuestion` tool calls are exact "waiting on you"
+ * markers. Codex has no such tools, so it falls back to last-role + question
+ * shape + mtime — same function, driven off the normalized events.
+ */
+import { summarizeToolUse } from './parse.js';
+/** A healthy live session writes several times a minute; 2 min ⇒ "recently active". */
+const ACTIVE_WINDOW_MS = 2 * 60_000;
+/** Claude tool names that structurally mean "the agent handed control back to you". */
+const PLAN_TOOL = 'ExitPlanMode';
+const ASK_TOOL = 'AskUserQuestion';
+/** Trailing '?' or a leading interrogative — a question aimed at the user. */
+const QUESTION_TRAILING = /\?["'”)\]]?\s*$/;
+const QUESTION_PHRASE = /\b(shall i|should i|do you want|would you like|which (?:one|option|approach|of)|can you (?:confirm|clarify)|please (?:confirm|clarify|advise)|let me know|are you (?:ok|okay|sure)|proceed\?)\b/i;
+/**
+ * Linear/Jira-style ref, e.g. RUSH-1234. Team key is letters-only (2–6) so a
+ * regex snippet like `[A-Z0-9]-\d` in a code discussion can't masquerade as a
+ * ticket. Uppercase-only so we don't match `utf-8`.
+ */
+const TICKET_RE = /\b([A-Z]{2,6}-\d{1,6})\b/;
+/** Lowercase branch form (Linear branch names): muqsit/rush-1234-fix. */
+const TICKET_BRANCH_RE = /(?:^|[/_-])([a-z]{2,6})-(\d{2,6})(?=[/_-]|$)/;
+/** Keys that look like tickets but aren't — avoid false positives from branches. */
+const TICKET_DENYLIST = new Set(['UTF', 'SHA', 'ISO', 'RFC', 'IPV', 'X86', 'ARM', 'MP', 'H']);
+const PR_URL_RE = /https:\/\/github\.com\/[^\s"'()<>]+\/pull\/(\d+)/;
+const WORKTREE_RE = /\/\.agents\/worktrees\/([^/]+)/;
+/** gh invocations that create/open a PR. */
+const GH_PR_CREATE_RE = /\bgh\s+pr\s+(?:create|new)\b/;
+/** Collapse to a single trimmed line for a one-row preview cell. */
+function oneLine(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+/** Detect a worktree from the session cwd, per the `.agents/worktrees/<slug>/` convention. */
+export function detectWorktree(cwd, branch) {
+    if (!cwd)
+        return undefined;
+    const m = cwd.match(WORKTREE_RE);
+    if (!m)
+        return undefined;
+    return { path: cwd, slug: m[1], branch: branch || undefined };
+}
+/** Detect a tracker ticket from free text (prompt/topic) then a branch name. */
+export function detectTicket(text, branch) {
+    if (text) {
+        const m = text.match(TICKET_RE);
+        if (m && !TICKET_DENYLIST.has(m[1].split('-')[0]))
+            return { id: m[1] };
+    }
+    if (branch) {
+        const m = branch.match(TICKET_BRANCH_RE);
+        if (m) {
+            const key = m[1].toUpperCase();
+            if (!TICKET_DENYLIST.has(key))
+                return { id: `${key}-${m[2]}` };
+        }
+    }
+    return undefined;
+}
+/** Pull a PR URL + number out of tool-result output text. */
+export function extractPrUrl(output) {
+    if (!output)
+        return undefined;
+    const m = output.match(PR_URL_RE);
+    if (!m)
+        return undefined;
+    return { url: m[0], number: Number.parseInt(m[1], 10) };
+}
+/** True when a Bash/exec command string is a `gh pr create`. */
+export function isPrCreateCommand(command) {
+    return !!command && GH_PR_CREATE_RE.test(command);
+}
+/** Does an assistant message read as a question directed at the user? */
+function looksLikeQuestion(text) {
+    const t = text.trim();
+    if (!t)
+        return false;
+    // Only weigh the final line — a long answer that ends with a question is a question.
+    const lastLine = t.split('\n').filter(Boolean).pop() ?? t;
+    return QUESTION_TRAILING.test(lastLine) || QUESTION_PHRASE.test(lastLine);
+}
+/** Human-readable one-liner for the latest event (message text or tool action). */
+function describeEvent(e) {
+    if (e.type === 'message' && e.content)
+        return oneLine(e.content);
+    if (e.type === 'tool_use' && e.tool)
+        return oneLine(summarizeToolUse(e.tool, e.args));
+    if (e.type === 'thinking')
+        return 'thinking…';
+    if (e.type === 'tool_result')
+        return e.tool ? `↳ ${e.tool}` : undefined;
+    if (e.type === 'error')
+        return oneLine(e.content || 'error');
+    return e.content ? oneLine(e.content) : undefined;
+}
+/** Last event of a given type, scanning from the end. */
+function lastOf(events, pred) {
+    for (let i = events.length - 1; i >= 0; i--)
+        if (pred(events[i]))
+            return events[i];
+    return undefined;
+}
+/**
+ * Infer live activity + a preview from a chronological event slice. `pr` /
+ * `ticket` / `worktree` are attached by `inferSessionState`; this focuses on the
+ * running-vs-waiting-vs-idle decision and the preview line.
+ */
+export function inferActivity(events, ctx = {}) {
+    const windowMs = ctx.activeWindowMs ?? ACTIVE_WINDOW_MS;
+    const fresh = ctx.mtimeMs != null && Date.now() - ctx.mtimeMs < windowMs;
+    // A non-live process (pidAlive === false) can never be "working"; the strongest
+    // it gets is "waiting on you" (a dangling question) or "idle".
+    const canWork = ctx.pidAlive !== false && (ctx.pidAlive === true || fresh);
+    const meaningful = events.filter(e => e.type === 'message' || e.type === 'tool_use' || e.type === 'tool_result' || e.type === 'thinking' || e.type === 'error');
+    const last = meaningful[meaningful.length - 1];
+    const lastMsg = lastOf(meaningful, e => e.type === 'message');
+    const lastToolUse = lastOf(meaningful, e => e.type === 'tool_use');
+    // The most informative recent line: a message or tool call as-is, but for a
+    // trailing tool_result/thinking show the tool *call* that produced it (its
+    // command) rather than a bare "↳ Bash".
+    const previewSource = !last
+        ? undefined
+        : last.type === 'message' || last.type === 'tool_use'
+            ? last
+            : (lastToolUse ?? last);
+    const base = {
+        activity: 'idle',
+        lastRole: lastMsg?.role,
+        lastEventKind: last?.type,
+        lastActivityMs: ctx.mtimeMs,
+        preview: previewSource ? describeEvent(previewSource) : undefined,
+    };
+    if (!last)
+        return base;
+    // Structural "waiting on you" — Claude handed control back via a plan/question
+    // tool and nothing has come after it.
+    const lastPlanOrAsk = lastOf(meaningful, e => e.type === 'tool_use' && (e.tool === PLAN_TOOL || e.tool === ASK_TOOL));
+    if (lastPlanOrAsk && meaningful.indexOf(lastPlanOrAsk) === meaningful.length - 1) {
+        return {
+            ...base,
+            activity: 'waiting_input',
+            awaitingReason: lastPlanOrAsk.tool === PLAN_TOOL ? 'plan_review' : 'question',
+            preview: lastPlanOrAsk.tool === PLAN_TOOL ? 'Plan ready — awaiting your review' : 'Asked you a question',
+        };
+    }
+    // Pending tool call (tool_use with no following tool_result): mid-turn.
+    if (last.type === 'tool_use') {
+        if (canWork && fresh)
+            return { ...base, activity: 'working' };
+        // Alive but the file hasn't moved — likely blocked on a permission prompt.
+        if (ctx.pidAlive)
+            return { ...base, activity: 'waiting_input', awaitingReason: 'permission' };
+        return { ...base, activity: 'idle' };
+    }
+    // Thinking or a tool result just landed → agent is mid-turn if recently active.
+    if (last.type === 'thinking' || last.type === 'tool_result' || last.type === 'error') {
+        return { ...base, activity: canWork && fresh ? 'working' : 'idle' };
+    }
+    // Last event is a message.
+    if (last.type === 'message') {
+        if (last.role === 'user') {
+            // User spoke last; the agent owes a reply → working if it's alive/fresh.
+            return { ...base, activity: canWork ? 'working' : 'idle' };
+        }
+        // Assistant spoke last and stopped. A trailing question → waiting; else idle.
+        if (looksLikeQuestion(last.content ?? '')) {
+            return { ...base, activity: 'waiting_input', awaitingReason: 'question' };
+        }
+        return { ...base, activity: 'idle' };
+    }
+    return base;
+}
+/**
+ * Scan an event slice for the durable signals (PR opened, ticket) that aren't
+ * about the cwd. Correlates each `gh pr create` with the nearest following
+ * tool_result URL; keeps the last PR found.
+ */
+export function detectDurableSignals(events) {
+    let pr;
+    let sawPrCreate = false;
+    let ticket;
+    for (const e of events) {
+        // Structural PR signal: a real `gh pr create` tool call, then the pull URL
+        // from a following tool_result — never a bare URL mentioned in prose.
+        if (e.type === 'tool_use' && isPrCreateCommand(e.command))
+            sawPrCreate = true;
+        if (sawPrCreate && e.type === 'tool_result') {
+            const found = extractPrUrl(e.output);
+            if (found) {
+                pr = found;
+                sawPrCreate = false;
+            }
+        }
+        if (!ticket && e.type === 'message' && e.role === 'user') {
+            ticket = detectTicket(e.content);
+        }
+    }
+    return { pr, ticket };
+}
+/** Full inference: activity + preview + durable signals + worktree/ticket from ctx. */
+export function inferSessionState(events, ctx = {}) {
+    const state = inferActivity(events, ctx);
+    const { pr, ticket } = detectDurableSignals(events);
+    const worktree = detectWorktree(ctx.cwd, ctx.gitBranch);
+    return {
+        ...state,
+        pr: pr ?? state.pr,
+        worktree: worktree ?? state.worktree,
+        ticket: ticket ?? detectTicket(undefined, ctx.gitBranch) ?? state.ticket,
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Fast tail read of a session transcript.
+ *
+ * The live `--active` view needs the *last* few events of a possibly-huge JSONL
+ * to infer state — parsing the whole file per row would make the view crawl. We
+ * read only the final chunk from an fd (mirroring the bounded head-read in
+ * active.ts's `quickExtractTopic`), drop a partial leading line, and hand the
+ * chunk to the existing content parsers so there's zero duplicated parse logic.
+ */
+import type { SessionAgentId, SessionEvent } from './types.js';
+/**
+ * Read the last `maxBytes` of a JSONL transcript and return its last
+ * `maxEvents` normalized events. A tail that begins mid-line yields one
+ * malformed leading line, which the per-line JSON try/catch in the content
+ * parsers skips. Only Claude and Codex are supported (the prioritized harnesses
+ * for live state); other agents return `[]`.
+ */
+export declare function readSessionTail(filePath: string, agent: SessionAgentId, maxBytes?: number, maxEvents?: number): SessionEvent[];

package/dist/lib/session/tail.js

@@ -0,0 +1,57 @@
+/**
+ * Fast tail read of a session transcript.
+ *
+ * The live `--active` view needs the *last* few events of a possibly-huge JSONL
+ * to infer state — parsing the whole file per row would make the view crawl. We
+ * read only the final chunk from an fd (mirroring the bounded head-read in
+ * active.ts's `quickExtractTopic`), drop a partial leading line, and hand the
+ * chunk to the existing content parsers so there's zero duplicated parse logic.
+ */
+import * as fs from 'fs';
+import { parseClaudeContent, parseCodexContent, sanitizeEvents } from './parse.js';
+const DEFAULT_MAX_BYTES = 128 * 1024;
+const DEFAULT_MAX_EVENTS = 60;
+/**
+ * Read the last `maxBytes` of a JSONL transcript and return its last
+ * `maxEvents` normalized events. A tail that begins mid-line yields one
+ * malformed leading line, which the per-line JSON try/catch in the content
+ * parsers skips. Only Claude and Codex are supported (the prioritized harnesses
+ * for live state); other agents return `[]`.
+ */
+export function readSessionTail(filePath, agent, maxBytes = DEFAULT_MAX_BYTES, maxEvents = DEFAULT_MAX_EVENTS) {
+    if (agent !== 'claude' && agent !== 'codex')
+        return [];
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return [];
+    }
+    try {
+        const size = fs.fstatSync(fd).size;
+        if (size === 0)
+            return [];
+        const start = Math.max(0, size - maxBytes);
+        const len = size - start;
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, start);
+        let content = buf.toString('utf8');
+        // If we started mid-file, the first line is almost certainly partial — drop it.
+        if (start > 0) {
+            const nl = content.indexOf('\n');
+            content = nl >= 0 ? content.slice(nl + 1) : '';
+        }
+        if (!content.trim())
+            return [];
+        const events = agent === 'codex' ? parseCodexContent(content) : parseClaudeContent(content);
+        sanitizeEvents(events);
+        return events.length > maxEvents ? events.slice(-maxEvents) : events;
+    }
+    catch {
+        return [];
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

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

@@ -63,6 +63,15 @@ export interface SessionMeta {
     label?: string;
     /** Set when this session was spawned by `agents teams`. */
     teamOrigin?: TeamOrigin;
+    /** Durable state signals extracted at scan time by the session-state engine. */
+    /** PR URL, if the session opened one (`gh pr create`). */
+    prUrl?: string;
+    /** PR number parsed from prUrl, for compact display. */
+    prNumber?: number;
+    /** Worktree slug when cwd is under `.agents/worktrees/<slug>/`. */
+    worktreeSlug?: string;
+    /** Tracker ticket ref (e.g. RUSH-1234) from the prompt or branch. */
+    ticketId?: string;
     /**
      * True when the session was spawned programmatically (SDK entrypoint) rather
      * than by a human at the Claude CLI. Captured at scan time from the JSONL

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

@@ -0,0 +1,29 @@
+/**
+ * Terminal display-width helpers.
+ *
+ * `String.length` is the wrong ruler for a terminal: it over-counts ANSI colour
+ * escapes (chalk output) and under-counts wide glyphs (CJK, emoji) which occupy
+ * two cells. The result is the drifting, wrapping session-table line users see
+ * under tmux and over `--host` SSH. Every renderer that sizes a session-table
+ * cell measures and truncates through this module so alignment is computed once,
+ * correctly, from the same source of truth.
+ */
+/** Strip SGR colour escapes so width is measured on visible characters only. */
+export declare function stripAnsi(s: string): string;
+/** Visible display width of a string, ANSI-aware and wide-char-aware. */
+export declare function stringWidth(s: string): number;
+/**
+ * Truncate to a target display width, appending '…' when shortened. Operates on
+ * the visible (ANSI-stripped) string; callers colour the result afterwards so
+ * the ellipsis is never inserted mid-escape.
+ */
+export declare function truncateToWidth(s: string, max: number): string;
+/** Right-pad with spaces to a target display width. Never truncates. */
+export declare function padToWidth(s: string, width: number): string;
+/**
+ * Effective terminal width. Reads `$COLUMNS` first so it survives tmux and
+ * `--host` SSH (where `process.stdout.columns` is unset or wrong), falls back to
+ * the TTY's reported width, then to `fallback`. Clamped to a sane band so a
+ * bogus value can't produce a 0-wide or absurdly long table.
+ */
+export declare function terminalWidth(fallback?: number): number;

package/dist/lib/session/width.js

@@ -0,0 +1,91 @@
+/**
+ * Terminal display-width helpers.
+ *
+ * `String.length` is the wrong ruler for a terminal: it over-counts ANSI colour
+ * escapes (chalk output) and under-counts wide glyphs (CJK, emoji) which occupy
+ * two cells. The result is the drifting, wrapping session-table line users see
+ * under tmux and over `--host` SSH. Every renderer that sizes a session-table
+ * cell measures and truncates through this module so alignment is computed once,
+ * correctly, from the same source of truth.
+ */
+/** SGR colour sequences emitted by chalk (e.g. `\x1b[32m`). */
+const SGR_REGEX = /\x1b\[[0-9;]*m/g;
+/** Strip SGR colour escapes so width is measured on visible characters only. */
+export function stripAnsi(s) {
+    return s.replace(SGR_REGEX, '');
+}
+/**
+ * Display cells for one code point: 0 for zero-width combining/ZWJ/variation
+ * selectors, 2 for East-Asian-wide and emoji ranges, 1 otherwise. Compact and
+ * dependency-free — covers the glyphs that actually show up in prompts/titles.
+ */
+function charWidth(cp) {
+    if (cp === 0)
+        return 0;
+    // Zero-width: combining marks, zero-width joiner, variation selectors.
+    if ((cp >= 0x0300 && cp <= 0x036f) ||
+        cp === 0x200b || cp === 0x200d ||
+        (cp >= 0xfe00 && cp <= 0xfe0f))
+        return 0;
+    // Wide (2 cells): CJK, Hangul, fullwidth forms, emoji & pictographs.
+    if ((cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+        (cp >= 0x2e80 && cp <= 0xa4cf) || // CJK radicals … Yi
+        (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+        (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+        (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+        (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+        (cp >= 0xffe0 && cp <= 0xffe6) || // Fullwidth signs
+        (cp >= 0x1f300 && cp <= 0x1faff) || // emoji & symbols
+        (cp >= 0x20000 && cp <= 0x3fffd) // CJK Ext-B and beyond
+    )
+        return 2;
+    return 1;
+}
+/** Visible display width of a string, ANSI-aware and wide-char-aware. */
+export function stringWidth(s) {
+    const plain = stripAnsi(s);
+    let w = 0;
+    for (const ch of plain)
+        w += charWidth(ch.codePointAt(0));
+    return w;
+}
+/**
+ * Truncate to a target display width, appending '…' when shortened. Operates on
+ * the visible (ANSI-stripped) string; callers colour the result afterwards so
+ * the ellipsis is never inserted mid-escape.
+ */
+export function truncateToWidth(s, max) {
+    if (max <= 0)
+        return '';
+    const plain = stripAnsi(s);
+    if (stringWidth(plain) <= max)
+        return plain;
+    let w = 0;
+    let out = '';
+    for (const ch of plain) {
+        const cw = charWidth(ch.codePointAt(0));
+        if (w + cw > max - 1)
+            break; // reserve one cell for the ellipsis
+        out += ch;
+        w += cw;
+    }
+    return out + '…';
+}
+/** Right-pad with spaces to a target display width. Never truncates. */
+export function padToWidth(s, width) {
+    const pad = width - stringWidth(s);
+    return pad > 0 ? s + ' '.repeat(pad) : s;
+}
+/**
+ * Effective terminal width. Reads `$COLUMNS` first so it survives tmux and
+ * `--host` SSH (where `process.stdout.columns` is unset or wrong), falls back to
+ * the TTY's reported width, then to `fallback`. Clamped to a sane band so a
+ * bogus value can't produce a 0-wide or absurdly long table.
+ */
+export function terminalWidth(fallback = 100) {
+    const env = Number.parseInt(process.env.COLUMNS ?? '', 10);
+    const raw = Number.isFinite(env) && env > 0
+        ? env
+        : (process.stdout.columns || fallback);
+    return Math.max(60, Math.min(200, raw));
+}

package/dist/lib/shims.d.ts

@@ -108,8 +108,14 @@ export declare function removeShim(agent: AgentId): boolean;
  *   v5 — hard-disable Codex startup update checks in versioned aliases.
  *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
+ *   v7 — runtime state split into ~/.agents/.history and ~/.agents/.cache.
+ *   v8 — resolve grok/kimi/droid binaries from their real install locations
+ *        (~/.grok/downloads, ~/.kimi-code/bin, ~/.local/bin) instead of the
+ *        hardcoded node_modules/.bin, which never exists for these three and
+ *        made every versioned alias (the path `agents teams` pins to) fail
+ *        with "<agent>@<version> not installed". Also emit GROK_HOME.
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 7;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 8;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary
@@ -159,6 +165,16 @@ export declare function versionedAliasExists(agent: AgentId, version: string): b
  *
  * Returns: { success: boolean, backupPath?: string, error?: string }
  */
+/**
+ * Seed a version's config home with the account credential so switching versions
+ * doesn't log the CLI out. Droid/antigravity/kimi (registry `authFiles`) store
+ * login as files inside the per-version config dir; sign-in is account-global,
+ * so we copy the FRESHEST existing copy (by mtime, across all installed version
+ * homes) into `toConfigDir` when its copy is missing or older. mtime is
+ * preserved so the "freshest" comparison stays stable and switches don't
+ * ping-pong. Best-effort: a failed copy just means the user re-logs in.
+ */
+export declare function carryForwardAuthFiles(agent: AgentId, toConfigDir: string): void;
 export declare function switchConfigSymlink(agent: AgentId, version: string): Promise<{
     success: boolean;
     backupPath?: string;

package/dist/lib/shims.js

@@ -16,7 +16,7 @@ import { confirm, select } from '@inquirer/prompts';
 import { IS_WINDOWS, prependToWindowsUserPath } from './platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, ensureAgentsDir } from './state.js';
 export { getShimsDir };
-import { AGENTS } from './agents.js';
+import { AGENTS, agentConfigDirName } from './agents.js';
 /**
  * Files and directories to always skip during conflict detection and migration.
  * These are never user config that should be migrated.
@@ -596,8 +596,14 @@ export function removeShim(agent) {
  *   v5 — hard-disable Codex startup update checks in versioned aliases.
  *   v6 — versions moved from ~/.agents-system/versions to ~/.agents/versions
  *        (two-repo split: system = shipped defaults, user = operational state).
+ *   v7 — runtime state split into ~/.agents/.history and ~/.agents/.cache.
+ *   v8 — resolve grok/kimi/droid binaries from their real install locations
+ *        (~/.grok/downloads, ~/.kimi-code/bin, ~/.local/bin) instead of the
+ *        hardcoded node_modules/.bin, which never exists for these three and
+ *        made every versioned alias (the path `agents teams` pins to) fail
+ *        with "<agent>@<version> not installed". Also emit GROK_HOME.
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 7;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 8;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -640,22 +646,70 @@ export CODEX_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${co
 # version MCP and session state are isolated.
 export COPILOT_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                : agent === 'kimi'
+                : agent === 'grok'
                     ? `
+# Grok Build uses GROK_HOME to isolate its entire configuration tree (skills,
+# hooks, plugins, agents, memory, sessions, config.toml, MCP). Point direct
+# aliases at the versioned home for isolation parity with the main shim.
+export GROK_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+`
+                    : agent === 'kimi'
+                        ? `
 # Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
 # mcp.json, sessions, skills, hooks). Point direct aliases at the versioned home.
 export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                    : '';
+                        : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
+    // Resolve the binary the same way the main shim does (see generateShimScript).
+    // Grok, Kimi, and Droid do NOT ship into node_modules/.bin — Grok downloads a
+    // native binary to ~/.grok/downloads, Kimi to ~/.kimi-code/bin, and Droid
+    // (Factory AI) installs a standalone binary to ~/.local/bin. Hardcoding the
+    // node_modules path made every versioned alias for these three fail with
+    // "<agent>@<version> not installed", which is exactly the path `agents teams`
+    // takes once it pins a teammate's version.
+    // This template is unix-only — on Windows the .cmd companion delegates to
+    // "agents __shim" which resolves via getBinaryPath() instead.
+    const versionDir = `$HOME/.agents/.history/versions/${agent}/${version}`;
+    const binaryResolution = agent === 'grok'
+        ? `# Grok ships its native binary in ~/.grok/downloads, not node_modules.
+GROK_DOWNLOADS="$HOME/.grok/downloads"
+BINARY=""
+if [ -d "$GROK_DOWNLOADS" ]; then
+  BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "${version}" | head -1)
+  [ -n "$BINARY" ] || BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+fi
+[ -n "$BINARY" ] && [ -x "$BINARY" ] || BINARY=$(command -v grok 2>/dev/null || echo "")`
+        : agent === 'kimi'
+            ? `# Kimi ships its binary in ~/.kimi-code/bin, not node_modules.
+KIMI_BINARY="$HOME/.kimi-code/bin/kimi"
+if [ -x "$KIMI_BINARY" ]; then
+  BINARY="$KIMI_BINARY"
+else
+  BINARY=$(command -v kimi 2>/dev/null || echo "")
+fi`
+            : agent === 'droid'
+                ? `# Droid (Factory AI) installs a standalone native binary at ~/.local/bin/droid;
+# there is no npm package and nothing lands in node_modules/.bin. The PATH
+# fallback refuses anything under our shims dir to avoid an infinite re-exec.
+DROID_BINARY="$HOME/.local/bin/droid"
+if [ -x "$DROID_BINARY" ]; then
+  BINARY="$DROID_BINARY"
+else
+  BINARY=$(command -v droid 2>/dev/null || echo "")
+  case "$BINARY" in
+    "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+  esac
+fi`
+                : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}
 # Direct alias for ${agentConfig.name}@${version}
 
-BINARY="$HOME/.agents/.history/versions/${agent}/${version}/node_modules/.bin/${agentConfig.cliCommand}"
+${binaryResolution}
 
-if [ ! -x "$BINARY" ]; then
+if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
   echo "agents: ${agent}@${version} not installed" >&2
   exit 1
 fi
@@ -831,6 +885,70 @@ function detectMigrationConflicts(agent, version) {
  *
  * Returns: { success: boolean, backupPath?: string, error?: string }
  */
+/**
+ * Seed a version's config home with the account credential so switching versions
+ * doesn't log the CLI out. Droid/antigravity/kimi (registry `authFiles`) store
+ * login as files inside the per-version config dir; sign-in is account-global,
+ * so we copy the FRESHEST existing copy (by mtime, across all installed version
+ * homes) into `toConfigDir` when its copy is missing or older. mtime is
+ * preserved so the "freshest" comparison stays stable and switches don't
+ * ping-pong. Best-effort: a failed copy just means the user re-logs in.
+ */
+export function carryForwardAuthFiles(agent, toConfigDir) {
+    const authFiles = AGENTS[agent].authFiles;
+    if (!authFiles || authFiles.length === 0)
+        return;
+    const configDirName = agentConfigDirName(agent);
+    const versionsBase = path.join(getVersionsDir(), agent);
+    let sourceDirs = [];
+    try {
+        sourceDirs = fs
+            .readdirSync(versionsBase)
+            .map(v => path.join(versionsBase, v, 'home', configDirName));
+    }
+    catch {
+        return; // no installed versions to source from
+    }
+    for (const rel of authFiles) {
+        const dest = path.join(toConfigDir, rel);
+        const destResolved = path.resolve(dest);
+        // Newest existing source copy across all version homes (excluding dest).
+        let newest = null;
+        for (const dir of sourceDirs) {
+            const src = path.join(dir, rel);
+            if (path.resolve(src) === destResolved)
+                continue;
+            let st;
+            try {
+                st = fs.statSync(src);
+            }
+            catch {
+                continue;
+            }
+            if (!st.isFile())
+                continue;
+            if (!newest || st.mtimeMs > newest.mtimeMs)
+                newest = { path: src, mtimeMs: st.mtimeMs };
+        }
+        if (!newest)
+            continue;
+        // Skip when the target already has an at-least-as-fresh copy.
+        try {
+            const dstat = fs.statSync(dest);
+            if (dstat.mtimeMs >= newest.mtimeMs)
+                continue;
+        }
+        catch { /* dest missing — copy below */ }
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            const srcStat = fs.statSync(newest.path);
+            fs.copyFileSync(newest.path, dest);
+            fs.chmodSync(dest, (srcStat.mode & 0o777) || 0o600);
+            fs.utimesSync(dest, srcStat.atime, srcStat.mtime);
+        }
+        catch { /* best-effort; a failed carry just means a re-login */ }
+    }
+}
 export async function switchConfigSymlink(agent, version) {
     const configPath = getAgentConfigPath(agent);
     const versionConfigPath = getVersionConfigPath(agent, version);
@@ -838,6 +956,12 @@ export async function switchConfigSymlink(agent, version) {
     if (!fs.existsSync(versionConfigPath)) {
         fs.mkdirSync(versionConfigPath, { recursive: true });
     }
+    // Carry the account credential into the version we're switching to. Droid /
+    // antigravity / kimi store login as files INSIDE the per-version config home;
+    // switching versions repoints the symlink to a home that was never logged in,
+    // silently logging the CLI out. Sign-in is account-global, so seed the target
+    // home with the freshest existing credential before we flip the symlink.
+    carryForwardAuthFiles(agent, versionConfigPath);
     try {
         const stat = fs.lstatSync(configPath);
         if (stat.isSymbolicLink()) {