@phnx-labs/agents-cli 1.20.4 → 1.20.6

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

@@ -1,6 +1,6 @@
 /**
  * Background sync for tracked git repos:
- *   - System repo (~/.agents-system/) is read-only locally — fast-forward auto-pull is safe.
+ *   - 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`.

package/dist/lib/auto-pull.js

@@ -1,6 +1,6 @@
 /**
  * Background sync for tracked git repos:
- *   - System repo (~/.agents-system/) is read-only locally — fast-forward auto-pull is safe.
+ *   - 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`.

package/dist/lib/beta.d.ts

@@ -3,7 +3,7 @@
  *
  * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
  * when present, and otherwise fall back to the local system state file
- * (~/.agents-system/agents.yaml). This keeps opt-ins portable for users with a
+ * (~/.agents/.system/agents.yaml). This keeps opt-ins portable for users with a
  * personal agents repo without mixing them into unrelated version capability
  * checks.
  */

package/dist/lib/beta.js

@@ -3,7 +3,7 @@
  *
  * Preview features live in the git-trackable user repo (~/.agents/agents.yaml)
  * when present, and otherwise fall back to the local system state file
- * (~/.agents-system/agents.yaml). This keeps opt-ins portable for users with a
+ * (~/.agents/.system/agents.yaml). This keeps opt-ins portable for users with a
  * personal agents repo without mixing them into unrelated version capability
  * checks.
  */

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

@@ -1,5 +1,15 @@
 import type { ChromeOptions } from './types.js';
 import type { BrowserType } from './types.js';
