@phnx-labs/agents-cli 1.16.0 → 1.17.0

package/dist/lib/browser/drivers/local.js

@@ -1,5 +1,5 @@
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
-import { launchBrowser, allocatePort } from '../chrome.js';
+import { launchBrowser, getPortOccupant } from '../chrome.js';
 export async function connectLocal(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'cdp:') {
@@ -17,7 +17,18 @@ export async function connectLocal(endpoint, profile) {
         if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
             throw err;
         }
-        const newPort = allocatePort();
+        // Distinguish "nothing listening on this port" (fine to launch fresh) from
+        // "something is listening but it's not a debuggable browser" (bail loudly —
+        // silently launching on a different port leads to confusing `pid 0` and
+        // `CDP connection not open` errors downstream).
+        const occupant = getPortOccupant(port);
+        if (occupant) {
+            throw new Error(`Port ${port} is occupied by ${occupant.command} (pid ${occupant.pid}) but is ` +
+                `not serving the Chrome DevTools Protocol. Either stop that process ` +
+                `(\`kill ${occupant.pid}\`) or restart it with \`--remote-debugging-port=${port}\` ` +
+                `so profile "${profile.name}" can attach.`);
+        }
+        const newPort = port;
         const chromeOpts = { ...profile.chrome, viewport: profile.viewport };
         const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary);
         const cdp = new CDPClient();

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

@@ -1,6 +1,7 @@
 import type { CDPClient } from './cdp.js';
 export declare function clickAtCoords(cdp: CDPClient, sessionId: string, x: number, y: number): Promise<void>;
 export declare function hoverAtCoords(cdp: CDPClient, sessionId: string, x: number, y: number): Promise<void>;
+export declare function scrollAtCoords(cdp: CDPClient, sessionId: string, x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
 export declare function typeText(cdp: CDPClient, sessionId: string, text: string): Promise<void>;
 export declare function pressKey(cdp: CDPClient, sessionId: string, keyName: string): Promise<void>;
 export declare function focusNode(cdp: CDPClient, sessionId: string, backendNodeId: number): Promise<void>;

package/dist/lib/browser/input.js

@@ -5,6 +5,9 @@ export async function clickAtCoords(cdp, sessionId, x, y) {
 export async function hoverAtCoords(cdp, sessionId, x, y) {
     await cdp.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y }, sessionId);
 }
