@phnx-labs/agents-cli 1.20.77 → 1.20.82

package/dist/lib/agents.js

@@ -1,9 +1,10 @@
 /**
  * Core agent configuration and detection module.
  *
- * Defines the canonical registry of all supported AI coding agents (Claude, Codex,
- * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Grok) with their
- * CLI commands, config paths, capability flags, and MCP integration points.
+ * Defines the canonical registry of current and legacy AI coding agents (Claude,
+ * Codex, Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Grok)
+ * with their CLI commands, config paths, capability flags, and MCP integration
+ * points.
  *
  * Provides functions for detecting installed CLIs, resolving version-managed binaries,
  * reading account/auth info, and managing MCP server registrations across agents.
@@ -256,13 +257,15 @@ export const AGENTS = {
         nativeAgentsSkillsDir: true,
         // Google retired the Gemini CLI (announced at Google I/O 2026, May 19); the `gemini`
         // command stopped serving free/Pro/Ultra requests on June 18, 2026. Antigravity CLI
-        // (`agy`) is the official successor. See warnAgentDeprecated() for the surfaced warning.
+        // (`agy`) is the official successor. Hard deprecation keeps legacy Gemini
+        // sessions/config parseable while blocking install/import/sync.
         deprecated: {
             by: 'Google',
             date: 'June 18, 2026',
             reason: 'The Gemini CLI was retired for free, Pro, and Ultra tiers and no longer serves requests (announced at Google I/O 2026 on May 19).',
             replacement: 'antigravity',
             url: 'https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/',
+            hard: true,
         },
         // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
         // extensions: gemini-extension.json bundles shipped in v0.8.0; custom subagents in v0.36.0.
@@ -697,58 +700,18 @@ export const AGENTS = {
             rulesImports: false,
         },
     },
-    // ForgeCode (`forge`) from Tailcall. It reads AGENTS.md project rules,
-    // SKILL.md directories, and MCP servers from `.mcp.json` files.
-    forge: {
-        id: 'forge',
-        name: 'ForgeCode',
-        color: 'greenBright',
-        cliCommand: 'forge',
-        npmPackage: '',
-        installScript: 'curl -fsSL https://forgecode.dev/cli | sh',
-        configDir: path.join(HOME, '.forge'),
-        commandsDir: path.join(HOME, '.forge', 'commands'),
-        commandsSubdir: 'commands',
-        skillsDir: path.join(HOME, '.forge', 'skills'),
-        hooksDir: 'hooks',
-        instructionsFile: 'AGENTS.md',
-        format: 'markdown',
-        variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
-        // Commands: ForgeCode reads Markdown slash commands from `~/.forge/commands/<name>.md`
-        // (also the shared `~/.agents/commands/`); the filename is the command name.
-        // Subagents: named `.md` agent definitions with YAML frontmatter under
-        // `~/.forge/agents/<name>.md` — same Markdown+frontmatter shape as Droid/Copilot
-        // (no `color` field), so transformSubagentForForge aliases transformSubagentForDroid.
-        // See https://forgecode.dev/docs/commands/ and /docs/agent-definition-guide/.
-        capabilities: {
-            hooks: false,
-            mcp: true,
-            mcpHttp: true,
-            mcpHeaders: false,
-            // Permissions: ~/.forge/permissions.yaml (or $FORGE_CONFIG/permissions.yaml)
-            // carries ordered operation-family glob policies. It is active only when
-            // `.forge.toml` sets `restricted = true`; MCP tools bypass this file.
-            allowlist: true,
-            skills: true,
-            commands: true,
-            plugins: false,
-            subagents: true,
-            rules: { file: 'AGENTS.md' },
-            workflows: false,
-            memory: false,
-            modes: ['edit'],
-            rulesImports: false,
-        },
-    },
 };
-/** All registered agent IDs derived from the AGENTS registry. */
+/** All current and legacy agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
+/** Agents retained only for legacy reads, not install/import/sync targets. */
+export const HARD_DEPRECATED_AGENT_IDS = ALL_AGENT_IDS.filter((id) => AGENTS[id].deprecated?.hard);
+/** Agents that can receive managed installs, imports, and resource sync writes. */
+export const MANAGED_AGENT_IDS = ALL_AGENT_IDS.filter((id) => !AGENTS[id].deprecated?.hard);
 /**
  * A self-updating agent is a single global binary installed by an official
  * `curl … | sh` / `brew install` script that carries NO version token — the
  * installer can only ever fetch the *current* release, and the binary then keeps
- * itself up to date in place (droid, grok, antigravity, cursor, hermes, forge,
+ * itself up to date in place (droid, grok, antigravity, cursor, hermes,
  * kiro, goose). There is no semver to pin, so agents-cli must not model these as
  * having multiple installable version-homes the way it does for npm-packaged
  * agents (claude, codex, kimi, …).
@@ -768,6 +731,9 @@ export function isSelfUpdatingAgent(agent) {
     const cfg = AGENTS[agent];
     return !cfg.npmPackage && !!cfg.installScript && !cfg.installScript.includes('VERSION');
 }
+export function isAgentHardDeprecated(agent) {
+    return AGENTS[agent].deprecated?.hard === true;
+}
 // Capability-filtered agent lists used to live here as `*_CAPABLE_AGENTS`
 // constants. They were a frequent source of silent-skip bugs (e.g. grok
 // rules sync gated on `COMMANDS_CAPABLE_AGENTS`). Use `capableAgents(cap)`
@@ -1404,43 +1370,6 @@ export function isClaudeCredentialFileBlank(base, platform = process.platform) {
         return false;
     }
 }
-/**
- * Whether a Claude version home holds its OWN on-disk credential — a non-blank
- * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
- * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
- *
- * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
- * (RUSH-1759) so a token-less default account still authenticates. But Claude —
- * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
- * env var over a pinned account's config dir, so when balanced rotation pins a
- * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
- * is inert and every fire 401s on the one stale token. A routine spawn drops the
- * ambient token when the pinned account has its own credential (this returns
- * true) so the account authenticates itself; when it does not (the RUSH-1759
- * default), the injected token is kept.
- *
- * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
- * login Keychain is the canonical store and probing it raises an auth sheet, and
- * there the daemon injects no token to shadow (broker-only, usually absent), so
- * returning false changes nothing. Sync, no Keychain, no network.
- */
-export function claudeHomeHasOwnCredential(base, platform = process.platform) {
-    if (platform === 'darwin')
-        return false;
-    if (fs.existsSync(path.join(base, '.claude', '.oauth_token')))
-        return true;
-    try {
-        const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
-        const oauth = JSON.parse(raw).claudeAiOauth;
-        if (!oauth)
-            return false;
-        const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
-        return nonEmpty(oauth.accessToken) || nonEmpty(oauth.refreshToken);
-    }
-    catch {
-        return false;
-    }
-}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {
@@ -1589,6 +1518,38 @@ export async function getAccountInfo(agentId, home) {
                 const email = data.active || null;
                 return { ...empty, email, signedIn: !!email, lastActive };
             }
+            case 'cursor': {
+                // Cursor CLI keeps account metadata in ~/.cursor/cli-config.json
+                // (authInfo: { email, userId, authId }) and its OAuth tokens SEPARATELY
+                // in ~/.config/cursor/auth.json ({ accessToken, refreshToken }). Presence
+                // of an access token is the signed-in signal; email/ids come from
+                // cli-config. authId is the OAuth subject (e.g. "google-oauth2|<n>") — the
+                // same value the usage endpoint keys on (see getCursorUsageInfo).
+                const cfgPath = resolveAccountCredentialPath(base, '.cursor', 'cli-config.json');
+                if (!cfgPath)
+                    return { ...empty, lastActive };
+                try {
+                    const cfg = JSON.parse(await fs.promises.readFile(cfgPath, 'utf-8'));
+                    const authInfo = cfg?.authInfo;
+                    const email = typeof authInfo?.email === 'string' ? authInfo.email : null;
+                    const accountId = normalizeIdentityPart(authInfo?.authId ?? authInfo?.userId);
+                    if (!email && !accountId)
+                        return { ...empty, lastActive };
+                    const authPath = resolveAccountCredentialPath(base, '.config', 'cursor', 'auth.json');
+                    let hasToken = false;
+                    if (authPath) {
+                        try {
+                            const tok = JSON.parse(fs.readFileSync(authPath, 'utf-8'));
+                            hasToken = typeof tok?.accessToken === 'string' && tok.accessToken.length > 0;
+                        }
+                        catch { /* unreadable token file */ }
+                    }
+                    const accountKey = buildIdentityKey(agentId, [['user', accountId]]);
+                    return { ...empty, email, accountId, accountKey, signedIn: hasToken || !!email, lastActive };
+                }
+                catch { }
+                return { ...empty, lastActive };
+            }
             case 'grok': {
                 // Grok stores auth in ~/.grok/auth.json as a map keyed by
                 // "<oidc_issuer>::<client_id>" -> { email, user_id, refresh_token,
@@ -1904,7 +1865,7 @@ function buildIdentityKey(agentId, parts) {
 /** Register an MCP server with an agent's CLI via `mcp add`. */
 export async function registerMcp(agentId, name, command, scope = 'user', transport = 'stdio', options) {
     const agent = AGENTS[agentId];
-    if (!agent.capabilities.mcp) {
+    if (!supports(agentId, 'mcp').ok) {
         return { success: false, error: 'Agent does not support MCP' };
     }
     if (transport === 'http' && !supports(agentId, 'mcpHttp').ok) {
@@ -1913,7 +1874,7 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
     if (transport === 'http' && options?.headers && Object.keys(options.headers).length > 0 && !supports(agentId, 'mcpHeaders').ok) {
         return { success: false, error: 'skipped: HTTP MCP headers are only supported for Claude registration' };
     }
-    if (agentId === 'hermes' || agentId === 'forge') {
+    if (agentId === 'hermes') {
         try {
             writeMcpToConfig(agentId, name, command, scope, transport, options?.home);
             return { success: true };
@@ -1964,10 +1925,10 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
 /** Unregister (remove) a named MCP server from an agent's CLI config. */
 export async function unregisterMcp(agentId, name, options) {
     const agent = AGENTS[agentId];
-    if (!agent.capabilities.mcp) {
+    if (!supports(agentId, 'mcp').ok) {
         return { success: false, error: 'Agent does not support MCP' };
     }
-    if (agentId === 'hermes' || agentId === 'forge') {
+    if (agentId === 'hermes') {
         try {
             removeMcpFromConfig(agentId, name, options?.home);
             return { success: true };
@@ -2319,8 +2280,6 @@ export function getUserMcpConfigPath(agentId) {
             return path.join(agent.configDir, 'mcp.json');
         case 'hermes':
             return path.join(agent.configDir, 'config.yaml');
-        case 'forge':
-            return path.join(agent.configDir, '.mcp.json');
         default:
             // Gemini and others use settings.json
             return path.join(agent.configDir, 'settings.json');
@@ -2357,8 +2316,6 @@ export function getMcpConfigPathForHome(agentId, home) {
             return path.join(home, '.factory', 'mcp.json');
         case 'hermes':
             return path.join(home, '.hermes', 'config.yaml');
-        case 'forge':
-            return path.join(home, '.forge', '.mcp.json');
         default:
             return path.join(home, agentConfigDirName(agentId), 'settings.json');
     }
@@ -2398,8 +2355,6 @@ export function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
             return path.join(cwd, '.factory', 'mcp.json');
         case 'hermes':
             return path.join(cwd, '.hermes', 'config.yaml');
-        case 'forge':
-            return path.join(cwd, '.mcp.json');
         default:
             return path.join(cwd, `.${agentId}`, 'settings.json');
     }
@@ -2543,9 +2498,6 @@ export const AGENT_NAME_ALIASES = {
     droid: 'droid',
     hermes: 'hermes',
     'hermes-agent': 'hermes',
-    forge: 'forge',
-    forgecode: 'forge',
-    'forge-code': 'forge',
 };
 /**
  * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.
@@ -2596,6 +2548,26 @@ export function deprecationNotice(agent) {
         lines.push(`  ${dep.url}`);
     return lines;
 }
+export function hardDeprecationNotice(agent) {
+    const dep = AGENTS[agent].deprecated;
+    if (!dep?.hard)
+        return null;
+    const name = AGENTS[agent].name;
+    const lines = [
+        `${name} is no longer supported by agents-cli because ${dep.by} retired it (${dep.date}).`,
+        `  ${dep.reason}`,
+    ];
+    if (dep.replacement) {
+        const rep = AGENTS[dep.replacement];
+        lines.push(`  Use ${rep.name} instead:  agents add ${rep.id}`);
+    }
+    if (dep.url)
+        lines.push(`  ${dep.url}`);
+    return lines;
+}
+export function hardDeprecationError(agent) {
+    return hardDeprecationNotice(agent)?.join('\n') ?? `${AGENTS[agent].name} is no longer supported.`;
+}
 /**
  * Print a deprecation warning (yellow) if the agent's registry entry carries a
  * `deprecated` marker; no-op otherwise. Call from any user entry point that

package/dist/lib/auto-pull.d.ts

@@ -2,12 +2,13 @@
  * Background sync for tracked git repos:
  *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
  *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
- *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
- *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.
+ *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
+ *     as a "Repo updates" section instead of printing to stderr on every command.
+ *     Pulling is left to the user via `agents repo pull`.
  *
  * Public API:
- *   spawnDetachedSync()           — fire-and-forget; never blocks the foreground command.
- *   printPendingUpdateNotices()   — synchronous; reads markers and prints + consumes them.
+ *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
+ *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
  */
 /** Per-repo lock file path. mtime acts as a recency check. */
 export declare function lockFilePath(alias: string): string;
@@ -24,8 +25,15 @@ export interface FetchStatusMarker {
 /** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
 export declare function spawnDetachedSync(): void;
 /**
- * Read any pending status markers and print one-line notices for repos that
- * are behind upstream. Markers are deleted after printing so notices don't
- * repeat on every invocation. Synchronous, cheap (small JSON files).
+ * Read all current status markers and return those where the local repo is
+ * behind upstream. Markers are NOT deleted — they persist until the next
+ * background fetch overwrites them with fresh data.
+ *
+ * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
+ * repo-behind warnings in one place instead of printing to stderr on every
+ * command.
+ *
+ * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
+ *   production getFetchCacheDir() path.
  */
-export declare function printPendingUpdateNotices(): void;
+export declare function readRepoBehindMarkers(fetchDir?: string): FetchStatusMarker[];

package/dist/lib/auto-pull.js

@@ -2,12 +2,13 @@
  * Background sync for tracked git repos:
  *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
  *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
- *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
- *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.
+ *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
+ *     as a "Repo updates" section instead of printing to stderr on every command.
+ *     Pulling is left to the user via `agents repo pull`.
  *
  * Public API:
- *   spawnDetachedSync()           — fire-and-forget; never blocks the foreground command.
- *   printPendingUpdateNotices()   — synchronous; reads markers and prints + consumes them.
+ *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
+ *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -57,21 +58,29 @@ export function spawnDetachedSync() {
     }
 }
 /**
- * Read any pending status markers and print one-line notices for repos that
- * are behind upstream. Markers are deleted after printing so notices don't
- * repeat on every invocation. Synchronous, cheap (small JSON files).
+ * Read all current status markers and return those where the local repo is
+ * behind upstream. Markers are NOT deleted — they persist until the next
+ * background fetch overwrites them with fresh data.
+ *
+ * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
+ * repo-behind warnings in one place instead of printing to stderr on every
+ * command.
+ *
+ * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
+ *   production getFetchCacheDir() path.
  */
-export function printPendingUpdateNotices() {
-    const dir = fetchStateDir();
+export function readRepoBehindMarkers(fetchDir) {
+    const dir = fetchDir ?? fetchStateDir();
     if (!fs.existsSync(dir))
-        return;
+        return [];
     let entries = [];
     try {
         entries = fs.readdirSync(dir);
     }
     catch {
-        return;
+        return [];
     }
+    const result = [];
     for (const name of entries) {
         if (!name.endsWith('.status.json'))
             continue;
@@ -81,25 +90,11 @@ export function printPendingUpdateNotices() {
             marker = JSON.parse(fs.readFileSync(file, 'utf-8'));
         }
         catch {
-            try {
-                fs.unlinkSync(file);
-            }
-            catch { /* ignore */ }
             continue;
         }
-        if (!marker || marker.behind <= 0) {
-            try {
-                fs.unlinkSync(file);
-            }
-            catch { /* ignore */ }
+        if (!marker || marker.behind <= 0)
             continue;
-        }
-        const repoLabel = marker.alias === 'user' ? '~/.agents/' : marker.alias;
-        process.stderr.write(`agents-cli: ${repoLabel} is ${marker.behind} commit${marker.behind === 1 ? '' : 's'} ` +
-            `behind ${marker.branch} — run 'agents repo pull ${marker.alias}' to update.\n`);
-        try {
-            fs.unlinkSync(file);
-        }
-        catch { /* ignore */ }
+        result.push(marker);
     }
+    return result;
 }

package/dist/lib/browser/service.js

@@ -14,6 +14,7 @@ import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focus
 import { typeEditorText } from './editor.js';
 import { detectUploadPattern, stageUploadFile, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
 import { emit } from '../events.js';
+import { resolveActor } from '../actor.js';
 import { sshExecAsync } from '../ssh-exec.js';
 function isPathInside(candidate, dir) {
     const rel = path.relative(dir, candidate);
@@ -331,6 +332,7 @@ export class BrowserService {
             currentTabId: undefined,
             createdAt: Date.now(),
             pid: conn.pid,
+            owner: resolveActor().id, // who launched this browser task (RUSH-2020)
         };
         // For Electron, get the existing window as the tab
         if (conn.electron) {
@@ -2012,6 +2014,7 @@ export class BrowserService {
             endedAt: Date.now(),
             domains,
             tabCount: Object.keys(task.tabs).length,
+            ...(task.owner ? { owner: task.owner } : {}), // carry who launched it (RUSH-2020)
         });
         // Keep only last 50 entries
         history = history.slice(0, 50);

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

@@ -78,6 +78,11 @@ export interface Task {
     currentTabId?: string;
     createdAt: number;
     pid: number;
+    /**
+     * Resolved actor id (`resolveActor().id`) stamped at task start — who launched
+     * this browser task. Optional: tasks persisted before RUSH-2020 carry none.
+     */
+    owner?: string;
     /**
      * Per-tab snapshot of the last ref listing captured for that tab
      * (shortId -> {descriptors, opts}). Persisted to tasks.json so a later
@@ -126,6 +131,8 @@ export interface HistoricalTask {
     endedAt: number;
     domains: string[];
     tabCount: number;
+    /** Actor id who launched the task (RUSH-2020); absent for pre-RUSH-2020 history. */
+    owner?: string;
 }
 export type IPCAction = 'start' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {

package/dist/lib/capabilities.js

@@ -7,7 +7,7 @@
  * is below `since`, the install path skips the write and surfaces a clear
  * reason instead of silently corrupting an older binary's settings file.
  */
-import { AGENTS } from './agents.js';
+import { AGENTS, MANAGED_AGENT_IDS } from './agents.js';
 /**
  * Compare semver-like versions ("0.116.0" vs "0.115.9"). Local copy to avoid
  * importing versions.ts (which imports agents.ts, which imports this file).
@@ -37,6 +37,8 @@ function getCapability(agent, cap) {
  * Useful for filtering UI lists; does not check installed version.
  */
 export function isCapable(agent, cap) {
+    if (AGENTS[agent]?.deprecated?.hard)
+        return false;
     const c = getCapability(agent, cap);
     return c !== false;
 }
@@ -47,6 +49,8 @@ export function isCapable(agent, cap) {
  * capable" filters but NOT for install-time gating.
  */
 export function supports(agent, cap, version) {
+    if (AGENTS[agent]?.deprecated?.hard)
+        return { ok: false, reason: 'unsupported' };
     const c = getCapability(agent, cap);
     if (c === false)
         return { ok: false, reason: 'unsupported' };
@@ -78,5 +82,5 @@ export function explainSkip(agent, cap, result, version) {
 }
 /** All agents whose `capabilities[cap]` is anything other than `false`. */
 export function capableAgents(cap) {
-    return Object.keys(AGENTS).filter((id) => isCapable(id, cap));
+    return MANAGED_AGENT_IDS.filter((id) => isCapable(id, cap));
 }

package/dist/lib/crabbox/lease.js

@@ -137,7 +137,7 @@ export function buildBootstrapScript(opts) {
         // (leaseAndRun, before this script). Here — after ENSURE_AGENTS_CLI installed
         // the CLI — we materialize that config into the runtime home. Gated by
         // copySetup (cleared for --bare). Best-effort; a refresh failure never aborts.
-        copySetup ? [step('copy-setup'), 'agents repo refresh >/dev/null 2>&1 || true'].join('\n') : '',
+        copySetup ? [step('copy-setup'), 'agents sync --local -y >/dev/null 2>&1 || true'].join('\n') : '',
         // Marker on its own line: the command layer shows everything before this as
         // setup progress and everything after (the agent's output) verbatim.
         `echo ${q(LEASE_AGENT_MARKER)}`,
@@ -176,7 +176,7 @@ export async function leaseAndRun(opts) {
     // Setup-copy (F1, RUSH-1920): push the git-tracked ~/.agents config onto the
     // box from the host, over crabbox's own per-lease ssh (a raw ssh fails
     // publickey). rsync only here — the box has no agents-cli yet, so the matching
-    // `agents repo refresh` runs inside the bootstrap script, after the install
+    // `agents sync --local` runs inside the bootstrap script, after the install
     // step. Best-effort: a copy failure never aborts the run (the agent just runs
     // without the config).
     if (opts.copySetup !== false) {

package/dist/lib/crabbox/setup-copy.d.ts

@@ -12,7 +12,7 @@
  *   2. `rsync` that exact file set to `~/.agents` on the box over crabbox's OWN
  *      ssh invocation (`crabboxSshArgv`) — crabbox provisions a per-lease identity
  *      key, so a raw `ssh crabbox@ip` fails publickey; only crabbox's key works.
- *   3. `agents repo refresh` on the box so the copied config takes effect.
+ *   3. `agents sync --local` on the box so the copied config takes effect.
  *
  * NEVER copies `~/.claude` / `~/.claude.json` — they live in `$HOME`, not
  * `~/.agents`, and are rebuilt on the box by `agents add` + refresh; an explicit
@@ -34,7 +34,7 @@ export interface CopySetupOptions {
     /** Receives combined stdout/stderr of the rsync + refresh, if set. */
     onData?: (chunk: string) => void;
     /**
-     * Run `agents repo refresh` on the box after the push (default `true`). Set
+     * Run `agents sync --local` on the box after the push (default `true`). Set
      * `false` when the caller runs the refresh itself in the box bootstrap — the
      * lease path does this so the refresh runs AFTER the box installs agents-cli
      * (this host-side push happens before the box boots agents-cli, so a host-side
@@ -47,7 +47,7 @@ export interface CopySetupResult {
     files: string[];
     /** rsync exit code, or null when the process failed to spawn. */
     pushExitCode: number | null;
-    /** `agents repo refresh` exit code, or null when it was skipped/failed to spawn. */
+    /** `agents sync --local` exit code, or null when it was skipped/failed to spawn. */
     refreshExitCode: number | null;
 }
 /**
@@ -80,7 +80,7 @@ export declare function buildSetupRsyncArgs(opts: {
 /**
  * Replicate the git-tracked subset of the local `~/.agents` onto the crabbox box
  * and refresh it. Enumerates tracked files, rsyncs them over ssh, then runs
- * `agents repo refresh` on the box. Refresh is skipped when the push fails or the
+ * `agents sync --local` on the box. Refresh is skipped when the push fails or the
  * file set is empty (nothing to refresh). Never throws — surfaces failure through
  * the returned exit codes.
  */

package/dist/lib/crabbox/setup-copy.js

@@ -12,7 +12,7 @@
  *   2. `rsync` that exact file set to `~/.agents` on the box over crabbox's OWN
  *      ssh invocation (`crabboxSshArgv`) — crabbox provisions a per-lease identity
  *      key, so a raw `ssh crabbox@ip` fails publickey; only crabbox's key works.
- *   3. `agents repo refresh` on the box so the copied config takes effect.
+ *   3. `agents sync --local` on the box so the copied config takes effect.
  *
  * NEVER copies `~/.claude` / `~/.claude.json` — they live in `$HOME`, not
  * `~/.agents`, and are rebuilt on the box by `agents add` + refresh; an explicit
@@ -88,7 +88,7 @@ function runStreaming(cmd, args, env, onData) {
 /**
  * Replicate the git-tracked subset of the local `~/.agents` onto the crabbox box
  * and refresh it. Enumerates tracked files, rsyncs them over ssh, then runs
- * `agents repo refresh` on the box. Refresh is skipped when the push fails or the
+ * `agents sync --local` on the box. Refresh is skipped when the push fails or the
  * file set is empty (nothing to refresh). Never throws — surfaces failure through
  * the returned exit codes.
  */
@@ -115,8 +115,8 @@ export async function copySetupToBox(opts) {
         const pushExitCode = await runStreaming('rsync', rsyncArgs, env, opts.onData);
         let refreshExitCode = null;
         if (pushExitCode === 0 && opts.refresh !== false) {
-            // ssh <opts> crabbox@host bash -lc 'agents repo refresh'
-            const refreshArgs = [...sshArgv.slice(1), 'bash', '-lc', 'agents repo refresh'];
+            // ssh <opts> crabbox@host bash -lc 'agents sync --local -y'
+            const refreshArgs = [...sshArgv.slice(1), 'bash', '-lc', 'agents sync --local -y'];
             refreshExitCode = await runStreaming('ssh', refreshArgs, env, opts.onData);
         }
         return { files, pushExitCode, refreshExitCode };