@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/migrate.js

@@ -9,6 +9,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
+import { createLink } from './platform/index.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -57,7 +58,7 @@ export function foldLegacySystemRepo() {
         try {
             fs.renameSync(LEGACY_SYSTEM_DIR, SYSTEM_DIR);
             try {
-                fs.symlinkSync(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
+                createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
             }
             catch { /* best-effort */ }
             console.error('Folded ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
@@ -71,7 +72,7 @@ export function foldLegacySystemRepo() {
         copyDirSkipExisting(LEGACY_SYSTEM_DIR, SYSTEM_DIR);
         fs.rmSync(LEGACY_SYSTEM_DIR, { recursive: true, force: true });
         try {
-            fs.symlinkSync(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
+            createLink(SYSTEM_DIR, LEGACY_SYSTEM_DIR);
         }
         catch { /* best-effort */ }
         console.error('Merged ~/.agents-system/ into ~/.agents/.system/ (left back-compat symlink)');
@@ -698,14 +699,14 @@ function repairAgentConfigSymlinks() {
                 continue; // already correct
             try {
                 fs.unlinkSync(symlinkPath);
-                fs.symlinkSync(userTarget, symlinkPath);
+                createLink(userTarget, symlinkPath);
                 repaired++;
             }
             catch { /* best-effort */ }
         }
         else if (!stat) {
             try {
-                fs.symlinkSync(userTarget, symlinkPath);
+                createLink(userTarget, symlinkPath);
                 repaired++;
             }
             catch { /* best-effort */ }
@@ -798,8 +799,11 @@ export function repairSelfReferentialBinShims(versionsRoot = path.join(HISTORY_D
             const realBinary = findInPath(cli);
             try {
                 fs.unlinkSync(binLink);
+                // createLink: a real symlink where the OS allows it (POSIX, and Windows
+                // with the symlink privilege), copy-fallback otherwise — so the repair
+                // lands a working binary on Windows runners without the symlink right.
                 if (realBinary)
-                    fs.symlinkSync(realBinary, binLink);
+                    createLink(realBinary, binLink);
                 repaired++;
             }
             catch { /* best-effort */ }

package/dist/lib/platform/exec.d.ts

@@ -1,5 +1,15 @@
 /** PATH-search command for the platform: `where` on Windows, else `which`. */
 export declare function whichCommand(platform?: NodeJS.Platform): string;
+/**
+ * Does spawning `binary` require `shell: true` on this platform?
+ *
+ * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
+ * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
+ * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
+ * command name (not an absolute path) needs the same PATHEXT resolution. Both
+ * cases require the shell. Always false off Windows, where direct exec is right.
+ */
+export declare function needsWindowsShell(binary: string, platform?: NodeJS.Platform): boolean;
 /**
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per

package/dist/lib/platform/exec.js

@@ -2,10 +2,27 @@
  * Executable resolution, platform-aware.
  */
 import { execFileSync } from 'child_process';
+import * as path from 'path';
 /** PATH-search command for the platform: `where` on Windows, else `which`. */
 export function whichCommand(platform = process.platform) {
     return platform === 'win32' ? 'where' : 'which';
 }
+/**
+ * Does spawning `binary` require `shell: true` on this platform?
+ *
+ * On Windows a `.cmd`/`.bat` wrapper (npm.cmd, bun.cmd, the agent shims) cannot
+ * be exec'd directly — `spawn`/`execFile` look for a literal executable and miss
+ * the PATHEXT/cmd-interpreter step, surfacing as `ENOENT`/`EINVAL`. A bare
+ * command name (not an absolute path) needs the same PATHEXT resolution. Both
+ * cases require the shell. Always false off Windows, where direct exec is right.
+ */
+export function needsWindowsShell(binary, platform = process.platform) {
+    if (platform !== 'win32')
+        return false;
+    // path.win32.isAbsolute, not path.isAbsolute: the latter uses the HOST's rules,
+    // so a Windows path would read as relative when this runs on a Linux CI host.
+    return !path.win32.isAbsolute(binary) || /\.(cmd|bat)$/i.test(binary);
+}
 /**
  * Resolve an executable name to its absolute path via the OS PATH search, or
  * `null` if not found. On Windows `where` can return several lines (one per

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

@@ -17,6 +17,7 @@ export declare const IS_MACOS: boolean;
 export declare const IS_LINUX: boolean;
 export * from './paths.js';
 export * from './exec.js';
+export * from './links.js';
 export * from './process.js';
 export * from './ipc.js';
 export * from './winpath.js';

package/dist/lib/platform/index.js

@@ -17,6 +17,7 @@ export const IS_MACOS = process.platform === 'darwin';
 export const IS_LINUX = process.platform === 'linux';
 export * from './paths.js';
 export * from './exec.js';
+export * from './links.js';
 export * from './process.js';
 export * from './ipc.js';
 export * from './winpath.js';

package/dist/lib/platform/links.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Create a link at `dst` pointing to `src`, portable across platforms.
+ *
+ * - **Directory** target: junction on Windows (no Developer Mode needed), plain
+ *   symlink on POSIX.
+ * - **File** target: symlink, falling back to `copyFileSync` when Windows
+ *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
+ *   point-in-time snapshot, not a live link; acceptable for the immutable
+ *   targets we link (binaries, config files).
+ *
+ * `dst` must not already exist. Callers that replace atomically should link to a
+ * temp name and `rename` over the destination, exactly as before — the copy
+ * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
+ */
+export declare function createLink(src: string, dst: string): void;

package/dist/lib/platform/links.js

@@ -0,0 +1,42 @@
+/**
+ * Filesystem linking, platform-aware.
+ *
+ * POSIX symlinks have no portable equivalent on Windows: directory symlinks and
+ * file symlinks both require either Administrator or Developer Mode, while
+ * *junctions* (directories only) need no elevation. `createLink` picks the form
+ * that works without privilege — junction for directories — and falls back to a
+ * copy for file links when the OS refuses the symlink.
+ */
+import * as fs from 'fs';
+/**
+ * Create a link at `dst` pointing to `src`, portable across platforms.
+ *
+ * - **Directory** target: junction on Windows (no Developer Mode needed), plain
+ *   symlink on POSIX.
+ * - **File** target: symlink, falling back to `copyFileSync` when Windows
+ *   refuses the symlink (`EPERM`/`ENOSYS` — no Developer Mode). The copy is a
+ *   point-in-time snapshot, not a live link; acceptable for the immutable
+ *   targets we link (binaries, config files).
+ *
+ * `dst` must not already exist. Callers that replace atomically should link to a
+ * temp name and `rename` over the destination, exactly as before — the copy
+ * fallback is non-atomic, so the temp+rename stays the caller's responsibility.
+ */
+export function createLink(src, dst) {
+    const win = process.platform === 'win32';
+    const isDir = fs.statSync(src).isDirectory();
+    // Type is ignored on POSIX; on Windows, junction (dir) avoids the elevation a
+    // dir symlink would need, and 'file' is the explicit file-symlink form.
+    const type = win ? (isDir ? 'junction' : 'file') : undefined;
+    try {
+        fs.symlinkSync(src, dst, type);
+    }
+    catch (err) {
+        const code = err.code;
+        if (win && !isDir && (code === 'EPERM' || code === 'ENOSYS')) {
+            fs.copyFileSync(src, dst);
+            return;
+        }
+        throw err;
+    }
+}

package/dist/lib/platform/paths.d.ts

@@ -27,3 +27,21 @@ export declare function homeDir(): string;
  * whether to apply it (typically gated on win32).
  */
 export declare function isWindowsAbsolutePath(p: string): boolean;
+/**
+ * Fold backslashes to forward slashes. Use when a path is going into a string
+ * that must read the same on every OS — a doc-comparable display path, a regex
+ * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
+ * (no backslashes) it returns the value unchanged.
+ */
+export declare function toPosix(p: string): string;
+/**
+ * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
+ * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
+ * folds path separators and spaces to `_`. For a POSIX path this produces the
+ * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
+ * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
+ *
+ * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
+ *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
+ */
+export declare function toPortableKey(p: string): string;

package/dist/lib/platform/paths.js

@@ -56,3 +56,25 @@ export function homeDir() {
 export function isWindowsAbsolutePath(p) {
     return WIN_DRIVE_RE.test(p) || p.startsWith('\\\\');
 }
+/**
+ * Fold backslashes to forward slashes. Use when a path is going into a string
+ * that must read the same on every OS — a doc-comparable display path, a regex
+ * subject, a forward-slash-keyed lookup. Pure string transform; on POSIX input
+ * (no backslashes) it returns the value unchanged.
+ */
+export function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Derive a filesystem-safe key/slug from an absolute path. Drops the Windows
+ * drive colon (`:` is illegal in NTFS filenames / is the ADS separator) and
+ * folds path separators and spaces to `_`. For a POSIX path this produces the
+ * exact historical slug (`/a/b c` -> `_a_b_c`), so existing on-disk keys are
+ * unchanged; on Windows `C:\a\b` -> `C_a_b` instead of an unusable name.
+ *
+ * Shell mirror (keep byte-identical in any bash shim that recomputes this key):
+ *   printf '%s' "$P" | tr -d ':' | tr '\\/ ' '_'
+ */
+export function toPortableKey(p) {
+    return p.replace(/^([a-zA-Z]):/, '$1').replace(/[\\/ ]/g, '_');
+}

package/dist/lib/platform/posixpath.d.ts

@@ -0,0 +1,28 @@
+/** The XDG user-bin dir, `~/.local/bin`. */
+export declare function localBinDir(home?: string): string;
+export interface SymlinkResult {
+    /** A usable symlink to `target` exists at the path after this call. */
+    ok: boolean;
+    /** True only when this call created the symlink (false = already correct, or left untouched). */
+    created: boolean;
+    /** Why an existing entry was left untouched (set only when ok is false). */
+    skippedReason?: string;
+    path: string;
+}
+/**
+ * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
+ * pre-existing real file or a symlink that already points elsewhere — most
+ * importantly a developer's `scripts/install.sh` dev build at
+ * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
+ * `target`, is created/treated as ok. Idempotent.
+ */
+export declare function ensureLocalBinSymlink(name: string, target: string, dir?: string): SymlinkResult;
+/**
+ * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
+ * for the consumers we heal. Best-effort: any probe failure returns false so
+ * the caller heals rather than wrongly assuming success. `command -v` is a
+ * POSIX builtin.
+ */
+export declare function loginShellResolves(cmd: string): boolean;
+/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
+export declare function dirOnLoginPath(dir: string): boolean;

package/dist/lib/platform/posixpath.js

@@ -0,0 +1,153 @@
+/**
+ * POSIX login-PATH primitives for making the `agents` command resolvable.
+ *
+ * The Unix analog of winpath.ts. `agents`/`ag` land on PATH only via npm's
+ * bin symlink into the npm global-bin dir; under nvm (and other per-user node
+ * prefixes) that dir is absent from a *non-interactive login* shell's PATH, so
+ * `bash -lc 'agents …'` fails with command-not-found. That breaks every
+ * consumer that drives a login shell on the box: `agents secrets export --host`
+ * (which runs `bash -lc 'agents secrets import …'` on the remote) and the
+ * routines daemon (`src/lib/daemon.ts`, which falls back to bare `agents`).
+ *
+ * The fix mirrors the Windows postinstall branch (which registers npm's
+ * global-bin dir on the user PATH): symlink the entrypoint into ~/.local/bin —
+ * the XDG user-bin dir that mainstream distros auto-add to the login PATH when
+ * it exists (Debian/Ubuntu via ~/.profile, Fedora via /etc/profile.d) — and,
+ * where it is not yet on PATH, the caller adds it.
+ *
+ * Leaf module — imports only child_process / fs / os / path so it is cheap to
+ * load from the npm lifecycle script without pulling the rest of the CLI.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+/** The XDG user-bin dir, `~/.local/bin`. */
+export function localBinDir(home = os.homedir()) {
+    return path.join(home, '.local', 'bin');
+}
+/**
+ * Ensure `<dir>/<name>` is a symlink to `target`, NEVER clobbering a
+ * pre-existing real file or a symlink that already points elsewhere — most
+ * importantly a developer's `scripts/install.sh` dev build at
+ * `~/.local/bin/agents`. Only an absent path, or a symlink already pointing at
+ * `target`, is created/treated as ok. Idempotent.
+ */
+export function ensureLocalBinSymlink(name, target, dir = localBinDir()) {
+    const linkPath = path.join(dir, name);
+    const want = path.resolve(target);
+    let current = null;
+    try {
+        current = fs.readlinkSync(linkPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EINVAL') {
+            // The path exists but is not a symlink — a real file/dir. Never clobber.
+            return { ok: false, created: false, skippedReason: 'a non-symlink file already exists here', path: linkPath };
+        }
+        if (code !== 'ENOENT') {
+            return { ok: false, created: false, skippedReason: err.message, path: linkPath };
+        }
+        // ENOENT — nothing there; fall through to create.
+    }
+    if (current !== null) {
+        const resolved = path.isAbsolute(current) ? current : path.resolve(dir, current);
+        if (resolved === want)
+            return { ok: true, created: false, path: linkPath };
+        // Points somewhere else (e.g. a dev build) — the existing link wins.
+        return { ok: false, created: false, skippedReason: `symlink already points to ${current}`, path: linkPath };
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    fs.symlinkSync(target, linkPath);
+    return { ok: true, created: true, path: linkPath };
+}
+/**
+ * Absolute path to `bash`. We probe bash specifically — NOT the user's $SHELL —
+ * because the consumers we are healing run `bash -lc` regardless of login shell:
+ * `secrets export --host` builds `bash -lc 'agents secrets import …'` for the
+ * remote, and the routines daemon resolves `agents` the same way. On a box whose
+ * login shell is zsh, zsh's login PATH may lack ~/.local/bin while bash's
+ * includes it (Debian/Ubuntu ~/.profile) — so probing $SHELL would give the
+ * wrong answer for what the consumer actually sees. Resolve from the *current*
+ * PATH (the install process has one) and fall back to /bin/bash.
+ */
+function bashPath() {
+    const found = (process.env.PATH || '')
+        .split(path.delimiter)
+        .map((d) => (d ? path.join(d, 'bash') : ''))
+        .find((p) => {
+        if (!p)
+            return false;
+        try {
+            fs.accessSync(p, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    return found || '/bin/bash';
+}
+/**
+ * Environment for the probe shell that reproduces a *fresh* `bash -lc` — the
+ * PATH that `ssh host 'bash -lc …'` and the routines daemon actually get — and
+ * NOT the nvm/npm-augmented PATH of the install process.
+ *
+ * This is the crux: `npm i -g` (and a dev `bun run`) execute under nvm, so the
+ * caller's PATH already contains nvm's bin. A spawned shell inherits that PATH,
+ * so it would resolve `agents` and the heal would skip — during the very nvm
+ * install it exists to fix. We strip PATH (and nvm's hint vars) so the login
+ * profile rebuilds PATH from scratch, exactly as an incoming SSH command shell
+ * does. Login bash still sources /etc/profile + ~/.profile (which adds
+ * ~/.local/bin) but bails out of ~/.bashrc's nvm block early because it is
+ * non-interactive — which is precisely why bare `agents` is missing there.
+ */
+function loginProbeEnv() {
+    const env = { ...process.env };
+    delete env.PATH;
+    delete env.NVM_BIN;
+    delete env.NVM_INC;
+    for (const k of Object.keys(env))
+        if (k.startsWith('npm_'))
+            delete env[k];
+    return env;
+}
+/**
+ * Does a fresh `bash -lc` resolve `cmd` on its PATH? This is the real question
+ * for the consumers we heal. Best-effort: any probe failure returns false so
+ * the caller heals rather than wrongly assuming success. `command -v` is a
+ * POSIX builtin.
+ */
+export function loginShellResolves(cmd) {
+    try {
+        const res = spawnSync(bashPath(), ['-lc', `command -v ${cmd}`], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 5000,
+            env: loginProbeEnv(),
+        });
+        return res.status === 0 && !!res.stdout && res.stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Is `dir` on a fresh `bash -lc` PATH? Best-effort; a probe failure returns false. */
+export function dirOnLoginPath(dir) {
+    try {
+        const res = spawnSync(bashPath(), ['-lc', 'printf %s "$PATH"'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf-8',
+            timeout: 5000,
+            env: loginProbeEnv(),
+        });
+        if (res.status !== 0 || !res.stdout)
+            return false;
+        const want = path.resolve(dir);
+        return res.stdout.split(':').some((p) => p && path.resolve(p) === want);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/plugins.d.ts

@@ -123,6 +123,16 @@ export declare function saveUserConfig(pluginName: string, config: Record<string
  * Returns names of missing dependencies (warning only — not a hard error).
  */
 export declare function checkPluginDependencies(manifest: PluginManifest): string[];
+/**
+ * Reconstruct a MarketplaceSpec from a marketplace name. The inverse of
+ * marketplaceNameFor(): "agents-cli" → user, "agents-project" → project,
+ * "agents-system" → system, "agents-<alias>" → extra. The per-version
+ * marketplace operations only key off the name (never spec.root), but we
+ * resolve the real source root anyway so the spec is honest for any caller that
+ * inspects it (e.g. descriptionFor, which would otherwise label the system
+ * marketplace as an extra repo named "system").
+ */
+export declare function marketplaceSpecForName(name: string | undefined, cwd?: string): MarketplaceSpec;
 /**
  * Sync a plugin to a specific agent version's home directory.
  *

package/dist/lib/plugins.js

@@ -397,7 +397,7 @@ export function checkPluginDependencies(manifest) {
  * inspects it (e.g. descriptionFor, which would otherwise label the system
  * marketplace as an extra repo named "system").
  */
-function marketplaceSpecForName(name, cwd = process.cwd()) {
+export function marketplaceSpecForName(name, cwd = process.cwd()) {
     if (!name || name === MARKETPLACE_NAME)
         return { kind: 'user' };
     if (name === SYSTEM_MARKETPLACE_NAME) {

package/dist/lib/project-launch.js

@@ -47,6 +47,7 @@ import * as path from 'path';
 import { supports } from './capabilities.js';
 import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
 import { getVersionHomePath } from './versions.js';
+import { toPortableKey } from './platform/index.js';
 import { transformSubagentForClaude } from './subagents.js';
 import { compileRulesForProject } from './rules/compile.js';
 import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins.js';
@@ -88,15 +89,17 @@ export function runLaunchSync(opts) {
 }
 /**
  * Path of the shim's skip-fast sentinel for this (agent, version, cwd) tuple.
- * Must match the SHIM-SIDE format in src/lib/shims.ts (PROJECT_SLUG derivation):
- *   slug = PWD with `/` → `_` and ` ` → `_`
+ * Must match the SHIM-SIDE format in src/lib/shims.ts (PROJECT_SLUG derivation),
+ * which is the canonical `toPortableKey` mapping: drop the Windows drive colon
+ * and fold `\`, `/`, and ` ` → `_`. On POSIX this is byte-identical to the old
+ * `/` and ` ` → `_` slug; on Windows it yields a legal filename (no `C:\`).
  *
  * Cache leak note: this dir accumulates one zero-byte file per
  * (agent, version, project) tuple ever launched. Disk impact is negligible
  * (inodes only). A periodic GC belongs in `agents prune` — follow-up.
  */
 function launchSentinelPath(agent, version, cwd) {
-    const slug = cwd.replace(/\//g, '_').replace(/ /g, '_');
+    const slug = toPortableKey(cwd);
     // Prefer $HOME (respects test overrides + matches bash's $HOME expansion in
     // the shim), fall back to os.homedir() so the lookup never resolves to '/'
     // if HOME is somehow unset.

package/dist/lib/sandbox.js

@@ -11,6 +11,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir, getUserAgentsDir } from './state.js';
+import { createLink } from './platform/index.js';
 function resolveRealHome() {
     const home = os.homedir();
     try {
@@ -126,9 +127,11 @@ export function symlinkAllowedDirs(overlayHome, dirs) {
         fs.mkdirSync(parentDir, { recursive: true });
         if (!fs.existsSync(symlinkTarget)) {
             try {
-                fs.symlinkSync(realPath, symlinkTarget);
+                // createLink uses a junction for directories on Windows (no elevation),
+                // a plain symlink on POSIX — allowed dirs are directories.
+                createLink(realPath, symlinkTarget);
             }
-            catch { /* symlink already exists */ }
+            catch { /* link already exists or refused */ }
         }
     }
 }

package/dist/lib/secrets/remote.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Remote secrets — read and use `agents secrets` bundles that live on another
+ * host, over the same hardened SSH path that `agents secrets export --host`
+ * (the write inverse) already uses.
+ *
+ * This is the READ / USE direction:
+ *   - browse:  drive the remote `agents secrets list|view` and stream its
+ *              stdout back verbatim (lossless, no parsing).
+ *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
+ *              inject it ephemerally — never written to this machine's keychain.
+ *
+ * Trust model: relies on the operator's existing SSH access to the host (same
+ * boundary as `export --host` / `run --host`). Bundle names are shell-quoted
+ * into the remote command; resolved VALUES return over ssh stdout; a forwarded
+ * file-backend passphrase travels over ssh stdin (first line) so it never lands
+ * in argv / `ps` / remote shell history. Nothing is persisted locally.
+ */
+import { type SshExecResult } from '../ssh-exec.js';
+/**
+ * Resolve a `--host` value to an ssh target string. Tries the `agents hosts`
+ * registry first (enrolled name → ssh-config alias / `user@host`); on a miss,
+ * treats the value as a raw ssh target and validates it against injection.
+ */
+export declare function resolveSshTarget(nameOrAlias: string): Promise<string>;
+/**
+ * Merge `--host <single>` and `--hosts <a,b,c>` into an ordered, de-duplicated
+ * list. Both flags compose; either alone works. Empty when neither is set.
+ */
+export declare function parseHostsOption(opts: {
+    host?: string;
+    hosts?: string;
+}): string[];
+/**
+ * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
+ * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
+ * separates the bundle from the ssh target — and the target itself may be a
+ * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
+ * `muqsit@box`).
+ */
+export declare function splitBundleRef(ref: string): {
+    bundle: string;
+    host?: string;
+};
+/**
+ * Run `agents secrets <args>` on a remote host over ssh and return the raw
+ * result. Used by the browse commands — the remote's human-readable stdout is
+ * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
+ * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ */
+export declare function remoteSecretsRaw(target: string, args: string[], opts?: {
+    tty?: boolean;
+    input?: string;
+}): SshExecResult;
+/**
+ * Resolve a remote bundle to a plaintext env map by driving the remote's
+ * `agents secrets export <bundle> --plaintext --format json`. Values cross over
+ * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ *
+ * The remote unlocks the bundle with ITS OWN credentials — the owner host's
+ * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
+ * env) for a file-backed bundle. We deliberately do NOT forward this machine's
+ * passphrase: the remote bundle is encrypted with the remote's passphrase, so
+ * overriding it would break the read. (A macOS remote under non-interactive
+ * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
+ * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ */
+export declare function remoteResolveEnv(target: string, bundle: string): Promise<Record<string, string>>;