@phnx-labs/agents-cli 1.20.11 → 1.20.13

package/dist/lib/versions.js

@@ -35,7 +35,7 @@ import { discoverPlugins } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
 import { emit } from './events.js';
 import { safeJoin } from './paths.js';
-import { listCommandSkillsInVersion, shouldInstallCommandAsSkill } from './command-skills.js';
+import { listCommandSkillsInVersion, readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
 import { getWriter, getDetector } from './staleness/registry.js';
 /** Promisified exec for running shell commands. */
 const execAsync = promisify(exec);
@@ -804,10 +804,7 @@ export function getVersionDir(agent, version) {
 export function getBinaryPath(agent, version) {
     const agentConfig = AGENTS[agent];
     if (agent === 'grok') {
-        // Grok binaries live in the global ~/.grok/downloads, not per-version node_modules.
-        // We return a best-effort path (used for display / checks). Real resolution
-        // happens in agents.ts resolveGrokBinary + the generated shims.
-        const grokDownloads = path.join(os.homedir(), '.grok', 'downloads');
+        const grokDownloads = path.join(getVersionHomePath(agent, version), '.grok', 'downloads');
         // Best effort: first matching file for this version
         try {
             const entries = fs.readdirSync(grokDownloads);
@@ -853,6 +850,26 @@ export async function getLatestNpmVersion(agent) {
         return null;
     }
 }
+/**
+ * Get the oldest published version from npm for an agent.
+ */
+export async function getOldestNpmVersion(agent) {
+    const agentConfig = AGENTS[agent];
+    if (!agentConfig.npmPackage)
+        return null;
+    try {
+        const { stdout } = await execFileAsync('npm', ['view', agentConfig.npmPackage, 'versions', '--json'], { shell: process.platform === 'win32' });
+        const parsed = JSON.parse(stdout.trim());
+        // `npm view ... versions --json` returns an array (multiple versions) or a
+        // bare string (single published version). Normalize to an array.
+        const versions = Array.isArray(parsed) ? parsed : [parsed];
+        const sorted = versions.filter((v) => VERSION_RE.test(v)).sort(compareVersions);
+        return sorted[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Check if 'latest' version is already installed (by resolving to actual version).
  */
@@ -863,6 +880,16 @@ export async function isLatestInstalled(agent) {
     }
     return { installed: isVersionInstalled(agent, latestVersion), version: latestVersion };
 }
+/**
+ * Check if 'oldest' published version is already installed (by resolving to actual version).
+ */
+export async function isOldestInstalled(agent) {
+    const oldestVersion = await getOldestNpmVersion(agent);
+    if (!oldestVersion) {
+        return { installed: false, version: null };
+    }
+    return { installed: isVersionInstalled(agent, oldestVersion), version: oldestVersion };
+}
 /**
  * List all installed versions for an agent.
  */
@@ -996,6 +1023,20 @@ export async function installVersion(agent, version, onProgress) {
         emit('version.install', { agent, version: installedVersion });
         return { success: true, installedVersion };
     }
+    // Resolve the `oldest` alias to a concrete npm version up front so the rest
+    // of the install path treats it as an ordinary pinned install. (`latest`
+    // keeps its bare-package-name + post-install-rename handling below.)
+    if (version === 'oldest') {
+        const oldest = await getOldestNpmVersion(agent);
+        if (!oldest) {
+            return {
+                success: false,
+                installedVersion: version,
+                error: `Could not resolve the oldest published version for ${agentConfig.name} from npm.`,
+            };
+        }
+        version = oldest;
+    }
     ensureAgentsDir();
     const versionDir = getVersionDir(agent, version);
     // Create version directory and isolated home
@@ -1012,6 +1053,8 @@ export async function installVersion(agent, version, onProgress) {
     const packageSpec = version === 'latest'
         ? agentConfig.npmPackage
         : `${agentConfig.npmPackage}@${version}`;
+    // The `${agentConfig.npmPackage}@` prefix is load-bearing: it ensures `version`
+    // (which VERSION_RE permits to start with `-`) is never passed as a standalone npm CLI flag.
     try {
         // Check npm is available
         const winShell = process.platform === 'win32';
@@ -1120,7 +1163,17 @@ export function softDeleteVersionDir(agent, version) {
     const trashDest = path.join(trashAgentDir, stamp);
     try {
         fs.mkdirSync(trashAgentDir, { recursive: true, mode: 0o700 });
-        fs.renameSync(versionDir, trashDest);
+        try {
+            fs.renameSync(versionDir, trashDest);
+        }
+        catch (renameErr) {
+            // On Windows, rename fails with EPERM/EACCES when any file in the tree
+            // is locked by a running process. Fall back to recursive copy + delete.
+            if (renameErr.code !== 'EPERM' && renameErr.code !== 'EACCES')
+                throw renameErr;
+            fs.cpSync(versionDir, trashDest, { recursive: true });
+            fs.rmSync(versionDir, { recursive: true, force: true });
+        }
         return trashDest;
     }
     catch {
@@ -1182,10 +1235,10 @@ export function printTrashFooter(moved) {
     console.log(chalk.gray('Sessions remain accessible via `agents sessions`.'));
     if (moved.length === 1) {
         const { agent, version } = moved[0];
-        console.log(chalk.gray(`Restore with: agents trash restore ${agent}@${version}`));
+        console.log(chalk.gray(`Restore with: agents restore ${agent}@${version}`));
     }
     else {
-        console.log(chalk.gray('Restore with: agents trash restore <agent>@<version>  (run `agents trash list` to see)'));
+        console.log(chalk.gray('Restore with: agents restore <agent>@<version>  (run `agents trash list` to see)'));
     }
 }
 /**
@@ -1223,6 +1276,7 @@ export function resolveVersion(agent, projectPath) {
  *
  *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
  *   "latest"                    -> highest installed version (process.exit if none installed)
+ *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
@@ -1234,14 +1288,14 @@ export function resolveVersion(agent, projectPath) {
 export function resolveVersionAlias(agent, raw) {
     if (!raw || raw === 'default')
         return undefined;
-    if (raw === 'latest') {
+    if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);
         if (installed.length === 0) {
             console.error(chalk.red(`No ${agent} versions installed.`));
             console.error(chalk.gray(`Install one: agents versions install ${agent}`));
             process.exit(1);
         }
-        return installed[installed.length - 1];
+        return raw === 'oldest' ? installed[0] : installed[installed.length - 1];
     }
     if (!isVersionInstalled(agent, raw)) {
         const installed = listInstalledVersions(agent);
@@ -1256,16 +1310,18 @@ export function resolveVersionAlias(agent, raw) {
 }
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest` semantics, but explicit versions
- * pass through unchanged so historical records of uninstalled versions remain
- * queryable.
+ * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * versions pass through unchanged so historical records of uninstalled versions
+ * remain queryable.
  */
 export function resolveVersionAliasLoose(agent, raw) {
     if (!raw || raw === 'default')
         return undefined;
-    if (raw === 'latest') {
+    if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);
-        return installed.length > 0 ? installed[installed.length - 1] : undefined;
+        if (installed.length === 0)
+            return undefined;
+        return raw === 'oldest' ? installed[0] : installed[installed.length - 1];
     }
     return raw;
 }
@@ -1643,10 +1699,10 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     const commandsToSync = selection
         ? resolveSelection(selection.commands, available.commands)
         : available.commands; // No selection = sync all
+    const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
     if (commandsToSync.length > 0 && commandsWriter) {
         const commandsTarget = path.join(agentDir, agentConfig.commandsSubdir);
-        const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
-        if (commandsAsSkills) {
+        if (commandsAsSkills && agentConfig.commandsSubdir) {
             removePath(commandsTarget);
         }
         const r = commandsWriter.write({ version, versionHome, selection: commandsToSync, cwd });
@@ -1680,9 +1736,22 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // ~/.agents/skills/ (Gemini) are not registered; we clear the version-home
     // skills dir for them so a stale per-version copy never shadows central.
     const skillsWriter = getWriter('skills', agent);
-    const skillsToSync = selection
+    let skillsToSync = selection
         ? resolveSelection(selection.skills, available.skills)
         : available.skills;
+    if (commandsAsSkills && commandsToSync.length > 0 && skillsToSync.length > 0) {
+        const commandNames = new Set(commandsToSync);
+        const skillRoots = [
+            path.join(getUserAgentsDir(), 'skills'),
+            getSkillsDir(),
+            ...getEnabledExtraRepos().map((e) => path.join(e.dir, 'skills')),
+        ];
+        skillsToSync = skillsToSync.filter((skill) => {
+            if (!commandNames.has(skill))
+                return true;
+            return readSkillSourceCommandMarker(skill, skillRoots) !== skill;
+        });
+    }
     if (agentConfig.nativeAgentsSkillsDir) {
         removePath(path.join(agentDir, 'skills'));
     }
@@ -1745,7 +1814,7 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     // CAPABLE_AGENTS list and silently skipped it). Project rules are NOT
     // synced into the version home — they are composed into the workspace at
     // agents-run time (see compileRulesForProject).
-    const skipMemory = selection && (selection.memory === undefined || (Array.isArray(selection.memory) && selection.memory.length === 0));
+    const skipMemory = selection && Array.isArray(selection.memory) && selection.memory.length === 0;
     const rulesWriter = getWriter('rules', agent);
     if (!skipMemory && rulesWriter) {
         try {

package/dist/lib/wallet/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Wallet: device-local credit-card vault.
+ *
+ * Two-tier storage so listing the wallet doesn't pop Touch ID, but reading
+ * a card always does:
+ *
+ *   Card metadata (id, nickname, brand, last4, expiry, created_at, kind)
+ *     -> ~/.agents/wallet/cards.json, mode 0600
+ *     -> Display-only data, equivalent of Apple Wallet's "card art" tier.
+ *
+ *   Card secret (PAN, CVC, cardholder)
+ *     -> Keychain item `agents-cli.secrets.wallet.<id>` (JSON-encoded)
+ *     -> Routed through the signed helper, so the OS gates decryption with
+ *        Touch ID + biometryCurrentSet. Re-enrolling Touch ID invalidates
+ *        the item, matching Apple Pay's AR-value rotation behavior.
+ *
+ * Not Apple Pay: we store a real PAN, not a network DPAN, and we do not
+ * generate per-transaction cryptograms. Callers must surface this clearly.
+ */
+/** Test seam: override the index path. Returns the previous override (or null). */
+export declare function _setIndexPathForTest(p: string | null): string | null;
+export type CardBrand = 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb' | 'unionpay' | 'unknown';
+/** Storage kind discriminator. Reserved for future kind: 'stripe_token'. */
+export type CardKind = 'pan_encrypted';
+/** Non-sensitive card metadata. Safe to display without biometric auth. */
+export interface CardMetadata {
+    id: string;
+    nickname: string;
+    brand: CardBrand;
+    last4: string;
+    exp_month: string;
+    exp_year: string;
+    created_at: string;
+    kind: CardKind;
+}
+/** Sensitive card fields. Keychain-stored, Touch ID required to read. */
+export interface CardSecret {
+    pan: string;
+    cvc: string;
+    cardholder: string;
+}
+/** Card metadata plus its secret payload. Returned by show() only. */
+export interface CardFull extends CardMetadata, CardSecret {
+}
+/** Input shape for add(). */
+export interface AddCardInput {
+    nickname: string;
+    pan: string;
+    cvc: string;
+    cardholder: string;
+    exp_month: string;
+    exp_year: string;
+}
+/** Compute the Luhn checksum and verify a candidate PAN. */
+export declare function isValidLuhn(pan: string): boolean;
+/** Detect card brand from the BIN (first 6 digits). */
+export declare function detectBrand(pan: string): CardBrand;
+/** Atomically read the index file. Returns [] when missing. */
+export declare function readIndex(): CardMetadata[];
+/** List all stored cards. Does NOT trigger biometric auth. */
+export declare function listCards(): CardMetadata[];
+/** Look up a card by id (or by case-insensitive nickname). Returns undefined when missing. */
+export declare function findCard(idOrNickname: string): CardMetadata | undefined;
+/**
+ * Add a new card. Validates Luhn + expiry. Returns the metadata for the
+ * stored card. The PAN/CVC/cardholder are written to Keychain in a single
+ * JSON blob; only metadata is mirrored to the index file.
+ */
+export declare function addCard(input: AddCardInput): CardMetadata;
+/**
+ * Reveal a card by id. **Triggers Touch ID on macOS.** Throws if the card
+ * isn't in the index or if the keychain entry is missing/cancelled.
+ */
+export declare function showCard(idOrNickname: string): CardFull;
+/** Delete a card from both the index and Keychain. Returns the removed metadata or undefined. */
+export declare function removeCard(idOrNickname: string): CardMetadata | undefined;
+/** Rename a card. Throws if the new nickname collides with an existing card. */
+export declare function renameCard(idOrNickname: string, newNickname: string): CardMetadata;

package/dist/lib/wallet/index.js

@@ -0,0 +1,253 @@
+/**
+ * Wallet: device-local credit-card vault.
+ *
+ * Two-tier storage so listing the wallet doesn't pop Touch ID, but reading
+ * a card always does:
+ *
+ *   Card metadata (id, nickname, brand, last4, expiry, created_at, kind)
+ *     -> ~/.agents/wallet/cards.json, mode 0600
+ *     -> Display-only data, equivalent of Apple Wallet's "card art" tier.
+ *
+ *   Card secret (PAN, CVC, cardholder)
+ *     -> Keychain item `agents-cli.secrets.wallet.<id>` (JSON-encoded)
+ *     -> Routed through the signed helper, so the OS gates decryption with
+ *        Touch ID + biometryCurrentSet. Re-enrolling Touch ID invalidates
+ *        the item, matching Apple Pay's AR-value rotation behavior.
+ *
+ * Not Apple Pay: we store a real PAN, not a network DPAN, and we do not
+ * generate per-transaction cryptograms. Callers must surface this clearly.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { deleteKeychainToken, getKeychainToken, secretsKeychainItem, setKeychainToken, } from '../secrets/index.js';
+const WALLET_BUNDLE = 'wallet';
+const DEFAULT_INDEX_DIR = path.join(os.homedir(), '.agents', 'wallet');
+const DEFAULT_INDEX_PATH = path.join(DEFAULT_INDEX_DIR, 'cards.json');
+let indexPathOverride = null;
+function indexPath() {
+    return indexPathOverride ?? DEFAULT_INDEX_PATH;
+}
+function indexDir() {
+    return path.dirname(indexPath());
+}
+/** Test seam: override the index path. Returns the previous override (or null). */
+export function _setIndexPathForTest(p) {
+    const prev = indexPathOverride;
+    indexPathOverride = p;
+    return prev;
+}
+/** Compute the Luhn checksum and verify a candidate PAN. */
+export function isValidLuhn(pan) {
+    const digits = pan.replace(/\D/g, '');
+    if (digits.length < 12 || digits.length > 19)
+        return false;
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let n = digits.charCodeAt(i) - 48;
+        if (alt) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+/** Detect card brand from the BIN (first 6 digits). */
+export function detectBrand(pan) {
+    const d = pan.replace(/\D/g, '');
+    if (/^4/.test(d))
+        return 'visa';
+    if (/^(5[1-5]|2[2-7])/.test(d))
+        return 'mastercard';
+    if (/^3[47]/.test(d))
+        return 'amex';
+    if (/^6(011|5|4[4-9])/.test(d))
+        return 'discover';
+    if (/^3(0[0-5]|[689])/.test(d))
+        return 'diners';
+    if (/^35(2[89]|[3-8])/.test(d))
+        return 'jcb';
+    if (/^(62|81)/.test(d))
+        return 'unionpay';
+    return 'unknown';
+}
+function normalizeMonth(mm) {
+    const n = Number(mm);
+    if (!Number.isInteger(n) || n < 1 || n > 12) {
+        throw new Error(`Invalid expiration month: ${mm}`);
+    }
+    return n.toString().padStart(2, '0');
+}
+function normalizeYear(yy) {
+    const d = yy.replace(/\D/g, '');
+    if (d.length === 2)
+        return '20' + d;
+    if (d.length === 4) {
+        const n = Number(d);
+        if (n < 2000 || n > 2100)
+            throw new Error(`Invalid expiration year: ${yy}`);
+        return d;
+    }
+    throw new Error(`Invalid expiration year: ${yy}`);
+}
+function ensureIndexDir() {
+    fs.mkdirSync(indexDir(), { recursive: true, mode: 0o700 });
+}
+/** Atomically read the index file. Returns [] when missing. */
+export function readIndex() {
+    const p = indexPath();
+    if (!fs.existsSync(p))
+        return [];
+    const raw = fs.readFileSync(p, 'utf-8');
+    if (!raw.trim())
+        return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+        throw new Error(`Wallet index at ${p} is not an array.`);
+    }
+    return parsed;
+}
+/** Atomically write the index file via tmp + rename. */
+function writeIndex(cards) {
+    ensureIndexDir();
+    const p = indexPath();
+    const tmp = p + '.tmp.' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(cards, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, indexPath());
+}
+function walletKeychainItem(id) {
+    return secretsKeychainItem(WALLET_BUNDLE, id);
+}
+function generateId() {
+    // 12 hex chars (6 bytes). Unique enough for a per-user wallet; short
+    // enough to type if needed.
+    return crypto.randomBytes(6).toString('hex');
+}
+/** List all stored cards. Does NOT trigger biometric auth. */
+export function listCards() {
+    return readIndex();
+}
+/** Look up a card by id (or by case-insensitive nickname). Returns undefined when missing. */
+export function findCard(idOrNickname) {
+    const cards = readIndex();
+    const exact = cards.find((c) => c.id === idOrNickname);
+    if (exact)
+        return exact;
+    const lc = idOrNickname.toLowerCase();
+    return cards.find((c) => c.nickname.toLowerCase() === lc);
+}
+/**
+ * Add a new card. Validates Luhn + expiry. Returns the metadata for the
+ * stored card. The PAN/CVC/cardholder are written to Keychain in a single
+ * JSON blob; only metadata is mirrored to the index file.
+ */
+export function addCard(input) {
+    const pan = input.pan.replace(/\s+/g, '');
+    if (!/^\d+$/.test(pan))
+        throw new Error('PAN must contain only digits.');
+    if (!isValidLuhn(pan))
+        throw new Error('PAN failed Luhn checksum.');
+    const cvc = input.cvc.replace(/\s+/g, '');
+    if (!/^\d{3,4}$/.test(cvc))
+        throw new Error('CVC must be 3 or 4 digits.');
+    const nickname = input.nickname.trim();
+    if (!nickname)
+        throw new Error('Nickname is required.');
+    const cardholder = input.cardholder.trim();
+    if (!cardholder)
+        throw new Error('Cardholder name is required.');
+    if (/[\r\n]/.test(cardholder))
+        throw new Error('Cardholder name contains newlines.');
+    const exp_month = normalizeMonth(input.exp_month);
+    const exp_year = normalizeYear(input.exp_year);
+    const last4 = pan.slice(-4);
+    const brand = detectBrand(pan);
+    const cards = readIndex();
+    if (cards.some((c) => c.nickname.toLowerCase() === nickname.toLowerCase())) {
+        throw new Error(`A card named '${nickname}' already exists. Pick a different nickname.`);
+    }
+    const id = generateId();
+    const meta = {
+        id,
+        nickname,
+        brand,
+        last4,
+        exp_month,
+        exp_year,
+        created_at: new Date().toISOString(),
+        kind: 'pan_encrypted',
+    };
+    const secret = { pan, cvc, cardholder };
+    // Keychain item first; if it succeeds, mirror to index. If the index
+    // write fails afterward, attempt to roll back the keychain insertion
+    // so callers don't see ghost secrets.
+    setKeychainToken(walletKeychainItem(id), JSON.stringify(secret));
+    try {
+        writeIndex([...cards, meta]);
+    }
+    catch (err) {
+        try {
+            deleteKeychainToken(walletKeychainItem(id));
+        }
+        catch { /* best-effort rollback */ }
+        throw err;
+    }
+    return meta;
+}
+/**
+ * Reveal a card by id. **Triggers Touch ID on macOS.** Throws if the card
+ * isn't in the index or if the keychain entry is missing/cancelled.
+ */
+export function showCard(idOrNickname) {
+    const meta = findCard(idOrNickname);
+    if (!meta)
+        throw new Error(`No card found matching '${idOrNickname}'.`);
+    const raw = getKeychainToken(walletKeychainItem(meta.id));
+    let secret;
+    try {
+        secret = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Card secret for '${meta.nickname}' is corrupted (not valid JSON).`);
+    }
+    if (!secret.pan || !secret.cvc || !secret.cardholder) {
+        throw new Error(`Card secret for '${meta.nickname}' is missing required fields.`);
+    }
+    return { ...meta, ...secret };
+}
+/** Delete a card from both the index and Keychain. Returns the removed metadata or undefined. */
+export function removeCard(idOrNickname) {
+    const cards = readIndex();
+    const meta = findCard(idOrNickname);
+    if (!meta)
+        return undefined;
+    const remaining = cards.filter((c) => c.id !== meta.id);
+    writeIndex(remaining);
+    try {
+        deleteKeychainToken(walletKeychainItem(meta.id));
+    }
+    catch { /* keychain may already be gone */ }
+    return meta;
+}
+/** Rename a card. Throws if the new nickname collides with an existing card. */
+export function renameCard(idOrNickname, newNickname) {
+    const nickname = newNickname.trim();
+    if (!nickname)
+        throw new Error('Nickname is required.');
+    const cards = readIndex();
+    const meta = findCard(idOrNickname);
+    if (!meta)
+        throw new Error(`No card found matching '${idOrNickname}'.`);
+    if (cards.some((c) => c.id !== meta.id && c.nickname.toLowerCase() === nickname.toLowerCase())) {
+        throw new Error(`A card named '${nickname}' already exists.`);
+    }
+    const updated = { ...meta, nickname };
+    const next = cards.map((c) => (c.id === meta.id ? updated : c));
+    writeIndex(next);
+    return updated;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.11",
+  "version": "1.20.13",
   "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",
@@ -97,9 +97,9 @@
   "devDependencies": {
     "@types/diff": "8.0.0",
     "@types/marked-terminal": "6.1.1",
-    "@types/node": "25.9.2",
+    "@types/node": "25.9.3",
     "tsx": "4.22.4",
     "typescript": "6.0.3",
-    "vitest": "4.1.8"
+    "vitest": "4.1.9"
   }
 }

package/scripts/postinstall.js

@@ -154,17 +154,45 @@ function isAlreadyConfigured(rcFile) {
 }
 
 async function main() {
-  // Windows has no shell rc files to edit. Write the `.cmd` shorthands here; the
-  // shims dir gets registered on the User PATH by `agents setup` (via the native
-  // registry API), so we point the user there instead of mutating PATH from an
-  // npm lifecycle script. The primary `agents` command is already on PATH via
-  // npm's global bin and works immediately.
+  // Windows has no shell rc files to edit. Write the `.cmd` shorthands here, then
+  // make sure npm's global-bin dir is on the User PATH so the `agents` command
+  // itself resolves: Node's installer normally adds it, but winget / portable /
+  // nvm-windows setups often don't — and then `npm i -g` succeeds yet `agents`
+  // is "not recognized". The shims dir (claude/codex/...) is still left to
+  // `agents setup`, which the user can now run because `agents` is discoverable.
   if (process.platform === 'win32') {
     console.log(`\nagents-cli installed.`);
     const written = writeAliasShims();
     console.log(`  Installed shorthands: ${written.join(', ')}`);
-    console.log(`\nNext: run  agents setup  — it finishes setup and adds the shims dir to your PATH`);
-    console.log(`(so the bare shorthands ${ALIASES.join(', ')} and versioned aliases work in a new terminal).`);
+
+    // Best-effort: import the platform leaf module from the just-installed dist.
+    // If it's missing or PowerShell is unavailable we degrade to plain guidance.
+    try {
+      const { prependToWindowsUserPath, getEffectiveExecutionPolicy, blocksLocalScripts, npmGlobalBinFromEntry } =
+        await import('../dist/lib/platform/winpath.js');
+
+      const npmBinDir = npmGlobalBinFromEntry(AGENTS_BIN);
+      const pathResult = prependToWindowsUserPath(npmBinDir);
+      if (pathResult.success && !pathResult.alreadyPresent) {
+        console.log(`  Added npm's global bin to your user PATH so 'agents' resolves:\n    ${npmBinDir}`);
+      } else if (!pathResult.success) {
+        console.log(`  Could not update PATH automatically. Add this to your user PATH manually:\n    ${npmBinDir}`);
+      }
+
+      // .ps1 launchers (npm.ps1, agents.ps1) are blocked under Restricted/AllSigned;
+      // we can't safely weaken a security setting from an installer, so guide instead.
+      const policy = getEffectiveExecutionPolicy();
+      if (blocksLocalScripts(policy)) {
+        console.log(`\n  PowerShell execution policy is '${policy}', which blocks the 'agents' launcher (a .ps1).`);
+        console.log(`  Allow local scripts for your user:`);
+        console.log(`    Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`);
+      }
+    } catch {
+      /* dist or PowerShell unavailable — skip; `agents setup` still wires shims */
+    }
+
+    console.log(`\nNext: open a new terminal, then run  agents setup`);
+    console.log(`(adds the shims dir so bare ${ALIASES.join(', ')} and versioned aliases work).`);
   }
   // Opt-in: AGENTS_INIT_SHELL=1 npm install -g @phnx-labs/agents-cli
   else if (process.env.AGENTS_INIT_SHELL === '1') {