@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/secrets/sync.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Remote sync client for secrets bundles.
+ *
+ * Replaces the previous "leave it to iCloud Keychain" model with explicit
+ * push/pull against api.prix.dev. Bundle contents (vars + secret values) are
+ * encrypted client-side with AES-256-GCM under a key derived from a
+ * user-supplied passphrase via PBKDF2-SHA256. Plaintext never leaves the
+ * machine — api.prix.dev only ever sees the ciphertext + KDF parameters.
+ */
+import { type SecretsBundle } from './bundles.js';
+export declare const MIN_PASSPHRASE_LEN = 12;
+/** Envelope for an encrypted bundle. All byte fields are base64. */
+export interface EncryptedEnvelope {
+    v: 1;
+    kdf: 'pbkdf2-sha256';
+    iter: number;
+    salt: string;
+    iv: string;
+    ct: string;
+    tag: string;
+}
+interface RemoteBundleSummary {
+    name: string;
+    updated_at: string;
+}
+/** Encrypt a JSON-serializable payload with a passphrase. */
+export declare function encryptBlob(plaintext: string, passphrase: string): EncryptedEnvelope;
+/** Decrypt an envelope. Throws on bad passphrase (auth tag mismatch). */
+export declare function decryptBlob(envelope: EncryptedEnvelope, passphrase: string): string;
+/** The plaintext we serialize before encrypting: bundle metadata + secret values. */
+export interface BundleSnapshot {
+    bundle: SecretsBundle;
+    /** keychain shortId -> plaintext value. Only present for keychain: refs. */
+    secrets: Record<string, string>;
+}
+/** Options for pushBundle. */
+export interface PushOptions {
+    passphrase: string;
+}
+/** Push a local bundle to api.prix.dev. Encrypts client-side; server only sees ciphertext. */
+export declare function pushBundle(name: string, opts: PushOptions): Promise<{
+    updated_at: string;
+}>;
+/** Options for pullBundle. */
+export interface PullOptions {
+    passphrase: string;
+    /** When true, overwrite an existing local bundle. */
+    force?: boolean;
+}
+/** Pull a bundle by name from api.prix.dev and materialize it locally. */
+export declare function pullBundle(name: string, opts: PullOptions): Promise<SecretsBundle>;
+/** Delete a bundle on the remote. */
+export declare function deleteRemoteBundle(name: string): Promise<boolean>;
+/** List bundles currently stored on api.prix.dev for this user. */
+export declare function listRemoteBundles(): Promise<RemoteBundleSummary[]>;
+export {};

package/dist/lib/secrets/sync.js

