@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/session/remote.js

@@ -9,12 +9,25 @@
  * upfront copy, always current, but the peer must be reachable. SSH access is the
  * only auth — if you can `ssh <host>`, you own the box (no identity layer by design).
  *
- * Mirrors the transport already used by `agents secrets export --to-ssh`
+ * Offline degradation (no sync, still fetch-first): every *successful* fetch is
+ * cached to `~/.agents/.cache/remote-sessions/`, keyed by host + the exact query.
+ * When a later run finds the host unreachable, the cache is replayed with a clearly
+ * labelled "showing cached results" banner instead of returning nothing. The cache
+ * is a byproduct of fetches you already made — never a background job, freely
+ * deletable — so the fetch-don't-replicate model holds; this is just graceful
+ * degradation when the peer is asleep.
+ *
+ * Mirrors the transport already used by `agents secrets export --host`
  * (`src/commands/secrets.ts`): `ssh -o BatchMode=yes <host> bash -lc '<cmd>'`,
  * with `bash -lc` so the remote login PATH resolves `agents`.
  */
 import { spawnSync } from 'child_process';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
 import chalk from 'chalk';
+import { getCacheDir } from '../state.js';
+import { formatRelativeTime } from './relative-time.js';
 /**
  * SSH target: a bare ssh-config host alias (e.g. `yosemite-s1`) or `user@host`.
  * The strict allowlist blocks shell metacharacters and a leading `-`, so a target
@@ -83,30 +96,124 @@ const SSH_OPTS = [
     '-o', 'StrictHostKeyChecking=accept-new',
     '-o', 'ConnectTimeout=10',
 ];
+/**
+ * Classify an ssh `spawnSync` result. ssh(1) reserves exit 255 for its own
+ * connection-layer failures (host down, timeout, refused, auth, changed host
+ * key) — distinct from any other non-zero, which is the remote `agents sessions`
+ * exit code forwarded back (the query ran but failed). The two must be handled
+ * differently: 255 may fall back to cache, a forwarded failure must surface.
+ */
+export function classifySshFailure(res) {
+    if (res.error)
+        return 'spawn-error';
+    if (res.status === 0)
+        return 'ok';
+    if (res.status === 255)
+        return 'unreachable';
+    return 'query-failed';
+}
+/** Root of the offline-replay cache (`~/.agents/.cache/remote-sessions/`). */
+const REMOTE_CACHE_DIR = join(getCacheDir(), 'remote-sessions');
+/**
+ * Deterministic cache path for a (host, forwarded-args) pair. The forwarded args
+ * are hashed so distinct queries cache independently; the host stays readable in
+ * the filename (sanitised so `user@host` and aliases are filesystem-safe).
+ */
+export function remoteCachePath(host, forwardedArgs) {
+    const hash = createHash('sha256').update(forwardedArgs.join('\u0000')).digest('hex').slice(0, 16);
+    const safeHost = host.replace(/[^a-zA-Z0-9._@-]/g, '_');
+    return join(REMOTE_CACHE_DIR, `${safeHost}__${hash}.txt`);
+}
+/** Banner shown above replayed cache rows when the peer is offline. */
+export function formatStaleBanner(host, mtimeMs) {
+    const ago = formatRelativeTime(new Date(mtimeMs).toISOString());
+    return chalk.yellow(`${host}: offline — showing cached results from ${ago}`);
+}
+/** Message shown when a host is unreachable and there is no cache to fall back to. */
+export function formatUnreachable(host) {
+    return chalk.red(`${host}: unreachable over SSH (asleep, offline, or host key changed?) — ConnectTimeout 10s`);
+}
+/** Persist a successful fetch for later offline replay. Best-effort: a cache
+ * write must never break the live query. */
+function writeRemoteCache(host, forwardedArgs, output) {
+    try {
+        mkdirSync(REMOTE_CACHE_DIR, { recursive: true });
+        writeFileSync(remoteCachePath(host, forwardedArgs), output);
+    }
+    catch {
+        // ignore — caching is an optimisation, not a guarantee
+    }
+}
+/** Replay a cached fetch for an unreachable host. Banner goes to stderr (so a
+ * piped stdout stays exactly the cached rows); returns false when nothing is
+ * cached for this exact (host, query). */
+function replayRemoteCache(host, forwardedArgs) {
+    try {
+        const p = remoteCachePath(host, forwardedArgs);
+        if (!existsSync(p))
+            return false;
+        process.stderr.write(formatStaleBanner(host, statSync(p).mtimeMs) + '\n');
+        process.stdout.write(readFileSync(p, 'utf8'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Run the current `agents sessions` invocation on one or more remote machines over
- * SSH, streaming each remote's output to the terminal. Sets `process.exitCode = 1`
- * if any host fails. Reads the invocation from `process.argv` (override via
- * `argv` for testing).
+ * SSH, writing each remote's output to the terminal. A successful fetch is cached;
+ * an unreachable host falls back to that cache (with a stale banner) when present.
+ * Sets `process.exitCode = 1` if any host could not be answered (live or cached).
+ * Reads the invocation from `process.argv` (override via `argv` for testing).
+ *
+ * Output is captured rather than `stdio: 'inherit'`-streamed so it can be cached.
+ * Session output is small and the remote returns quickly, so buffering is
+ * imperceptible; `maxBuffer` is generous for the rare large `--markdown <id>` dump.
  */
 export function runRemoteSessions(hosts, argv = process.argv) {
     for (const host of hosts)
         assertValidSshTarget(host); // fail fast on any bad target
-    const remoteCmd = buildRemoteCommand(buildForwardedArgs(argv, new Set(hosts)));
+    const forwarded = buildForwardedArgs(argv, new Set(hosts));
+    const remoteCmd = buildRemoteCommand(forwarded);
     const multi = hosts.length > 1;
     let failures = 0;
     for (const host of hosts) {
         if (multi)
             process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
-        const res = spawnSync('ssh', [...SSH_OPTS, host, remoteCmd], { stdio: 'inherit' });
-        if (res.error) {
-            failures++;
-            console.error(chalk.red(`${host}: ${res.error.message}`));
-            continue;
-        }
-        if (res.status !== 0) {
-            failures++;
-            console.error(chalk.red(`${host}: remote query failed (exit ${res.status ?? 'signal'}).`));
+        const res = spawnSync('ssh', [...SSH_OPTS, host, remoteCmd], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        switch (classifySshFailure(res)) {
+            case 'ok':
+                process.stdout.write(res.stdout ?? '');
+                if (res.stderr)
+                    process.stderr.write(res.stderr);
+                writeRemoteCache(host, forwarded, res.stdout ?? '');
+                break;
+            case 'unreachable':
+                // Served-from-cache counts as answered (degraded, but with data + a clear
+                // banner), so it does not increment failures. No cache → a real failure.
+                if (!replayRemoteCache(host, forwarded)) {
+                    failures++;
+                    console.error(formatUnreachable(host));
+                }
+                break;
+            case 'spawn-error':
+                failures++;
+                console.error(chalk.red(`${host}: ${res.error?.message ?? 'failed to launch ssh'}`));
+                break;
+            case 'query-failed':
+                // The remote ran but its query exited non-zero — surface its own output
+                // and exit code; never mask a genuine error with stale cache.
+                failures++;
+                if (res.stdout)
+                    process.stdout.write(res.stdout);
+                if (res.stderr)
+                    process.stderr.write(res.stderr);
+                console.error(chalk.red(`${host}: remote query failed (exit ${res.status ?? 'signal'}).`));
+                break;
         }
     }
     if (failures > 0)

package/dist/lib/session/types.d.ts

@@ -7,7 +7,7 @@
  * speaks these types.
  */
 /** Agents that store session data on disk and can be discovered by `agents sessions`. */
-export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi';
+export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi' | 'droid';
 /** All agents with session discovery support, in display order. */
 export declare const SESSION_AGENTS: SessionAgentId[];
 /** A single normalized event within a session (message, tool call, thinking, etc.). */

package/dist/lib/session/types.js

@@ -7,4 +7,4 @@
  * speaks these types.
  */
 /** All agents with session discovery support, in display order. */
-export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi'];
+export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid'];

package/dist/lib/ssh-exec.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared SSH exec primitive — the single hardened choke point for running a
+ * command on a remote host over the system `ssh`.
+ *
+ * `agents hosts` dispatch and the browser driver both go through here so the
+ * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
+ * target-injection guard live in exactly one place. Target validation is the
+ * canonical definition; `commands/secrets.ts` re-exports it.
+ */
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s0`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters so a target can't be
+ * smuggled in as part of a remote command, and `sshExec` additionally rejects a
+ * leading `-` so it can never be parsed as an ssh argv flag.
+ */
+export declare const SSH_TARGET_RE: RegExp;
+export declare function assertValidSshTarget(host: string): void;
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export declare function shellQuote(s: string): string;
+/** Hardened ssh options applied to every connection. */
+export declare const SSH_OPTS: readonly string[];
+export interface SshExecOptions {
+    /** Piped to the remote command's stdin (never interpolated into the shell). */
+    input?: string;
+    /** Kill the ssh process after this many ms. */
+    timeoutMs?: number;
+    /** Extra ssh flags inserted before the target (e.g. `-tt`). */
+    extraSshArgs?: string[];
+}
+export interface SshExecResult {
+    /** Remote exit status, or null if ssh itself failed / timed out. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/**
+ * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
+ *
+ * `remoteCmd` is passed as a single argv to ssh (the remote login shell parses
+ * it); callers that build it from user input must `shellQuote` the pieces.
+ */
+export declare function sshExec(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecResult;
+/** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
+export declare function sshReachable(target: string, timeoutMs?: number): boolean;

package/dist/lib/ssh-exec.js

@@ -0,0 +1,61 @@
+/**
+ * Shared SSH exec primitive — the single hardened choke point for running a
+ * command on a remote host over the system `ssh`.
+ *
+ * `agents hosts` dispatch and the browser driver both go through here so the
+ * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
+ * target-injection guard live in exactly one place. Target validation is the
+ * canonical definition; `commands/secrets.ts` re-exports it.
+ */
+import { spawnSync } from 'child_process';
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s0`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters so a target can't be
+ * smuggled in as part of a remote command, and `sshExec` additionally rejects a
+ * leading `-` so it can never be parsed as an ssh argv flag.
+ */
+export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+export function assertValidSshTarget(host) {
+    if (host.startsWith('-') || !SSH_TARGET_RE.test(host)) {
+        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host (letters, digits, '.', '_', '-').`);
+    }
+}
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export function shellQuote(s) {
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(s))
+        return s;
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/** Hardened ssh options applied to every connection. */
+export const SSH_OPTS = [
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=10',
+];
+/**
+ * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
+ *
+ * `remoteCmd` is passed as a single argv to ssh (the remote login shell parses
+ * it); callers that build it from user input must `shellQuote` the pieces.
+ */
+export function sshExec(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const args = [...SSH_OPTS, ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    const res = spawnSync('ssh', args, {
+        input: opts.input,
+        encoding: 'utf-8',
+        timeout: opts.timeoutMs,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    return {
+        code: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout ?? '',
+        stderr: res.stderr ?? '',
+        timedOut,
+    };
+}
+/** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
+export function sshReachable(target, timeoutMs = 10000) {
+    return sshExec(target, 'true', { timeoutMs }).code === 0;
+}

package/dist/lib/startup/command-registry.d.ts

@@ -67,6 +67,8 @@ export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
+export declare const loadHosts: ModuleLoader;
+export declare const loadSsh: ModuleLoader;
 export declare const loadPull: ModuleLoader;
 export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -45,6 +45,8 @@ export const loadPty = async () => (await import('../../commands/pty.js')).regis
 export const loadTmux = async () => (await import('../../commands/tmux.js')).registerTmuxCommands;
 export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
 export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
+export const loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
+export const loadSsh = async () => (await import('../../commands/ssh.js')).registerSshCommands;
 export const loadPull = async () => (await import('../../commands/pull.js')).registerPullCommand;
 export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
 export const loadRepo = async () => (await import('../../commands/repo.js')).registerRepoCommands;
@@ -126,6 +128,9 @@ export const COMMAND_LOADERS = {
     tmux: [loadTmux],
     browser: [loadBrowser],
     computer: [loadComputer],
+    hosts: [loadHosts],
+    ssh: [loadSsh],
+    devices: [loadSsh],
     pull: [loadPull],
     push: [loadPush],
     repo: [loadRepo],

package/dist/lib/state.d.ts

@@ -152,6 +152,8 @@ export declare function getTeamsDir(): string;
 export declare function getTeamsAgentsDir(): string;
 /** Path to the team registry — list of named teams with timestamps. Durable runtime, per-machine. */
 export declare function getTeamsRegistryPath(): string;
+/** Path to the device registry — SSH device profiles with platform/auth metadata. Durable runtime, per-machine (host list + addresses are NOT pulled by `agents repo push`). */
+export declare function getDevicesRegistryPath(): string;
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export declare function getCloudDir(): string;
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/state.js

@@ -334,6 +334,8 @@ export function getTeamsDir() { return TEAMS_DIR; }
 export function getTeamsAgentsDir() { return TEAMS_AGENTS_DIR; }
 /** Path to the team registry — list of named teams with timestamps. Durable runtime, per-machine. */
 export function getTeamsRegistryPath() { return path.join(HISTORY_DIR, 'teams', 'registry.json'); }
+/** Path to the device registry — SSH device profiles with platform/auth metadata. Durable runtime, per-machine (host list + addresses are NOT pulled by `agents repo push`). */
+export function getDevicesRegistryPath() { return path.join(HISTORY_DIR, 'devices', 'registry.json'); }
 /** Path to cloud dispatch cache (~/.agents/.cache/cloud/). */
 export function getCloudDir() { return CLOUD_DIR; }
 /** Path to terminal session metadata (~/.agents/.cache/terminals/). */

package/dist/lib/types.d.ts

@@ -612,6 +612,27 @@ export interface Meta {
      * lives separately in ~/.agents/.cache/browser/<profile>/.
      */
     browser?: Record<string, BrowserProfileConfig>;
+    /**
+     * Agent-host registry keyed by host name (`agents hosts`). Portable user
+     * config synced with `agents repo push/pull`. For `ssh-config` hosts this is
+     * just an overlay (caps/os) — the connection details stay in ~/.ssh/config and
+     * are never copied. `inline` hosts carry their own address/user.
+     */
+    hosts?: Record<string, HostEntry>;
+}
+/** Persisted agent-host entry in agents.yaml (overlay or inline). */
+export interface HostEntry {
+    /** `ssh-config`: reach via the bare name (ssh resolves). `inline`: use address/user below. */
+    source: 'ssh-config' | 'inline';
+    /** SSH-reachable target — inline hosts only (ssh-config hosts omit it). */
+    address?: string;
+    /** SSH user — inline hosts only. */
+    user?: string;
+    /** Captured at enroll probe. */
+    os?: string;
+    /** Free-form capability tags for routing (e.g. ['gpu']). */
+    caps?: string[];
+    addedAt?: string;
 }
 /** Browser profile definition stored in agents.yaml. */
 export interface BrowserProfileConfig {

package/dist/lib/versions.d.ts

@@ -241,12 +241,16 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *
- *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
+ *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
  *   "latest"                    -> highest installed version (process.exit if none installed)
  *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
+ * `pinned` is a synonym for `default`: both name the project pin / global
+ * default, which the caller resolves.
+ *
  * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
  * vocabulary consistent. Subcommands with different semantics for `latest`
  * (install/remove/use, where `latest` means npm-latest) keep their existing
@@ -255,7 +259,7 @@ export declare function resolveVersion(agent: AgentId, projectPath?: string): st
 export declare function resolveVersionAlias(agent: AgentId, raw: string | undefined | null): string | undefined;
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * team history). Same `default`/`pinned`/`latest`/`oldest` semantics, but explicit
  * versions pass through unchanged so historical records of uninstalled versions
  * remain queryable.
  */

package/dist/lib/versions.js

@@ -1363,19 +1363,23 @@ export function resolveVersion(agent, projectPath) {
 /**
  * Normalize a user-supplied @version token across CLI subcommands.
  *
- *   undefined / "" / "default"  -> undefined  (caller falls back to project pin or global default)
+ *   undefined / "" / "default" / "pinned" -> undefined  (caller falls back to project pin or global default)
+ *   "any"                       -> undefined  (caller imposes no version constraint — e.g. resume across any version)
  *   "latest"                    -> highest installed version (process.exit if none installed)
  *   "oldest"                    -> lowest installed version (process.exit if none installed)
  *   "x.y.z" (installed)         -> "x.y.z"
  *   "x.y.z" (not installed)     -> process.exit with installed-list hint
  *
+ * `pinned` is a synonym for `default`: both name the project pin / global
+ * default, which the caller resolves.
+ *
  * Use this anywhere the user can type `agents <cmd> claude@<token>` to keep the
  * vocabulary consistent. Subcommands with different semantics for `latest`
  * (install/remove/use, where `latest` means npm-latest) keep their existing
  * parsing.
  */
 export function resolveVersionAlias(agent, raw) {
-    if (!raw || raw === 'default')
+    if (!raw || raw === 'default' || raw === 'pinned' || raw === 'any')
         return undefined;
     if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);
@@ -1399,12 +1403,12 @@ export function resolveVersionAlias(agent, raw) {
 }
 /**
  * Loose variant of resolveVersionAlias for record-filter contexts (sessions,
- * team history). Same `default`/`latest`/`oldest` semantics, but explicit
+ * team history). Same `default`/`pinned`/`latest`/`oldest` semantics, but explicit
  * versions pass through unchanged so historical records of uninstalled versions
  * remain queryable.
  */
 export function resolveVersionAliasLoose(agent, raw) {
-    if (!raw || raw === 'default')
+    if (!raw || raw === 'default' || raw === 'pinned' || raw === 'any')
         return undefined;
     if (raw === 'latest' || raw === 'oldest') {
         const installed = listInstalledVersions(agent);

package/package.json

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

@@ -239,6 +239,10 @@ To enable version-aware shims, add this to your shell config:
     console.log(`  Installed shorthands: ${written.join(', ')}`);
   }
 
+  if (process.platform !== 'win32') {
+    await ensureAgentsResolvablePosix();
+  }
+
   await healLongRunningProcesses();
 
   const version = getVersion();
@@ -252,6 +256,64 @@ To enable version-aware shims, add this to your shell config:
   }
 }
 
+/**
+ * Make the `agents` command resolvable in a *login* shell on POSIX.
+ *
+ * `agents`/`ag` reach PATH only through npm's bin symlink in the npm global-bin
+ * dir. Under nvm (and other per-user node prefixes) that dir is missing from a
+ * non-interactive login shell's PATH, so `bash -lc 'agents …'` fails with
+ * command-not-found — which breaks `agents secrets export --host` (it runs
+ * `bash -lc 'agents secrets import …'` on the remote) and the routines daemon
+ * (src/lib/daemon.ts falls back to bare `agents`). This is the POSIX symmetric
+ * counterpart of the Windows branch in main() that registers npm's global-bin
+ * dir on the user PATH.
+ *
+ * Self-heal, not a prompt: it fires ONLY when `agents` is otherwise
+ * unresolvable — the genuinely-broken state — so it acts decisively, exactly
+ * like the Windows PATH registration. The symlink never clobbers a dev build
+ * (scripts/install.sh) or any real file. Skipped in CI (ephemeral homes) and
+ * when AGENTS_NO_HEAL=1.
+ */
+async function ensureAgentsResolvablePosix() {
+  if (process.env.CI || process.env.AGENTS_NO_HEAL === '1') return;
+  try {
+    const { localBinDir, ensureLocalBinSymlink, loginShellResolves, dirOnLoginPath } =
+      await import('../dist/lib/platform/posixpath.js');
+
+    // macOS/homebrew, system-node Linux, and dev-build users already resolve it.
+    if (loginShellResolves('agents')) return;
+
+    const binDir = localBinDir();
+    const results = ['agents', 'ag'].map((name) => ensureLocalBinSymlink(name, AGENTS_BIN, binDir));
+    if (!results.some((r) => r.created)) return; // nothing we could safely link
+
+    if (dirOnLoginPath(binDir)) {
+      console.log(`\n  Linked 'agents' into ${binDir} (already on the login PATH) so 'bash -lc agents' resolves.`);
+      return;
+    }
+
+    // ~/.local/bin isn't on the *bash* login PATH yet. The consumers run
+    // `bash -lc`, so add it to the file a bash login shell reads (~/.bash_profile
+    // when present, else ~/.profile) — not the interactive $SHELL rc, which for a
+    // zsh user (.zshrc) bash would never source.
+    const bashRc = fs.existsSync(path.join(HOME, '.bash_profile'))
+      ? path.join(HOME, '.bash_profile')
+      : path.join(HOME, '.profile');
+    const marker = '# agents-cli: ensure ~/.local/bin on PATH (so the agents command resolves)';
+    let already = false;
+    try {
+      already = fs.existsSync(bashRc) && fs.readFileSync(bashRc, 'utf-8').includes(marker);
+    } catch { /* unreadable rc — fall through and append */ }
+    if (!already) {
+      fs.appendFileSync(bashRc, `\n${marker}\nexport PATH="${binDir}:$PATH"\n`);
+    }
+    console.log(`\n  Linked 'agents' into ${binDir} and added it to PATH in ${path.basename(bashRc)}.`);
+    console.log(`  Restart your shell (or run: source ~/${path.basename(bashRc)}) to pick it up.`);
+  } catch {
+    /* best-effort: a failure here must never break the install */
+  }
+}
+
 /**
  * Self-heal long-running processes onto the just-installed code (macOS).
  *