@phnx-labs/agents-cli 1.20.15 → 1.20.16

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

@@ -0,0 +1,251 @@
+/**
+ * Cross-machine session sync orchestration.
+ *
+ *  PUSH  this machine's transcripts (changed since last tick) to its own R2
+ *        prefix, then publish a manifest. Single-writer prefixes mean no two
+ *        machines ever write the same object — zero remote contention.
+ *
+ *  PULL  every other machine's manifest, fetch changed transcripts, CRDT-union
+ *        copies of the same session, and write the result into the local mirror
+ *        (a scan root). The existing scanner indexes it; sessions present in the
+ *        live home always win, so the mirror only fills in remote-origin sessions.
+ *
+ * Invariants:
+ *  - Live home transcripts are only ever READ + uploaded, never rewritten.
+ *  - Union is idempotent, so once sets match nothing is transferred (quiescence).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { R2Client } from './r2.js';
+import { loadR2Config, machineId } from './config.js';
+import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, SESSIONS_PREFIX, } from './agents.js';
+import { mergeTranscripts, transcriptStats } from './crdt.js';
+import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, } from './manifest.js';
+const nowIso = () => new Date().toISOString();
+function specById(id) {
+    return SYNC_AGENTS.find(s => s.id === id);
+}
+/** Upload this machine's changed transcripts and publish its manifest. */
+async function pushOwn(r2, me, opts, result) {
+    const ledger = loadLedger();
+    const prev = loadLocalManifest();
+    const manifest = emptyManifest(me, nowIso());
+    for (const spec of SYNC_AGENTS) {
+        const agentManifest = {};
+        for (const t of listLocalTranscripts(spec)) {
+            let stat;
+            try {
+                stat = fs.statSync(t.absPath);
+            }
+            catch {
+                continue;
+            }
+            const prevEntry = prev?.agents?.[spec.id]?.[t.sessionId];
+            if (prevEntry && ledgerUnchanged(ledger, t.absPath, stat.size, stat.mtimeMs)) {
+                agentManifest[t.sessionId] = prevEntry; // unchanged: reuse, no read, no upload
+                result.pushSkipped++;
+                continue;
+            }
+            let content;
+            try {
+                content = fs.readFileSync(t.absPath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const hash = hashContent(content);
+            const { lastTs } = transcriptStats(content);
+            const entry = { relKey: t.relKey, size: stat.size, hash, lastTs };
+            try {
+                await r2.put(objectKey(me, spec.id, t.sessionId), content, 'application/x-ndjson');
+                ledgerRecord(ledger, t.absPath, stat.size, stat.mtimeMs, hash);
+                agentManifest[t.sessionId] = entry;
+                result.pushed++;
+                if (opts.verbose)
+                    opts.log?.(`  push ${spec.id}/${t.sessionId.slice(0, 8)} (${stat.size}B)`);
+            }
+            catch (err) {
+                result.errors.push(`push ${spec.id}/${t.sessionId}: ${err.message}`);
+            }
+        }
+        if (Object.keys(agentManifest).length > 0)
+            manifest.agents[spec.id] = agentManifest;
+    }
+    try {
+        await r2.put(manifestKey(me), JSON.stringify(manifest), 'application/json');
+        saveLocalManifest(manifest);
+        saveLedger(ledger);
+    }
+    catch (err) {
+        result.errors.push(`manifest publish: ${err.message}`);
+    }
+}
+/**
+ * Decide which remote sessions need fetching this tick. Pure: no I/O.
+ * Skips sessions we hold locally (home wins) and sessions whose source set is
+ * unchanged since we last materialized them (pull-state hit → quiescence).
+ */
+export function selectSessionsToFetch(copies, localIdsByAgent, pullState) {
+    const pending = [];
+    for (const [agentId, byAgent] of copies) {
+        const localIds = localIdsByAgent.get(agentId) ?? new Set();
+        for (const [sessionId, list] of byAgent) {
+            if (localIds.has(sessionId))
+                continue;
+            const sig = sourceSignature(list.map(c => c.entry.hash));
+            if (pullState[`${agentId}/${sessionId}`] === sig)
+                continue;
+            pending.push({ agentId, sessionId, copies: list, sig });
+        }
+    }
+    return pending;
+}
+/**
+ * Resolve the mirror destination + merged content for one session. Pure.
+ * The canonical path comes from the lexicographically-smallest machine so every
+ * puller derives an identical location; the content is the CRDT union of copies.
+ */
+export function resolveMirrorWrite(spec, copies, contents) {
+    const canonical = [...copies].sort((a, b) => (a.machine < b.machine ? -1 : a.machine > b.machine ? 1 : 0))[0];
+    const content = contents.length === 1 ? contents[0] : mergeTranscripts(contents);
+    return {
+        dest: mirrorPath(spec, canonical.machine, canonical.entry.relKey),
+        content,
+        merged: contents.length > 1,
+    };
+}
+/**
+ * Decide how to reconcile one session's fetched copies. Pure: no I/O.
+ *
+ * `fetched` is positionally aligned to `copies` — a `null` slot means that
+ * copy's object wasn't retrievable this tick (R2 404 / LIST→GET consistency
+ * lag / a transient get error). If ANY listed copy is missing, returns `null`:
+ * the caller must then skip the mirror write AND skip stamping pull-state, so
+ * the session is retried next tick. Writing a partial set instead would
+ * materialize a non-converged union and — because pull-state would record the
+ * full source signature — abandon the missing branch forever (the bug this
+ * guards: a signature match in selectSessionsToFetch never re-fetches it).
+ */
+export function reconcileCopies(spec, copies, fetched) {
+    const contents = [];
+    for (const text of fetched) {
+        if (text === null)
+            return null; // incomplete fetch — retry next tick
+        contents.push(text);
+    }
+    if (contents.length === 0)
+        return null;
+    return resolveMirrorWrite(spec, copies, contents);
+}
+/** Fetch other machines' manifests, union changed sessions into the mirror. */
+async function pullAndReconcile(r2, me, opts, result) {
+    const prefixes = await r2.listPrefixes(SESSIONS_PREFIX); // sessions/<machine>/
+    const machines = prefixes
+        .map(p => p.slice(SESSIONS_PREFIX.length).replace(/\/$/, ''))
+        .filter(m => m && m !== me);
+    // agentId -> sessionId -> copies across machines
+    const copies = new Map();
+    for (const m of machines) {
+        let manifest = null;
+        try {
+            const text = await r2.get(manifestKey(m));
+            manifest = text ? parseManifest(text) : null;
+        }
+        catch (err) {
+            result.errors.push(`fetch manifest ${m}: ${err.message}`);
+        }
+        if (!manifest)
+            continue;
+        for (const [agentId, sessions] of Object.entries(manifest.agents)) {
+            if (!specById(agentId))
+                continue;
+            let byAgent = copies.get(agentId);
+            if (!byAgent)
+                copies.set(agentId, (byAgent = new Map()));
+            for (const [sessionId, entry] of Object.entries(sessions)) {
+                const list = byAgent.get(sessionId) ?? [];
+                list.push({ machine: m, entry });
+                byAgent.set(sessionId, list);
+            }
+        }
+    }
+    const pullState = loadPullState();
+    const localIdsByAgent = new Map();
+    for (const agentId of copies.keys()) {
+        const spec = specById(agentId);
+        if (spec)
+            localIdsByAgent.set(agentId, localSessionIds(spec));
+    }
+    const pending = selectSessionsToFetch(copies, localIdsByAgent, pullState);
+    let candidates = 0;
+    for (const byAgent of copies.values())
+        candidates += byAgent.size;
+    result.pullSkipped += candidates - pending.length; // local-owned or unchanged
+    for (const { agentId, sessionId, copies: list, sig } of pending) {
+        const spec = specById(agentId);
+        // Download each copy (could be a fork across >1 machine), keeping the
+        // result positionally aligned to `list` — null marks a copy we couldn't
+        // fetch this tick (404 / consistency lag / error).
+        const fetched = [];
+        for (const c of list) {
+            try {
+                fetched.push(await r2.get(objectKey(c.machine, agentId, sessionId)));
+            }
+            catch (err) {
+                result.errors.push(`get ${c.machine}/${sessionId}: ${err.message}`);
+                fetched.push(null);
+            }
+        }
+        // null ⇒ an incomplete fetch: skip the write AND the pull-state stamp so we
+        // retry next tick instead of persisting a partial union / abandoning a branch.
+        const resolved = reconcileCopies(spec, list, fetched);
+        if (!resolved)
+            continue;
+        const { dest, content, merged } = resolved;
+        try {
+            let existing = null;
+            try {
+                existing = fs.readFileSync(dest, 'utf-8');
+            }
+            catch { /* not present yet */ }
+            if (existing !== content) {
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                fs.writeFileSync(dest, content, 'utf-8');
+                if (merged)
+                    result.merged++;
+                result.pulled++;
+                if (opts.verbose) {
+                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)} <- ${list.map(c => c.machine).join('+')}`);
+                }
+            }
+            else {
+                result.pullSkipped++;
+            }
+            pullState[`${agentId}/${sessionId}`] = sig;
+        }
+        catch (err) {
+            result.errors.push(`write mirror ${sessionId}: ${err.message}`);
+        }
+    }
+    savePullState(pullState);
+}
+/** Run one full sync cycle: push this machine's changes, pull everyone else's. */
+export async function syncSessions(opts = {}) {
+    const cfg = loadR2Config();
+    const me = machineId();
+    const r2 = new R2Client(cfg);
+    const result = {
+        machine: me,
+        pushed: 0,
+        pushSkipped: 0,
+        pulled: 0,
+        merged: 0,
+        pullSkipped: 0,
+        errors: [],
+    };
+    if (opts.push !== false)
+        await pushOwn(r2, me, opts, result);
+    if (opts.pull !== false)
+        await pullAndReconcile(r2, me, opts, result);
+    return result;
+}

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 18;
+export declare const SHIM_SCHEMA_VERSION = 19;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -202,7 +202,7 @@ async function promptConflictStrategy(conflictInfos) {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export const SHIM_SCHEMA_VERSION = 18;
+export const SHIM_SCHEMA_VERSION = 19;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -414,6 +414,22 @@ elif [ "$AGENT" = "kimi" ]; then
     # Last resort: whatever is on PATH
     BINARY=$(command -v kimi 2>/dev/null || echo "")
   fi
+# Droid (Factory AI) special case: the official installer drops a standalone
+# native binary at ~/.local/bin/droid — there is no npm package and nothing
+# lands in node_modules/.bin. Resolve the fixed install path directly. The
+# PATH fallback explicitly refuses anything under our own shims dir: that path
+# IS this dispatcher, so exec'ing it would re-enter and spin in an infinite
+# re-exec loop (the bug this branch fixes).
+elif [ "$AGENT" = "droid" ]; then
+  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
+      "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+    esac
+  fi
 else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 fi

package/dist/lib/teams/parsers.js

@@ -2,7 +2,7 @@
  * Agent event stream parsers.
  *
  * Normalizes the heterogeneous JSON event formats emitted by each agent CLI
- * (Claude, Codex, Gemini, Cursor, OpenCode, Grok, Antigravity) into a unified
+ * (Claude, Codex, Gemini, Cursor, OpenCode, Grok, Antigravity, Kimi) into a unified
  * event schema with consistent types: init, message, tool_use, bash,
  * file_read, file_write, file_create, file_delete, result, error, and others.
  */
@@ -31,6 +31,9 @@ export function normalizeEvents(agentType, raw) {
     else if (agentType === 'antigravity') {
         return normalizeAntigravity(raw);
     }
+    else if (agentType === 'kimi') {
+        return normalizeKimi(raw);
+    }
     // droid (Factory AI) intentionally falls through to the generic normalizer
     // below: its `-o stream-json` JSONL event schema is not yet verified against
     // a live run (the documented `debug` format differs from stream-json). Events
@@ -908,6 +911,161 @@ function normalizeGrok(raw) {
             timestamp: timestamp,
         }];
 }
+// --- Kimi parsing ---
+// Kimi's `--output-format stream-json` emits one JSON object per line with a
+// simple `role`-based schema:
+//   - {"role":"assistant","content":"..."}                          → final message
+//   - {"role":"assistant","tool_calls":[{"function":{"name":"Bash","arguments":"<json>"}}]} → tool use
+//   - {"role":"tool","tool_call_id":"...","content":"..."}            → tool result
+//   - {"role":"meta","type":"session.resume_hint","session_id":"..."} → init / session id
+// Tool arguments are JSON-stringified inside `function.arguments` and must be
+// parsed before extracting paths/commands. Verified against live `kimi` runs.
+function normalizeKimi(raw) {
+    const timestamp = new Date().toISOString();
+    if (!raw || typeof raw !== 'object') {
+        return [{
+                type: 'unknown',
+                agent: 'kimi',
+                raw: raw,
+                timestamp: timestamp,
+            }];
+    }
+    const role = typeof raw.role === 'string' ? raw.role : '';
+    // Assistant message (final answer or tool-call request).
+    if (role === 'assistant') {
+        const events = [];
+        if (typeof raw.content === 'string' && raw.content) {
+            events.push({
+                type: 'message',
+                agent: 'kimi',
+                content: raw.content,
+                complete: true,
+                timestamp: timestamp,
+            });
+        }
+        const toolCalls = Array.isArray(raw.tool_calls) ? raw.tool_calls : [];
+        for (const toolCall of toolCalls) {
+            const fn = toolCall?.function || {};
+            const toolName = typeof fn.name === 'string' ? fn.name : 'unknown';
+            let toolArgs = {};
+            if (typeof fn.arguments === 'string') {
+                try {
+                    toolArgs = JSON.parse(fn.arguments);
+                }
+                catch {
+                    toolArgs = { _raw: fn.arguments };
+                }
+            }
+            else if (fn.arguments && typeof fn.arguments === 'object') {
+                toolArgs = fn.arguments;
+            }
+            const filePath = toolArgs?.path || toolArgs?.file_path || '';
+            const command = toolArgs?.command || '';
+            // Map known tools to structured events. If a known tool is missing the
+            // fields we need (e.g. unparseable arguments), fall back to tool_use so
+            // the event is still visible in summaries rather than dropped.
+            let normalized = null;
+            if (toolName === 'Bash' && command) {
+                const bashEvents = [{
+                        type: 'bash',
+                        agent: 'kimi',
+                        tool: toolName,
+                        command: command,
+                        timestamp: timestamp,
+                    }];
+                const [filesRead, filesWritten, filesDeleted] = extractFileOpsFromBash(command);
+                for (const p of filesRead) {
+                    bashEvents.push({ type: 'file_read', agent: 'kimi', tool: 'bash', path: p, command, timestamp });
+                }
+                for (const p of filesWritten) {
+                    bashEvents.push({ type: 'file_write', agent: 'kimi', tool: 'bash', path: p, command, timestamp });
+                }
+                for (const p of filesDeleted) {
+                    bashEvents.push({ type: 'file_delete', agent: 'kimi', tool: 'bash', path: p, command, timestamp });
+                }
+                normalized = bashEvents;
+            }
+            else if (toolName === 'Read' && filePath) {
+                normalized = [{
+                        type: 'file_read',
+                        agent: 'kimi',
+                        tool: toolName,
+                        path: filePath,
+                        timestamp: timestamp,
+                    }];
+            }
+            else if (toolName === 'Edit' && filePath) {
+                normalized = [{
+                        type: 'file_write',
+                        agent: 'kimi',
+                        tool: toolName,
+                        path: filePath,
+                        timestamp: timestamp,
+                    }];
+            }
+            else if (toolName === 'Write' && filePath) {
+                normalized = [{
+                        type: 'file_create',
+                        agent: 'kimi',
+                        tool: toolName,
+                        path: filePath,
+                        timestamp: timestamp,
+                    }];
+            }
+            if (normalized) {
+                events.push(...normalized);
+            }
+            else {
+                events.push({
+                    type: 'tool_use',
+                    agent: 'kimi',
+                    tool: toolName,
+                    args: toolArgs,
+                    timestamp: timestamp,
+                });
+            }
+        }
+        return events.length > 0 ? events : [];
+    }
+    // Tool result (response to an assistant tool_call).
+    if (role === 'tool') {
+        const content = typeof raw.content === 'string' ? raw.content : '';
+        const success = raw.isError !== true && !(content && content.startsWith('Error:'));
+        return [{
+                type: 'tool_result',
+                agent: 'kimi',
+                tool_call_id: typeof raw.tool_call_id === 'string' ? raw.tool_call_id : null,
+                success: success,
+                content: content,
+                timestamp: timestamp,
+            }];
+    }
+    // Meta events (session lifecycle).
+    if (role === 'meta') {
+        const metaType = typeof raw.type === 'string' ? raw.type : '';
+        if (metaType === 'session.resume_hint') {
+            return [{
+                    type: 'init',
+                    agent: 'kimi',
+                    session_id: typeof raw.session_id === 'string' ? raw.session_id : null,
+                    timestamp: timestamp,
+                }];
+        }
+        return [{
+                type: 'meta',
+                agent: 'kimi',
+                meta_type: metaType,
+                raw: raw,
+                timestamp: timestamp,
+            }];
+    }
+    return [{
+            type: raw.type || 'unknown',
+            agent: 'kimi',
+            raw: raw,
+            timestamp: timestamp,
+        }];
+}
 // --- Antigravity parsing ---
 // Intentionally conservative. Antigravity's `agy` binary advertises an
 // `--output-format json` flag in its docs, but the released binary errors with

package/dist/lib/usage.d.ts

@@ -85,6 +85,24 @@ export declare function getUsageInfoByIdentity(inputs: UsageIdentityInput[]): Pr
 export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Promise<UsageInfo>;
 /** Format a one-line usage summary with compact bars for inline display. */
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
+/**
+ * Derive an account's real throttle state from its live usage windows — the
+ * same signal `agents usage` shows and balanced rotation trusts
+ * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
+ * the account is throttled until that window resets.
+ *
+ * Returns `null` when there is no snapshot, so callers render no badge rather
+ * than a misleading one. This deliberately never consults
+ * `cachedExtraUsageDisabledReason`: that field describes why pay-as-you-go
+ * overage is disabled (`out_of_credits` = no overage credits purchased,
+ * `org_level_disabled` = an admin turned overage off), NOT whether the account
+ * can do work right now. A Pro account at 5% weekly usage with overage disabled
+ * is fully usable, yet that flag would mislabel it "out of credits".
+ *
+ * The model-specific `sonnet_week` sub-limit is excluded: hitting it throttles
+ * one model, not the account, so it shouldn't flip the whole row to throttled.
+ */
+export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot | null | undefined): 'available' | 'rate_limited' | null;
 /**
  * Compact colored badge for the account's overall usage status. Renders only
  * when the account is throttled — `available` and `null` return ''.

package/dist/lib/usage.js

@@ -201,6 +201,31 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
     }
     return parts.join('  ');
 }
+/**
+ * Derive an account's real throttle state from its live usage windows — the
+ * same signal `agents usage` shows and balanced rotation trusts
+ * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
+ * the account is throttled until that window resets.
+ *
+ * Returns `null` when there is no snapshot, so callers render no badge rather
+ * than a misleading one. This deliberately never consults
+ * `cachedExtraUsageDisabledReason`: that field describes why pay-as-you-go
+ * overage is disabled (`out_of_credits` = no overage credits purchased,
+ * `org_level_disabled` = an admin turned overage off), NOT whether the account
+ * can do work right now. A Pro account at 5% weekly usage with overage disabled
+ * is fully usable, yet that flag would mislabel it "out of credits".
+ *
+ * The model-specific `sonnet_week` sub-limit is excluded: hitting it throttles
+ * one model, not the account, so it shouldn't flip the whole row to throttled.
+ */
+export function deriveUsageStatusFromSnapshot(snapshot) {
+    if (!snapshot || snapshot.windows.length === 0)
+        return null;
+    const blocking = snapshot.windows.filter((window) => window.key !== 'sonnet_week');
+    const windows = blocking.length > 0 ? blocking : snapshot.windows;
+    const maxUsed = Math.max(...windows.map((window) => window.usedPercent));
+    return maxUsed >= 100 ? 'rate_limited' : 'available';
+}
 /**
  * Compact colored badge for the account's overall usage status. Renders only
  * when the account is throttled — `available` and `null` return ''.

package/dist/lib/versions.js

@@ -25,7 +25,7 @@ import { checkbox, select } from '@inquirer/prompts';
 import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
 import { listResources } from './resources.js';
-import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError } from './agents.js';
+import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath } from './agents.js';
 import { discoverPermissionGroups, getActivePermissionPresetName, readPermissionPresetRecipe, PERMISSION_PRESET_ENV_VAR } from './permissions.js';
 import { parseMcpServerConfig } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
@@ -818,6 +818,14 @@ export function getBinaryPath(agent, version) {
         catch { }
         return path.join(grokDownloads, `grok-${version}`);
     }
+    if (agent === 'droid') {
+        // Factory's installer drops a standalone native binary at ~/.local/bin/droid
+        // (no npm package, nothing in node_modules/.bin). The binary is global, not
+        // per-version — config isolation rides the ~/.factory symlink switch, not a
+        // separate binary per version. Mirror the shim's `droid` branch so
+        // isVersionInstalled/`agents view` agree with what actually executes.
+        return path.join(os.homedir(), '.local', 'bin', 'droid');
+    }
     const versionDir = getVersionDir(agent, version);
     return path.join(versionDir, 'node_modules', '.bin', agentConfig.cliCommand);
 }
@@ -1005,19 +1013,28 @@ export async function installVersion(agent, version, onProgress) {
         // but `agents view` shows the agent under "Not Managed" because
         // listInstalledVersions returns [] — the installer drops the binary in
         // ~/.local/bin (or similar) rather than the version's node_modules/.bin.
-        // Grok is special-cased in getBinaryPath itself (binary lives in
-        // ~/.grok/downloads), so we skip the symlink there.
-        if (agent !== 'grok') {
-            try {
-                const { stdout: whichOut } = await execFileAsync(process.platform === 'win32' ? 'where' : 'which', [agentConfig.cliCommand]);
-                const installedBinary = whichOut.trim().split('\n')[0];
-                if (installedBinary && fs.existsSync(installedBinary)) {
-                    importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installedVersion, installedBinary, versionDir);
-                }
-            }
-            catch {
-                /* binary missing from PATH — install script failed silently; surface via the existing version.install error path below isn't possible here since the script returned 0. Leave the version dir empty so getBinaryPath check correctly reports it uninstalled. */
+        //
+        // Agents whose binary is special-cased in getBinaryPath (grok ->
+        // ~/.grok/downloads, droid -> ~/.local/bin/droid) need no symlink — and
+        // creating one is actively harmful: `which <cli>` can resolve to OUR OWN
+        // dispatcher shim, because ~/.agents/.cache/shims sits ahead of ~/.local/bin
+        // on PATH. Symlinking node_modules/.bin/<cli> at the shim makes the shim
+        // exec itself forever. So we skip the resolver-backed agents here AND, for
+        // everyone else, filter the shims dir out of the `which` candidates so the
+        // same race can't bite a non-special-cased installScript agent.
+        if (agent !== 'grok' && agent !== 'droid') {
+            // findInPath is a pure-Node PATH scan that already skips our own shims
+            // dir — so it returns the genuine install, never our dispatcher shim
+            // (which sits ahead of ~/.local/bin on PATH and would otherwise be
+            // captured, producing a self-referential node_modules/.bin/<cli> link
+            // that exec-loops forever).
+            const installedBinary = findInPath(agentConfig.cliCommand);
+            if (installedBinary) {
+                importInstallScriptBinary({ agentId: agent, npmPackage: agentConfig.npmPackage, cliCommand: agentConfig.cliCommand }, installedVersion, installedBinary, versionDir);
             }
+            /* If null: binary missing from PATH (install script failed silently) or
+               only our shim is present. Leave the version dir empty so getBinaryPath
+               correctly reports it uninstalled. */
         }
         createVersionedAlias(agent, installedVersion);
         emit('version.install', { agent, version: installedVersion });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.15",
+  "version": "1.20.16",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -82,6 +82,7 @@
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
+    "aws4fetch": "1.0.20",
     "chalk": "5.6.2",
     "commander": "15.0.0",
     "croner": "10.0.1",