@@ -0,0 +1,180 @@
+/**
+ * Remote sync client for secrets bundles.
+ *
+ * Replaces the previous "leave it to iCloud Keychain" model with explicit
+ * push/pull against api.prix.dev. Bundle contents (vars + secret values) are
+ * encrypted client-side with AES-256-GCM under a key derived from a
+ * user-supplied passphrase via PBKDF2-SHA256. Plaintext never leaves the
+ * machine — api.prix.dev only ever sees the ciphertext + KDF parameters.
+ */
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { readBundle, writeBundle, keychainItemsForBundle, validateBundleName, } from './bundles.js';
+const PROXY_BASE = 'https://api.prix.dev';
+const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
+const BUNDLE_ENDPOINT = '/api/v1/secrets/bundles';
+// PBKDF2 cost. 600k SHA-256 iters matches OWASP 2023+ guidance and keeps a
+// passphrase prompt under a second on the hardware the CLI targets.
+const PBKDF2_ITER = 600_000;
+export const MIN_PASSPHRASE_LEN = 12;
+const KEY_LEN = 32;
+const SALT_LEN = 16;
+const IV_LEN = 12;
+function readRushToken() {
+    if (!fs.existsSync(USER_YAML)) {
+        throw new Error('Not logged in to Rush. Run `rush login` first.');
+    }
+    const raw = fs.readFileSync(USER_YAML, 'utf-8');
+    const data = yaml.parse(raw);
+    const token = data?.session?.access_token;
+    if (!token) {
+        throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
+    }
+    return token;
+}
+async function api(method, endpoint, body) {
+    const token = readRushToken();
+    const url = endpoint.startsWith('http') ? endpoint : `${PROXY_BASE}${endpoint}`;
+    return fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+}
+function deriveKey(passphrase, salt) {
+    return crypto.pbkdf2Sync(passphrase, salt, PBKDF2_ITER, KEY_LEN, 'sha256');
+}
+/** Encrypt a JSON-serializable payload with a passphrase. */
+export function encryptBlob(plaintext, passphrase) {
+    if (!passphrase || passphrase.length < MIN_PASSPHRASE_LEN) {
+        throw new Error(`Passphrase must be at least ${MIN_PASSPHRASE_LEN} characters.`);
+    }
+    const salt = crypto.randomBytes(SALT_LEN);
+    const iv = crypto.randomBytes(IV_LEN);
+    const key = deriveKey(passphrase, salt);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return {
+        v: 1,
+        kdf: 'pbkdf2-sha256',
+        iter: PBKDF2_ITER,
+        salt: salt.toString('base64'),
+        iv: iv.toString('base64'),
+        ct: ct.toString('base64'),
+        tag: tag.toString('base64'),
+    };
+}
+/** Decrypt an envelope. Throws on bad passphrase (auth tag mismatch). */
+export function decryptBlob(envelope, passphrase) {
+    if (envelope.v !== 1 || envelope.kdf !== 'pbkdf2-sha256') {
+        throw new Error(`Unsupported envelope version (v${envelope.v}, kdf=${envelope.kdf}).`);
+    }
+    const salt = Buffer.from(envelope.salt, 'base64');
+    const iv = Buffer.from(envelope.iv, 'base64');
+    const ct = Buffer.from(envelope.ct, 'base64');
+    const tag = Buffer.from(envelope.tag, 'base64');
+    const key = deriveKey(passphrase, salt);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf-8');
+    }
+    catch {
+        throw new Error('Decryption failed — wrong passphrase or corrupt blob.');
+    }
+}
+function snapshotBundle(name) {
+    const bundle = readBundle(name);
+    const secrets = {};
+    for (const { key, item } of keychainItemsForBundle(bundle)) {
+        if (!hasKeychainToken(item)) {
+            throw new Error(`Bundle '${name}' key '${key}': keychain item '${item}' missing — cannot push incomplete bundle.`);
+        }
+        const raw = bundle.vars[key];
+        if (typeof raw !== 'string' || !raw.startsWith('keychain:'))
+            continue;
+        const shortId = raw.slice('keychain:'.length);
+        secrets[shortId] = getKeychainToken(item);
+    }
+    return { bundle, secrets };
+}
+function restoreSnapshot(snap) {
+    const bundle = snap.bundle;
+    validateBundleName(bundle.name);
+    for (const [shortId, value] of Object.entries(snap.secrets)) {
+        const item = secretsKeychainItem(bundle.name, shortId);
+        setKeychainToken(item, value);
+    }
+    writeBundle(bundle);
+}
+/** Push a local bundle to api.prix.dev. Encrypts client-side; server only sees ciphertext. */
+export async function pushBundle(name, opts) {
+    validateBundleName(name);
+    const snap = snapshotBundle(name);
+    const envelope = encryptBlob(JSON.stringify(snap), opts.passphrase);
+    const updated_at = new Date().toISOString();
+    const payload = { envelope, updated_at };
+    const res = await api('PUT', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`, payload);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Push failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    return { updated_at };
+}
+/** Pull a bundle by name from api.prix.dev and materialize it locally. */
+export async function pullBundle(name, opts) {
+    validateBundleName(name);
+    const res = await api('GET', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`);
+    if (res.status === 404) {
+        throw new Error(`Remote bundle '${name}' not found on api.prix.dev.`);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Pull failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    const data = await res.json();
+    const plaintext = decryptBlob(data.envelope, opts.passphrase);
+    const snap = JSON.parse(plaintext);
+    if (!snap || !snap.bundle || snap.bundle.name !== name) {
+        throw new Error(`Decrypted payload for '${name}' is malformed (bundle name mismatch).`);
+    }
+    // existence check is the caller's responsibility; we trust opts.force.
+    if (!opts.force) {
+        const { bundleExists } = await import('./bundles.js');
+        if (bundleExists(name)) {
+            throw new Error(`Local bundle '${name}' already exists. Re-run with --force to overwrite.`);
+        }
+    }
+    restoreSnapshot(snap);
+    return snap.bundle;
+}
+/** Delete a bundle on the remote. */
+export async function deleteRemoteBundle(name) {
+    validateBundleName(name);
+    const res = await api('DELETE', `${BUNDLE_ENDPOINT}/${encodeURIComponent(name)}`);
+    if (res.status === 404)
+        return false;
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Delete failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    return true;
+}
+/** List bundles currently stored on api.prix.dev for this user. */
+export async function listRemoteBundles() {
+    const res = await api('GET', BUNDLE_ENDPOINT);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`List failed (${res.status} ${res.statusText}): ${body}`);
+    }
+    const data = await res.json();
+    return data.bundles ?? [];
+}

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

