@phnx-labs/agents-cli 1.21.3 → 1.22.1

package/dist/lib/session/tool-store.d.ts

@@ -0,0 +1,15 @@
+import type Database from '../sqlite.js';
+import { type IndexedToolCall } from './tool-calls.js';
+import type { SessionMeta } from './types.js';
+export declare function canonicalToolLedgerPath(filePath: string): string;
+/** Resolve the transcript that actually carries tool events for split-file harnesses. */
+export declare function toolEvidenceSourcePath(filePath: string, agent: string): string;
+/** Remove cached tool evidence when its source transcript no longer exists. */
+export declare function purgeToolCalls(db: Database.Database, sessionId: string): void;
+/** Purge deleted direct children when a transcript directory's stamp changes. */
+export declare function purgeMissingToolCallsInDirectory(db: Database.Database, dirPath: string, currentFilePaths: string[]): number;
+/** Persist one parser batch and its file stamp atomically. */
+export declare function persistToolCalls(db: Database.Database, session: SessionMeta, calls: IndexedToolCall[], sourceStamp: {
+    fileMtimeMs: number;
+    fileSize: number;
+}, mode?: 'replace' | 'append', maxSessionBytes?: number): void;

package/dist/lib/session/tool-store.js

@@ -0,0 +1,198 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { TOOL_INDEX_VERSION, TOOL_INDEX_LIMIT_ORDINAL, TOOL_SESSION_EVIDENCE_MAX_BYTES, toolCallEvidenceBytes, toolCallKey, } from './tool-calls.js';
+export function canonicalToolLedgerPath(filePath) {
+    let probe = path.resolve(filePath);
+    const suffix = [];
+    while (true) {
+        try {
+            return path.join(fs.realpathSync(probe), ...suffix.reverse());
+        }
+        catch {
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                return path.resolve(filePath);
+            suffix.push(path.basename(probe));
+            probe = parent;
+        }
+    }
+}
+/** Resolve the transcript that actually carries tool events for split-file harnesses. */
+export function toolEvidenceSourcePath(filePath, agent) {
+    if (agent === 'kimi' && path.basename(filePath) === 'state.json') {
+        return path.join(path.dirname(filePath), 'agents', 'main', 'wire.jsonl');
+    }
+    if (agent === 'grok' && path.basename(filePath) === 'summary.json') {
+        return path.join(path.dirname(filePath), 'chat_history.jsonl');
+    }
+    return filePath;
+}
+function deleteSessionCalls(db, sessionId) {
+    const keys = db.prepare(`SELECT call_key FROM tool_calls WHERE session_id = ?`).all(sessionId);
+    for (const { call_key } of keys) {
+        db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`).run(call_key);
+        db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`).run(call_key);
+        db.prepare(`DELETE FROM tool_call_text WHERE call_key = ?`).run(call_key);
+    }
+    db.prepare(`DELETE FROM tool_calls WHERE session_id = ?`).run(sessionId);
+}
+/** Remove cached tool evidence when its source transcript no longer exists. */
+export function purgeToolCalls(db, sessionId) {
+    deleteSessionCalls(db, sessionId);
+    db.prepare(`DELETE FROM tool_scan_ledger WHERE session_id = ?`).run(sessionId);
+}
+/** Purge deleted direct children when a transcript directory's stamp changes. */
+export function purgeMissingToolCallsInDirectory(db, dirPath, currentFilePaths) {
+    const normalizedDir = path.normalize(dirPath);
+    const prefix = normalizedDir.endsWith(path.sep) ? normalizedDir : normalizedDir + path.sep;
+    const present = new Set(currentFilePaths.map((filePath) => path.normalize(filePath)));
+    const rows = db.prepare(`
+    SELECT s.id, s.file_path, s.agent
+    FROM sessions s
+    WHERE substr(s.file_path, 1, ?) = ?
+  `).all(prefix.length, prefix);
+    let purged = 0;
+    for (const row of rows) {
+        const filePath = path.normalize(row.file_path);
+        if (path.dirname(filePath) !== normalizedDir || present.has(filePath))
+            continue;
+        purgeToolCalls(db, row.id);
+        purged++;
+    }
+    return purged;
+}
+/** Persist one parser batch and its file stamp atomically. */
+export function persistToolCalls(db, session, calls, sourceStamp, mode = 'replace', maxSessionBytes = TOOL_SESSION_EVIDENCE_MAX_BYTES) {
+    const sourcePath = toolEvidenceSourcePath(session.filePath, session.agent);
+    const insertCall = db.prepare(`
+    INSERT INTO tool_calls (
+      call_key, session_id, ordinal, source_call_id, timestamp, tool, input,
+      outcome, exit_code, status_code, error_code, output, error, parse_error
+      , evidence_bytes
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id, ordinal) DO UPDATE SET
+      source_call_id = excluded.source_call_id,
+      timestamp = excluded.timestamp,
+      tool = excluded.tool,
+      input = excluded.input,
+      outcome = excluded.outcome,
+      exit_code = excluded.exit_code,
+      status_code = excluded.status_code,
+      error_code = excluded.error_code,
+      output = excluded.output,
+      error = excluded.error,
+      parse_error = excluded.parse_error,
+      evidence_bytes = excluded.evidence_bytes
+  `);
+    const insertProgram = db.prepare(`INSERT OR IGNORE INTO tool_call_programs (call_key, program) VALUES (?, ?)`);
+    const insertOccurrence = db.prepare(`
+    INSERT INTO tool_program_occurrences (call_key, occurrence_ordinal, program, role)
+    VALUES (?, ?, ?, ?)
+  `);
+    const insertText = db.prepare(`INSERT INTO tool_call_text (call_key, tool, input, output, error) VALUES (?, ?, ?, ?, ?)`);
+    const deletePrograms = db.prepare(`DELETE FROM tool_call_programs WHERE call_key = ?`);
+    const deleteOccurrences = db.prepare(`DELETE FROM tool_program_occurrences WHERE call_key = ?`);
+    const deleteText = db.prepare(`DELETE FROM tool_call_text WHERE call_key = ?`);
+    const deleteCall = db.prepare(`DELETE FROM tool_calls WHERE call_key = ?`);
+    const writeLedger = db.prepare(`
+    INSERT INTO tool_scan_ledger (
+      session_id, file_path, file_mtime_ms, file_size, extractor_version, indexed_at, call_count,
+      evidence_bytes
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_path = excluded.file_path,
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      indexed_at = excluded.indexed_at,
+      call_count = excluded.call_count,
+      evidence_bytes = excluded.evidence_bytes
+  `);
+    const txn = db.transaction(() => {
+        if (mode === 'replace')
+            deleteSessionCalls(db, session.id);
+        const ledgerPath = canonicalToolLedgerPath(sourcePath);
+        const priorLedger = mode === 'append'
+            ? db.prepare(`SELECT call_count, evidence_bytes FROM tool_scan_ledger WHERE session_id = ?`).get(session.id)
+            : undefined;
+        if (mode === 'append' && !priorLedger) {
+            throw new Error('Append tool evidence requires an existing tool ledger row.');
+        }
+        if (mode === 'append' && calls.length === 0) {
+            writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), priorLedger.call_count, priorLedger.evidence_bytes);
+            return;
+        }
+        const limitKey = toolCallKey(session.id, TOOL_INDEX_LIMIT_ORDINAL);
+        const existingSize = db.prepare(`
+      SELECT evidence_bytes FROM tool_calls WHERE session_id = ? AND ordinal = ?
+    `);
+        const priorLimit = mode === 'append'
+            ? existingSize.get(session.id, TOOL_INDEX_LIMIT_ORDINAL)
+            : undefined;
+        deletePrograms.run(limitKey);
+        deleteOccurrences.run(limitKey);
+        deleteText.run(limitKey);
+        deleteCall.run(limitKey);
+        const existingRows = mode === 'append'
+            ? calls.map((call) => ({
+                ordinal: call.ordinal,
+                bytes: existingSize.get(session.id, call.ordinal)?.evidence_bytes ?? 0,
+            }))
+            : [];
+        const existingByOrdinal = new Map(existingRows.map((row) => [row.ordinal, row.bytes]));
+        let storedBytes = priorLedger?.evidence_bytes ?? 0;
+        let count = priorLedger?.call_count ?? 0;
+        if (priorLimit) {
+            storedBytes -= priorLimit.evidence_bytes;
+            count--;
+        }
+        const limitCall = {
+            ordinal: TOOL_INDEX_LIMIT_ORDINAL,
+            timestamp: session.timestamp,
+            tool: 'index_limit',
+            programs: [],
+            programOccurrences: [],
+            input: `Tool evidence stopped at the ${Math.floor(maxSessionBytes / 1024 / 1024)} MiB per-session payload limit.`,
+            outcome: 'unknown',
+            parseError: 'Additional tool calls were not indexed for this session.',
+        };
+        const limitBytes = toolCallEvidenceBytes(limitCall);
+        const ordinaryLimit = Math.max(0, maxSessionBytes - limitBytes);
+        const accepted = [];
+        let truncated = false;
+        for (const call of [...calls].sort((a, b) => a.ordinal - b.ordinal)) {
+            const replacingBytes = existingByOrdinal.get(call.ordinal) ?? 0;
+            const nextBytes = storedBytes - replacingBytes + toolCallEvidenceBytes(call);
+            if (nextBytes > ordinaryLimit) {
+                truncated = true;
+                break;
+            }
+            storedBytes = nextBytes;
+            accepted.push(call);
+            if (!existingByOrdinal.has(call.ordinal) || replacingBytes === 0)
+                count++;
+        }
+        if (truncated) {
+            if (storedBytes + limitBytes <= maxSessionBytes) {
+                accepted.push(limitCall);
+                storedBytes += limitBytes;
+                count++;
+            }
+        }
+        for (const call of accepted) {
+            const key = toolCallKey(session.id, call.ordinal);
+            insertCall.run(key, session.id, call.ordinal, call.sourceCallId ?? null, call.timestamp, call.tool, call.input, call.outcome, call.exitCode ?? null, call.statusCode ?? null, call.errorCode ?? null, call.output ?? null, call.error ?? null, call.parseError ?? null, toolCallEvidenceBytes(call));
+            deletePrograms.run(key);
+            deleteOccurrences.run(key);
+            deleteText.run(key);
+            for (const program of call.programs)
+                insertProgram.run(key, program);
+            call.programOccurrences.forEach((occurrence, occurrenceOrdinal) => {
+                insertOccurrence.run(key, occurrenceOrdinal, occurrence.program, occurrence.role);
+            });
+            insertText.run(key, call.tool, call.input, call.output ?? '', call.error ?? '');
+        }
+        writeLedger.run(session.id, ledgerPath, sourceStamp.fileMtimeMs, sourceStamp.fileSize, TOOL_INDEX_VERSION, Date.now(), count, storedBytes);
+    });
+    txn();
+}

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

