@phnx-labs/agents-cli 1.20.6 → 1.20.8

package/dist/commands/computer.js

@@ -3,22 +3,24 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { registerCommandGroups } from '../lib/help.js';
-import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, describeTransport, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
+import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
+import { registerActionCommands, withClient, unwrap, pickTarget } from './computer-actions.js';
 // Help groups — mirror `agents browser` so the mental model carries over.
 const COMPUTER_HELP_GROUPS = [
-    { title: 'Installation', names: ['install-helper'] },
+    { title: 'Installation', names: ['setup'] },
     { title: 'Daemon lifecycle', names: ['start', 'stop', 'reload', 'status'] },
-    { title: 'Capture evidence', names: ['screenshot'] },
+    { 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
-        .command('computers')
+        .command('computer')
         .description('Drive macOS apps via Accessibility — list, screenshot, click, type (macOS only)')
         // The whole subsystem is macOS Accessibility / TCC. Fail fast with a clear
         // message on other platforms instead of a downstream ENOENT / launchctl error.
         .hook('preAction', () => {
         if (process.platform !== 'darwin') {
-            console.error('agents computers: macOS only — it drives apps via the macOS Accessibility API.');
+            console.error('agents computer: macOS only — it drives apps via the macOS Accessibility API.');
             process.exit(1);
         }
     });
@@ -26,18 +28,15 @@ export function registerComputerCommand(program) {
     registerCommandGroups(computer, COMPUTER_HELP_GROUPS);
 }
 export function registerComputerSubcommands(program) {
-    registerInstallHelperCommand(program);
+    registerSetupCommand(program);
     registerStartCommand(program);
     registerStopCommand(program);
     registerReloadCommand(program);
     registerStatusCommand(program);
     registerScreenshotCommand(program);
+    registerActionCommands(program);
     registerCommandGroups(program, COMPUTER_HELP_GROUPS);
 }
-function reportMissingHelper() {
-    console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
-    process.exit(1);
-}
 function registerStatusCommand(program) {
     program
         .command('status')
@@ -58,7 +57,7 @@ function registerStatusCommand(program) {
         console.log(`peers:     ${callers.length} caller${callers.length === 1 ? '' : 's'} (peer-auth on socket)`);
         if (!installed) {
             console.log('');
-            console.log('Run:  agents computer install-helper');
+            console.log('Run:  agents computer setup');
             return;
         }
         if (!socketUp) {
@@ -92,50 +91,55 @@ function registerStatusCommand(program) {
 function registerScreenshotCommand(program) {
     program
         .command('screenshot')
-        .description('Capture a JPEG of the frontmost window of a bundle id (default: frontmost app)')
-        .option('--bundle <id>', 'Bundle id to capture (default: bundle id of frontmost app)')
+        .description('Capture a window (default: largest), enumerate windows (--list), or the whole display (--display)')
+        .option('--bundle <id>', 'Bundle id to capture (default: frontmost allow-listed app)')
+        .option('--pid <n>', 'Target pid directly (overrides --bundle)', (v) => parseInt(v, 10))
+        .option('--list', 'List the app\'s windows (id/title/layer/bounds) instead of capturing — reveals modals/popups')
+        .option('--window-id <n>', 'Capture a specific window by id (from --list)', (v) => parseInt(v, 10))
+        .option('--display', 'Capture the whole display the app is on (composites stacked modals)')
         .option('--out <path>', 'Output JPEG path', './computer-screenshot.jpg')
         .option('--quality <n>', 'JPEG quality 1-100', (v) => parseInt(v, 10), 85)
+        .option('--json', 'Emit JSON (metadata for captures; window list for --list)')
         .action(async (opts) => {
-        const transport = describeTransport();
-        if (transport.kind === 'none')
-            reportMissingHelper();
         const quality = Math.max(1, Math.min(100, opts.quality || 85));
-        const client = openComputerClient();
-        try {
-            // Step 1: list_apps to get the candidate set.
-            const apps = await client.call('list_apps');
-            if (apps.error) {
-                console.error(`error: ${apps.error.code}: ${apps.error.message}`);
-                process.exit(1);
-            }
-            const list = apps.result?.apps || [];
-            let target;
-            if (opts.bundle) {
-                target = list.find((a) => a.bundle_id === opts.bundle);
-                if (!target) {
-                    console.error(`bundle not in allow list (or not running): ${opts.bundle}`);
-                    console.error(`add Computer(${opts.bundle}) to a permissions group, then \`agents computer reload\``);
+        await withClient(async (client) => {
+            // Resolve the target pid (explicit --pid, else --bundle, else frontmost).
+            let pid = opts.pid;
+            if (pid == null) {
+                const list = unwrap(await client.call('list_apps')).apps || [];
+                const picked = pickTarget(list, { bundle: opts.bundle });
+                if (!picked.ok) {
+                    console.error(picked.error);
                     process.exit(1);
                 }
+                pid = picked.app.pid;
             }
-            else {
-                target = list.find((a) => a.active);
-                if (!target) {
-                    console.error('no active app found in allow list');
-                    console.error('add Computer(<bundle-id>) to a permissions group, then `agents computer reload`');
-                    process.exit(1);
+            // --list: enumerate windows, no image.
+            if (opts.list) {
+                const res = unwrap(await client.call('screenshot', { pid, list: true }));
+                const windows = res.windows || [];
+                if (opts.json) {
+                    console.log(JSON.stringify(res, null, 2));
                 }
+                else if (windows.length === 0) {
+                    console.log('(no windows)');
+                }
+                else {
+                    for (const w of windows) {
+                        const b = w.bounds || [];
+                        console.log(`${String(w.window_id).padStart(8)}  layer ${w.layer}  [${b.join(',')}]  ${w.title || '(untitled)'}`);
+                    }
+                }
+                return;
             }
-            // Step 2: screenshot.
-            const shot = await client.call('screenshot', { pid: target.pid, quality });
-            if (shot.error) {
-                console.error(`error: ${shot.error.code}: ${shot.error.message}`);
-                process.exit(1);
-            }
-            const b64 = shot.result?.image_data;
-            const width = shot.result?.width;
-            const height = shot.result?.height;
+            // Capture: window (default / --window-id) or full display.
+            const params = { pid, quality };
+            if (opts.display)
+                params.display = true;
+            else if (opts.windowId != null)
+                params.window_id = opts.windowId;
+            const res = unwrap(await client.call('screenshot', params));
+            const b64 = res.image_data;
             if (!b64) {
                 console.error('helper returned no image_data');
                 process.exit(1);
@@ -143,14 +147,20 @@ function registerScreenshotCommand(program) {
             const buf = Buffer.from(b64, 'base64');
             const outPath = path.resolve(opts.out);
             fs.writeFileSync(outPath, buf);
-            console.log(`saved: ${outPath} (${width ?? '?'}x${height ?? '?'}, ${buf.byteLength} bytes)`);
-        }
-        finally {
-            await client.close();
-        }
+            if (opts.json) {
+                // Drop the heavy base64 from the metadata echo; report where it went.
+                const meta = { ...res, image_data: `<saved to ${outPath}>` };
+                console.log(JSON.stringify(meta, null, 2));
+            }
+            else {
+                const origin = res.origin || [];
+                const originStr = origin.length === 2 ? `, origin [${origin.join(',')}], scale ${res.scale ?? '?'}` : '';
+                console.log(`saved: ${outPath} (${res.width ?? '?'}x${res.height ?? '?'}, ${buf.byteLength} bytes${originStr})`);
+            }
+        });
     });
 }
-// install-helper:
+// setup (alias: install-helper):
 //   1. resolve dist .app
 //   2. copy to /Applications/Computer Helper.app
 //   3. codesign --verify the destination
@@ -167,9 +177,10 @@ const HELPER_BUNDLE_ID = 'com.phnx-labs.computer-helper';
 const HELPER_APP_NAME = 'Computer Helper.app';
 const HELPER_APP_DEST = `/Applications/${HELPER_APP_NAME}`;
 const HELPER_LABEL = HELPER_BUNDLE_ID;
-function registerInstallHelperCommand(program) {
+function registerSetupCommand(program) {
     program
-        .command('install-helper')
+        .command('setup')
+        .alias('install-helper')
         .description('Install ComputerHelper.app to /Applications/ (does NOT activate the daemon — run `start` to enable)')
         .action(async () => {
         const srcApp = resolveHelperApp();
@@ -263,12 +274,12 @@ function registerStartCommand(program) {
         const logPath = resolveLogPath();
         if (!fs.existsSync(plistPath)) {
             console.error(`plist not found at ${plistPath}`);
-            console.error('run: agents computer install-helper');
+            console.error('run: agents computer setup');
             process.exit(1);
         }
         if (!fs.existsSync(HELPER_APP_DEST)) {
             console.error(`helper app not found at ${HELPER_APP_DEST}`);
-            console.error('run: agents computer install-helper');
+            console.error('run: agents computer setup');
             process.exit(1);
         }
         const uid = process.getuid?.();

package/dist/commands/inspect.d.ts

@@ -1,14 +1,30 @@
 /**
- * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ * `agents inspect <target>` — detail view for one agent+version or one DotAgents repo.
  *
- * Summary mode shows the per-version header (paths, shim, capabilities, resource
- * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
- * one resource kind; passing a positional query to the same flag fuzzy-searches
- * for a single resource and prints its detail. Resource names render as OSC-8
- * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
- * itself) so users can click straight to the source.
+ * Agent targets (`claude`, `claude@2.1.170`) show the per-version header (paths,
+ * shim, capabilities, resource counts, sessions). Repo targets (`user`, `system`,
+ * `project`, a registered extra-repo alias, or a filesystem path to a repo with a
+ * `.agents/` dir or to a DotAgents root itself) show the repo root, git state, and
+ * per-kind resource counts. Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...)
+ * list one resource kind for either target form; passing a positional query to the
+ * same flag fuzzy-searches for a single resource and prints its detail. Resource
+ * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
+ * AGENT.md / the file itself) so users can click straight to the source.
  */
 import { Command } from 'commander';
+/** Resource kinds the inspect command can drill into. */
+declare const DRILLABLE_KINDS: readonly ["commands", "skills", "hooks", "mcp", "rules", "plugins", "workflows", "subagents"];
+type DrillableKind = typeof DRILLABLE_KINDS[number];
+interface ResourceItem {
+    name: string;
+    source: string;
+    /** Absolute path to the resource entry (file or directory). */
+    path: string;
+    /** Path the OSC-8 link should point at — marker file inside bundles, else `path`. */
+    linkTarget: string;
+    /** One-line description (frontmatter `description:` or first non-frontmatter line). */
+    description: string;
+}
 interface InspectOptions {
     brief?: boolean;
     json?: boolean;
@@ -23,4 +39,19 @@ interface InspectOptions {
 }
 export declare function registerInspectCommand(program: Command): void;
 export declare function inspectAction(target: string, options: InspectOptions): Promise<void>;
+export interface RepoTarget {
+    /** Display label: 'user' | 'system' | 'project', an extra-repo alias, or a path-derived name. */
+    label: string;
+    /** Absolute path to the DotAgents root (the dir holding commands/, skills/, ...). */
+    root: string;
+}
+/**
+ * Resolve a non-agent target as a DotAgents repo: the built-in layer names,
+ * a registered extra-repo alias, or a filesystem path. Paths accept either a
+ * DotAgents root itself or a repo whose `.agents/` dir should be inspected.
+ * Returns null when the target is none of these.
+ */
+export declare function resolveRepoTarget(target: string, cwd?: string): RepoTarget | null;
+/** List one resource kind from a single repo root — no layering, no overrides. */
+export declare function collectRepoKind(repo: RepoTarget, kind: DrillableKind): ResourceItem[];
 export {};

package/dist/commands/inspect.js

@@ -1,13 +1,17 @@
 /**
- * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ * `agents inspect <target>` — detail view for one agent+version or one DotAgents repo.
  *
- * Summary mode shows the per-version header (paths, shim, capabilities, resource
- * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
- * one resource kind; passing a positional query to the same flag fuzzy-searches
- * for a single resource and prints its detail. Resource names render as OSC-8
- * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
- * itself) so users can click straight to the source.
+ * Agent targets (`claude`, `claude@2.1.170`) show the per-version header (paths,
+ * shim, capabilities, resource counts, sessions). Repo targets (`user`, `system`,
+ * `project`, a registered extra-repo alias, or a filesystem path to a repo with a
+ * `.agents/` dir or to a DotAgents root itself) show the repo root, git state, and
+ * per-kind resource counts. Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...)
+ * list one resource kind for either target form; passing a positional query to the
+ * same flag fuzzy-searches for a single resource and prints its detail. Resource
+ * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
+ * AGENT.md / the file itself) so users can click straight to the source.
  */
+import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -15,7 +19,7 @@ import chalk from 'chalk';
 import * as yaml from 'yaml';
 import { AGENTS, getCliState } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
-import { readMeta } from '../lib/state.js';
+import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
@@ -39,8 +43,8 @@ const CAPABILITY_NAMES = [
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
     const cmd = program
-        .command('inspect <agent>')
-        .description('Inspect one installed agent at one version — paths, capabilities, resources, drill into any kind.')
+        .command('inspect <target>')
+        .description('Inspect one installed agent at one version, or a DotAgents repo (user|system|project|alias|path) — paths, capabilities, resources, drill into any kind.')
         .option('--brief', 'header + capabilities only; skip resources/sessions')
         .option('--json', 'machine-readable JSON output');
     for (const kind of DRILLABLE_KINDS) {
@@ -52,6 +56,20 @@ export function registerInspectCommand(program) {
 }
 // ─── Main dispatcher ─────────────────────────────────────────────────────────
 export async function inspectAction(target, options) {
+    const agentKey = target.split('@')[0].toLowerCase();
+    if (!(agentKey in AGENTS)) {
+        const repo = resolveRepoTarget(target);
+        if (repo) {
+            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);
+    }
     const { agent, version } = parseTarget(target);
     const versionHome = getVersionHomePath(agent, version);
     if (!fs.existsSync(versionHome)) {
@@ -75,13 +93,7 @@ export async function inspectAction(target, options) {
 }
 function parseTarget(target) {
     const [rawAgent, rawVersion] = target.split('@');
-    const agentKey = (rawAgent || '').toLowerCase();
-    if (!(agentKey in AGENTS)) {
-        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
-        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
-        process.exit(1);
-    }
-    const agent = agentKey;
+    const agent = (rawAgent || '').toLowerCase();
     let version = rawVersion;
     if (!version || version === 'default') {
         const meta = readMeta();
@@ -110,6 +122,160 @@ function pickDrillKind(options) {
     }
     return active[0];
 }
+/** Files at a DotAgents root that mark it as one, beyond the per-kind dirs. */
+const REPO_MARKER_FILES = ['agents.yaml', 'hooks.yaml'];
+/**
+ * Resolve a non-agent target as a DotAgents repo: the built-in layer names,
+ * a registered extra-repo alias, or a filesystem path. Paths accept either a
+ * DotAgents root itself or a repo whose `.agents/` dir should be inspected.
+ * Returns null when the target is none of these.
+ */
+export function resolveRepoTarget(target, cwd) {
+    if (target === 'user')
+        return { label: 'user', root: getUserAgentsDir() };
+    if (target === 'system')
+        return { label: 'system', root: getSystemAgentsDir() };
+    if (target === 'project') {
+        const dir = getProjectAgentsDir(cwd);
+        if (!dir) {
+            console.error(chalk.red('No project .agents/ directory found from the current directory.'));
+            process.exit(1);
+        }
+        return { label: 'project', root: dir };
+    }
+    for (const extra of getEnabledExtraRepos()) {
+        if (extra.alias === target)
+            return { label: extra.alias, root: extra.dir };
+    }
+    const expanded = target.startsWith('~/') ? path.join(os.homedir(), target.slice(2)) : target;
+    const abs = path.resolve(cwd ?? process.cwd(), expanded);
+    const stat = safeStat(abs);
+    if (!stat || !stat.isDirectory())
+        return null;
+    // A dir that is itself a DotAgents root wins over its nested .agents/ —
+    // extra repos like ~/.agents-extras keep resources at the top level and use
+    // .agents/ only for worktrees.
+    if (isDotAgentsRoot(abs)) {
+        const label = path.basename(abs) === '.agents' ? path.basename(path.dirname(abs)) : path.basename(abs);
+        return { label, root: abs };
+    }
+    if (path.basename(abs) !== '.agents') {
+        const nested = path.join(abs, '.agents');
+        if (safeStat(nested)?.isDirectory()) {
+            return { label: path.basename(abs), root: nested };
+        }
+    }
+    return null;
+}
+function isDotAgentsRoot(dir) {
+    for (const marker of REPO_MARKER_FILES) {
+        if (fs.existsSync(path.join(dir, marker)))
+            return true;
+    }
+    for (const kind of DRILLABLE_KINDS) {
+        if (safeStat(path.join(dir, kind))?.isDirectory())
+            return true;
+    }
+    return false;
+}
+async function inspectRepo(repo, options) {
+    const drill = pickDrillKind(options);
+    const jsonHead = { repo: repo.label, root: repo.root };
+    if (drill) {
+        const items = collectRepoKind(repo, drill.kind);
+        if (drill.query === true || drill.query === undefined) {
+            renderItemList(repo.label, jsonHead, drill.kind, items, options);
+        }
+        else {
+            renderItemDetail(repo.label, jsonHead, drill.kind, String(drill.query), items, options);
+        }
+        return;
+    }
+    renderRepoSummary(repo, options);
+}
+/** List one resource kind from a single repo root — no layering, no overrides. */
+export function collectRepoKind(repo, kind) {
+    const dir = path.join(repo.root, kind);
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const p = path.join(dir, entry.name);
+        items.push({
+            name: entry.name.replace(/\.(md|yaml|yml|toml|json)$/, ''),
+            source: repo.label,
+            path: p,
+            linkTarget: linkTarget(p),
+            description: readDescription(p),
+        });
+    }
+    return items.sort((a, b) => a.name.localeCompare(b.name));
+}
+function renderRepoSummary(repo, options) {
+    const git = repoGitInfo(repo.root);
+    const manifests = REPO_MARKER_FILES.filter(m => fs.existsSync(path.join(repo.root, m)));
+    const counts = {};
+    if (!options.brief) {
+        for (const kind of DRILLABLE_KINDS) {
+            const items = collectRepoKind(repo, kind);
+            counts[kind] = { total: items.length, bySource: { [repo.label]: items.length } };
+        }
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            repo: repo.label,
+            root: repo.root,
+            git,
+            manifests,
+            resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => [kind, counts[kind].total])),
+        }, null, 2));
+        return;
+    }
+    console.log('\n' + chalk.bold(repo.label) + '  ' + chalk.gray('[dotagents repo]') + '\n');
+    const rows = [['root', termLink(repo.root, repo.root)]];
+    if (git) {
+        const dirty = git.dirty > 0 ? ` ${chalk.gray('·')} ${chalk.yellow(`${git.dirty} dirty`)}` : '';
+        const url = git.url ? ` ${chalk.gray('·')} ${chalk.gray(git.url)}` : '';
+        rows.push(['git', `${git.branch}${dirty}${url}`]);
+    }
+    if (manifests.length > 0)
+        rows.push(['manifests', manifests.join(', ')]);
+    for (const [k, v] of rows)
+        console.log(`  ${k.padEnd(10)} ${v}`);
+    if (!options.brief) {
+        console.log('\n' + chalk.bold('Resources'));
+        for (const kind of DRILLABLE_KINDS) {
+            console.log(`  ${kind.padEnd(10)} ${String(counts[kind].total).padStart(4)}`);
+        }
+    }
+    console.log('');
+    console.log(chalk.gray(`Drill in:   agents inspect ${repo.label} --skills <query>`));
+    console.log('');
+}
+function repoGitInfo(root) {
+    const git = (args) => {
+        try {
+            return execSync(`git -C ${JSON.stringify(root)} ${args}`, { stdio: ['ignore', 'pipe', 'ignore'] })
+                .toString().trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    const branch = git('rev-parse --abbrev-ref HEAD');
+    if (branch === null)
+        return null;
+    const status = git('status --porcelain');
+    const dirty = status ? status.split('\n').filter(Boolean).length : 0;
+    return { branch, dirty, url: git('remote get-url origin') };
+}
 // ─── Summary mode ────────────────────────────────────────────────────────────
 async function renderSummary(agent, version, versionHome, options) {
     const meta = readMeta();
@@ -184,17 +350,19 @@ async function renderSummary(agent, version, versionHome, options) {
 // ─── List mode ───────────────────────────────────────────────────────────────
 async function renderList(agent, version, versionHome, kind, options) {
     const items = collectKind(agent, versionHome, kind);
+    renderItemList(`${agent}@${version}`, { agent, version }, kind, items, options);
+}
+function renderItemList(header, jsonHead, kind, items, options) {
     if (options.json) {
         console.log(JSON.stringify({
-            agent,
-            version,
+            ...jsonHead,
             kind,
             count: items.length,
             items: items.map(i => ({ name: i.name, source: i.source, path: i.path, description: i.description })),
         }, null, 2));
         return;
     }
-    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} (${items.length})`) + '\n');
+    console.log('\n' + chalk.bold(header) + '  ' + chalk.gray(`${kind} (${items.length})`) + '\n');
     if (items.length === 0) {
         console.log(chalk.gray(`  (none installed)`));
         console.log('');
@@ -212,11 +380,14 @@ async function renderList(agent, version, versionHome, kind, options) {
 // ─── Detail mode (fuzzy) ─────────────────────────────────────────────────────
 async function renderDetail(agent, version, versionHome, kind, query, options) {
     const items = collectKind(agent, versionHome, kind);
+    renderItemDetail(`${agent}@${version}`, { agent, version }, kind, query, items, options);
+}
+function renderItemDetail(header, jsonHead, kind, query, items, options) {
     const matches = findMatches(items, query);
     if (matches.length === 0) {
         const suggestions = suggestClosest(items, query, 3);
         if (options.json) {
-            console.log(JSON.stringify({ agent, version, kind, query, match: null, suggestions: suggestions.map(s => s.name) }, null, 2));
+            console.log(JSON.stringify({ ...jsonHead, kind, query, match: null, suggestions: suggestions.map(s => s.name) }, null, 2));
         }
         else {
             console.error(chalk.red(`No ${kind} matching '${query}'.`));
@@ -231,8 +402,7 @@ async function renderDetail(agent, version, versionHome, kind, query, options) {
     if (options.json) {
         const detail = buildDetail(best.item, kind);
         console.log(JSON.stringify({
-            agent,
-            version,
+            ...jsonHead,
             kind,
             query,
             match: { ...detail, matchKind: best.matchKind },
@@ -240,7 +410,7 @@ async function renderDetail(agent, version, versionHome, kind, query, options) {
         }, null, 2));
         return;
     }
-    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} matching "${query}"`) + '\n');
+    console.log('\n' + chalk.bold(header) + '  ' + chalk.gray(`${kind} matching "${query}"`) + '\n');
     const matchTag = best.matchKind === 'exact' ? 'exact' : best.matchKind === 'substring' ? 'substring' : `~${best.distance}`;
     console.log(`  ${chalk.green('✓')}  ${termLink(chalk.bold.cyan(best.item.name), best.item.linkTarget)}  ${chalk.gray(`[${matchTag}, ${best.item.source}]`)}`);
     if (best.item.description) {

package/dist/commands/sessions.js

@@ -15,6 +15,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
+import { looksLikePath, toComparablePath, homeDir } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
@@ -69,15 +70,6 @@ function createScanProgressTracker(verbs, suffix, spinner) {
 }
 const PICKER_RECENT_COUNT = 15;
 const PICKER_POOL_LIMIT = 200;
-/**
- * Detect whether a positional argument looks like a filesystem path.
- * Naked paths (., ./, ../, /, ~) filter sessions by project directory.
- * Everything else is treated as a search query string.
- */
-function isPathLike(query) {
-    return query === '.' || query.startsWith('./') || query.startsWith('../')
-        || query.startsWith('/') || query.startsWith('~');
-}
 /**
  * Resolve a path-like query to an absolute directory path.
  */
@@ -153,8 +145,13 @@ function contextColor(context) {
 function shortCwd(cwd) {
     if (!cwd)
         return '-';
-    const home = os.homedir();
-    return cwd.startsWith(home) ? '~' + cwd.slice(home.length) : cwd;
+    const home = homeDir();
+    // Compare in normalized form so the `~` shorthand also lands on Windows
+    // (case-insensitive, backslash paths); on POSIX this is byte-identical to the
+    // previous `cwd.startsWith(home)`. The displayed tail keeps original casing.
+    return toComparablePath(cwd).startsWith(toComparablePath(home))
+        ? '~' + cwd.slice(home.length)
+        : cwd;
 }
 function formatStartedAt(startedAtMs) {
     if (!startedAtMs)
@@ -334,7 +331,7 @@ async function sessionsAction(query, options) {
     // Path-like queries filter by project directory instead of text search.
     let pathFilter;
     let searchQuery;
-    if (query && isPathLike(query)) {
+    if (query && looksLikePath(query)) {
         const resolved = resolvePathFilter(query);
         if (!fs.existsSync(resolved)) {
             console.log(chalk.yellow(`Path not found: ${resolved}`));

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