@phnx-labs/agents-cli 1.20.29 → 1.20.30

package/dist/lib/ssh-tunnel.js

@@ -0,0 +1,346 @@
+/**
+ * Shared SSH port-forward tunnel + remote computer-helper provisioning.
+ *
+ * Two layers live here:
+ *
+ *  1. `startSSHTunnel` — the generic `ssh -L localPort:127.0.0.1:remotePort -N`
+ *     spawn, extracted verbatim from the browser CDP driver so both the browser
+ *     and `agents computer --host` reach a remote loopback service through one
+ *     hardened tunnel. Behavior for the browser caller is unchanged (default,
+ *     foreground, stderr-captured).
+ *
+ *  2. Remote computer-helper orchestration — resolve a registered device to an
+ *     ssh target, push the cross-published Windows daemon exe, register it as a
+ *     LOGON scheduled task (interactive session so real-desktop UIA/screenshot
+ *     works and it survives the ssh disconnect), and open a tunnel the TS RPC
+ *     client drives via TCP. Everything rides the existing `ssh-exec` /
+ *     `devices/connect` primitives — no parallel SSH implementation.
+ */
+import { spawn } from 'child_process';
+import * as net from 'net';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { randomBytes } from 'crypto';
+import { sshExec } from './ssh-exec.js';
+import { encodePowerShell } from './browser/drivers/ssh.js';
+import { getDevice } from './devices/registry.js';
+import { sshTargetFor } from './devices/connect.js';
+import { hostNameFor } from './devices/ssh-config.js';
+import { getCacheDir } from './state.js';
+import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
+/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure. */
+export function buildTunnelArgs(user, host, localPort, remotePort) {
+    return [
+        '-L',
+        `${localPort}:127.0.0.1:${remotePort}`,
+        `${user}@${host}`,
+        '-N',
+        '-o',
+        'StrictHostKeyChecking=accept-new',
+        '-o',
+        'BatchMode=yes',
+        '-o',
+        'ConnectTimeout=10',
+    ];
+}
+/**
+ * Spawn `ssh -L localPort:127.0.0.1:remotePort -N user@host`.
+ *
+ * Foreground (default): stderr is captured so a tunnel that dies inside 500ms
+ * rejects with the ssh error — the browser driver's original contract. Detached
+ * mode ignores stdio and `unref`s the child so the parent can exit while the
+ * tunnel lives; liveness is then confirmed by the caller probing the service.
+ */
+export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const args = buildTunnelArgs(user, host, localPort, remotePort);
+        const tunnel = spawn('ssh', args, {
+            stdio: opts.detached ? 'ignore' : ['ignore', 'ignore', 'pipe'],
+            detached: Boolean(opts.detached),
+        });
+        let stderr = '';
+        tunnel.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        tunnel.on('error', (err) => {
+            reject(new Error(`SSH tunnel failed: ${err.message}`));
+        });
+        setTimeout(() => {
+            if (tunnel.killed) {
+                reject(new Error(`SSH tunnel died: ${stderr}`));
+            }
+            else {
+                // Let the CLI exit without waiting on a persistent tunnel.
+                if (opts.detached)
+                    tunnel.unref();
+                resolve(tunnel);
+            }
+        }, 500);
+    });
+}
+// ---------------------------------------------------------------------------
+// 2. Remote computer-helper orchestration
+// ---------------------------------------------------------------------------
+/** Loopback TCP port the Windows daemon binds on the remote (Program.cs default). */
+export const REMOTE_HELPER_PORT = 8765;
+/** Task Scheduler task name for the daemon. Stable so setup/stop pair up. */
+export const REMOTE_TASK_NAME = 'AgentsComputerHelper';
+/** Basename of the cross-published exe under packages/computer-helper-win/dist. */
+export const WIN_HELPER_EXE = 'computer-helper-win.exe';
+/**
+ * Locate the cross-published Windows daemon exe. Only the local build output is
+ * a candidate — `scripts/build-win.sh` writes it to packages/.../dist/.
+ */
+export function resolveWinHelperExe() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // Running from the agents-cli checkout (src/lib -> repo root).
+        path.resolve(here, '..', '..', 'packages', 'computer-helper-win', 'dist', WIN_HELPER_EXE),
+        // Bundled with the npm package (dist/lib -> package root).
+        path.resolve(here, '..', 'computer-helper-win', WIN_HELPER_EXE),
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+function remoteStateDir() {
+    return path.join(getCacheDir(), 'computer', 'remote');
+}
+/** State file path for a device. Device names are ssh-alias safe (validated). */
+export function remoteStatePath(device) {
+    return path.join(remoteStateDir(), `${device}.json`);
+}
+export function readRemoteState(device) {
+    try {
+        return JSON.parse(fs.readFileSync(remoteStatePath(device), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeRemoteState(state) {
+    const dir = remoteStateDir();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(remoteStatePath(state.device), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+export function clearRemoteState(device) {
+    try {
+        fs.unlinkSync(remoteStatePath(device));
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Resolve a registered device to its ssh pieces, or throw a clear error. */
+export async function resolveRemoteDevice(name) {
+    const device = await getDevice(name);
+    if (!device) {
+        throw new Error(`Unknown device '${name}'. Register it with \`agents devices add\` / \`agents devices sync\`, then retry.`);
+    }
+    if (device.platform !== 'windows') {
+        throw new Error(`Device '${name}' is ${device.platform}, not windows. \`agents computer --host\` drives the Windows computer-helper daemon.`);
+    }
+    const target = sshTargetFor(device); // validates address + injection guard
+    const host = hostNameFor(device); // sshTargetFor already threw if absent
+    const user = device.user || process.env.USER || 'Administrator';
+    return { device, target, user, host };
+}
+/**
+ * PowerShell that streams base64 from stdin, decodes it incrementally to
+ * %LOCALAPPDATA%\agents\computer-helper-win.exe, and stops any running instance
+ * first so the file isn't locked. The CryptoStream/FromBase64Transform decode
+ * is streaming — the ~156MB exe never lands in memory whole on the remote.
+ */
+export function buildPushScript() {
+    return [
+        `$dir = Join-Path $env:LOCALAPPDATA 'agents'`,
+        `New-Item -ItemType Directory -Force -Path $dir | Out-Null`,
+        `$dst = Join-Path $dir '${WIN_HELPER_EXE}'`,
+        `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
+        `$si = [Console]::OpenStandardInput()`,
+        `$t = New-Object Security.Cryptography.FromBase64Transform`,
+        `$cs = New-Object Security.Cryptography.CryptoStream($si, $t, [Security.Cryptography.CryptoStreamMode]::Read)`,
+        `$fs = [IO.File]::Create($dst)`,
+        `$cs.CopyTo($fs)`,
+        `$fs.Close(); $cs.Close()`,
+        `Write-Output $dst`,
+    ].join('; ');
+}
+/**
+ * PowerShell that registers the daemon as a LOGON scheduled task. Interactive
+ * logon type + Highest run level so the daemon runs in the real desktop session
+ * (UIAutomation and ScreenCapture need a live session, not Session 0) and
+ * survives ssh disconnect — the same rationale as the browser WMI launch. The
+ * task is started immediately so the caller need not log out/in.
+ */
+export function buildRegisterTaskScript(port, taskName) {
+    return [
+        `$exe = Join-Path (Join-Path $env:LOCALAPPDATA 'agents') '${WIN_HELPER_EXE}'`,
+        `$action = New-ScheduledTaskAction -Execute $exe -Argument '--port ${port}'`,
+        `$trigger = New-ScheduledTaskTrigger -AtLogOn`,
+        `$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Highest`,
+        `$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -ExecutionTimeLimit ([TimeSpan]::Zero)`,
+        `Register-ScheduledTask -TaskName '${taskName}' -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null`,
+        `Start-ScheduledTask -TaskName '${taskName}'`,
+    ].join('; ');
+}
+/** PowerShell that unregisters the task and stops any running daemon process. */
+export function buildUnregisterTaskScript(taskName) {
+    return [
+        `Unregister-ScheduledTask -TaskName '${taskName}' -Confirm:$false -ErrorAction SilentlyContinue`,
+        `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
+    ].join('; ');
+}
+/**
+ * `setup --host`: push the exe, then register + start the LOGON task. Both hops
+ * go through `sshExec` (BatchMode key auth — the same hardening the browser
+ * driver and `agents ssh` use). Throws with the remote stderr on any failure.
+ */
+export async function setupRemoteHelper(name) {
+    const { target } = await resolveRemoteDevice(name);
+    const exe = resolveWinHelperExe();
+    if (!exe) {
+        throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
+    }
+    // Push: base64 the exe locally, stream it over ssh stdin to the decoder.
+    const b64 = fs.readFileSync(exe).toString('base64');
+    const push = sshExec(target, encodePowerShell(buildPushScript()), {
+        input: b64,
+        timeoutMs: 600_000, // ~156MB over the wire — allow up to 10 minutes
+    });
+    if (push.code !== 0) {
+        throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim() || push.stdout.trim()}`);
+    }
+    // Register + start the LOGON task.
+    const reg = sshExec(target, encodePowerShell(buildRegisterTaskScript(REMOTE_HELPER_PORT, REMOTE_TASK_NAME)), {
+        timeoutMs: 60_000,
+    });
+    if (reg.code !== 0) {
+        throw new Error(`registering scheduled task on '${name}' failed (exit ${reg.code ?? 'null'}): ${reg.stderr.trim() || reg.stdout.trim()}`);
+    }
+    return { target, taskName: REMOTE_TASK_NAME };
+}
+/** Reserve a free local TCP port by binding :0 and reading the assigned port. */
+export function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const addr = srv.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error('could not reserve a local port'))));
+        });
+    });
+}
+/**
+ * `start --host`: open a detached ssh -L tunnel to the remote daemon, verify it
+ * answers over TCP, and persist the tunnel state so verbs can reconnect. Returns
+ * the state (and leaves the tunnel running in the background).
+ */
+export async function startRemoteTunnel(name) {
+    const { target, user, host } = await resolveRemoteDevice(name);
+    const remotePort = REMOTE_HELPER_PORT;
+    const localPort = await pickFreePort();
+    const tunnel = await startSSHTunnel(user, host, localPort, remotePort, { detached: true });
+    const tunnelPid = tunnel.pid ?? 0;
+    // Verify the daemon answers through the tunnel before we record it. This is
+    // the real end-to-end check: tunnel up + daemon listening + RPC round-trips.
+    const token = null; // tunnel-gated; the daemon runs token-less
+    const prevTcp = process.env.COMPUTER_HELPER_TCP;
+    process.env.COMPUTER_HELPER_TCP = `127.0.0.1:${localPort}`;
+    const client = openComputerClient();
+    let ok = false;
+    let probeErr = '';
+    try {
+        const r = await client.call('list_apps');
+        ok = !r.error;
+        if (r.error)
+            probeErr = `${r.error.code}: ${r.error.message}`;
+    }
+    catch (e) {
+        probeErr = e.message;
+    }
+    finally {
+        await client.close();
+        if (prevTcp === undefined)
+            delete process.env.COMPUTER_HELPER_TCP;
+        else
+            process.env.COMPUTER_HELPER_TCP = prevTcp;
+    }
+    if (!ok) {
+        try {
+            if (tunnelPid)
+                process.kill(tunnelPid);
+        }
+        catch { /* gone */ }
+        throw new Error(`tunnel to '${name}' opened but the daemon did not answer (${probeErr}). ` +
+            `Is it installed? Run: agents computer setup --host ${name}`);
+    }
+    const state = {
+        device: name,
+        target,
+        localPort,
+        remotePort,
+        tunnelPid,
+        token,
+        taskName: REMOTE_TASK_NAME,
+        startedAt: Date.now(),
+    };
+    writeRemoteState(state);
+    return state;
+}
+/**
+ * `stop --host`: kill the local tunnel, unregister the remote task (best-effort
+ * — the box may be offline), and clear the persisted state.
+ */
+export async function stopRemoteHelper(name) {
+    const state = readRemoteState(name);
+    let tunnelKilled = false;
+    if (state?.tunnelPid) {
+        try {
+            process.kill(state.tunnelPid);
+            tunnelKilled = true;
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    let taskRemoved = false;
+    try {
+        const { target } = await resolveRemoteDevice(name);
+        const res = sshExec(target, encodePowerShell(buildUnregisterTaskScript(REMOTE_TASK_NAME)), { timeoutMs: 60_000 });
+        taskRemoved = res.code === 0;
+    }
+    catch {
+        /* device gone / offline — local teardown still succeeds */
+    }
+    clearRemoteState(name);
+    return { tunnelKilled, taskRemoved };
+}
+/**
+ * Point this process's RPC client at a device's live tunnel by setting
+ * COMPUTER_HELPER_TCP / COMPUTER_HELPER_TOKEN from persisted state. Called for
+ * remote verbs (`apps --host`, `click --host`, …) so the shared
+ * openComputerClient() transparently selects the TcpClient transport — no
+ * per-verb wiring. Exits with guidance when there is no active tunnel.
+ */
+export function hydrateRemoteEnvFromState(name) {
+    const state = readRemoteState(name);
+    if (!state) {
+        console.error(`No active remote tunnel for '${name}'.`);
+        console.error(`Run:  agents computer start --host ${name}`);
+        process.exit(1);
+    }
+    process.env.COMPUTER_HELPER_TCP = `127.0.0.1:${state.localPort}`;
+    if (state.token)
+        process.env.COMPUTER_HELPER_TOKEN = state.token;
+    // Touch resolveTcpEndpoint so a later platform-gate check sees the endpoint.
+    void resolveTcpEndpoint();
+}
+/** Generate a shared-secret token (reserved for token-file provisioning). */
+export function generateToken() {
+    return randomBytes(24).toString('hex');
+}

package/dist/lib/state.d.ts

@@ -99,6 +99,8 @@ export declare function getSystemWorkflowsDir(): string;
 export declare function getUserWorkflowsDir(): string;
 export declare function getUserSecretsDir(): string;
 export declare function getUserPromptcutsPath(): string;
+/** Canonical home anchor (HOME env override or os.homedir()). */
+export declare function getHomeDir(): string;
 /** Bucket root for durable runtime data (~/.agents/.history/). */
 export declare function getHistoryDir(): string;
 /** Bucket root for regenerable runtime data (~/.agents/.cache/). */

package/dist/lib/state.js

@@ -29,6 +29,20 @@ import * as yaml from 'yaml';
 import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { SEEDED_REGISTRIES } from './types.js';
 const HOME = process.env.HOME ?? os.homedir();
+/**
+ * Compare two filesystem paths for identity, resolving symlinks and (on
+ * Windows) 8.3 short-name vs long-name divergence via the OS realpath.
+ * Falls back to a case-folded normalize when a path doesn't exist on disk.
+ */
+function isSamePath(a, b) {
+    try {
+        return fs.realpathSync.native(a) === fs.realpathSync.native(b);
+    }
+    catch {
+        const norm = (p) => process.platform === 'win32' ? path.resolve(p).toLowerCase() : path.resolve(p);
+        return norm(a) === norm(b);
+    }
+}
 // ─── Root directories ─────────────────────────────────────────────────────────
 /** User repo — user-authored resources and agents.yaml. Always-on. */
 const USER_AGENTS_DIR = path.join(HOME, '.agents');
@@ -161,7 +175,7 @@ export function getProjectAgentsDir(startPath = process.cwd()) {
     while (true) {
         const agentsPath = path.join(dir, '.agents');
         if (fs.existsSync(agentsPath) && fs.statSync(agentsPath).isDirectory()) {
-            if (agentsPath !== SYSTEM_AGENTS_DIR && agentsPath !== USER_AGENTS_DIR) {
+            if (!isSamePath(agentsPath, SYSTEM_AGENTS_DIR) && !isSamePath(agentsPath, USER_AGENTS_DIR)) {
                 return agentsPath;
             }
         }
@@ -269,6 +283,8 @@ export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
 //
 // Top-level dirs hold definitions/configs only; runtime data lives under
 // .history/ (durable) or .cache/ (regenerable). See file header.
+/** Canonical home anchor (HOME env override or os.homedir()). */
+export function getHomeDir() { return HOME; }
 /** Bucket root for durable runtime data (~/.agents/.history/). */
 export function getHistoryDir() { return HISTORY_DIR; }
 /** Bucket root for regenerable runtime data (~/.agents/.cache/). */

package/dist/lib/teams/agents.d.ts

@@ -50,7 +50,17 @@ type Mode = 'plan' | 'edit' | 'auto' | 'skip';
 export declare function resolveMode(requestedMode: string | null | undefined, defaultMode?: Mode): Mode;
 /** Ensure Gemini's settings.json has experimental.plan enabled for headless plan mode. */
 export declare function ensureGeminiPlanMode(): Promise<void>;
-/** Check whether the CLI binary for a given agent type exists in PATH. Returns [available, pathOrError]. */
+/**
+ * Check whether the CLI binary for a given agent type is installed.
+ * Returns [available, pathOrError].
+ *
+ * The agents-managed shims dir (`~/.agents/.cache/shims`) is the canonical
+ * install location, so a shim there means installed regardless of the caller's
+ * PATH. Non-interactive callers — the menu-bar helper, cron, CI — run with a
+ * minimal launchd PATH that omits the shims dir; a bare PATH lookup false-flags
+ * every shim-based CLI as "not installed". Check the shim first, PATH second
+ * (for CLIs the user installed outside agents-cli).
+ */
 export declare function checkCliAvailable(agentType: AgentType): [boolean, string | null];
 /** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export declare function checkAllClis(): Record<string, {

package/dist/lib/teams/agents.js

@@ -18,7 +18,7 @@ import { findExecutable } from '../platform/index.js';
 import { normalizeEvents } from './parsers.js';
 import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
-import { getAgentsDir as getSystemAgentsDir } from '../state.js';
+import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
 import { AGENTS } from '../agents.js';
 import { sanitizeProcessEnv } from '../secrets/bundles.js';
 let lastMemoryWarnAt = 0;
@@ -314,12 +314,26 @@ export async function ensureGeminiPlanMode() {
         console.warn('[Swarm] Could not enable Gemini plan mode:', err);
     }
 }
-/** Check whether the CLI binary for a given agent type exists in PATH. Returns [available, pathOrError]. */
+/**
+ * Check whether the CLI binary for a given agent type is installed.
+ * Returns [available, pathOrError].
+ *
+ * The agents-managed shims dir (`~/.agents/.cache/shims`) is the canonical
+ * install location, so a shim there means installed regardless of the caller's
+ * PATH. Non-interactive callers — the menu-bar helper, cron, CI — run with a
+ * minimal launchd PATH that omits the shims dir; a bare PATH lookup false-flags
+ * every shim-based CLI as "not installed". Check the shim first, PATH second
+ * (for CLIs the user installed outside agents-cli).
+ */
 export function checkCliAvailable(agentType) {
     const executable = AGENTS[agentType]?.cliCommand;
     if (!executable) {
         return [false, `Unknown agent type: ${agentType}`];
     }
+    const shimPath = path.join(getShimsDir(), executable);
+    if (fsSync.existsSync(shimPath)) {
+        return [true, shimPath];
+    }
     const resolved = findExecutable(executable);
     return resolved
         ? [true, resolved]

package/dist/lib/types.d.ts

@@ -74,6 +74,7 @@ export interface AgentConfig {
     installScript?: string;
     configDir: string;
     homeFiles?: string[];
+    authFiles?: string[];
     commandsDir: string;
     commandsSubdir: string;
     skillsDir: string;

package/dist/lib/versions.d.ts

@@ -314,6 +314,25 @@ export interface ResourceDiff {
  * Uses filesystem state - no tracking needed.
  */
 export declare function getResourceDiff(agent: AgentId, version: string): ResourceDiff;
+/**
+ * Enumerate the DotAgent repo names that resources can be scoped to:
+ * the fixed `project` / `user` / `system` layers plus every enabled extra
+ * repo alias. Used to validate `agents sync <agent> --repo <name>`.
+ */
+export declare function listRepoNames(): string[];
+/**
+ * Build a ResourceSelection scoped to a single DotAgent repo (`system`,
+ * `user`, `project`, or an extra-repo alias). Every resource kind is filtered
+ * to the entries whose source layer matches `repo`, reusing the same
+ * name→source maps and `source:*` pattern expansion the persisted-pattern
+ * sync path uses. Passing the result as an explicit `selection` means the sync
+ * touches only that repo's resources — no orphan-sweep of the other layers.
+ *
+ * `memory` is set to `[]` (not omitted): that empty-array sentinel is what
+ * `syncResourcesToVersion`'s `skipMemory` gate keys on to leave the memory
+ * file untouched — it's a merge of all layers, not a per-repo artifact.
+ */
+export declare function buildRepoScopedSelection(repo: string, cwd?: string): ResourceSelection;
 /**
  * Sync central resources (~/.agents/) into a specific version's config directory.
  * Copies selected resources from central storage into {versionHome}/.{agent}/.

package/dist/lib/versions.js

@@ -16,13 +16,12 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import * as yaml from 'yaml';
 import { exec, execFile } from 'child_process';
 import { promisify } from 'util';
 import chalk from 'chalk';
 import { checkbox, select } from '@inquirer/prompts';
-import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset } from './state.js';
+import { getVersionsDir, ensureAgentsDir, readMeta, writeMeta, getCommandsDir, getSkillsDir, getHooksDir, getResolvedRulesDir, getUserRulesDir, getVersionResources, ensureVersionResourcePatterns, getProjectAgentsDir, getPromptcutsPath, getUserPromptcutsPath, getEnabledExtraRepos, getAgentsDir, getUserAgentsDir, getTrashVersionsDir, getActiveRulesPreset, getHomeDir } from './state.js';
 import { defaultPatterns, expandPatterns } from './resource-patterns.js';
 import { listResources } from './resources.js';
 import { AGENTS, agentConfigDirName, getAccountEmail, resolveAgentName, formatAgentError, findInPath } from './agents.js';
@@ -30,6 +29,7 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpServerConfig } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
+import { IS_WINDOWS } from './platform/index.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
@@ -819,12 +819,17 @@ export function getBinaryPath(agent, version) {
         return path.join(grokDownloads, `grok-${version}`);
     }
     if (agent === 'droid') {
-        // Factory's installer drops a standalone native binary at ~/.local/bin/droid
-        // (no npm package, nothing in node_modules/.bin). The binary is global, not
-        // per-version — config isolation rides the ~/.factory symlink switch, not a
-        // separate binary per version. Mirror the shim's `droid` branch so
-        // isVersionInstalled/`agents view` agree with what actually executes.
-        return path.join(os.homedir(), '.local', 'bin', 'droid');
+        // Factory's installer drops a standalone native binary (no npm package,
+        // nothing in node_modules/.bin). The binary is global, not per-version —
+        // config isolation rides the ~/.factory symlink switch, not a separate
+        // binary per version. Install location is platform-specific:
+        //   macOS/Linux: ~/.local/bin/droid       (curl app.factory.ai/cli | sh)
+        //   Windows:     %USERPROFILE%\bin\droid.exe  (irm app.factory.ai/cli/windows | iex)
+        // Mirror the shim's `droid` branch so isVersionInstalled/`agents view`
+        // agree with what actually executes.
+        return IS_WINDOWS
+            ? path.join(getHomeDir(), 'bin', 'droid.exe')
+            : path.join(getHomeDir(), '.local', 'bin', 'droid');
     }
     const versionDir = getVersionDir(agent, version);
     return path.join(versionDir, 'node_modules', '.bin', agentConfig.cliCommand);
@@ -1302,7 +1307,7 @@ export function removeVersion(agent, version) {
     // Clean up dangling config symlink if it pointed to the removed version
     const symlinkVersion = getConfigSymlinkVersion(agent);
     if (symlinkVersion === version) {
-        const configPath = path.join(os.homedir(), agentConfigDirName(agent));
+        const configPath = path.join(getHomeDir(), agentConfigDirName(agent));
         try {
             fs.unlinkSync(configPath);
         }
@@ -1636,6 +1641,68 @@ export function getResourceDiff(agent, version) {
         diff.hooks.dangling.length + diff.memory.dangling.length;
     return diff;
 }
+/**
+ * Enumerate the DotAgent repo names that resources can be scoped to:
+ * the fixed `project` / `user` / `system` layers plus every enabled extra
+ * repo alias. Used to validate `agents sync <agent> --repo <name>`.
+ */
+export function listRepoNames() {
+    return ['project', 'user', 'system', ...getEnabledExtraRepos().map(e => e.alias)];
+}
+/**
+ * Build the name→source-layer map for one resource kind, the input
+ * `expandPatterns` matches `source:*` patterns against. This is the single
+ * source of truth for how each kind attributes its source layer:
+ *   - commands/skills/hooks/subagents → real layer from `listResources`
+ *   - permissions                     → always the system repo
+ *   - mcp                             → project vs user scope preserved
+ *   - plugins/workflows               → user repo
+ * Both the persisted-pattern sync path and `buildRepoScopedSelection` use it
+ * so the attribution can't drift between the two.
+ */
+function resourceSourceMap(kind, cwd, available) {
+    switch (kind) {
+        case 'commands':
+        case 'skills':
+        case 'hooks':
+        case 'subagents':
+            return new Map(listResources(kind, cwd).map(r => [r.name, r.source]));
+        case 'permissions':
+            return new Map(available.permissions.map(n => [n, 'system']));
+        case 'mcp':
+            return new Map(getScopedMcpResources(cwd).map(r => [r.name, r.scope]));
+        case 'plugins':
+            return new Map(available.plugins.map(n => [n, 'user']));
+        case 'workflows':
+            return new Map(available.workflows.map(n => [n, 'user']));
+    }
+}
+/**
+ * Build a ResourceSelection scoped to a single DotAgent repo (`system`,
+ * `user`, `project`, or an extra-repo alias). Every resource kind is filtered
+ * to the entries whose source layer matches `repo`, reusing the same
+ * name→source maps and `source:*` pattern expansion the persisted-pattern
+ * sync path uses. Passing the result as an explicit `selection` means the sync
+ * touches only that repo's resources — no orphan-sweep of the other layers.
+ *
+ * `memory` is set to `[]` (not omitted): that empty-array sentinel is what
+ * `syncResourcesToVersion`'s `skipMemory` gate keys on to leave the memory
+ * file untouched — it's a merge of all layers, not a per-repo artifact.
+ */
+export function buildRepoScopedSelection(repo, cwd = process.cwd()) {
+    const patterns = [`${repo}:*`];
+    const available = getAvailableResources(cwd);
+    const selection = {};
+    const kinds = ['commands', 'skills', 'hooks', 'subagents', 'permissions', 'mcp', 'plugins', 'workflows'];
+    for (const kind of kinds) {
+        const names = expandPatterns(patterns, resourceSourceMap(kind, cwd, available));
+        if (names.length > 0)
+            selection[kind] = names;
+    }
+    // Empty-array sentinel → skip the memory writer (see skipMemory below).
+    selection.memory = [];
+    return selection;
+}
 /**
  * Sync central resources (~/.agents/) into a specific version's config directory.
  * Copies selected resources from central storage into {versionHome}/.{agent}/.
@@ -1701,28 +1768,21 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                 const patterns = vr[type];
                 if (!Array.isArray(patterns) || patterns.length === 0)
                     continue;
-                const sourceMap = new Map(listResources(kind, cwd).map(r => [r.name, r.source]));
-                patternSelection[type] = expandPatterns(patterns, sourceMap);
+                patternSelection[type] = expandPatterns(patterns, resourceSourceMap(kind, cwd, available));
             }
-            // permissions: all groups are 'system' source.
+            // permissions / mcp / plugins / workflows: source attribution lives in
+            // resourceSourceMap so it can't drift from buildRepoScopedSelection.
             if (Array.isArray(vr.permissions) && vr.permissions.length > 0) {
-                const permMap = new Map(available.permissions.map(n => [n, 'system']));
-                patternSelection.permissions = expandPatterns(vr.permissions, permMap);
+                patternSelection.permissions = expandPatterns(vr.permissions, resourceSourceMap('permissions', cwd, available));
             }
-            // mcp: pattern matching must preserve project vs user scope.
             if (Array.isArray(vr.mcp) && vr.mcp.length > 0) {
-                const mcpMap = new Map(getScopedMcpResources(cwd).map(resource => [resource.name, resource.scope]));
-                patternSelection.mcp = expandPatterns(vr.mcp, mcpMap);
+                patternSelection.mcp = expandPatterns(vr.mcp, resourceSourceMap('mcp', cwd, available));
             }
-            // plugins: treat all as 'user' source for now.
             if (Array.isArray(vr.plugins) && vr.plugins.length > 0) {
-                const pluginMap = new Map(available.plugins.map(n => [n, 'user']));
-                patternSelection.plugins = expandPatterns(vr.plugins, pluginMap);
+                patternSelection.plugins = expandPatterns(vr.plugins, resourceSourceMap('plugins', cwd, available));
             }
-            // workflows: treat all as 'user' source.
             if (Array.isArray(vr.workflows) && vr.workflows.length > 0) {
-                const workflowMap = new Map(available.workflows.map(n => [n, 'user']));
-                patternSelection.workflows = expandPatterns(vr.workflows, workflowMap);
+                patternSelection.workflows = expandPatterns(vr.workflows, resourceSourceMap('workflows', cwd, available));
             }
             // memory is not pattern-controlled (rulesPreset handles it) — always sync.
             patternSelection.memory = 'all';
@@ -2071,7 +2131,7 @@ export function getEffectiveHome(agentId) {
     if (resolved && isVersionInstalled(agentId, resolved)) {
         return getVersionHomePath(agentId, resolved);
     }
-    return os.homedir();
+    return getHomeDir();
 }
 /**
  * Thrown when the user references an agent@version that is not installed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.29",
+  "version": "1.20.30",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",