@phnx-labs/agents-cli 1.20.7 → 1.20.8

package/dist/commands/computer-actions.d.ts

@@ -31,6 +31,25 @@ export declare function buildElementOrCoords(opts: {
     ok: false;
     error: string;
 };
+export declare function buildRaiseParams(opts: {
+    windowId?: number;
+    title?: string;
+}): Record<string, unknown>;
+export declare function buildWaitParams(opts: {
+    duration?: number;
+    id?: string;
+    until?: string;
+    role?: string;
+    label?: string;
+    identifier?: string;
+    timeout?: number;
+}): {
+    ok: true;
+    params: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
 export declare function withClient<T>(fn: (client: ComputerClient) => Promise<T>): Promise<T>;
 export declare function unwrap(r: RPCResponse): Record<string, unknown>;
 export declare function registerActionCommands(program: Command): void;

package/dist/commands/computer-actions.js

@@ -60,6 +60,51 @@ export function buildElementOrCoords(opts) {
         return { ok: true, params: { x: opts.x, y: opts.y } };
     return { ok: false, error: 'pass --id <@eN> (from `describe`) or --x <n> --y <n>' };
 }
+// Build the focus_window params for `raise`. Pure + tested: window_id and
+// title are both optional refinements over the app-level activate.
+export function buildRaiseParams(opts) {
+    const params = {};
+    if (opts.windowId != null)
+        params.window_id = opts.windowId;
+    if (opts.title)
+        params.title = opts.title;
+    return params;
+}
+// Build the wait RPC params. Pure + tested. Three modes, mirroring the
+// daemon's Wait.run: --duration (unconditional sleep), --id + --until
+// (cached-element poll), or --role/--label/--identifier (live locator poll).
+export function buildWaitParams(opts) {
+    if (opts.duration != null) {
+        return { ok: true, params: { duration_ms: opts.duration } };
+    }
+    const params = {};
+    if (opts.until)
+        params.until = opts.until;
+    if (opts.timeout != null)
+        params.timeout_ms = opts.timeout;
+    if (opts.id) {
+        return { ok: true, params: { ...params, element_id: opts.id } };
+    }
+    const locator = {};
+    if (opts.role)
+        locator.role = opts.role;
+    if (opts.label)
+        locator.label = opts.label;
+    if (opts.identifier)
+        locator.identifier = opts.identifier;
+    if (Object.keys(locator).length === 0) {
+        return { ok: false, error: 'pass --duration <ms>, --id <@eN>, or a locator (--role/--label/--identifier)' };
+    }
+    return { ok: true, params: { ...params, locator } };
+}
+// postToPid keyboard delivery is dropped by key-window-gated apps (Parallels
+// VMs and friends) — when the daemon reports the target was not frontmost,
+// the keystrokes may have landed nowhere. Surface that loudly on stderr.
+function warnIfNotFrontmost(res) {
+    if (res.frontmost === false) {
+        console.error('warning: target was not the frontmost app — keystrokes may have been dropped. Run `agents computer raise` first.');
+    }
+}
 function reportMissingHelper() {
     console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
     process.exit(1);
@@ -99,6 +144,12 @@ async function resolveTargetPid(client, opts) {
     }
     return picked.app.pid;
 }
+// --raise flag: app-level focus_window before the main action so coordinate
+// clicks and keystrokes land on a visible, key window.
+async function raiseIfRequested(client, pid, raise) {
+    if (raise)
+        unwrap(await client.call('focus_window', { pid }));
+}
 function emit(result, json, human) {
     if (json) {
         console.log(JSON.stringify(result, null, 2));
@@ -158,6 +209,7 @@ export function registerActionCommands(program) {
         .description('Click an element (--id) or screen coordinate (--x --y)')
         .option('--count <n>', 'Click count (2 = double-click)', (v) => parseInt(v, 10))
         .option('--background', 'Focus-safe postToPid delivery (plain AppKit only; skips HID tap)')
+        .option('--raise', 'Bring the target app to the front first')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts);
@@ -166,6 +218,7 @@ export function registerActionCommands(program) {
                 console.error(spec.error);
                 process.exit(1);
             }
+            await raiseIfRequested(client, pid, opts.raise);
             const params = { pid, ...spec.params };
             if (opts.count != null)
                 params.count = opts.count;
@@ -221,13 +274,19 @@ export function registerActionCommands(program) {
         .description('Type an arbitrary unicode string into the focused field (focus first via click/focus)')
         .requiredOption('--text <s>', 'Text to type')
         .option('--commit', 'Press Return after typing')
+        .option('--raise', 'Bring the target app to the front first')
+        .option('--require-frontmost', 'Fail (not warn) if the target is not the frontmost app')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts);
+            await raiseIfRequested(client, pid, opts.raise);
             const params = { pid, text: opts.text };
             if (opts.commit)
                 params.commit = true;
+            if (opts.requireFrontmost)
+                params.require_frontmost = true;
             const res = unwrap(await client.call('type_text', params));
+            warnIfNotFrontmost(res);
             emit(res, Boolean(opts.json), () => `typed ${res.chars ?? opts.text.length} char(s)`);
         });
     });
@@ -236,10 +295,17 @@ export function registerActionCommands(program) {
         .command('key')
         .description('Send a key chord, e.g. "cmd+shift+s", "enter", "esc"')
         .requiredOption('--keys <chord>', 'Key chord')
+        .option('--raise', 'Bring the target app to the front first')
+        .option('--require-frontmost', 'Fail (not warn) if the target is not the frontmost app')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts);
-            const res = unwrap(await client.call('key', { pid, keys: opts.keys }));
+            await raiseIfRequested(client, pid, opts.raise);
+            const params = { pid, keys: opts.keys };
+            if (opts.requireFrontmost)
+                params.require_frontmost = true;
+            const res = unwrap(await client.call('key', params));
+            warnIfNotFrontmost(res);
             emit(res, Boolean(opts.json), () => `sent ${opts.keys}`);
         });
     });
@@ -251,6 +317,7 @@ export function registerActionCommands(program) {
         .requiredOption('--to <x,y>', 'End coordinate "x,y"')
         .option('--button <left|right>', 'Mouse button', 'left')
         .option('--background', 'Focus-safe postToPid delivery (plain AppKit only)')
+        .option('--raise', 'Bring the target app to the front first')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         let from;
         let to;
@@ -264,6 +331,7 @@ export function registerActionCommands(program) {
         }
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts);
+            await raiseIfRequested(client, pid, opts.raise);
             const params = {
                 pid,
                 from: [from.x, from.y],
@@ -282,9 +350,11 @@ export function registerActionCommands(program) {
         .description('Scroll by a pixel delta at an element or coordinate')
         .option('--dy <n>', 'Vertical delta (negative = down)', (v) => parseInt(v, 10))
         .option('--dx <n>', 'Horizontal delta', (v) => parseInt(v, 10))
+        .option('--raise', 'Bring the target app to the front first')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
             const pid = await resolveTargetPid(client, opts);
+            await raiseIfRequested(client, pid, opts.raise);
             const params = { pid };
             if (opts.id)
                 params.element_id = opts.id;
@@ -325,4 +395,92 @@ export function registerActionCommands(program) {
             emit(res, Boolean(opts.json), () => `focused ${opts.id}`);
         });
     });
+    // raise — bring an app (or one of its windows) to the front. The window
+    // forms (--window-id/--title) also switch macOS Spaces, which is the only
+    // way to reach a fullscreen-Space window (VM, fullscreen editor) for
+    // capture and HID-tap input.
+    addTargetOpts(program
+        .command('raise')
+        .description('Bring an app (or a specific window) to the front — switches Spaces for fullscreen windows')
+        .option('--window-id <n>', 'Raise a specific window by id (from `screenshot --list`)', (v) => parseInt(v, 10))
+        .option('--title <s>', 'Raise the window whose title contains this string')
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const res = unwrap(await client.call('focus_window', { pid, ...buildRaiseParams(opts) }));
+            emit(res, Boolean(opts.json), () => {
+                const scope = res.raised_window ? `window ${res.title ?? res.window_id ?? ''}`.trim() : 'app';
+                return `raised ${scope} (${res.focus_elapsed_ms ?? 0}ms)`;
+            });
+        });
+    });
+    // wait — settle the UI before the next action
+    addTargetOpts(program
+        .command('wait')
+        .description('Wait for a duration (--duration) or for an element (--id / --role/--label) to satisfy --until')
+        .option('--duration <ms>', 'Unconditional sleep in ms (50-30000)', (v) => parseInt(v, 10))
+        .option('--id <@eN>', 'Element id from `describe` to poll')
+        .option('--until <cond>', 'Condition: exists | enabled | disappears (default: exists)')
+        .option('--role <s>', 'Locator: AX role (e.g. AXButton)')
+        .option('--label <s>', 'Locator: element label')
+        .option('--identifier <s>', 'Locator: AX identifier')
+        .option('--timeout <ms>', 'Poll timeout in ms (default 5000)', (v) => parseInt(v, 10))
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        const spec = buildWaitParams(opts);
+        if (!spec.ok) {
+            console.error(spec.error);
+            process.exit(1);
+        }
+        await withClient(async (client) => {
+            const params = { ...spec.params };
+            // duration-only waits don't need a target pid
+            if (params.duration_ms == null)
+                params.pid = await resolveTargetPid(client, opts);
+            const res = unwrap(await client.call('wait', params));
+            emit(res, Boolean(opts.json), () => res.satisfied ? `satisfied (${res.waited_ms}ms)` : `timed out (${res.waited_ms}ms)`);
+        });
+    });
+    // get-text — read text without OCR
+    addTargetOpts(program
+        .command('get-text')
+        .description('Extract visible text from the app (or a subtree via --id)')
+        .option('--id <@eN>', 'Element id from `describe` to scope the extraction')
+        .option('--max-chars <n>', 'Cap the extracted text length', (v) => parseInt(v, 10))
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const params = { pid };
+            if (opts.id)
+                params.element_id = opts.id;
+            if (opts.maxChars != null)
+                params.max_chars = opts.maxChars;
+            const res = unwrap(await client.call('get_text', params));
+            emit(res, Boolean(opts.json), () => String(res.text ?? ''));
+        });
+    });
+    // launch — start an app (no target resolution: it isn't running yet)
+    program
+        .command('launch')
+        .description('Launch an app by bundle id, path, or name')
+        .option('--bundle <id>', 'Bundle id (e.g. com.apple.TextEdit)')
+        .option('--path <p>', 'Path to the .app bundle')
+        .option('--name <s>', 'App name (resolved via /Applications and LaunchServices)')
+        .option('--json', 'Emit JSON')
+        .action(async (opts) => {
+        if (!opts.bundle && !opts.path && !opts.name) {
+            console.error('pass one of --bundle, --path, --name');
+            process.exit(1);
+        }
+        await withClient(async (client) => {
+            const params = {};
+            if (opts.bundle)
+                params.bundle_id = opts.bundle;
+            if (opts.path)
+                params.path = opts.path;
+            if (opts.name)
+                params.name = opts.name;
+            const res = unwrap(await client.call('launch_app', params));
+            emit(res, Boolean(opts.json), () => `launched ${res.name} (pid ${res.pid})`);
+        });
+    });
 }

package/dist/commands/computer.js

@@ -9,8 +9,8 @@ import { registerActionCommands, withClient, unwrap, pickTarget } from './comput
 const COMPUTER_HELP_GROUPS = [
     { title: 'Installation', names: ['setup'] },
     { title: 'Daemon lifecycle', names: ['start', 'stop', 'reload', 'status'] },
-    { title: 'Observe', names: ['apps', 'describe', 'screenshot'] },
-    { title: 'Interact', names: ['click', 'right-click', 'type', 'type-text', 'key', 'drag', 'scroll', 'ax-action', 'focus'] },
+    { title: 'Observe', names: ['apps', 'describe', 'screenshot', 'get-text'] },
+    { title: 'Interact', names: ['launch', 'raise', 'click', 'right-click', 'type', 'type-text', 'key', 'drag', 'scroll', 'ax-action', 'focus', 'wait'] },
 ];
 export function registerComputerCommand(program) {
     const computer = program

package/dist/commands/setup.js

@@ -145,8 +145,8 @@ export async function runSetup(program, options = {}) {
             if (!isShimsInPath()) {
                 const pathResult = addShimsToPath();
                 if (pathResult.success && !pathResult.alreadyPresent) {
-                    console.log(chalk.green(`\nAdded shims to ~/${pathResult.rcFile}`));
-                    console.log(chalk.gray('Restart your shell or run: source ~/' + pathResult.rcFile));
+                    console.log(chalk.green(`\nAdded shims to ${pathResult.location}`));
+                    console.log(chalk.gray(pathResult.reloadHint));
                 }
                 else if (!pathResult.success) {
                     console.log(chalk.yellow('\nTo enable version switching, add shims to PATH:'));

package/dist/commands/versions.js

@@ -402,8 +402,8 @@ export function registerVersionsCommands(program) {
                     if (!isShimsInPath()) {
                         const pathResult = addShimsToPath();
                         if (pathResult.success && !pathResult.alreadyPresent) {
-                            console.log(chalk.green(`  Added shims to ~/${pathResult.rcFile}`));
-                            console.log(chalk.gray('  Restart your shell or run: source ~/' + pathResult.rcFile));
+                            console.log(chalk.green(`  Added shims to ${pathResult.location}`));
+                            console.log(chalk.gray('  ' + pathResult.reloadHint));
                         }
                         else if (!pathResult.success) {
                             console.log(chalk.yellow('\nCould not auto-add shims to PATH:'));

package/dist/lib/computer-rpc.d.ts

@@ -21,6 +21,8 @@ export declare function writeComputerPeers(allowedExecPaths: string[]): void;
 export declare function resolveHelperExec(): string | null;
 export declare function resolveHelperApp(): string | null;
 export declare function openComputerClient(): ComputerClient;
+export declare const RPC_TIMEOUT_MS = 30000;
+export declare function resolveRpcTimeoutMs(env: string | undefined): number;
 export declare function describeTransport(): {
     kind: 'socket' | 'stdio' | 'none';
     path: string | null;

package/dist/lib/computer-rpc.js

@@ -200,6 +200,15 @@ export function openComputerClient() {
     }
     return new StdioClient(helperExec);
 }
+// Per-call RPC timeout. Without it a hung daemon (deadlocked connection
+// queue, stopped process) hangs the CLI forever — the waiter map never
+// settles. 30s clears every daemon-side ceiling (wait caps at 30s,
+// launch_app at 10s, screenshot at 5s). Overridable for slower flows.
+export const RPC_TIMEOUT_MS = 30_000;
+export function resolveRpcTimeoutMs(env) {
+    const n = Number(env);
+    return Number.isFinite(n) && n > 0 ? n : RPC_TIMEOUT_MS;
+}
 // Shared waiter map + line parser. Both transports plug their reader into
 // `handleChunk` and their writer into `send`.
 class BaseClient {
@@ -241,8 +250,19 @@ class BaseClient {
         }
         const id = this.nextId++;
         const payload = JSON.stringify({ id, method, params: params ?? {} }) + '\n';
+        const timeoutMs = resolveRpcTimeoutMs(process.env.COMPUTER_HELPER_RPC_TIMEOUT_MS);
         return new Promise((resolve) => {
-            this.waiters.set(id, resolve);
+            const timer = setTimeout(() => {
+                if (this.waiters.delete(id)) {
+                    resolve({ id, error: { code: 'rpc_timeout', message: `helper did not respond within ${timeoutMs}ms` } });
+                }
+            }, timeoutMs);
+            // Resolve as an error (never reject) so callers flow through unwrap()
+            // uniformly, matching failPending's contract.
+            this.waiters.set(id, (r) => {
+                clearTimeout(timer);
+                resolve(r);
+            });
             this.send(payload);
         });
     }

package/dist/lib/refresh.js

@@ -212,8 +212,8 @@ export async function refresh(options = {}) {
     if (!isShimsInPath()) {
         const pathResult = addShimsToPath();
         if (pathResult.success && !pathResult.alreadyPresent) {
-            console.log(chalk.green(`\nAdded shims to ~/${pathResult.rcFile}`));
-            console.log(chalk.gray('Restart your shell or run: source ~/' + pathResult.rcFile));
+            console.log(chalk.green(`\nAdded shims to ${pathResult.location}`));
+            console.log(chalk.gray(pathResult.reloadHint));
         }
         else if (!pathResult.success) {
             console.log(chalk.yellow('\nCould not auto-add shims to PATH:'));

package/dist/lib/shims.d.ts

@@ -248,20 +248,25 @@ export declare function isShimsInPath(): boolean;
  * Get shell configuration instructions for adding shims to PATH.
  */
 export declare function getPathSetupInstructions(): string;
+interface ShimPathResult {
+    success: boolean;
+    alreadyPresent?: boolean;
+    rcFile?: string;
+    /** Human label of where the entry landed, e.g. `~/.zshrc` or `your user PATH`. */
+    location?: string;
+    /** Per-platform "how to pick it up" hint, e.g. `source ~/.zshrc` / open a new terminal. */
+    reloadHint?: string;
+    error?: string;
+}
 /**
- * Add shims directory to shell PATH configuration.
- * Returns true if added, false if already present or failed.
+ * Add the shims directory to PATH: edits the shell rc file on POSIX, or registers
+ * it on the Windows User PATH (registry + WM_SETTINGCHANGE). Idempotent.
  */
 export declare function addShimsToPath(overrides?: {
     homeDir?: string;
     shell?: string;
     shimsDir?: string;
-}): {
-    success: boolean;
-    alreadyPresent?: boolean;
-    rcFile?: string;
-    error?: string;
-};
+}): ShimPathResult;
 export declare function listAgentsWithInstalledVersions(): AgentId[];
 /**
  * Resource diff between two versions. Each field lists resources present in

package/dist/lib/shims.js

@@ -11,6 +11,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { confirm, select } from '@inquirer/prompts';
 import { IS_WINDOWS } from './platform/index.js';
@@ -1520,18 +1521,15 @@ Then restart your shell or run:
   source ~/${rcFile}`;
 }
 /**
- * Add shims directory to shell PATH configuration.
- * Returns true if added, false if already present or failed.
+ * Add the shims directory to PATH: edits the shell rc file on POSIX, or registers
+ * it on the Windows User PATH (registry + WM_SETTINGCHANGE). Idempotent.
  */
 export function addShimsToPath(overrides) {
-    // Windows has no shell rc file to edit: the primary `agents` command is already
-    // on PATH via npm's global bin, and bare shorthands / versioned aliases are
-    // handled by the `.cmd` shims plus the PATH guidance printed at install time.
-    // Report "already present" so callers don't emit a misleading "added to
-    // ~/.bashrc / source ~/.bashrc" message. (The `shell` override is the test hook
-    // for exercising the POSIX path, so it bypasses this short-circuit.)
+    // Windows has no shell rc file to edit. Register the shims dir on the User PATH
+    // via the platform-native mechanism instead. (The `shell` override is the test
+    // hook for exercising the POSIX path, so it bypasses this branch.)
     if (IS_WINDOWS && !overrides?.shell) {
-        return { success: true, alreadyPresent: true };
+        return addShimsToWindowsUserPath(overrides?.shimsDir || getShimsDir());
     }
     const shimsDir = overrides?.shimsDir || getShimsDir();
     const { rcFile, rcPath, shell } = getShellRcFile(overrides);
@@ -1565,16 +1563,53 @@ export function addShimsToPath(overrides) {
         const separator = contentWithoutShimLines.length > 0 && !contentWithoutShimLines.endsWith('\n') ? '\n' : '';
         let newContent = contentWithoutShimLines + separator + exportBlock;
         newContent = newContent.replace(/\n{2,}$/g, '\n');
+        const location = `~/${rcFile}`;
+        const reloadHint = `Restart your shell or run: source ~/${rcFile}`;
         if (newContent === content) {
-            return { success: true, alreadyPresent: true, rcFile };
+            return { success: true, alreadyPresent: true, rcFile, location, reloadHint };
         }
         fs.writeFileSync(rcPath, newContent, 'utf-8');
-        return { success: true, rcFile };
+        return { success: true, rcFile, location, reloadHint };
     }
     catch (err) {
         return { success: false, error: `Could not write ${rcFile}: ${err.message}` };
     }
 }
+/**
+ * Register the shims dir on the Windows User PATH via the .NET environment API,
+ * which writes the registry AND broadcasts WM_SETTINGCHANGE — the correct analog
+ * of editing a shell rc file (no `setx` truncation, no manual step). Idempotent:
+ * a no-op when the dir is already present. The shims dir is passed via an env var
+ * so it is never interpolated into the PowerShell script text.
+ */
+function addShimsToWindowsUserPath(shimsDir) {
+    const script = [
+        '$d = $env:AGENTS_SHIMS_DIR',
+        "$u = [Environment]::GetEnvironmentVariable('Path','User')",
+        "if ($null -eq $u) { $u = '' }",
+        "$parts = @($u -split ';' | Where-Object { $_ -ne '' })",
+        "if ($parts -contains $d) { 'present' } else {",
+        "  [Environment]::SetEnvironmentVariable('Path', (($parts + $d) -join ';'), 'User')",
+        "  'added'",
+        '}',
+    ].join('\n');
+    try {
+        const out = execFileSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            encoding: 'utf-8',
+            env: { ...process.env, AGENTS_SHIMS_DIR: shimsDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+        return {
+            success: true,
+            alreadyPresent: out.includes('present'),
+            location: 'your user PATH',
+            reloadHint: 'Open a new terminal for the change to take effect.',
+        };
+    }
+    catch (err) {
+        return { success: false, error: `Could not update the Windows user PATH: ${err.message}` };
+    }
+}
 export function listAgentsWithInstalledVersions() {
     const versionsDir = getVersionsDir();
     if (!fs.existsSync(versionsDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.7",
+  "version": "1.20.8",
   "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",

package/scripts/postinstall.js

@@ -144,17 +144,17 @@ function isAlreadyConfigured(rcFile) {
 }
 
 async function main() {
-  // Windows has no shell rc files to edit. Write the `.cmd` shorthands and point
-  // the user at the PATH entry they can add (the primary `agents` command is
-  // already on PATH via npm's global bin, so this only affects bare shorthands
-  // and versioned aliases).
+  // 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.
   if (process.platform === 'win32') {
     console.log(`\nagents-cli installed.`);
     const written = writeAliasShims();
     console.log(`  Installed shorthands: ${written.join(', ')}`);
-    console.log(`\nTo use bare shorthands (${ALIASES.join(', ')}) and versioned aliases, add this to your PATH:`);
-    console.log(`  ${SHIMS_DIR}`);
-    console.log(`  PowerShell: setx PATH "$env:PATH;${SHIMS_DIR}"  (then open a new terminal)`);
+    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).`);
   }
   // Opt-in: AGENTS_INIT_SHELL=1 npm install -g @phnx-labs/agents-cli
   else if (process.env.AGENTS_INIT_SHELL === '1') {