@@ -20,6 +20,14 @@ export interface ActiveSession {
     cloudProvider?: string;
     cloudTaskId?: string;
     cloudStatus?: string;
+    /**
+     * IDE window that owns this terminal. Source of truth is the per-window
+     * slice key in `live-terminals.json` (computeWindowId in the swarmify
+     * extension): `${vscode.env.sessionId}-${extension-host pid}`. Lets the
+     * renderer cluster terminals that belong to the same IDE window even when
+     * two windows have the same cwd open. Only populated for `terminal` context.
+     */
+    windowId?: string;
 }
 export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */

package/dist/lib/session/active.js

@@ -73,11 +73,11 @@ function readLiveTerminals() {
     if (!parsed || typeof parsed !== 'object')
         return [];
     const merged = new Map();
-    for (const slice of Object.values(parsed)) {
+    for (const [windowId, slice] of Object.entries(parsed)) {
         for (const e of (slice?.entries ?? [])) {
             if (!e?.sessionId || !isPidAlive(e.pid))
                 continue;
-            merged.set(e.sessionId, e);
+            merged.set(e.sessionId, { ...e, windowId });
         }
     }
     return Array.from(merged.values());
@@ -259,6 +259,7 @@ export async function listTerminalsActive() {
             sessionFile,
             startedAtMs: t.startedAtMs,
             status: classifyActivity(sessionFile),
+            windowId: t.windowId,
         };
     });
 }

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

@@ -155,8 +155,6 @@ export declare function getRowCount(): {
     sessions: number;
     textRows: number;
 };
-/** Count sessions older than the given timestamp (for dry-run previews). */
-export declare function countSessionsOlderThan(cutoffMs: number): number;
 /**
  * Rewrite file_path for all sessions whose path starts with oldPrefix, replacing
  * it with newPrefix + the unchanged suffix. Also clears the matching scan_ledger
@@ -167,5 +165,3 @@ export declare function countSessionsOlderThan(cutoffMs: number): number;
  * Returns the number of session rows updated.
  */
 export declare function updateSessionFilePaths(oldPrefix: string, newPrefix: string): number;