@@ -24,10 +24,17 @@ export interface SessionEvent {
     role?: 'user' | 'assistant';
     content?: string;
     tool?: string;
+    /** Harness-native call identity, used to correlate concurrent results. */
+    callId?: string;
     args?: Record<string, any>;
     path?: string;
     command?: string;
     success?: boolean;
+    /** Structured harness outcome; never inferred from free-text output. */
+    outcome?: 'ok' | 'error' | 'unknown';
+    exitCode?: number;
+    statusCode?: number;
+    errorCode?: string;
     output?: string;
     /** Internal: marks tool_use events from local commands */
     _local?: boolean;

package/dist/lib/state.d.ts

@@ -272,7 +272,16 @@ export declare function getCompanionDir(): string;
 export declare function getBrowserRuntimeDir(): string;
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export declare function getHelpersDir(): string;
-/** Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/). */
+/**
+ * Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/) — holds
+ * the daemon pid file, heartbeat, start lock, and log. AGENTS_DAEMON_DIR
+ * redirects it to a fork-private temp so daemon tests (which write pid/heartbeat
+ * files and acquire the real start lock) can never clobber a live daemon's state
+ * on a dev machine — the surgical mirror of AGENTS_DEVICES_DIR /
+ * AGENTS_HOOK_SHIMS_DIR, leaving HOME untouched. Read at CALL time (daemon.ts
+ * resolves every path helper through this), so tests/setup.ts can set it before
+ * the daemon module is exercised. Never set in production code.
+ */
 export declare function getDaemonDir(): string;
 /** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
 export declare function getPtyDir(): string;

package/dist/lib/state.js

@@ -579,8 +579,17 @@ export function getCompanionDir() { return COMPANION_CACHE_DIR; }
 export function getBrowserRuntimeDir() { return BROWSER_RUNTIME_DIR; }
 /** Path to helper subprocess scratch (~/.agents/.cache/helpers/). */
 export function getHelpersDir() { return HELPERS_DIR; }
-/** Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/). */
-export function getDaemonDir() { return DAEMON_DIR; }
+/**
+ * Path to scheduler daemon scratch (~/.agents/.cache/helpers/daemon/) — holds
+ * the daemon pid file, heartbeat, start lock, and log. AGENTS_DAEMON_DIR
+ * redirects it to a fork-private temp so daemon tests (which write pid/heartbeat
+ * files and acquire the real start lock) can never clobber a live daemon's state
+ * on a dev machine — the surgical mirror of AGENTS_DEVICES_DIR /
+ * AGENTS_HOOK_SHIMS_DIR, leaving HOME untouched. Read at CALL time (daemon.ts
+ * resolves every path helper through this), so tests/setup.ts can set it before
+ * the daemon module is exercised. Never set in production code.
+ */
+export function getDaemonDir() { return process.env.AGENTS_DAEMON_DIR ?? DAEMON_DIR; }
 /** Path to PTY server scratch (~/.agents/.cache/helpers/pty/). */
 export function getPtyDir() { return PTY_DIR; }
 /** Path to tmux scratch (~/.agents/.cache/helpers/tmux/) — shared server socket + per-session meta JSONs. */

package/dist/lib/teams/remoteWorktree.d.ts

@@ -26,10 +26,9 @@ export declare function remoteDefaultBranch(target: string, repoPath: string): s
  * Create a worktree on the host for a teammate, branched off the freshly-fetched
  * default branch. Returns the absolute worktree path on the host.
  *
- * Mirrors local `createWorktree`, with two deliberate differences: it fetches
- * origin first (the orchestrator can't reach into the host's tree to do it), and
- * it bases the branch on `origin/<default>` rather than local `HEAD` so a stale
- * checkout on the host can't fork the teammate off old code.
+ * Same base policy as local `createWorktree`: fetch origin, then
+ * `worktree add -b … origin/<default>` so a stale checkout can't fork the
+ * teammate off old code.
  */
 export declare function createRemoteWorktree(target: string, repoPath: string, worktreeName: string): string;
 /**

package/dist/lib/teams/remoteWorktree.js

@@ -87,10 +87,9 @@ export function remoteDefaultBranch(target, repoPath) {
  * Create a worktree on the host for a teammate, branched off the freshly-fetched
  * default branch. Returns the absolute worktree path on the host.
  *
- * Mirrors local `createWorktree`, with two deliberate differences: it fetches
- * origin first (the orchestrator can't reach into the host's tree to do it), and
- * it bases the branch on `origin/<default>` rather than local `HEAD` so a stale
- * checkout on the host can't fork the teammate off old code.
+ * Same base policy as local `createWorktree`: fetch origin, then
+ * `worktree add -b … origin/<default>` so a stale checkout can't fork the
+ * teammate off old code.
  */
 export function createRemoteWorktree(target, repoPath, worktreeName) {
     assertValidSshTarget(target);

package/dist/lib/teams/worktree.d.ts

@@ -22,7 +22,17 @@ export declare const DEFAULT_DIFF_MAX_BYTES = 200000;
  */
 export declare function gitDiff(worktreePath: string, maxBytes?: number): Promise<string>;
 /**
- * Create a new git worktree for a teammate.
+ * Resolve the repo's default branch name (origin/HEAD → `main`/`master`/…).
+ * Refreshes origin/HEAD first so a repo cloned before the default was set resolves.
+ * Falls back to `main` when origin/HEAD isn't set.
+ */
+export declare function localDefaultBranch(gitRoot: string): Promise<string>;
+/**
+ * Create a new git worktree for a teammate, branched off the freshly-fetched
+ * default branch. Fetches `origin` first and bases the branch on
+ * `origin/<default>` so a stale local checkout cannot fork teammates off old
+ * code. Matches `createRemoteWorktree` — local and remote isolation share one
+ * base policy.
  *
  * @param repoDir - Directory inside the git repository
  * @param worktreeName - Name for the worktree (used in path and branch)

package/dist/lib/teams/worktree.js

@@ -77,7 +77,34 @@ export async function gitDiff(worktreePath, maxBytes = DEFAULT_DIFF_MAX_BYTES) {
     }
 }
 /**
- * Create a new git worktree for a teammate.
+ * Resolve the repo's default branch name (origin/HEAD → `main`/`master`/…).
+ * Refreshes origin/HEAD first so a repo cloned before the default was set resolves.
+ * Falls back to `main` when origin/HEAD isn't set.
+ */
+export async function localDefaultBranch(gitRoot) {
+    try {
+        await execFileAsync('git', ['remote', 'set-head', 'origin', '--auto'], { cwd: gitRoot });
+    }
+    catch {
+        // Offline / no origin — fall through to symbolic-ref or main.
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { cwd: gitRoot });
+        const base = stdout.trim().replace(/^origin\//, '');
+        if (base)
+            return base;
+    }
+    catch {
+        // no origin/HEAD
+    }
+    return 'main';
+}
+/**
+ * Create a new git worktree for a teammate, branched off the freshly-fetched
+ * default branch. Fetches `origin` first and bases the branch on
+ * `origin/<default>` so a stale local checkout cannot fork teammates off old
+ * code. Matches `createRemoteWorktree` — local and remote isolation share one
+ * base policy.
  *
  * @param repoDir - Directory inside the git repository
  * @param worktreeName - Name for the worktree (used in path and branch)
@@ -90,10 +117,21 @@ export async function createWorktree(repoDir, worktreeName) {
     const gitRoot = await getGitRoot(repoDir);
     const worktreePath = safeJoin(path.join(gitRoot, '.agents', 'worktrees'), worktreeName);
     const branchName = `agents/${worktreeName}`;
+    const base = await localDefaultBranch(gitRoot);
     await fs.mkdir(path.dirname(worktreePath), { recursive: true });
-    await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath, 'HEAD'], {
-        cwd: gitRoot,
-    });
+    // Fetch first so origin/<default> is current. Fail loud on network errors —
+    // silent fallback to HEAD is how swarms write on a days-stale base and only
+    // discover it at merge time.
+    try {
+        await execFileAsync('git', ['fetch', 'origin'], { cwd: gitRoot });
+    }
+    catch (err) {
+        const detail = (err?.stderr || err?.message || String(err)).toString().trim();
+        throw new Error(`createWorktree: git fetch origin failed in ${gitRoot}` +
+            (detail ? `: ${detail}` : '') +
+            `. Cannot base a teammate worktree on a stale remote-tracking ref.`);
+    }
+    await execFileAsync('git', ['worktree', 'add', '-b', branchName, worktreePath, `origin/${base}`], { cwd: gitRoot });
     return worktreePath;
 }
 /**

package/dist/lib/types.d.ts

@@ -11,6 +11,23 @@ import type { FeedBroadcastConfig } from './feed-broadcast.js';
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
+/**
+ * Reserved `<agent>` keyword for `agents run auto` — full-auto dispatch:
+ * host (14d launch affinity) → harness (best-account headroom, weighted) →
+ * account (balanced). Lives in lib (not commands/) because both the run
+ * command (exec.ts) and the host dispatch layer (hosts/dispatch.ts, which
+ * arms the chain-hop guard for remote `run auto`) must agree on it.
+ */
+export declare const RUN_AUTO_KEYWORD = "auto";
+/**
+ * Env var a host dispatcher exports into the remote SHELL when it dispatches
+ * `agents run auto`: tells the remote CLI its host layer is already resolved,
+ * so it must not re-run affinity and chain-hop to a third host. It rides the
+ * shell-export prelude (hosts/dispatch.ts `remoteRunShellPrelude`) because
+ * `--env` flags only reach the spawned AGENT's env — the remote CLI's own
+ * process.env (which exec.ts `runAutoDefaultsToAffinity` reads) never sees them.
+ */
+export declare const RUN_AUTO_HOST_RESOLVED_ENV = "AGENTS_RUN_AUTO_HOST_RESOLVED";
 /** Per-agent run strategy config. */
 export interface AgentRunConfig {
     strategy?: RunStrategy;

package/dist/lib/types.js

@@ -5,6 +5,23 @@
  * configuration schemas, resource tracking, registry types, and permission
  * formats for each supported agent.
  */
+/**
+ * Reserved `<agent>` keyword for `agents run auto` — full-auto dispatch:
+ * host (14d launch affinity) → harness (best-account headroom, weighted) →
+ * account (balanced). Lives in lib (not commands/) because both the run
+ * command (exec.ts) and the host dispatch layer (hosts/dispatch.ts, which
+ * arms the chain-hop guard for remote `run auto`) must agree on it.
+ */
+export const RUN_AUTO_KEYWORD = 'auto';
+/**
+ * Env var a host dispatcher exports into the remote SHELL when it dispatches
+ * `agents run auto`: tells the remote CLI its host layer is already resolved,
+ * so it must not re-run affinity and chain-hop to a third host. It rides the
+ * shell-export prelude (hosts/dispatch.ts `remoteRunShellPrelude`) because
+ * `--env` flags only reach the spawned AGENT's env — the remote CLI's own
+ * process.env (which exec.ts `runAutoDefaultsToAffinity` reads) never sees them.
+ */
+export const RUN_AUTO_HOST_RESOLVED_ENV = 'AGENTS_RUN_AUTO_HOST_RESOLVED';
 /** Every canonical mode in declaration order. Useful for iteration / validation. */
 export const ALL_MODES = ['plan', 'edit', 'auto', 'skip'];
 /** Canonical system repo cloned into ~/.agents/.system/. */

package/dist/lib/versions.js

@@ -1267,34 +1267,23 @@ export function isVersionIsolated(agent, version) {
     return fs.existsSync(getIsolatedMarkerPath(agent, version));
 }
 /**
- * Grok's official installer writes into ~/.grok/downloads, which (because we
- * symlink ~/.grok to the active version home) resolves to the PREVIOUS default
- * home during `agents add grok@<new>`. Move the freshly-downloaded binary and
- * its generic platform copy into the target version's isolated home so
- * `listInstalledVersions` and the shim resolve the right binary.
+ * Move any `grok-<installedVersion>-...` binary (and its generic platform
+ * copy) found directly under `sourceDownloads` into `targetDownloads`.
+ * Returns true if the versioned binary was moved.
  */
-function relocateGrokBinaryToVersionHome(installedVersion) {
-    const hostGrokLink = path.join(getHomeDir(), agentConfigDirName('grok'));
-    let sourceDownloads;
-    try {
-        sourceDownloads = path.join(fs.readlinkSync(hostGrokLink), 'downloads');
-    }
-    catch {
-        sourceDownloads = path.join(hostGrokLink, 'downloads');
-    }
-    const targetDownloads = path.join(getVersionHomePath('grok', installedVersion), agentConfigDirName('grok'), 'downloads');
+function tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion) {
     if (!fs.existsSync(sourceDownloads))
-        return;
+        return false;
     if (path.resolve(sourceDownloads) === path.resolve(targetDownloads))
-        return;
+        return false;
     const entries = fs.readdirSync(sourceDownloads).filter((e) => e.startsWith('grok-'));
     if (entries.length === 0)
-        return;
-    fs.mkdirSync(targetDownloads, { recursive: true });
+        return false;
     const escapedVersion = installedVersion.replace(/\./g, '\\.');
     const versionedPattern = new RegExp(`^grok-${escapedVersion}-`);
     const movedPaths = [];
-    // Move the versioned binary first.
+    // Move the versioned binary first — only create the target dir once we
+    // know there is something to move into it.
     for (const entry of entries) {
         if (!versionedPattern.test(entry))
             continue;
@@ -1303,6 +1292,7 @@ function relocateGrokBinaryToVersionHome(installedVersion) {
         if (fs.existsSync(dst))
             continue;
         try {
+            fs.mkdirSync(targetDownloads, { recursive: true });
             fs.renameSync(src, dst);
             movedPaths.push(dst);
         }
@@ -1311,7 +1301,7 @@ function relocateGrokBinaryToVersionHome(installedVersion) {
         }
     }
     if (movedPaths.length === 0)
-        return;
+        return false;
     // The installer also creates a generic platform binary (e.g. grok-macos-aarch64)
     // that is a copy of the versioned binary. Move it too if its size matches.
     const movedSize = fs.statSync(movedPaths[0]).size;
@@ -1331,6 +1321,42 @@ function relocateGrokBinaryToVersionHome(installedVersion) {
             /* ignore per-file failures */
         }
     }
+    return true;
+}
+/**
+ * Grok's official installer writes into ~/.grok/downloads, which (because we
+ * symlink ~/.grok to the active version home) resolves to the PREVIOUS default
+ * home during `agents add grok@<new>`. Move the freshly-downloaded binary and
+ * its generic platform copy into the target version's isolated home so
+ * `listInstalledVersions` and the shim resolve the right binary.
+ *
+ * Self-healing: if `~/.grok`'s current target has nothing matching (e.g. a
+ * PAST install mislabeled `installedVersion` as the literal string 'latest',
+ * whose regex never matched the real filename, stranding the binary in
+ * whatever version was default at the time), sweep every other installed
+ * grok version home for the missing file before giving up.
+ */
+function relocateGrokBinaryToVersionHome(installedVersion) {
+    const hostGrokLink = path.join(getHomeDir(), agentConfigDirName('grok'));
+    let sourceDownloads;
+    try {
+        sourceDownloads = path.join(fs.readlinkSync(hostGrokLink), 'downloads');
+    }
+    catch {
+        sourceDownloads = path.join(hostGrokLink, 'downloads');
+    }
+    const targetDownloads = path.join(getVersionHomePath('grok', installedVersion), agentConfigDirName('grok'), 'downloads');
+    if (tryMoveGrokDownloads(sourceDownloads, targetDownloads, installedVersion))
+        return;
+    for (const version of listInstalledVersions('grok')) {
+        if (version === installedVersion)
+            continue;
+        const candidate = path.join(getVersionHomePath('grok', version), agentConfigDirName('grok'), 'downloads');
+        if (path.resolve(candidate) === path.resolve(sourceDownloads))
+            continue; // already tried
+        if (tryMoveGrokDownloads(candidate, targetDownloads, installedVersion))
+            return;
+    }
 }
 /**
  * Install a specific version of an agent.
@@ -1376,7 +1402,28 @@ export async function installVersion(agent, version, onProgress, opts) {
                 await execAsync(script, { timeout: 120000 });
             }
             if (version === 'latest') {
-                installedVersion = await getCliVersionFromPath(agent) || version;
+                // A freshly-installed self-updating binary (grok, …) can take a
+                // moment to become resolvable on PATH right after the installer
+                // exits — retry briefly rather than silently falling back to the
+                // literal string 'latest'. That fallback used to corrupt version
+                // bookkeeping downstream: it creates a bogus `versions/<agent>/latest/`
+                // dir, and for grok specifically defeats relocateGrokBinaryToVersionHome
+                // (its exact-filename regex can never match `grok-latest-...`), which
+                // permanently strands the real downloaded binary in the PREVIOUS
+                // default's downloads dir.
+                let probed = await getCliVersionFromPath(agent);
+                for (let attempt = 0; !probed && attempt < 2; attempt++) {
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                    probed = await getCliVersionFromPath(agent);
+                }
+                if (!probed) {
+                    return {
+                        success: false,
+                        installedVersion: version,
+                        error: `${agentConfig.name} installed but its version could not be determined after several attempts.`,
+                    };
+                }
+                installedVersion = probed;
                 // Fold any stale literal `latest` dir from an earlier probe-failed
                 // install into the real version so it stops shadowing `agents view`.
                 await reconcileStaleLatestDir(agent, installedVersion);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.21.3",
+  "version": "1.22.1",
   "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",
@@ -89,6 +89,7 @@
     "@types/proper-lockfile": "4.1.4",
     "@xterm/headless": "6.0.0",
     "@zed-industries/agent-client-protocol": "0.4.5",
+    "acorn": "8.18.0",
     "age-encryption": "0.3.0",
     "chalk": "5.6.2",
     "commander": "15.0.0",
@@ -101,6 +102,7 @@
     "shlex": "3.0.0",
     "simple-git": "3.36.0",
     "smol-toml": "1.7.0",
+    "unbash": "4.0.5",
     "ws": "^8.21.0",
     "yaml": "2.9.0"
   },