+export async function scrollAtCoords(cdp, sessionId, x, y, deltaX, deltaY) {
+    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x, y, deltaX, deltaY }, sessionId);
+}
 export async function typeText(cdp, sessionId, text) {
     for (const char of text) {
         await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', text: char }, sessionId);

package/dist/lib/browser/ipc.js

@@ -78,6 +78,13 @@ export class BrowserIPCServer {
                     windowTargetId: result.windowId,
                 };
             }
+            case 'launch-profile': {
+                if (!request.profile) {
+                    return { ok: false, error: 'Profile required' };
+                }
+                const result = await this.service.launchProfile(request.profile);
+                return { ok: true, port: result.port, pid: result.pid };
+            }
             case 'done': {
                 if (!request.task) {
                     return { ok: false, error: 'Task required' };
@@ -191,6 +198,13 @@ export class BrowserIPCServer {
                 await this.service.hover(request.task, request.ref, request.tabId);
                 return { ok: true };
             }
+            case 'scroll': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                await this.service.scroll(request.task, request.scrollX ?? 0, request.scrollY ?? 0, request.scrollAtX, request.scrollAtY, request.tabId);
+                return { ok: true };
+            }
             case 'set-viewport': {
                 if (!request.task || !request.width || !request.height) {
                     return { ok: false, error: 'Task, width, and height required' };

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

@@ -4,6 +4,11 @@ export declare function getBrowserRuntimeDir(): string;
 export declare function getProfileRuntimeDir(name: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
+/**
+ * Find a port in 9222–9399 that is not already claimed by another profile
+ * and is not currently in use by any OS process.
+ */
+export declare function findFreeProfilePort(): Promise<number>;
 export declare function createProfile(profile: BrowserProfile): Promise<void>;
 export declare function updateProfile(profile: BrowserProfile): Promise<void>;
 export declare function deleteProfile(name: string): Promise<void>;

package/dist/lib/browser/profiles.js

@@ -1,5 +1,7 @@
 import * as path from 'path';
+import { execSync } from 'child_process';
 import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, writeMeta, } from '../state.js';
+import { findBrowserPath } from './chrome.js';
 export function getBrowserRuntimeDir() {
     return getBrowserRuntimeDirRoot();
 }
@@ -51,11 +53,54 @@ export async function getProfile(name) {
         return null;
     return configToProfile(name, config);
 }
+/**
+ * Find a port in 9222–9399 that is not already claimed by another profile
+ * and is not currently in use by any OS process.
+ */
+export async function findFreeProfilePort() {
+    const profiles = await listProfiles();
+    const usedByProfile = new Set();
+    for (const p of profiles) {
+        const port = extractConfiguredPort(p);
+        if (port !== undefined)
+            usedByProfile.add(port);
+    }
+    for (let port = 9222; port <= 9399; port++) {
+        if (usedByProfile.has(port))
+            continue;
+        try {
+            execSync(`lsof -i :${port}`, { stdio: 'ignore' });
+            // lsof succeeded → something is listening → port is in use
+        }
+        catch {
+            // lsof threw → nothing on this port → it's free
+            return port;
+        }
+    }
+    throw new Error('No available ports in range 9222-9399');
+}
 export async function createProfile(profile) {
     const meta = readMeta();
     if (meta.browser?.[profile.name]) {
         throw new Error(`Profile "${profile.name}" already exists`);
     }
+    // Check for port collision with existing profiles
+    const newPort = extractConfiguredPort(profile);
+    if (newPort !== undefined && meta.browser) {
+        for (const [existingName, existingConfig] of Object.entries(meta.browser)) {
+            const existingProfile = configToProfile(existingName, existingConfig);
+            const existingPort = extractConfiguredPort(existingProfile);
+            if (existingPort === newPort) {
+                throw new Error(`Port ${newPort} is already used by profile "${existingName}". ` +
+                    `Each profile must own a unique port. Use a different port or omit --endpoint to auto-assign.`);
+            }
+        }
+    }
+    // Resolve the browser binary at create time. Fails fast with an actionable
+    // error ("Comet not installed at /Applications/Comet.app") rather than
+    // deferring the failure to the first task. `findBrowserPath` short-circuits
+    // for browser=custom without a binary by throwing — same outcome.
+    findBrowserPath(profile.browser, profile.binary);
     meta.browser = meta.browser ?? {};
     meta.browser[profile.name] = profileToConfig(profile);
     writeMeta(meta);

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

@@ -17,6 +17,15 @@ export declare class BrowserService {
         tabId?: string;
         windowId?: string;
     }>;
+    /**
+     * Launch (or attach to) the profile's browser without creating a task. Used by
+     * `agents browser profiles launch <name>` so users can warm up the browser —
+     * including the first-run onboarding flow — before any automation starts.
+     */
+    launchProfile(profileName: string): Promise<{
+        port: number;
+        pid: number;
+    }>;
     stop(taskName: string): Promise<{
         ok: boolean;
         profile?: string;
@@ -60,6 +69,7 @@ export declare class BrowserService {
     type(taskId: string, ref: number, text: string, tabHint?: string): Promise<void>;
     press(taskId: string, key: string, tabHint?: string): Promise<void>;
     hover(taskId: string, ref: number, tabHint?: string): Promise<void>;
+    scroll(taskId: string, deltaX: number, deltaY: number, atX?: number, atY?: number, tabHint?: string): Promise<void>;
     status(profileName?: string): Promise<ProfileStatus[]>;
     private reconcileFromDisk;
     setViewport(taskId: string, width: number, height: number, options?: {

package/dist/lib/browser/service.js

@@ -7,7 +7,7 @@ import { connectLocal } from './drivers/local.js';
 import { connectSSH } from './drivers/ssh.js';
 import { generateTaskId, generateShortId, generateFunName, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
-import { clickAtCoords, hoverAtCoords, typeText, pressKey, focusNode } from './input.js';
+import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { emit } from '../events.js';
 export class BrowserService {
     connections = new Map();
@@ -97,6 +97,24 @@ export class BrowserService {
         }
         return { task: taskId, name: taskName, tabId };
     }
+    /**
+     * Launch (or attach to) the profile's browser without creating a task. Used by
+     * `agents browser profiles launch <name>` so users can warm up the browser —
+     * including the first-run onboarding flow — before any automation starts.
+     */
+    async launchProfile(profileName) {
+        const profile = await getProfile(profileName);
+        if (!profile) {
+            throw new Error(`Profile "${profileName}" not found`);
+        }
+        let conn = this.connections.get(profileName);
+        if (!conn) {
+            conn = await this.connectProfile(profile);
+            this.connections.set(profileName, conn);
+        }
+        emit('browser.launch', { profile: profileName, task: '', pid: conn.pid });
+        return { port: conn.port, pid: conn.pid };
+    }
     async stop(taskName) {
         for (const [profileName, conn] of this.connections) {
             const task = conn.tasks.get(taskName);
@@ -424,6 +442,16 @@ export class BrowserService {
         const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, ref);
         await hoverAtCoords(conn.cdp, sessionId, x, y);
     }
+    async scroll(taskId, deltaX, deltaY, atX, atY, tabHint) {
+        const { conn, task } = await this.findTask(taskId);
+        const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
+        const cdpTargetId = this.getCdpTargetId(task, shortId);
+        const target = await this.getTarget(conn, cdpTargetId);
+        if (!target)
+            throw new Error(`Tab ${shortId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        await scrollAtCoords(conn.cdp, sessionId, atX ?? 0, atY ?? 0, deltaX, deltaY);
+    }
     async status(profileName) {
         const seen = new Set();
         const statuses = [];

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

@@ -11,6 +11,8 @@ export interface BrowserProfile {
     viewport?: {
         width: number;
         height: number;
+        x?: number;
+        y?: number;
     };
 }
 export interface ChromeOptions {
@@ -19,6 +21,8 @@ export interface ChromeOptions {
     viewport?: {
         width: number;
         height: number;
+        x?: number;
+        y?: number;
     };
 }
 export interface Task {
@@ -69,7 +73,7 @@ export interface HistoricalTask {
     domains: string[];
     tabCount: number;
 }
-export type IPCAction = 'start' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download';
+export type IPCAction = 'start' | 'launch-profile' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -82,6 +86,10 @@ export interface IPCRequest {
     ref?: number;
     text?: string;
     key?: string;
+    scrollX?: number;
+    scrollY?: number;
+    scrollAtX?: number;
+    scrollAtY?: number;
     interactive?: boolean;
     limit?: number;
     width?: number;
@@ -111,6 +119,8 @@ export interface IPCResponse {
     result?: unknown;
     path?: string;
     refs?: string;
+    port?: number;
+    pid?: number;
     logs?: ConsoleEntry[];
     errors?: ErrorEntry[];
     requests?: NetworkRequest[];

package/dist/lib/cloud/rush.d.ts

@@ -5,6 +5,8 @@
  * Requires the Rush GitHub App installed on the target repo.
  */
 import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
+export declare const RUSH_CONSENT_PATH: string;
+export declare function hasRushUploadConsent(opts?: DispatchOptions): boolean;
 /** One version's entry in the account manifest sent on every dispatch. */
 export interface AccountManifestEntry {
     version: string;
@@ -35,7 +37,7 @@ export interface AccountTokenEntry {
  * Returns null when no Claude versions are signed in (the dispatch falls back
  * to the platform-wide key, current behavior).
  */
-export declare function buildAccountManifest(): Promise<AccountManifest | null>;
+export declare function buildAccountManifest(strategy?: string): Promise<AccountManifest | null>;
 /**
  * Re-load OAuth blobs for the given versions so they can be uploaded to the
  * server on a retry. Only the versions named in the manifest are loaded — we
@@ -52,6 +54,7 @@ export declare function buildDispatchBody(input: {
     agent?: string;
     prompt: string;
     mode?: string;
+    strategy?: string;
     resolvedRepos: Array<{
         installation_id: number;
         repo_owner: string;
@@ -60,6 +63,30 @@ export declare function buildDispatchBody(input: {
     accountManifest?: AccountManifest | null;
     accountTokens?: AccountTokenEntry[] | null;
 }): Record<string, unknown>;
+/** A single account registered in Rush Cloud's multi-account rotation pool. */
+export interface RemoteAccount {
+    id: string;
+    provider: string;
+    email: string | null;
+    subscription_type: string | null;
+    five_hour_pct: number | null;
+    seven_day_pct: number | null;
+    usage_fetched_at: string | null;
+    created_at: string;
+}
+/** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
+export declare function listRemoteAccounts(): Promise<RemoteAccount[]>;
+/**
+ * Register a CLAUDE_CODE_OAUTH_TOKEN with Rush Cloud's rotation pool.
+ * The server validates the token against the Anthropic usage API and stores it
+ * encrypted in Vault. Returns the account metadata (no token).
+ */
+export declare function addRemoteAccount(provider: string, pastedToken: string): Promise<RemoteAccount & {
+    five_hour_pct: number | null;
+    seven_day_pct: number | null;
+}>;
+/** Remove a Claude account from Rush Cloud's rotation pool by its ID. */
+export declare function removeRemoteAccount(id: string): Promise<void>;
 export declare class RushCloudProvider implements CloudProvider {
     id: "rush";
     name: string;

package/dist/lib/cloud/rush.js

@@ -15,14 +15,15 @@ import { parseSSE } from './stream.js';
 import { listInstalledVersions, getVersionHomePath } from '../versions.js';
 import { getAccountInfo } from '../agents.js';
 import { loadClaudeOauth } from '../usage.js';
+import { selectBalancedVersion } from '../rotate.js';
 const PROXY_BASE = 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 // Persistent consent record for uploading Claude OAuth blobs to Rush Cloud.
 // Created on first explicit consent (env var or flag); subsequent dispatches
 // see it and proceed without re-prompting.
-const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
+export const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
 const RUSH_CONSENT_ENV = 'AGENTS_RUSH_UPLOAD_TOKENS';
-function hasRushUploadConsent(opts) {
+export function hasRushUploadConsent(opts) {
     if (process.env[RUSH_CONSENT_ENV] === '1')
         return true;
     const po = opts?.providerOptions;
@@ -184,20 +185,37 @@ async function readClaudeCredentialsBlob(home) {
  * Returns null when no Claude versions are signed in (the dispatch falls back
  * to the platform-wide key, current behavior).
  */
-export async function buildAccountManifest() {
-    const versions = listInstalledVersions('claude');
-    if (versions.length === 0)
-        return null;
+export async function buildAccountManifest(strategy) {
+    let candidateVersions;
+    if (strategy === 'balanced') {
+        // Use the same health-checked, deduped-by-email set that `agents run --balanced` uses.
+        // `result.healthy` contains one candidate per unique email, ordered by remaining capacity.
+        const result = await selectBalancedVersion('claude');
+        if (!result || result.healthy.length === 0)
+            return null;
+        candidateVersions = result.healthy
+            .filter((c) => !!c.email)
+            .map((c) => ({ version: c.version, email: c.email }));
+    }
+    else {
+        // Default: all installed versions that have a signed-in account.
+        const versions = listInstalledVersions('claude');
+        if (versions.length === 0)
+            return null;
+        const rows = await Promise.all(versions.map(async (version) => {
+            const home = getVersionHomePath('claude', version);
+            const info = await getAccountInfo('claude', home);
+            return info.email ? { version, email: info.email } : null;
+        }));
+        candidateVersions = rows.filter((r) => r !== null);
+    }
     const entries = [];
-    for (const version of versions) {
+    for (const { version, email } of candidateVersions) {
         const home = getVersionHomePath('claude', version);
-        const info = await getAccountInfo('claude', home);
-        if (!info.email)
-            continue;
         const blob = await readClaudeCredentialsBlob(home);
         if (!blob)
             continue;
-        entries.push({ version, email: info.email, cred_fp: sha256(blob) });
+        entries.push({ version, email, cred_fp: sha256(blob) });
     }
     if (entries.length === 0)
         return null;
@@ -237,6 +255,7 @@ export function buildDispatchBody(input) {
         prompt: input.prompt,
         repos: input.resolvedRepos,
         mode: input.mode,
+        ...(input.strategy ? { strategy: input.strategy } : {}),
     };
     if (input.resolvedRepos.length === 1) {
         body.installation_id = primary.installation_id;
@@ -251,6 +270,37 @@ export function buildDispatchBody(input) {
     }
     return body;
 }
+/** Fetch all Claude accounts in this user's Rush Cloud rotation pool (no tokens). */
+export async function listRemoteAccounts() {
+    const token = readToken();
+    const res = await api('GET', '/api/v1/cloud-accounts', token);
+    if (!res.ok) {
+        throw new Error(`Failed to list accounts (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+    const data = await res.json();
+    return data.accounts ?? [];
+}
+/**
+ * Register a CLAUDE_CODE_OAUTH_TOKEN with Rush Cloud's rotation pool.
+ * The server validates the token against the Anthropic usage API and stores it
+ * encrypted in Vault. Returns the account metadata (no token).
+ */
+export async function addRemoteAccount(provider, pastedToken) {
+    const token = readToken();
+    const res = await api('POST', '/api/v1/cloud-accounts', token, { provider, token: pastedToken });
+    if (!res.ok) {
+        throw new Error(`Failed to add account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+    return await res.json();
+}
+/** Remove a Claude account from Rush Cloud's rotation pool by its ID. */
+export async function removeRemoteAccount(id) {
+    const token = readToken();
+    const res = await api('DELETE', `/api/v1/cloud-accounts/${encodeURIComponent(id)}`, token);
+    if (!res.ok) {
+        throw new Error(`Failed to remove account (${res.status}): ${sanitizeErrorBody(await res.text())}`);
+    }
+}
 export class RushCloudProvider {
     id = 'rush';
     name = 'Rush Cloud';
@@ -289,13 +339,18 @@ export class RushCloudProvider {
             repo_owner: r.owner,
             repo_name: r.name,
         })));
-        const accountManifest = await buildAccountManifest();
+        const strategy = options.providerOptions?.strategy;
+        // When balanced, the server owns the pool and rotates internally — no
+        // client-side manifest needed. We just forward the strategy so the server
+        // knows to load from Vault instead of waiting for a manifest.
+        const accountManifest = strategy === 'balanced' ? null : await buildAccountManifest();
         const body = buildDispatchBody({
             agent: options.agent,
             prompt: options.prompt,
             mode: options.providerOptions?.mode,
             resolvedRepos,
             accountManifest,
+            strategy,
         });
         let res = await api('POST', '/api/v1/cloud-runs', token, body);
         // Server detects drift (new account or rotated token) by comparing the
@@ -317,7 +372,7 @@ export class RushCloudProvider {
                         ``,
                         `To consent, re-run with one of:`,
                         `  AGENTS_RUSH_UPLOAD_TOKENS=1 agents cloud run ...`,
-                        `  agents cloud run --upload-account-tokens ...   # if your CLI exposes this flag`,
+                        `  agents cloud run --upload-account-tokens ...`,
                         ``,
                         `Consent will be recorded at ${RUSH_CONSENT_PATH} so you won't be asked again.`,
                         `Remove that file to revoke.`,

package/dist/lib/commands.d.ts

@@ -35,10 +35,6 @@ export interface InstalledCommand {
     path: string;
     description?: string;
 }
-/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
-/** Validate command metadata, returning errors and warnings. */
-export declare function validateCommandMetadata(metadata: CommandMetadata | null, commandName: string): ValidationResult;
 /** Discover all command markdown files in a repository's commands/ directory. */
 export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
 /** Find the source path for a command in a repository. */
@@ -98,17 +94,6 @@ export declare function iterCommandsCapableVersions(filter?: {
 }>;
 /** Remove a command from an agent's config directory. */
 export declare function uninstallCommand(agentId: AgentId, commandName: string): boolean;
-/** List command names installed for an agent in the active version home. */
-export declare function listInstalledCommands(agentId: AgentId): string[];
-/**
- * Check if a command exists for an agent.
- */
-export declare function commandExists(agentId: AgentId, commandName: string): boolean;
-/**
- * Check if installed command content matches source content.
- * Handles format conversion (markdown to TOML for Gemini).
- */
-export declare function commandContentMatches(agentId: AgentId, commandName: string, sourcePath: string): boolean;
 /**
  * List installed commands with scope information.
  * Pass options.home to read from a version-managed agent's home directory.

package/dist/lib/commands.js

@@ -15,7 +15,7 @@ import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAge
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
 /** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-export function parseCommandMetadata(filePath) {
+function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
     }
@@ -51,7 +51,7 @@ export function parseCommandMetadata(filePath) {
     }
 }
 /** Validate command metadata, returning errors and warnings. */
-export function validateCommandMetadata(metadata, commandName) {
+function validateCommandMetadata(metadata, commandName) {
     const errors = [];
     const warnings = [];
     if (!metadata) {
@@ -336,7 +336,7 @@ export function uninstallCommand(agentId, commandName) {
     return false;
 }
 /** List command names installed for an agent in the active version home. */
-export function listInstalledCommands(agentId) {
+function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
@@ -352,7 +352,7 @@ export function listInstalledCommands(agentId) {
 /**
  * Check if a command exists for an agent.
  */
-export function commandExists(agentId, commandName) {
+function commandExists(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
@@ -370,7 +370,7 @@ function normalizeContent(content) {
  * Check if installed command content matches source content.
  * Handles format conversion (markdown to TOML for Gemini).
  */
-export function commandContentMatches(agentId, commandName, sourcePath) {
+function commandContentMatches(agentId, commandName, sourcePath) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
     const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);

package/dist/lib/hooks.js

@@ -14,16 +14,15 @@ import * as TOML from 'smol-toml';
 import { AGENTS, HOOKS_CAPABLE_AGENTS } from './agents.js';
 import { supports, explainSkip } from './capabilities.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
-import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir } from './state.js';
+import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos } from './state.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
 /**
- * Resolve a hook script's absolute path by checking the user dir first
- * (where `installHooksCentrally` lands new files) and falling back to the
- * system dir (where npm-shipped defaults live). Returns null if neither
- * exists. Mirrors the precedence used by `listCentralHooks`.
+ * Resolve a hook script's absolute path. Checks user dir first, then enabled
+ * extra repos in insertion order, then system dir. Returns null if not found.
  */
 function resolveHookScriptPath(script) {
-    for (const root of [getUserAgentsDir(), getSystemAgentsDir()]) {
+    const extraDirs = getEnabledExtraRepos().map(e => e.dir);
+    for (const root of [getUserAgentsDir(), ...extraDirs, getSystemAgentsDir()]) {
         const candidate = path.join(root, 'hooks', script);
         if (fs.existsSync(candidate))
             return candidate;
@@ -32,14 +31,15 @@ function resolveHookScriptPath(script) {
 }
 /**
  * Prefixes used for stale-entry cleanup in agent settings files. A registered
- * hook command is considered "managed by us" if it lives under either
- * `~/.agents/hooks/` (user) or `~/.agents-system/hooks/` (system). Cleanup
- * filters use this list so leftover entries from either dir get garbage
- * collected on rewrite.
+ * hook command is considered "managed" if it lives under any known hooks dir
+ * (user, extra repos, or system). Entries from removed extra repos are also
+ * garbage-collected because they won't appear in this list any more.
  */
 function getManagedHookPrefixes() {
+    const extraDirs = getEnabledExtraRepos().map(e => e.dir);
     return [
         path.join(getUserAgentsDir(), 'hooks') + path.sep,
+        ...extraDirs.map(d => path.join(d, 'hooks') + path.sep),
         path.join(getSystemAgentsDir(), 'hooks') + path.sep,
     ];
 }
@@ -616,16 +616,29 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
         return { registered: [], errors: [] };
     }
     const overrideRoots = agentsDirOverride ? [agentsDirOverride] : null;
+    // Scripts are copied into the version home during sync — prefer that stable
+    // local path so registered commands don't break when source dirs change.
+    const localHooksDir = !overrideRoots
+        ? path.join(versionHome, `.${agentId}`, AGENTS[agentId].hooksDir)
+        : null;
     const resolveScript = (script) => {
         if (overrideRoots) {
             const candidate = path.join(overrideRoots[0], 'hooks', script);
             return fs.existsSync(candidate) ? candidate : null;
         }
+        if (localHooksDir) {
+            const local = path.join(localHooksDir, script);
+            if (fs.existsSync(local))
+                return local;
+        }
         return resolveHookScriptPath(script);
     };
     const managedPrefixes = overrideRoots
         ? [path.join(overrideRoots[0], 'hooks') + path.sep]
-        : getManagedHookPrefixes();
+        : [
+            ...getManagedHookPrefixes(),
+            ...(localHooksDir ? [localHooksDir + path.sep] : []),
+        ];
     if (agentId === 'claude') {
         return registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes);
     }