-/** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
-export declare function deleteSessionsOlderThan(cutoffMs: number): number;

package/dist/lib/session/db.js

@@ -742,13 +742,6 @@ export function getRowCount() {
     const textRows = db.prepare(`SELECT COUNT(*) AS c FROM session_text`).get().c;
     return { sessions, textRows };
 }
-/** Count sessions older than the given timestamp (for dry-run previews). */
-export function countSessionsOlderThan(cutoffMs) {
-    const db = getDB();
-    const cutoffIso = new Date(cutoffMs).toISOString();
-    const row = db.prepare(`SELECT COUNT(*) AS n FROM sessions WHERE timestamp < ?`).get(cutoffIso);
-    return row.n;
-}
 /**
  * Rewrite file_path for all sessions whose path starts with oldPrefix, replacing
  * it with newPrefix + the unchanged suffix. Also clears the matching scan_ledger
@@ -775,22 +768,3 @@ export function updateSessionFilePaths(oldPrefix, newPrefix) {
     txn();
     return rows.length;
 }
-/** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
-export function deleteSessionsOlderThan(cutoffMs) {
-    const db = getDB();
-    const cutoffIso = new Date(cutoffMs).toISOString();
-    const rows = db.prepare(`SELECT id, file_path FROM sessions WHERE timestamp < ?`).all(cutoffIso);
-    if (rows.length === 0)
-        return 0;
-    const txn = db.transaction(() => {
-        for (const { id, file_path } of rows) {
-            db.prepare(`DELETE FROM session_text WHERE session_id = ?`).run(id);
-            db.prepare(`DELETE FROM sessions WHERE id = ?`).run(id);
-            if (file_path) {
-                db.prepare(`DELETE FROM scan_ledger WHERE file_path = ?`).run(canonicalLedgerKey(file_path));
-            }
-        }
-    });
-    txn();
-    return rows.length;
-}

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

@@ -43,6 +43,7 @@ export declare function parseGemini(filePath: string): SessionEvent[];
  * Messages have role (user/assistant) and metadata.
  * Parts contain the actual content: text, tool, reasoning, patch, step-start/finish.
  */
+export declare function parseGrok(filePath: string): SessionEvent[];
 export declare function parseOpenCode(filePath: string): SessionEvent[];
 /** Parse a Rush JSONL session file into normalized events. */
 export declare function parseRush(filePath: string): SessionEvent[];

package/dist/lib/session/parse.js

