@phnx-labs/agents-cli 1.20.72 → 1.20.74

package/dist/lib/project-resources.js

@@ -0,0 +1,306 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from './agents.js';
+import { supports } from './capabilities.js';
+import { buildCommandSkillContent, commandSkillName, readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
+import { commandAppliesTo, parseCommandMetadata } from './commands.js';
+import { markdownToToml } from './convert.js';
+import { safeJoin } from './paths.js';
+import { subagentTarget } from './subagents-registry.js';
+import { parseSubagentFrontmatter } from './subagents.js';
+import { syncWorkflowToVersion } from './workflows.js';
+const MANIFEST_FILE = '.agents-managed.json';
+const MANIFEST_VERSION = 1;
+const COPY_IGNORE = new Set(['.DS_Store', '.git', '.gitignore', '.venv', '__pycache__', 'node_modules']);
+export function projectAgentRoot(projectRoot, agent) {
+    return path.join(projectRoot, agentConfigDirName(agent));
+}
+export function syncProjectResourcesToAgent(agent, version, projectAgentsDir) {
+    const projectRoot = path.dirname(projectAgentsDir);
+    const agentRoot = projectAgentRoot(projectRoot, agent);
+    const manifest = loadProjectManifest(agentRoot);
+    const result = { synced: [], skipped: [] };
+    const next = new Set();
+    if (manifest) {
+        for (const rel of manifest.paths)
+            removeManagedPath(agentRoot, rel);
+    }
+    syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result, next);
+    syncProjectSkills(agent, version, projectAgentsDir, agentRoot, result, next);
+    syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, agentRoot, manifest, result, next);
+    syncProjectWorkflows(agent, version, projectAgentsDir, projectRoot, agentRoot, result, next);
+    if (next.size > 0 || manifest) {
+        writeProjectManifest(agentRoot, Array.from(next).sort());
+    }
+    return result;
+}
+function loadProjectManifest(agentRoot) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(agentRoot, MANIFEST_FILE), 'utf-8'));
+        if (raw.v !== MANIFEST_VERSION || !Array.isArray(raw.paths))
+            return null;
+        if (!raw.paths.every((p) => typeof p === 'string' && p.length > 0))
+            return null;
+        return { ...raw, paths: raw.paths.map(toPosixRel) };
+    }
+    catch {
+        return null;
+    }
+}
+function writeProjectManifest(agentRoot, paths) {
+    fs.mkdirSync(agentRoot, { recursive: true });
+    const p = path.join(agentRoot, MANIFEST_FILE);
+    const tmp = p + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify({ v: MANIFEST_VERSION, paths }, null, 2));
+    fs.renameSync(tmp, p);
+}
+function removeManagedPath(agentRoot, rel) {
+    if (path.isAbsolute(rel) || rel.includes('..'))
+        return;
+    const target = path.resolve(agentRoot, rel);
+    const root = path.resolve(agentRoot);
+    if (target !== root && !target.startsWith(root + path.sep))
+        return;
+    removePath(target);
+}
+function removePath(p) {
+    try {
+        const st = fs.lstatSync(p);
+        if (st.isSymbolicLink() || st.isFile())
+            fs.unlinkSync(p);
+        else if (st.isDirectory())
+            fs.rmSync(p, { recursive: true, force: true });
+    }
+    catch {
+        // already absent
+    }
+}
+function pathExists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (entry.isSymbolicLink() || COPY_IGNORE.has(entry.name))
+            continue;
+        const s = safeJoin(src, entry.name);
+        const d = safeJoin(dest, entry.name);
+        if (entry.isDirectory())
+            copyDir(s, d);
+        else if (entry.isFile())
+            fs.copyFileSync(s, d);
+    }
+}
+function projectEntries(projectAgentsDir, kind) {
+    const dir = path.join(projectAgentsDir, kind);
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true }).filter((entry) => !entry.name.startsWith('.'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Manifest paths are persisted to `.agents-managed.json`, which lives in the
+ * version-controlled project dir and therefore travels between machines. Store
+ * them POSIX-style: `path.join` yields `skills\myskill` on Windows, and a
+ * manifest carrying that would silently fail to match — and so fail to clean up
+ * its managed files — when the same project is synced on macOS or Linux.
+ * Normalizing on both write and read also repairs manifests written by earlier
+ * Windows builds.
+ */
+function toPosixRel(rel) {
+    return rel.replace(/\\/g, '/');
+}
+function record(kind, name, relPaths, result, manifestPaths) {
+    result.synced.push(`${kind}/${name}`);
+    for (const rel of relPaths)
+        manifestPaths.add(toPosixRel(rel));
+}
+function skip(dest, projectRoot, result) {
+    const rel = path.relative(projectRoot, dest);
+    result.skipped.push(rel);
+    console.warn(`Skipping project resource target ${rel}: already exists and is user-owned`);
+}
+function syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {
+    const cfg = AGENTS[agent];
+    const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+    const supportsCommands = supports(agent, 'commands', version).ok;
+    if (!commandsAsSkills && !supportsCommands)
+        return;
+    const projectRoot = path.dirname(projectAgentsDir);
+    for (const entry of projectEntries(projectAgentsDir, 'commands')) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const name = entry.name.slice(0, -'.md'.length);
+        const srcFile = path.join(projectAgentsDir, 'commands', entry.name);
+        const metadata = parseCommandMetadata(srcFile);
+        if (!commandAppliesTo(agent, version, metadata).ok)
+            continue;
+        if (commandsAsSkills) {
+            const sourceMarker = readSkillSourceCommandMarker(name, [path.join(projectAgentsDir, 'skills')]);
+            if (pathExists(path.join(projectAgentsDir, 'skills', name)) && sourceMarker !== name)
+                continue;
+            const skillName = commandSkillName(name);
+            const rel = path.join('skills', skillName);
+            const destDir = path.join(agentRoot, rel);
+            if (pathExists(destDir)) {
+                skip(destDir, projectRoot, result);
+                continue;
+            }
+            fs.mkdirSync(destDir, { recursive: true });
+            fs.writeFileSync(path.join(destDir, 'SKILL.md'), buildCommandSkillContent(name, srcFile), 'utf-8');
+            record('commands', name, [rel], result, manifestPaths);
+            continue;
+        }
+        const ext = cfg.format === 'toml' ? '.toml' : '.md';
+        const rel = path.join(cfg.commandsSubdir, `${name}${ext}`);
+        const destFile = path.join(agentRoot, rel);
+        if (pathExists(destFile)) {
+            skip(destFile, projectRoot, result);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(destFile), { recursive: true });
+        if (cfg.format === 'toml') {
+            fs.writeFileSync(destFile, markdownToToml(name, fs.readFileSync(srcFile, 'utf-8')), 'utf-8');
+        }
+        else {
+            fs.copyFileSync(srcFile, destFile);
+        }
+        record('commands', name, [rel], result, manifestPaths);
+    }
+}
+function syncProjectSkills(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {
+    if (!supports(agent, 'skills', version).ok)
+        return;
+    const projectRoot = path.dirname(projectAgentsDir);
+    for (const entry of projectEntries(projectAgentsDir, 'skills')) {
+        if (!entry.isDirectory())
+            continue;
+        const srcDir = path.join(projectAgentsDir, 'skills', entry.name);
+        if (!fs.existsSync(path.join(srcDir, 'SKILL.md')))
+            continue;
+        const rel = path.join('skills', entry.name);
+        const destDir = path.join(agentRoot, rel);
+        if (pathExists(destDir)) {
+            skip(destDir, projectRoot, result);
+            continue;
+        }
+        copyDir(srcDir, destDir);
+        record('skills', entry.name, [rel], result, manifestPaths);
+    }
+}
+function readProjectSubagents(projectAgentsDir) {
+    const map = new Map();
+    for (const entry of projectEntries(projectAgentsDir, 'subagents')) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(projectAgentsDir, 'subagents', entry.name);
+        const agentMd = path.join(dir, 'AGENT.md');
+        if (!fs.existsSync(agentMd))
+            continue;
+        const frontmatter = parseSubagentFrontmatter(agentMd);
+        if (!frontmatter)
+            continue;
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+        map.set(entry.name, { name: entry.name, path: dir, files, frontmatter });
+    }
+    return map;
+}
+function syncProjectSubagents(agent, version, projectAgentsDir, projectRoot, agentRoot, manifest, result, manifestPaths) {
+    if (!supports(agent, 'subagents', version).ok)
+        return;
+    const target = subagentTarget(agent);
+    if (!target)
+        return;
+    const all = readProjectSubagents(projectAgentsDir);
+    const dir = target.dir(projectRoot);
+    const targetDirRel = toPosixRel(path.relative(agentRoot, dir));
+    const hadManagedTarget = manifest?.paths.some((rel) => rel === targetDirRel || rel.startsWith(targetDirRel + '/')) ?? false;
+    for (const sub of all.values()) {
+        const occupied = target.occupied(dir, sub.name);
+        const existing = occupied.find((entry) => pathExists(entry.path));
+        if (existing) {
+            skip(existing.path, projectRoot, result);
+            continue;
+        }
+        try {
+            target.write(dir, sub);
+            record('subagents', sub.name, occupied.map((entry) => path.relative(agentRoot, entry.path)), result, manifestPaths);
+        }
+        catch {
+            // Malformed source or unsupported transform; skip this item.
+        }
+    }
+    const syncedNames = result.synced
+        .filter((name) => name.startsWith('subagents/'))
+        .map((name) => name.slice('subagents/'.length))
+        .filter((name) => all.has(name))
+        .map((name) => all.get(name));
+    if (target.finalize && (syncedNames.length > 0 || hadManagedTarget)) {
+        target.finalize(dir, syncedNames);
+        for (const entry of target.finalizeOccupied?.(dir) ?? []) {
+            // Same normalization as record(): this is the one manifest write that
+            // doesn't funnel through it (the parent subagent index, e.g. Kimi's
+            // agents/_agents-cli.yaml).
+            manifestPaths.add(toPosixRel(path.relative(agentRoot, entry.path)));
+        }
+    }
+}
+function workflowManagedRelPaths(agent, projectRoot, name, workflowDir) {
+    if (agent === 'kimi')
+        return [path.join('.kimi-code', 'skills', name)];
+    if (agent === 'goose') {
+        const rels = [path.join('.config', 'goose', 'recipes', `${name}.yaml`)];
+        const subagentsDir = path.join(workflowDir, 'subagents');
+        let hasSubagents = false;
+        try {
+            hasSubagents = fs.readdirSync(subagentsDir).some((f) => f.endsWith('.md'));
+        }
+        catch {
+            hasSubagents = false;
+        }
+        if (hasSubagents)
+            rels.push(path.join('.config', 'goose', 'recipes', `${name}.subrecipes`));
+        return rels;
+    }
+    if (agent === 'openclaw')
+        return [path.join('.openclaw', 'workflows', `${name}.lobster`)];
+    return [path.join(agentConfigDirName(agent), 'workflows', name)];
+}
+function syncProjectWorkflows(agent, version, projectAgentsDir, projectRoot, agentRoot, result, manifestPaths) {
+    if (!supports(agent, 'workflows', version).ok)
+        return;
+    if (agent === 'antigravity')
+        return;
+    for (const entry of projectEntries(projectAgentsDir, 'workflows')) {
+        if (!entry.isDirectory())
+            continue;
+        const workflowDir = path.join(projectAgentsDir, 'workflows', entry.name);
+        if (!fs.existsSync(path.join(workflowDir, 'WORKFLOW.md')))
+            continue;
+        const rels = workflowManagedRelPaths(agent, projectRoot, entry.name, workflowDir);
+        const existing = rels.map((rel) => path.join(projectRoot, rel)).find((dest) => pathExists(dest));
+        if (existing) {
+            skip(existing, projectRoot, result);
+            continue;
+        }
+        let success = false;
+        if (agent === 'kimi' || agent === 'goose' || agent === 'openclaw') {
+            success = syncWorkflowToVersion(workflowDir, entry.name, agent, projectRoot).success;
+        }
+        else {
+            copyDir(workflowDir, path.join(agentRoot, 'workflows', entry.name));
+            success = true;
+        }
+        if (success) {
+            record('workflows', entry.name, rels.map((rel) => path.relative(agentRoot, path.join(projectRoot, rel))), result, manifestPaths);
+        }
+    }
+}

package/dist/lib/pty-client.d.ts

@@ -4,6 +4,14 @@
  * Thin client that connects to the PTY sidecar server over unix socket.
  * Each call opens a connection, sends a JSON request, reads the JSON response, and closes.
  */
+export interface ServerSpawnArgs {
+    bin: string;
+    args: string[];
+}
+export interface ServerExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
 /** JSON response envelope from the PTY server. */
 export interface PtyResponse {
     ok: boolean;
@@ -15,6 +23,25 @@ export interface PtyResponse {
  * Auto-starts the server if not running.
  */
 export declare function ptyRequest(action: string, id?: string, params?: Record<string, any>): Promise<PtyResponse>;
+export declare function getServerSpawnArgs(options?: {
+    isStandaloneExecutable?: boolean;
+    /** Physical binary path (test seam). Defaults to `process.execPath`. */
+    execPath?: string;
+    /** Locate a real `node` (test seam). Defaults to `which/where node`. */
+    resolveNode?: () => string | undefined;
+    /** File-existence check (test seam). Defaults to `fs.existsSync`. */
+    fileExists?: (p: string) => boolean;
+}): ServerSpawnArgs;
+export declare function isBunStandaloneExecutable(moduleUrl?: string): boolean;
+export declare function readRecentLogLines(logPath: string, maxLines?: number): string[];
+export declare function buildPtyStartFailureMessage(details: {
+    timeoutMs: number;
+    spawn: ServerSpawnArgs;
+    exit?: ServerExit;
+    spawnError?: Error;
+    lastReadinessError?: Error;
+    logPath: string;
+}): string;
 /**
  * Parse escape sequences in user input strings.
  * Handles: \n \r \t \e \xHH \\

package/dist/lib/pty-client.js

@@ -11,8 +11,10 @@ import { fileURLToPath } from 'url';
 import * as path from 'path';
 import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
 import { backgroundSpawnOptions } from './platform/process.js';
+import { BUN_VIRTUAL_ROOT } from './cli-entry.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
+const START_TIMEOUT_MS = 5000;
 const IS_WINDOWS = process.platform === 'win32';
 /**
  * Send a request to the PTY server and return the response.
@@ -36,18 +38,44 @@ async function ensureServer() {
     // Find the entry point to spawn the server
     const { bin, args } = getServerSpawnArgs();
     const logPath = getPtyLogPath();
-    const logFd = fs.openSync(logPath, 'a');
-    const child = spawn(bin, args, {
-        stdio: ['ignore', logFd, logFd],
-        ...backgroundSpawnOptions({ fdStdio: true }),
+    let logFd;
+    try {
+        logFd = fs.openSync(logPath, 'a');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error([
+            'PTY server failed to start before spawning.',
+            `Spawned: ${formatCommand({ bin, args })}`,
+            `Log: ${logPath}`,
+            `Log open error: ${message}`,
+        ].join('\n'));
+    }
+    let child;
+    try {
+        child = spawn(bin, args, {
+            stdio: ['ignore', logFd, logFd],
+            ...backgroundSpawnOptions({ fdStdio: true }),
+        });
+    }
+    finally {
+        fs.closeSync(logFd);
+    }
+    let childExit;
+    let childError;
+    let lastReadinessError;
+    child.once('exit', (code, signal) => {
+        childExit = { code, signal };
+    });
+    child.once('error', (err) => {
+        childError = err;
     });
     child.unref();
-    fs.closeSync(logFd);
     // Wait for the server to become reachable. On Unix the socket file appearing is
     // a cheap readiness signal; on Windows the named pipe is not a filesystem object
     // (fs.existsSync always returns false), so we just attempt the ping directly.
     const socketPath = getSocketPath();
-    const deadline = Date.now() + 5000;
+    const deadline = Date.now() + START_TIMEOUT_MS;
     while (Date.now() < deadline) {
         if (IS_WINDOWS || fs.existsSync(socketPath)) {
             // Verify we can connect
@@ -55,15 +83,50 @@ async function ensureServer() {
                 await sendRequest({ action: 'ping' });
                 return;
             }
-            catch {
-                // Not ready yet
+            catch (err) {
+                lastReadinessError = err instanceof Error ? err : new Error(String(err));
             }
         }
+        if (childError || childExit)
+            break;
         await new Promise(r => setTimeout(r, 100));
     }
-    throw new Error('PTY server failed to start within 5 seconds. Check ~/.agents/.system/helpers/pty/logs.jsonl');
+    throw new Error(buildPtyStartFailureMessage({
+        timeoutMs: START_TIMEOUT_MS,
+        spawn: { bin, args },
+        exit: childExit,
+        spawnError: childError,
+        lastReadinessError,
+        logPath,
+    }));
 }
-function getServerSpawnArgs() {
+export function getServerSpawnArgs(options = {}) {
+    const isStandaloneExecutable = options.isStandaloneExecutable
+        ?? isBunStandaloneExecutable();
+    if (isStandaloneExecutable) {
+        // A Bun `--compile` standalone binary cannot `require()` a native addon, so
+        // running the PTY sidecar AS this binary fails to load node-pty's pty.node
+        // (fatal on macOS; see #315). Prefer a real `node` running the dist/index.js
+        // that ships beside the binary — there node-pty loads from the on-disk
+        // prebuild. We can't do `<binary> dist/index.js` (the standalone misparses a
+        // script arg as a subcommand), so a genuine `node` is required. Fall back to
+        // the binary itself only when no node / no dist is found (a bare standalone
+        // install with no Node — PTY may then be unavailable, but nothing else can
+        // load the addon anyway).
+        const node = (options.resolveNode ?? resolveNodeExecutable)();
+        const exists = options.fileExists ?? fs.existsSync;
+        const execPath = options.execPath ?? process.execPath;
+        if (node) {
+            try {
+                const distIndex = path.join(path.dirname(execPath), '..', 'index.js');
+                if (exists(distIndex)) {
+                    return { bin: node, args: [distIndex, 'pty', '_server'] };
+                }
+            }
+            catch { }
+        }
+        return { bin: process.execPath, args: ['pty', '_server'] };
+    }
     // Prefer the dist/index.js from the same installation as this code.
     // This avoids version mismatch when a globally installed `agents` is older.
     try {
@@ -86,6 +149,69 @@ function getServerSpawnArgs() {
     catch { }
     return { bin: 'agents', args: ['pty', '_server'] };
 }
+export function isBunStandaloneExecutable(moduleUrl = import.meta.url) {
+    return BUN_VIRTUAL_ROOT.test(moduleUrl);
+}
+/**
+ * Locate a real `node` on PATH for running the sidecar's dist/index.js from a
+ * Bun standalone binary (which cannot itself load native addons). Returns
+ * undefined when no node is found — the caller then falls back to the binary.
+ */
+function resolveNodeExecutable() {
+    try {
+        const lookup = IS_WINDOWS ? 'where node' : 'which node';
+        const node = execSync(lookup, { encoding: 'utf-8' }).split(/\r?\n/)[0].trim();
+        if (node && fs.existsSync(node))
+            return node;
+    }
+    catch { }
+    return undefined;
+}
+export function readRecentLogLines(logPath, maxLines = 20) {
+    try {
+        if (!fs.existsSync(logPath))
+            return [];
+        return fs.readFileSync(logPath, 'utf-8')
+            .split(/\r?\n/)
+            .filter(line => line.trim().length > 0)
+            .slice(-maxLines);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return [`Unable to read PTY server log: ${message}`];
+    }
+}
+export function buildPtyStartFailureMessage(details) {
+    const lines = [
+        `PTY server failed to start within ${Math.round(details.timeoutMs / 1000)} seconds.`,
+        `Spawned: ${formatCommand(details.spawn)}`,
+    ];
+    if (details.spawnError) {
+        lines.push(`Spawn error: ${details.spawnError.message}`);
+    }
+    if (details.exit) {
+        const reason = details.exit.signal
+            ? `signal ${details.exit.signal}`
+            : `code ${details.exit.code ?? 'unknown'}`;
+        lines.push(`PTY server process exited with ${reason} before listening.`);
+    }
+    if (details.lastReadinessError) {
+        lines.push(`Last readiness error: ${details.lastReadinessError.message}`);
+    }
+    lines.push(`Log: ${details.logPath}`);
+    const logLines = readRecentLogLines(details.logPath);
+    if (logLines.length > 0) {
+        lines.push('Recent PTY server log:');
+        lines.push(...logLines.map(line => `  ${line}`));
+    }
+    else {
+        lines.push('No PTY server log output was written.');
+    }
+    return lines.join('\n');
+}
+function formatCommand(spawnArgs) {
+    return [spawnArgs.bin, ...spawnArgs.args].map((part) => JSON.stringify(part)).join(' ');
+}
 /**
  * Send a JSON request over the unix socket and return the parsed response.
  */

package/dist/lib/refresh.js

@@ -16,7 +16,7 @@ import { capableAgents } from './capabilities.js';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, registerMcpToTargets, agentLabel, } from './agents.js';
 import { readManifest, MANIFEST_FILENAME } from './manifest.js';
 import { getUserAgentsDir } from './state.js';
-import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './versions.js';
+import { installVersion, listInstalledVersions, isVersionIsolated, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from './versions.js';
 import { listCliStatus, installCli, describeMethod, describeCheck, selectInstallMethod, } from './cli-resources.js';
 import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructions, switchConfigSymlink, switchHomeFileSymlinks, } from './shims.js';
 import { parseHookManifest, registerHooksToSettings } from './hooks.js';
@@ -133,13 +133,9 @@ export async function refresh(options = {}) {
             actuallySynced.plugins.length > 0;
         try {
             let selection;
+            let forceFullSync = false;
             if (skipPrompts) {
-                if (!hasAnySynced || hasNewResources(newResources, agentId)) {
-                    selection = {
-                        commands: 'all', skills: 'all', hooks: 'all', memory: 'all',
-                        mcp: 'all', permissions: 'all', subagents: 'all', plugins: 'all',
-                    };
-                }
+                forceFullSync = true;
             }
             else if (!hasAnySynced) {
                 console.log(chalk.yellow(`\n${agentLabel(agentId)}@${defaultVer} has no synced resources.`));
@@ -153,8 +149,11 @@ export async function refresh(options = {}) {
                 if (userSelection)
                     selection = userSelection;
             }
-            if (selection && Object.keys(selection).length > 0) {
-                const syncResult = syncResourcesToVersion(agentId, defaultVer, selection);
+            else {
+                forceFullSync = true;
+            }
+            if (forceFullSync || (selection && Object.keys(selection).length > 0)) {
+                const syncResult = syncResourcesToVersion(agentId, defaultVer, selection, forceFullSync ? { force: true } : undefined);
                 const synced = [];
                 if (syncResult.commands)
                     synced.push('commands');
@@ -231,7 +230,12 @@ export async function refresh(options = {}) {
         }
         const selectedVersions = [];
         for (const agentId of agentsNeedingDefault) {
-            const versions = listInstalledVersions(agentId);
+            // Isolated copies are not default-eligible — `agents use` refuses them and
+            // setting one here would also switch the config symlink, pointing the user's
+            // real ~/.<agent> at an isolated home. Keep them out of the picker entirely.
+            const versions = listInstalledVersions(agentId).filter((v) => !isVersionIsolated(agentId, v));
+            if (versions.length === 0)
+                continue;
             const agent = AGENTS[agentId];
             const shouldSwitch = await select({
                 message: `${agentLabel(agent.id)} has no default version. Set one now?`,

package/dist/lib/resource-profiles.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Top-level resource profiles.
+ *
+ * These are distinct from model-provider run profiles in lib/profiles.ts. A
+ * resource profile is a global mode switch stored in agents.yaml that filters
+ * the resolved DotAgents resource view and secrets bundles.
+ */
+import type { ResourceProfilePreset } from './types.js';
+export type ProfiledResourceKind = 'commands' | 'skills' | 'hooks' | 'subagents' | 'plugins' | 'workflows' | 'permissions' | 'mcp' | 'memory' | 'secrets';
+export type PatternedProfileKind = Exclude<ProfiledResourceKind, 'memory' | 'secrets'>;
+export interface ActiveResourceProfile {
+    name: string;
+    preset: ResourceProfilePreset;
+}
+export declare function validateResourceProfileName(name: string): void;
+export declare function listResourceProfileNames(): string[];
+export declare function getResourceProfilePreset(name: string): ResourceProfilePreset | null;
+export declare function getActiveResourceProfileName(): string | null;
+export declare function getActiveResourceProfile(): ActiveResourceProfile | null;
+export declare function upsertResourceProfilePreset(name: string, preset: ResourceProfilePreset): void;
+export declare function setActiveResourceProfile(name: string | null): void;
+export declare function patternedProfileKinds(): PatternedProfileKind[];
+export declare function activeRulesPreset(): string | null;
+export declare function filterNamesForActiveResourceProfile(kind: ProfiledResourceKind, names: string[], sourceMap?: Map<string, string>): string[];
+export declare function isNameActiveInResourceProfile(kind: ProfiledResourceKind, name: string, source?: string): boolean;
+export declare function assertNameActiveInResourceProfile(kind: ProfiledResourceKind, name: string): void;