+/**
+ * True when `binaryPath` is a shebang script rather than a native browser
+ * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
+ * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
+ * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
+ * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
+ * Linux/Unix concept — returns false on Windows/macOS app bundles.
+ */
+export declare function isLauncherScript(binaryPath: string): boolean;
+export declare function resolveBrowserBinary(binaryPath: string): string;
 export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
 /**
  * Walk the per-platform priority list and return the first browser that's

package/dist/lib/browser/chrome.js

@@ -42,12 +42,90 @@ const BROWSER_PATHS = {
         custom: [],
     },
 };
+/**
+ * On Debian/Ubuntu the canonical launchers under `/usr/bin`
+ * (`brave-browser`, `google-chrome`, `chromium`) are not the browser ELF —
+ * they're `#!/bin/bash` wrapper scripts (the upstream Chromium wrapper) that,
+ * as their final step, run the real binary as a NON-exec child:
+ *
+ *     exec < /dev/null
+ *     exec > >(exec cat)
+ *     exec 2> >(exec cat >&2)
+ *     "$HERE/brave" "$@" || true
+ *
+ * That breaks `launchBrowser`'s `--remote-debugging-pipe` transport two ways:
+ * the std-fd sanitization (and the extra `cat` process-substitution children)
+ * disturbs the inherited CDP pipe on fd 3/4, and the pid we record is the
+ * wrapper's, not the browser's. The symptom is `read ECONNRESET` /
+ * `CDP connection closed` right after spawn (issue #229).
+ *
+ * Follow the wrapper to the ELF it execs. The wrapper sets
+ * `HERE="dirname(readlink -f "$0")"` and invokes `"$HERE/<name>"`, so we
+ * resolve the script path, scan for that invocation line, and join the two.
+ * Returns the original path untouched when it's already an ELF, when it's not
+ * a resolvable wrapper, or on any non-Linux platform.
+ */
+function readsAsShebangScript(binaryPath) {
+    let fd;
+    try {
+        fd = fs.openSync(binaryPath, 'r');
+    }
+    catch {
+        return false;
+    }
+    try {
+        const head = Buffer.alloc(2);
+        fs.readSync(fd, head, 0, 2, 0);
+        // ELF binaries start with 0x7f 'E'; shebang scripts with '#!'.
+        return head[0] === 0x23 && head[1] === 0x21;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * True when `binaryPath` is a shebang script rather than a native browser
+ * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
+ * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
+ * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
+ * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
+ * Linux/Unix concept — returns false on Windows/macOS app bundles.
+ */
+export function isLauncherScript(binaryPath) {
+    if (os.platform() === 'win32')
+        return false;
+    return readsAsShebangScript(binaryPath);
+}
+export function resolveBrowserBinary(binaryPath) {
+    if (os.platform() !== 'linux')
+        return binaryPath;
+    // Only shebang scripts need unwrapping; a real ELF passes straight through.
+    if (!readsAsShebangScript(binaryPath))
+        return binaryPath;
+    let script;
+    let realScriptPath;
+    try {
+        realScriptPath = fs.realpathSync(binaryPath);
+        script = fs.readFileSync(realScriptPath, 'utf8');
+    }
+    catch {
+        return binaryPath;
+    }
+    // Match the Chromium wrapper's launch line: `"$HERE/<name>" "$@"`, optionally
+    // prefixed with `exec -a "$0"`. The captured name is the real ELF, sitting in
+    // the same directory as the resolved wrapper.
+    const match = script.match(/"\$HERE\/([A-Za-z0-9._-]+)"\s+"\$@"/);
+    if (!match)
+        return binaryPath;
+    const realBinary = path.join(path.dirname(realScriptPath), match[1]);
+    return fs.existsSync(realBinary) ? realBinary : binaryPath;
+}
 export function findBrowserPath(browserType, customBinary) {
     if (customBinary) {
         if (!fs.existsSync(customBinary)) {
             throw new Error(`Custom binary not found: ${customBinary}`);
         }
-        return customBinary;
+        return resolveBrowserBinary(customBinary);
     }
     if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
@@ -60,9 +138,12 @@ export function findBrowserPath(browserType, customBinary) {
     const candidates = platformPaths[browserType] || [];
     for (const p of candidates) {
         if (fs.existsSync(p)) {
-            return p;
+            return resolveBrowserBinary(p);
         }
     }
+    if (browserType === 'comet' && platform !== 'darwin') {
+        throw new Error('Browser "comet" is macOS-only (Comet is a macOS Chromium fork). Use chrome, chromium, brave, or edge on this platform.');
+    }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
 // Per-platform Chromium-family priority list for "no --profile" auto-pick.
@@ -98,7 +179,7 @@ export function findFirstInstalledBrowser(platform = os.platform()) {
         const candidates = platformPaths[browserType] || [];
         for (const p of candidates) {
             if (fs.existsSync(p)) {
-                return { browserType, binary: p };
+                return { browserType, binary: resolveBrowserBinary(p) };
             }
         }
     }

package/dist/lib/capabilities.js

@@ -46,6 +46,8 @@ export function supports(agent, cap, version) {
         return { ok: false, reason: 'unsupported' };
     if (c === true)
         return { ok: true };
+    if ('file' in c)
+        return { ok: true };
     if (!version)
         return { ok: true };
     if (c.since && compareVersions(version, c.since) < 0) {

package/dist/lib/commands.d.ts

@@ -13,7 +13,28 @@ export type CommandScope = 'user' | 'project';
 export interface CommandMetadata {
     name: string;
     description: string;
+    /** When set, sync only to these agents (aliases resolved at parse time). */
+    agents?: AgentId[];
+    /** Minimum agent CLI version (inclusive) for this command. */
+    since?: string;
+    /** Exclusive upper bound on agent CLI version for this command. */
+    until?: string;
 }
+export type CommandApplyFailReason = 'unsupported' | 'agent_excluded' | 'too_old' | 'too_new';
+export type CommandApplyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: CommandApplyFailReason;
+    need?: string;
+};
+/**
+ * Whether a slash command should sync to the given agent@version. Checks
+ * frontmatter `agents` / `since` / `until` after the agent-level commands
+ * (or commands-as-skills) capability gate.
+ */
+export declare function commandAppliesTo(agent: AgentId, version: string, metadata: Pick<CommandMetadata, 'agents' | 'since' | 'until'> | null | undefined): CommandApplyResult;
+export declare function explainCommandSkip(agent: AgentId, version: string, commandName: string, result: CommandApplyResult): string;
 /** Result of validating command metadata. */
 export interface ValidationResult {
     valid: boolean;
@@ -35,6 +56,8 @@ export interface InstalledCommand {
     path: string;
     description?: string;
 }
+/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
+export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
 /** 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. */
@@ -59,6 +82,8 @@ export interface VersionCommandDiff {
     toAdd: string[];
     toUpdate: string[];
     matched: string[];
+    /** Installed but excluded by frontmatter agents/since/until — safe to remove. */
+    toRemove: string[];
     orphans: string[];
 }
 /**
@@ -72,6 +97,8 @@ export declare function diffVersionCommands(agent: AgentId, version: string): Ve
 export declare function installCommandToVersion(agent: AgentId, version: string, commandName: string, method?: 'symlink' | 'copy'): {
     success: boolean;
     error?: string;
+    skipped?: boolean;
+    skipReason?: string;
 };
 /**
  * Remove a single command from a specific version home.
@@ -112,7 +139,7 @@ export declare function installCommandCentrally(sourcePath: string, commandName:
     warnings?: string[];
 };
 /**
- * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralCommands(): string[];

package/dist/lib/commands.js

@@ -9,13 +9,78 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { AGENTS, COMMANDS_CAPABLE_AGENTS, ensureCommandsDir } from './agents.js';
+import { AGENTS, ensureCommandsDir, agentConfigDirName, resolveAgentName } from './agents.js';
+import { capableAgents, isCapable, supports } from './capabilities.js';
 import { markdownToToml } from './convert.js';
 import { getCommandsDir, getUserCommandsDir, getEnabledExtraRepos, getProjectAgentsDir, getSkillsDir, getTrashCommandsDir } from './state.js';
-import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
+import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
 import { commandSkillMatches, installCommandSkillToVersion, listCommandSkillsInVersion, removeCommandSkillFromVersion, shouldInstallCommandAsSkill, } from './command-skills.js';
-/** Parse command metadata (name, description) from YAML frontmatter or TOML headers. */
-function parseCommandMetadata(filePath) {
+function compareVersions(a, b) {
+    const aParts = a.split('.').map((n) => parseInt(n, 10) || 0);
+    const bParts = b.split('.').map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aVal = aParts[i] || 0;
+        const bVal = bParts[i] || 0;
+        if (aVal !== bVal)
+            return aVal - bVal;
+    }
+    return 0;
+}
+function parseAgentsField(raw) {
+    if (raw == null)
+        return undefined;
+    const tokens = Array.isArray(raw)
+        ? raw
+        : typeof raw === 'string'
+            ? raw.split(/[,\s]+/)
+            : [];
+    const out = [];
+    for (const token of tokens) {
+        const id = resolveAgentName(String(token).trim());
+        if (id && !out.includes(id))
+            out.push(id);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Whether a slash command should sync to the given agent@version. Checks
+ * frontmatter `agents` / `since` / `until` after the agent-level commands
+ * (or commands-as-skills) capability gate.
+ */
+export function commandAppliesTo(agent, version, metadata) {
+    if (!supports(agent, 'commands', version).ok && !shouldInstallCommandAsSkill(agent, version)) {
+        return { ok: false, reason: 'unsupported' };
+    }
+    if (metadata?.agents?.length && !metadata.agents.includes(agent)) {
+        return { ok: false, reason: 'agent_excluded' };
+    }
+    if (metadata?.since && compareVersions(version, metadata.since) < 0) {
+        return { ok: false, reason: 'too_old', need: `>= ${metadata.since}` };
+    }
+    if (metadata?.until && compareVersions(version, metadata.until) >= 0) {
+        return { ok: false, reason: 'too_new', need: `< ${metadata.until}` };
+    }
+    return { ok: true };
+}
+export function explainCommandSkip(agent, version, commandName, result) {
+    if (result.ok)
+        return '';
+    const tag = `${agent}@${version}`;
+    switch (result.reason) {
+        case 'unsupported':
+            return `${tag}: /${commandName} not supported for this agent version`;
+        case 'agent_excluded':
+            return `${tag}: /${commandName} excluded by command frontmatter agents list`;
+        case 'too_old':
+            return `${tag}: /${commandName} requires ${result.need}`;
+        case 'too_new':
+            return `${tag}: /${commandName} requires ${result.need}`;
+        default:
+            return `${tag}: /${commandName} skipped`;
+    }
+}
+/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
+export function parseCommandMetadata(filePath) {
     if (!fs.existsSync(filePath)) {
         return null;
     }
@@ -31,6 +96,9 @@ function parseCommandMetadata(filePath) {
                 return {
                     name: parsed.name || '',
                     description: parsed.description || '',
+                    agents: parseAgentsField(parsed.agents),
+                    since: typeof parsed.since === 'string' ? parsed.since : undefined,
+                    until: typeof parsed.until === 'string' ? parsed.until : undefined,
                 };
             }
         }
@@ -126,10 +194,22 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
             warnings: validation.warnings,
         };
     }
+    const pinnedVersion = resolveVersion(agentId, process.cwd());
+    if (pinnedVersion) {
+        const gate = commandAppliesTo(agentId, pinnedVersion, metadata);
+        if (!gate.ok) {
+            return {
+                path: '',
+                method: 'copy',
+                error: explainCommandSkip(agentId, pinnedVersion, commandName, gate),
+                warnings: validation.warnings,
+            };
+        }
+    }
     const agent = AGENTS[agentId];
     ensureCommandsDir(agentId);
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     fs.mkdirSync(commandsDir, { recursive: true });
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(commandsDir, `${commandName}${ext}`);
@@ -157,14 +237,14 @@ export function installCommand(sourcePath, agentId, commandName, method = 'symli
  */
 export function getVersionCommandsDir(agent, version) {
     const home = getVersionHomePath(agent, version);
-    return path.join(home, `.${agent}`, AGENTS[agent].commandsSubdir);
+    return path.join(home, agentConfigDirName(agent), AGENTS[agent].commandsSubdir);
 }
 /**
  * List command names (without extension) installed in a specific version home.
  */
 export function listCommandsInVersionHome(agent, version) {
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return listCommandSkillsInVersion(agentDir);
     }
@@ -186,7 +266,7 @@ function versionCommandMatches(agent, version, commandName) {
     if (!fs.existsSync(sourcePath))
         return false;
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return commandSkillMatches(agentDir, commandName, sourcePath);
     }
@@ -217,8 +297,13 @@ export function diffVersionCommands(agent, version) {
     const toAdd = [];
     const toUpdate = [];
     const matched = [];
+    const toRemove = [];
     const orphans = [];
     for (const name of central) {
+        const sourcePath = path.join(getCommandsDir(), `${name}.md`);
+        const metadata = parseCommandMetadata(sourcePath);
+        if (!commandAppliesTo(agent, version, metadata).ok)
+            continue;
         if (!installed.has(name)) {
             toAdd.push(name);
         }
@@ -230,10 +315,25 @@ export function diffVersionCommands(agent, version) {
         }
     }
     for (const name of installed) {
-        if (!central.has(name))
+        if (!central.has(name)) {
             orphans.push(name);
+            continue;
+        }
+        const sourcePath = path.join(getCommandsDir(), `${name}.md`);
+        const metadata = parseCommandMetadata(sourcePath);
+        if (!commandAppliesTo(agent, version, metadata).ok) {
+            toRemove.push(name);
+        }
     }
-    return { agent, version, toAdd: toAdd.sort(), toUpdate: toUpdate.sort(), matched, orphans: orphans.sort() };
+    return {
+        agent,
+        version,
+        toAdd: toAdd.sort(),
+        toUpdate: toUpdate.sort(),
+        matched,
+        toRemove: toRemove.sort(),
+        orphans: orphans.sort(),
+    };
 }
 /**
  * Install a single command from central into a specific version home.
@@ -244,8 +344,13 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
     if (!fs.existsSync(sourcePath)) {
         return { success: false, error: `Command '${commandName}' not found in central` };
     }
+    const metadata = parseCommandMetadata(sourcePath);
+    const gate = commandAppliesTo(agent, version, metadata);
+    if (!gate.ok) {
+        return { success: true, skipped: true, skipReason: explainCommandSkip(agent, version, commandName, gate) };
+    }
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return installCommandSkillToVersion(agentDir, commandName, sourcePath, [
             getSkillsDir(),
@@ -283,7 +388,7 @@ export function installCommandToVersion(agent, version, commandName, method = 'c
  */
 export function removeCommandFromVersion(agent, version, commandName) {
     const versionHome = getVersionHomePath(agent, version);
-    const agentDir = path.join(versionHome, `.${agent}`);
+    const agentDir = path.join(versionHome, agentConfigDirName(agent));
     if (shouldInstallCommandAsSkill(agent, version)) {
         return removeCommandSkillFromVersion(agentDir, commandName);
     }
@@ -309,9 +414,9 @@ export function removeCommandFromVersion(agent, version, commandName) {
  */
 export function iterCommandsCapableVersions(filter) {
     const pairs = [];
-    const agents = filter?.agent ? [filter.agent] : COMMANDS_CAPABLE_AGENTS;
+    const agents = filter?.agent ? [filter.agent] : capableAgents('commands');
     for (const agent of agents) {
-        if (!COMMANDS_CAPABLE_AGENTS.includes(agent))
+        if (!isCapable(agent, 'commands'))
             continue;
         const versions = listInstalledVersions(agent);
         for (const version of versions) {
@@ -326,7 +431,7 @@ export function iterCommandsCapableVersions(filter) {
 export function uninstallCommand(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(commandsDir, `${commandName}${ext}`);
     if (fs.existsSync(targetPath)) {
@@ -339,7 +444,7 @@ export function uninstallCommand(agentId, commandName) {
 function listInstalledCommands(agentId) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     if (!fs.existsSync(commandsDir)) {
         return [];
     }
@@ -355,7 +460,7 @@ function listInstalledCommands(agentId) {
 function commandExists(agentId, commandName) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const targetPath = path.join(commandsDir, `${commandName}${ext}`);
     return fs.existsSync(targetPath);
@@ -373,7 +478,7 @@ function normalizeContent(content) {
 function commandContentMatches(agentId, commandName, sourcePath) {
     const agent = AGENTS[agentId];
     const home = getEffectiveHome(agentId);
-    const commandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const commandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const ext = agent.format === 'toml' ? '.toml' : '.md';
     const installedPath = path.join(commandsDir, `${commandName}${ext}`);
     if (!fs.existsSync(installedPath) || !fs.existsSync(sourcePath)) {
@@ -455,7 +560,7 @@ export function listInstalledCommandsWithScope(agentId, cwd = process.cwd(), opt
     }
     // User-scoped commands (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
-    const userCommandsDir = path.join(home, `.${agentId}`, agent.commandsSubdir);
+    const userCommandsDir = path.join(home, agentConfigDirName(agentId), agent.commandsSubdir);
     const userExts = [ext];
     const userCommands = listCommandsFromDir(userCommandsDir, userExts);
     for (const name of userCommands) {
@@ -509,7 +614,7 @@ export function installCommandCentrally(sourcePath, commandName) {
     }
 }
 /**
- * List commands from user (~/.agents/commands/) and system (~/.agents-system/commands/) dirs.
+ * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralCommands() {

package/dist/lib/doctor-diff.js

@@ -21,7 +21,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS } from './agents.js';
+import { AGENTS, agentConfigDirName } from './agents.js';
 import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir, getEffectivePromptcutsPath, } from './state.js';
 import { getAvailableResources, getActuallySyncedResources, getVersionHomePath, } from './versions.js';
 import { markdownToToml } from './convert.js';
@@ -352,7 +352,7 @@ function expectedRuleContent(agent, name, sourcePath) {
 function diffRules(agent, version, cwd) {
     const agentConfig = AGENTS[agent];
     const versionHome = getVersionHomePath(agent, version);
-    const configDir = path.join(versionHome, `.${agent}`);
+    const configDir = path.join(versionHome, agentConfigDirName(agent));
     const sourcesByName = listRulesNames(cwd);
     // Files actually present in the version home.
     const homeFiles = new Set();

package/dist/lib/exec.d.ts

@@ -23,6 +23,20 @@ export declare function normalizeMode(input: string | null | undefined): Mode;
  * - `plan` on an agent without plan support throws the same way.
  */
 export declare function resolveMode(agent: AgentId, requested: Mode): Mode;
+/**
+ * The mode an agent should run in when the caller has no preference.
+ *
+ * Returns the first entry in the agent's `capabilities.modes` table — the
+ * declaration order is the source of truth for "the safest mode this agent
+ * supports." Agents that include `plan` list it first; agents like
+ * antigravity that have no read-only mode list `edit` first.
+ *
+ * Use this when the user did not pass `--mode` explicitly. When the user
+ * *did* pass `--mode plan` and the agent doesn't support it, call
+ * `resolveMode` instead so the user sees a loud error rather than a silent
+ * elevation from read-only to writable.
+ */
+export declare function defaultModeFor(agent: AgentId): Mode;
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */