@phnx-labs/agents-cli 1.20.7 → 1.20.9

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+**Single-typo agent names auto-correct everywhere, not just `agents run`**
+
+- `agents view cladue` used to print `Unknown agent 'cladue'` even though `agents run cladue` auto-corrected. `resolveAgentName` — the canonical resolver behind `view`, `usage`, `inspect`, `doctor`, `sync`, `models`, `skills`, `hooks`, `import`, `sessions --agent`, and every `agent@version` spec (`agents add claud@latest`, `agents use codx@2.1.170`) — now falls back to Damerau-Levenshtein distance-1 matching against canonical ids and multi-letter aliases: `cladue` -> `claude` (transposition), `kim` -> `kimi`, `codx` -> `codex`, `gemni` -> `gemini`.
+- Corrections apply only when unambiguous: every distance-1 candidate must agree on one agent. `kiri` (one edit from both `kiro` and `kimi`) and inputs under 3 characters still error. `agents run` keeps its existing exact -> profile -> workflow -> fuzzy precedence, so a profile named `claud` still beats the typo correction.
+- Fixes `kimi` being listed as a valid agent but missing from the alias map — `agents view kimi` previously errored. Added `kimi` / `kimi-code` entries.
+
 ## 1.20.7
 
 **`agents inspect` — DotAgents repo targets (#256)**

package/README.md

@@ -122,7 +122,7 @@ agents run codex "Fix the issues Claude found"
 agents run gemini "Write tests for the fixed code"
 ```
 
-Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced.
+Each resolves to the project-pinned version with skills, MCP servers, and permissions already synced. Single-typo names auto-correct across every command — `agents view cladue` resolves to `claude`, `agents add codx@latest` to `codex`.
 
 ### Rate-limited? Keep working.
 

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/daemon.js

@@ -5,7 +5,6 @@
  * aliases for `agents routines` scheduler lifecycle commands. Scheduled
  * for removal in v2.0.
  */
-import { spawn } from 'child_process';
 import chalk from 'chalk';
 import * as path from 'path';
 import { startDaemon, stopDaemon, isDaemonRunning, readDaemonPid, readDaemonLog, runDaemon, } from '../lib/daemon.js';
@@ -92,12 +91,13 @@ you never need to start it manually.
         warnDeprecated('logs', 'agents routines scheduler-logs');
         if (options.follow) {
             const { getDaemonDir } = await import('../lib/state.js');
+            const { followFile } = await import('../lib/log-follow.js');
             const logPath = path.join(getDaemonDir(), 'logs.jsonl');
-            const child = spawn('tail', ['-f', logPath], { stdio: ['ignore', 'pipe', 'pipe'] });
-            child.stdout.pipe(process.stdout);
-            child.stderr.pipe(process.stderr);
-            child.on('exit', () => process.exit(0));
-            process.on('SIGINT', () => { child.kill(); process.exit(0); });
+            const recent = readDaemonLog(parseInt(options.lines, 10));
+            if (recent)
+                console.log(recent);
+            const stop = followFile(logPath, (text) => process.stdout.write(text), { fromEnd: true });
+            process.on('SIGINT', () => { stop(); process.exit(0); });
             return;
         }
         const lines = parseInt(options.lines, 10);

package/dist/commands/import.js

@@ -27,20 +27,17 @@ import * as os from 'os';
 import * as path from 'path';
 import { confirm } from '@inquirer/prompts';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
-import { AGENTS, getCliPath, getCliVersion, agentLabel } from '../lib/agents.js';
+import { AGENTS, getCliPath, getCliVersion, agentLabel, resolveAgentName } from '../lib/agents.js';
 import { getVersionDir } from '../lib/versions.js';
 import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
-function isValidAgentId(value) {
-    return ALL_AGENT_IDS.includes(value);
-}
 async function runImport(agentArg, opts) {
-    if (!isValidAgentId(agentArg)) {
+    const agentId = resolveAgentName(agentArg);
+    if (!agentId) {
         console.error(chalk.red(`Unknown agent: ${agentArg}`));
         console.error(chalk.gray(`Known agents: ${ALL_AGENT_IDS.join(', ')}`));
         process.exit(1);
     }
-    const agentId = agentArg;
     const agent = AGENTS[agentId];
     // installScript-based agents (Grok, Antigravity, Cursor, Kiro, Goose, Roo)
     // don't have an npm package; their binary lives wherever the curl/brew

package/dist/commands/inspect.js

@@ -17,7 +17,7 @@ import * as os from 'os';
 import * as path from 'path';
 import chalk from 'chalk';
 import * as yaml from 'yaml';
-import { AGENTS, getCliState } from '../lib/agents.js';
+import { AGENTS, getCliState, resolveAgentName } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
@@ -63,12 +63,16 @@ export async function inspectAction(target, options) {
             await inspectRepo(repo, options);
             return;
         }
-        const extras = getEnabledExtraRepos();
-        console.error(chalk.red(`Unknown target: ${target}`));
-        console.error(chalk.gray(`Agents: ${Object.keys(AGENTS).join(', ')}`));
-        const aliases = extras.length > 0 ? `, ${extras.map(e => e.alias).join(', ')}` : '';
-        console.error(chalk.gray(`Repos:  user, system, project${aliases} — or a path to a repo with a .agents/ dir`));
-        process.exit(1);
+        // Repo targets take precedence over typo correction; only fall through to
+        // parseTarget when the key resolves to an agent (alias or single-edit fix).
+        if (!resolveAgentName(agentKey)) {
+            const extras = getEnabledExtraRepos();
+            console.error(chalk.red(`Unknown target: ${target}`));
+            console.error(chalk.gray(`Agents: ${Object.keys(AGENTS).join(', ')}`));
+            const aliases = extras.length > 0 ? `, ${extras.map(e => e.alias).join(', ')}` : '';
+            console.error(chalk.gray(`Repos:  user, system, project${aliases} — or a path to a repo with a .agents/ dir`));
+            process.exit(1);
+        }
     }
     const { agent, version } = parseTarget(target);
     const versionHome = getVersionHomePath(agent, version);
@@ -93,7 +97,12 @@ export async function inspectAction(target, options) {
 }
 function parseTarget(target) {
     const [rawAgent, rawVersion] = target.split('@');
-    const agent = (rawAgent || '').toLowerCase();
+    const agent = resolveAgentName(rawAgent || '');
+    if (!agent) {
+        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
+        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
+        process.exit(1);
+    }
     let version = rawVersion;
     if (!version || version === 'default') {
         const meta = readMeta();

package/dist/commands/models.js

@@ -7,6 +7,7 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
+import { homeDir } from '../lib/platform/index.js';
 import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
@@ -166,5 +167,5 @@ function printCatalog(agent, version, isDefault, options) {
 }
 /** Abbreviate a path by replacing the home directory with ~. */
 function shortPath(p) {
-    return p.replace(process.env.HOME || '~', '~');
+    return p.replace(homeDir(), '~');
 }

package/dist/commands/plugins.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
+import { homeDir } from '../lib/platform/index.js';
 import { input } from '@inquirer/prompts';
 import { agentLabel } from '../lib/agents.js';
 import { capableAgents, isCapable } from '../lib/capabilities.js';
@@ -21,7 +22,7 @@ import { safeJoin } from '../lib/paths.js';
 import { discoverMarketplaces } from '../lib/plugin-marketplace.js';
 /** Replace the home directory prefix with ~ for display. */
 function formatPath(p) {
-    const home = process.env.HOME || '';
+    const home = homeDir();
     if (home && p.startsWith(home)) {
         return '~' + p.slice(home.length);
     }
@@ -355,7 +356,7 @@ Examples:
             });
         }
         const name = nameArg;
-        const pluginsDir = path.join(process.env.HOME || '', '.agents', 'plugins');
+        const pluginsDir = path.join(homeDir(), '.agents', 'plugins');
         const pluginRoot = safeJoin(pluginsDir, name);
         // Use discovered plugin when present; fall back to name+root if source is already gone
         const plugin = getPlugin(name);

package/dist/commands/refresh-rules.js

@@ -6,7 +6,7 @@
  * Recompiles only when source files have changed.
  */
 import chalk from 'chalk';
-import { AGENTS } from '../lib/agents.js';
+import { AGENTS, resolveAgentName } from '../lib/agents.js';
 import { isVersionInstalled } from '../lib/versions.js';
 import { ensureRulesFresh, supportsRulesImports } from '../lib/rules/compile.js';
 /**
@@ -23,12 +23,12 @@ export function registerRefreshRulesCommand(program) {
         .requiredOption('--agent-version <version>', 'Installed version whose rules file should be refreshed')
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
         .action((opts) => {
-        const agentId = opts.agent;
+        const agentId = resolveAgentName(opts.agent);
         const version = opts.agentVersion;
         const quiet = !!opts.quiet;
-        if (!AGENTS[agentId]) {
+        if (!agentId) {
             if (!quiet)
-                console.error(chalk.red(`Unknown agent '${agentId}'`));
+                console.error(chalk.red(`Unknown agent '${opts.agent}'`));
             process.exitCode = 1;
             return;
         }

package/dist/commands/routines.js

@@ -14,6 +14,7 @@ import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemo
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, } from '../lib/routines.js';
 import { getRoutinesDir } from '../lib/state.js';
+import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
 import { executeJob, executeJobDetached } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
@@ -385,7 +386,7 @@ export function registerRoutinesCommands(program) {
             console.log(chalk.gray(`Created new job file: ${newPath}`));
         }
         const targetPath = jobPath || path.join(getRoutinesDir(), `${name}.yml`);
-        const editor = process.env.EDITOR || process.env.VISUAL || 'vi';
+        const editor = process.env.EDITOR || process.env.VISUAL || (IS_WINDOWS ? 'notepad' : 'vi');
         const editorParts = editor.split(/\s+/).filter(Boolean);
         const editorBin = editorParts[0];
         const editorArgs = [...editorParts.slice(1), targetPath];
@@ -691,14 +692,14 @@ export function registerRoutinesCommands(program) {
         .option('-f, --follow', 'Stream log output in real time (like tail -f)')
         .action(async (options) => {
         if (options.follow) {
-            const { spawn } = await import('child_process');
             const { getDaemonDir } = await import('../lib/state.js');
+            const { followFile } = await import('../lib/log-follow.js');
             const logPath = path.join(getDaemonDir(), 'logs.jsonl');
-            const child = spawn('tail', ['-f', logPath]);
-            child.stdout?.pipe(process.stdout);
-            child.stderr?.pipe(process.stderr);
-            child.on('exit', () => process.exit(0));
-            process.on('SIGINT', () => { child.kill(); process.exit(0); });
+            const recent = readDaemonLog(parseInt(options.lines, 10));
+            if (recent)
+                console.log(recent);
+            const stop = followFile(logPath, (text) => process.stdout.write(text), { fromEnd: true });
+            process.on('SIGINT', () => { stop(); process.exit(0); });
             return;
         }
         const lines = parseInt(options.lines, 10);

package/dist/commands/sessions.js

@@ -23,6 +23,7 @@ import { parseSession } from '../lib/session/parse.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { colorAgent, resolveAgentName } from '../lib/agents.js';
+import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker } from './sessions-picker.js';
@@ -822,8 +823,22 @@ function parseAgentFilter(agentName) {
     if (!agentName)
         return {};
     const [name, version] = agentName.split('@', 2);
-    const agent = name;
-    if (!SESSION_AGENTS.includes(agent)) {
+    let agent = SESSION_AGENTS.includes(name)
+        ? name
+        : null;
+    if (!agent) {
+        // Aliases and single-typo corrections (cladue -> claude). SESSION_AGENTS
+        // includes ids (rush, hermes) that resolveAgentName doesn't know, so fall
+        // back to fuzzy-matching the session list directly.
+        const resolved = resolveAgentName(name);
+        if (resolved && SESSION_AGENTS.includes(resolved)) {
+            agent = resolved;
+        }
+        else {
+            agent = fuzzyMatch(name, SESSION_AGENTS, FUZZY_PRESETS.agents);
+        }
+    }
+    if (!agent) {
         console.error(chalk.red(`Unknown agent: ${name}. Use: ${SESSION_AGENTS.join(', ')}`));
         process.exit(1);
     }

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/subagents.js

@@ -10,6 +10,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { agentLabel } from '../lib/agents.js';
+import { homeDir } from '../lib/platform/index.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverSubagentsFromRepo, installSubagentCentrally, listInstalledSubagents, getInstalledSubagent, listSubagentsForAgent, iterSubagentsCapableVersions, removeSubagentFromVersion, } from '../lib/subagents.js';
@@ -19,7 +20,7 @@ import { requireDestructiveArg, promptRemovalTargets, parseCommaSeparatedList, r
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Replace the home directory prefix with ~ for display. */
 function formatPath(p) {
-    const home = process.env.HOME || '';
+    const home = homeDir();
     if (home && p.startsWith(home)) {
         return '~' + p.slice(home.length);
     }

package/dist/commands/usage.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, } from '../lib/agents.js';
+import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
 import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
 /** Agents whose CLI surfaces usage data we can read today. */
@@ -15,9 +15,17 @@ Examples:
   agents usage codex        Show usage for Codex only
 `)
         .action(async (agentFilter) => {
-        const filter = agentFilter;
+        let filter;
+        if (agentFilter) {
+            const resolved = resolveAgentName(agentFilter);
+            if (!resolved) {
+                console.error(chalk.red(formatAgentError(agentFilter)));
+                process.exit(1);
+            }
+            filter = resolved;
+        }
         const targets = filter
-            ? [filter].filter((id) => ALL_AGENT_IDS.includes(id))
+            ? [filter]
             : ALL_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
         if (targets.length === 0) {
             console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));

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:'));