@@ -93,6 +93,9 @@ export function parseSession(filePath, agent) {
         case 'opencode':
             events = parseOpenCode(filePath);
             break;
+        case 'grok':
+            events = parseGrok(filePath);
+            break;
         case 'rush':
             events = parseRush(filePath);
             break;
@@ -118,6 +121,8 @@ export function detectAgent(filePath) {
         return 'codex';
     if (filePath.includes('/.gemini/') || filePath.includes('\\.gemini\\'))
         return 'gemini';
+    if (filePath.includes('/.grok/') || filePath.includes('\\.grok\\'))
+        return 'grok';
     if (filePath.includes('/.rush/') || filePath.includes('\\.rush\\'))
         return 'rush';
     if (filePath.includes('/.hermes/') || filePath.includes('\\.hermes\\'))
@@ -645,6 +650,45 @@ function extractGeminiContent(content) {
  * Messages have role (user/assistant) and metadata.
  * Parts contain the actual content: text, tool, reasoning, patch, step-start/finish.
  */
+export function parseGrok(filePath) {
+    // Grok sessions are rich (summary.json + events.jsonl + chat_history.jsonl + updates.jsonl)
+    // This is a minimal stub for now so grok appears in `agents sessions`.
+    // Full parser (with subagents, tool calls, etc.) can be expanded later.
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        // If it's a summary.json, create a basic event
+        if (filePath.endsWith('summary.json')) {
+            const summary = JSON.parse(content);
+            return [{
+                    timestamp: summary.created_at || new Date().toISOString(),
+                    type: 'session_start',
+                    content: summary.session_summary || 'Grok session',
+                    agent: 'grok',
+                    metadata: { sessionId: summary.id, cwd: summary.cwd },
+                }];
+        }
+        // For JSONL files (events, chat_history, updates), return basic parsed lines
+        if (filePath.endsWith('.jsonl')) {
+            const lines = content.trim().split('\n').filter(Boolean);
+            return lines.slice(0, 50).map((line, i) => {
+                try {
+                    const obj = JSON.parse(line);
+                    return {
+                        timestamp: obj.timestamp || obj.ts || new Date().toISOString(),
+                        type: obj.type || obj.method || 'grok_event',
+                        content: typeof obj.content === 'string' ? obj.content : JSON.stringify(obj).slice(0, 200),
+                        agent: 'grok',
+                    };
+                }
+                catch {
+                    return { timestamp: new Date().toISOString(), type: 'raw', content: line.slice(0, 200), agent: 'grok' };
+                }
+            });
+        }
+    }
+    catch { }
+    return [];
+}
 export function parseOpenCode(filePath) {
     const [dbPath, sessionId] = filePath.split('#');
     if (!dbPath || !sessionId)

package/dist/lib/session/render.js

@@ -806,15 +806,15 @@ export function renderConversationMarkdown(events, opts = {}) {
     for (const event of events) {
         if (event.type === 'message') {
             if (event.role === 'user') {
-                parts.push(`## User\n\n${event.content ?? ''}`);
+                parts.push(`## User\n\n${sanitize(event.content ?? '')}`);
             }
             else if (event.role === 'assistant') {
-                parts.push(`## Assistant\n\n${event.content ?? ''}`);
+                parts.push(`## Assistant\n\n${sanitize(event.content ?? '')}`);
             }
         }
         else if (event.type === 'thinking') {
             if (event.content)
-                parts.push(`### Thinking\n\n${event.content}`);
+                parts.push(`### Thinking\n\n${sanitize(event.content)}`);
         }
         else if (event.type === 'tool_use') {
             const tool = event.tool || 'unknown';
@@ -837,7 +837,7 @@ export function renderConversationMarkdown(events, opts = {}) {
             }
         }
         else if (event.type === 'error') {
-            parts.push(`### Error\n\n${event.content || event.tool || 'Unknown error'}`);
+            parts.push(`### Error\n\n${event.content ? sanitize(event.content) : (event.tool || 'Unknown error')}`);
         }
     }
     return parts.join('\n\n');

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

@@ -7,7 +7,7 @@
  * speaks these types.
  */
 /** Agents that store session data on disk and can be discovered by `agents sessions`. */
-export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'opencode' | 'openclaw' | 'rush' | 'hermes';
+export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok';
 /** All agents with session discovery support, in display order. */
 export declare const SESSION_AGENTS: SessionAgentId[];
 /** A single normalized event within a session (message, tool call, thinking, etc.). */
@@ -37,7 +37,7 @@ export interface SessionEvent {
 export interface TeamOrigin {
     /** Teammate name if set, otherwise first 8 chars of the agent UUID. */
     handle?: string;
-    /** Agent mode: 'plan', 'edit', or 'full'. */
+    /** Agent mode: 'plan', 'edit', 'auto', or 'skip' ('full' accepted as legacy alias for 'skip'). */
     mode?: string;
 }
 /** Lightweight metadata for a discovered session, used in listings and pickers. */

package/dist/lib/session/types.js

@@ -7,4 +7,4 @@
  * speaks these types.
  */
 /** All agents with session discovery support, in display order. */
-export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes'];
+export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok'];

package/dist/lib/shims.d.ts

@@ -59,8 +59,11 @@ export interface ConflictInfo {
  *         instead of hardcoding `.${agent}`. Backwards-compatible for every
  *         existing agent (their configDir is `~/.{agent}`); enables nested
  *         layouts like Antigravity's `~/.gemini/antigravity-cli/`.
+ *   v15 — remove foreground resource sync / rules refresh from launch shims.
+ *         Version homes are reconciled by agents-cli management commands; the
+ *         shim hot path only resolves a version and execs the agent binary.
  */
-export declare const SHIM_SCHEMA_VERSION = 14;
+export declare const SHIM_SCHEMA_VERSION = 15;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -213,7 +216,7 @@ export declare function getPathShadowingExecutable(agent: AgentId): string | nul
  * Delete the legacy ~/.agents/shims/<cli> file if it exists, returning whether
  * anything was removed. Pre-split installs put shims under ~/.agents/shims/;
  * the new layout uses ~/.agents-system/shims/. The leftover file causes the
- * repair-prompt loop reported in EXAMPLE-664 — `getPathShadowingExecutable` flags
+ * repair-prompt loop reported in PROJ-789 — `getPathShadowingExecutable` flags
  * it as a shadow but `addShimsToPath` only edits rc files, never the file
  * itself. Removing it ends the loop.
  */

package/dist/lib/shims.js

@@ -183,8 +183,11 @@ async function promptConflictStrategy(conflictInfos) {
  *         instead of hardcoding `.${agent}`. Backwards-compatible for every
  *         existing agent (their configDir is `~/.{agent}`); enables nested
  *         layouts like Antigravity's `~/.gemini/antigravity-cli/`.
+ *   v15 — remove foreground resource sync / rules refresh from launch shims.
+ *         Version homes are reconciled by agents-cli management commands; the
+ *         shim hot path only resolves a version and execs the agent binary.
  */
-export const SHIM_SCHEMA_VERSION = 14;
+export const SHIM_SCHEMA_VERSION = 15;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -226,19 +229,22 @@ fi
 # written by agents-cli actually take effect.
 export CODEX_HOME="$VERSION_DIR/home/${configDirName}"
 `
-            : '';
-    // Agents that don't natively resolve @-imports in their rules file need
-    // agents-cli to recompile when the user edits a rule/preset file. The
-    // check is fast (sha256 of ~8 small files) and skips the recompile when
-    // sources haven't changed.
-    const refreshRulesCall = !agentConfig.capabilities.rulesImports
-        ? `
-# Recompile rules if any rule/preset source has changed since last sync.
-# Fast-path check (~10-20ms) when nothing changed; full recompile only on
-# actual diff. Non-blocking failure — if the refresh errors, we still launch.
-"$AGENTS_BIN" refresh-rules --agent "$AGENT" --agent-version "$VERSION" --quiet 2>/dev/null || true
+            : agent === 'copilot'
+                ? `
+# GitHub Copilot CLI honors COPILOT_HOME to relocate its config and state
+# (settings.json, mcp-config.json, session-state/, logs/, plugins/). Point
+# it at the versioned home so MCP servers, custom agents, and session
+# history are isolated per copilot version.
+export COPILOT_HOME="$VERSION_DIR/home/${configDirName}"
+`
+                : agent === 'grok'
+                    ? `
+# Grok Build uses GROK_HOME to isolate its entire configuration tree
+# (skills, hooks, plugins, agents, memory, sessions, config.toml, MCP, etc.).
+# This gives agents-cli full versioned isolation + resource sync for grok.
+export GROK_HOME="$VERSION_DIR/home/.grok"
 `
-        : '';
+                    : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
@@ -292,22 +298,6 @@ resolve_default_version() {
   fi
 }
 
-# Find project-scoped .agents directory (stop at agents.yaml or .git)
-find_project_agents_dir() {
-  local dir="$PWD"
-  while [ "$dir" != "/" ]; do
-    if [ -d "$dir/.agents" ]; then
-      echo "$dir/.agents"
-      return 0
-    fi
-    if [ -f "$dir/agents.yaml" ] || [ -d "$dir/.git" ] || [ -f "$dir/.git" ]; then
-      break
-    fi
-    dir=$(dirname "$dir")
-  done
-  return 1
-}
-
 # Find the latest installed version by numeric component comparison.
 # Handles both semver (2.1.138) and date-based (2026.5.7) version strings.
 find_latest_installed() {
@@ -376,7 +366,27 @@ if [[ ! "$VERSION" =~ ^(latest|[A-Za-z0-9._+-]{1,64})$ || "$VERSION" == *..* ]];
 fi
 
 VERSION_DIR="$AGENTS_USER_DIR/.history/versions/$AGENT/$VERSION"
-BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
+
+# Grok special case: binary lives in ~/.grok/downloads/, not node_modules.
+# We still use the agents-cli version dir purely for GROK_HOME isolation.
+if [ "$AGENT" = "grok" ]; then
+  # Try to find a matching binary for the pinned version in the global grok downloads dir.
+  GROK_DOWNLOADS="$HOME/.grok/downloads"
+  if [ -d "$GROK_DOWNLOADS" ]; then
+    # Prefer a binary whose filename contains the exact version
+    BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | grep -i "$VERSION" | head -1)
+    if [ -z "$BINARY" ]; then
+      # Fallback to the "current" grok binary (symlink or latest)
+      BINARY=$(ls "$GROK_DOWNLOADS"/grok-* 2>/dev/null | head -1)
+    fi
+  fi
+  if [ -z "$BINARY" ] || [ ! -x "$BINARY" ]; then
+    # Last resort: whatever is on PATH (user may have installed grok globally)
+    BINARY=$(command -v grok 2>/dev/null || echo "")
+  fi
+else
+  BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
+fi
 
 # Auto-install if not present
 if [ ! -x "$BINARY" ]; then
@@ -439,12 +449,7 @@ if [ ! -x "$BINARY" ]; then
   fi
 fi
 
-# Sync project-scoped resources into version home if a project .agents/ is present
-PROJECT_AGENTS_DIR=$(find_project_agents_dir)
-if [ -n "$PROJECT_AGENTS_DIR" ]; then
-  "$AGENTS_BIN" sync --agent "$AGENT" --agent-version "$VERSION" --project-dir "$PROJECT_AGENTS_DIR" --quiet >/dev/null 2>&1
-fi
-${refreshRulesCall}${managedEnv}
+${managedEnv}
 
 exec "$BINARY"${launchArgs} "$@"
 `;
@@ -528,7 +533,14 @@ export CLAUDE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/ho
 # and rules written by agents-cli actually take effect.
 export CODEX_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-            : '';
+            : agent === 'copilot'
+                ? `
+# Copilot honors COPILOT_HOME to relocate ~/.copilot (settings, mcp-config.json,
+# session-state, logs). Point direct aliases at the versioned home so per-
+# version MCP and session state are isolated.
+export COPILOT_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
+`
+                : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
@@ -719,6 +731,26 @@ export async function switchConfigSymlink(agent, version) {
                 // Already pointing to correct target, no-op
                 return { success: true };
             }
+            // openclaw mixes user data (openclaw.json, openclaw.db, per-agent
+            // workspaces under ~/.openclaw/{agentId}/, memory/) with the version
+            // home — silently swapping the symlink to a fresh version home strips
+            // every running agent's config + workspace + memory. Carry the user
+            // data forward into the new version home before flipping the symlink
+            // (keep-dest preserves anything the new version already shipped).
+            // Other agents (Claude, Codex, etc.) keep user data outside the
+            // version-home dir, so this is openclaw-only by design.
+            if (agent === 'openclaw') {
+                try {
+                    if (fs.existsSync(resolvedCurrent) && fs.statSync(resolvedCurrent).isDirectory()) {
+                        await copyDirContents(resolvedCurrent, versionConfigPath, 'keep-dest');
+                    }
+                }
+                catch (migrationErr) {
+                    console.error(`Warning: openclaw data migration from ${resolvedCurrent} -> ${versionConfigPath} ` +
+                        `failed: ${migrationErr.message}. The previous version's data is intact ` +
+                        `at the old path; you can copy it manually if needed.`);
+                }
+            }
             // Different target - update it
             fs.unlinkSync(configPath);
             fs.mkdirSync(path.dirname(configPath), { recursive: true });
@@ -1182,7 +1214,7 @@ export function getPathShadowingExecutable(agent) {
  * Delete the legacy ~/.agents/shims/<cli> file if it exists, returning whether
  * anything was removed. Pre-split installs put shims under ~/.agents/shims/;
  * the new layout uses ~/.agents-system/shims/. The leftover file causes the
- * repair-prompt loop reported in EXAMPLE-664 — `getPathShadowingExecutable` flags
+ * repair-prompt loop reported in PROJ-789 — `getPathShadowingExecutable` flags
  * it as a shadow but `addShimsToPath` only edits rc files, never the file
  * itself. Removing it ends the loop.
  */