@phnx-labs/agents-cli 1.22.26 → 1.22.28

package/dist/commands/ssh.js

@@ -31,7 +31,7 @@ import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-targe
 import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
-import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, deviceIdentityArgs, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
 import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
@@ -44,6 +44,7 @@ import { checkAllClis } from '../lib/teams/agents.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
+import { collectLocalHarnessInventory, groupByAccount, renderAccountsMatrix, renderHarnessMatrix, } from '../lib/devices/harness-inventory.js';
 import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js';
 import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort } from './lease.js';
 import { authCellColor, formatCheckedAge, isDeadVerdict, probeLocalFleetAuth, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
@@ -351,7 +352,7 @@ async function probeRemoteFleetStatus(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
     const cmd = buildRemoteAgentsInvocation(['devices', 'status', '--local', '--json'], undefined, isWin ? 'windows' : undefined, env);
-    const res = await sshExecAsync(target.dialTarget, cmd, { timeoutMs: 15000, multiplex: true });
+    const res = await sshExecAsync(target.dialTarget, cmd, { timeoutMs: 15000, multiplex: true, extraSshArgs: target.extraSshArgs });
     if (res.code !== 0) {
         throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
     }
@@ -361,10 +362,10 @@ async function probeRemoteHealth(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
     const versionCmd = buildRemoteAgentsInvocation(['--version'], undefined, isWin ? 'windows' : undefined, env);
-    const versionRes = await sshExecAsync(target.dialTarget, versionCmd, { timeoutMs: 15000, multiplex: true });
+    const versionRes = await sshExecAsync(target.dialTarget, versionCmd, { timeoutMs: 15000, multiplex: true, extraSshArgs: target.extraSshArgs });
     const version = versionRes.code === 0 ? versionRes.stdout.trim().split(/\s+/)[0] || null : null;
     const doctorCmd = buildRemoteAgentsInvocation(['doctor', '--json'], undefined, isWin ? 'windows' : undefined, env);
-    const doctorRes = await sshExecAsync(target.dialTarget, doctorCmd, { timeoutMs: 30000, multiplex: true });
+    const doctorRes = await sshExecAsync(target.dialTarget, doctorCmd, { timeoutMs: 30000, multiplex: true, extraSshArgs: target.extraSshArgs });
     if (doctorRes.code !== 0) {
         throw new Error(doctorRes.timedOut ? 'timed out' : (doctorRes.stderr.trim() || `exit ${doctorRes.code ?? 'unknown'}`));
     }
@@ -425,6 +426,7 @@ async function runFleetStatus(opts) {
         // this is trusted on the default path, not just under `--refresh`.
         skip: fleetHealthSkip(t.skip, statsMap.get(t.device.name)),
         dialTarget: fleetDialTarget(t.device),
+        extraSshArgs: deviceIdentityArgs(t.device),
     }));
     const remote = await fanOutDevices(remoteTargets, probeRemoteHealth);
     for (const result of remote) {
@@ -533,7 +535,7 @@ async function probeRemoteAuth(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
     const cmd = buildRemoteAgentsInvocation(['devices', 'ping', '--local', '--json'], undefined, isWin ? 'windows' : undefined, env);
-    const res = await sshExecAsync(target.dialTarget, cmd, { timeoutMs: 15000, multiplex: true });
+    const res = await sshExecAsync(target.dialTarget, cmd, { timeoutMs: 15000, multiplex: true, extraSshArgs: target.extraSshArgs });
     if (res.code !== 0) {
         throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
     }
@@ -601,6 +603,7 @@ async function runFleetPing(opts) {
         platform: t.device.platform,
         skip: t.skip,
         dialTarget: fleetDialTarget(t.device),
+        extraSshArgs: deviceIdentityArgs(t.device),
     }));
     const probeable = remoteTargets.filter((t) => !t.skip).length;
     const spinner = isInteractiveTerminal() && !opts.json
@@ -645,6 +648,118 @@ async function runFleetPing(opts) {
     if (opts.strict && anyBad)
         process.exitCode = 1;
 }
+/** SSH into a host and read its raw harness rows (the `--local --json` worker). */
+async function probeRemoteHarnesses(target, refresh) {
+    const isWin = /^win/i.test((target.platform ?? '').trim());
+    const env = isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
+    const args = ['devices', 'harnesses', '--local', '--json'];
+    if (refresh)
+        args.push('--refresh');
+    const cmd = buildRemoteAgentsInvocation(args, undefined, isWin ? 'windows' : undefined, env);
+    const res = await sshExecAsync(target.dialTarget, cmd, { timeoutMs: 15000, multiplex: true, extraSshArgs: target.extraSshArgs });
+    if (res.code !== 0) {
+        throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
+    }
+    const parsed = JSON.parse(res.stdout);
+    return parsed.rows ?? [];
+}
+/**
+ * Gather harness rows across the fleet: THIS host in process, every reachable
+ * peer over SSH. Shared by both `harnesses` and `accounts` (they differ only in
+ * how the rows are rendered). Honors an optional `--device` allowlist on both
+ * the local and remote rows. Bounded by the same per-device + overall deadlines
+ * as `fleet ping`, so one unreachable box can never stall the glance.
+ */
+async function collectFleetHarnesses(opts) {
+    const self = machineId();
+    const want = opts.devices?.length ? new Set(opts.devices) : null;
+    const results = [];
+    if (!want || want.has(self)) {
+        const localRows = await collectLocalHarnessInventory({ agents: opts.agents, refresh: opts.refresh });
+        results.push({ host: self, rows: localRows });
+    }
+    const reg = await loadDevices();
+    const planned = planFleetTargets(reg);
+    let remoteTargets = remoteFleetTargets(planned, self).map((t) => ({
+        name: t.device.name,
+        platform: t.device.platform,
+        skip: t.skip,
+        dialTarget: fleetDialTarget(t.device),
+        extraSshArgs: deviceIdentityArgs(t.device),
+    }));
+    if (want)
+        remoteTargets = remoteTargets.filter((t) => want.has(t.name));
+    if (remoteTargets.length > 0) {
+        const probeable = remoteTargets.filter((t) => !t.skip).length;
+        const spinner = isInteractiveTerminal() && !opts.json
+            ? ora(`Probing ${probeable} device${probeable === 1 ? '' : 's'}…`).start()
+            : undefined;
+        let remote;
+        try {
+            const fanOut = fanOutDevices(remoteTargets, (t) => probeRemoteHarnesses(t, !!opts.refresh), { perDeviceTimeoutMs: 15_000 });
+            remote = await raceFleetPingDeadline(fanOut, remoteTargets, 30_000);
+        }
+        finally {
+            spinner?.stop();
+        }
+        for (const r of remote) {
+            if (r.status === 'ok' && r.value) {
+                results.push({ host: r.name, rows: r.value });
+            }
+            else {
+                results.push({
+                    host: r.name,
+                    rows: [],
+                    error: r.error,
+                    skipped: r.reason ? String(r.reason) : undefined,
+                });
+            }
+        }
+    }
+    return results;
+}
+async function runDevicesHarnesses(opts) {
+    if (opts.local) {
+        const rows = await collectLocalHarnessInventory({ agents: opts.agents, refresh: opts.refresh });
+        if (opts.json)
+            console.log(JSON.stringify({ host: machineId(), rows }));
+        else
+            for (const line of renderHarnessMatrix([{ host: machineId(), rows }]))
+                console.log(line);
+        return;
+    }
+    const results = await collectFleetHarnesses(opts);
+    if (opts.json)
+        console.log(JSON.stringify(results, null, 2));
+    else
+        for (const line of renderHarnessMatrix(results))
+            console.log(line);
+}
+async function runDevicesAccounts(opts) {
+    if (opts.local) {
+        const rows = await collectLocalHarnessInventory({ agents: opts.agents, refresh: opts.refresh });
+        if (opts.json)
+            console.log(JSON.stringify({ host: machineId(), accounts: groupByAccount(rows) }));
+        else
+            for (const line of renderAccountsMatrix([{ host: machineId(), rows }]))
+                console.log(line);
+        return;
+    }
+    const results = await collectFleetHarnesses(opts);
+    if (opts.json) {
+        const grouped = results.map((r) => ({
+            host: r.host,
+            error: r.error,
+            skipped: r.skipped,
+            accounts: groupByAccount(r.rows),
+        }));
+        console.log(JSON.stringify(grouped, null, 2));
+    }
+    else {
+        for (const line of renderAccountsMatrix(results))
+            console.log(line);
+    }
+}
 /** Resolve an {@link AuthCellColor} to a chalk painter. Single map for cells + labels. */
 const CELL_PAINT = {
     green: chalk.green,
@@ -777,6 +892,7 @@ Typical workflow:
   agents devices configure mac-mini --max-agents 4 --scheduler off
   agents devices note mac-mini "runs the releases — don't reboot"
   agents devices set win-mini --auth password --bundle muqsit
+  agents devices set worker --auth key --identity-file ~/.ssh/worker_ed25519
   agents devices render --write  # write ~/.ssh/config.d/agents include
   agents fleet update            # roll out latest agents-cli to every online device
   agents fleet run uname -a      # run a command on every online device
@@ -1219,6 +1335,59 @@ Typical workflow:
         const verbose = opts.verbose ?? Boolean(cmd.optsWithGlobals().verbose);
         await runFleetPing({ ...opts, verbose });
     });
+    const csvList = (s) => s ? s.split(',').map((x) => x.trim()).filter(Boolean) : undefined;
+    const harnessInvOpts = (opts) => ({
+        agents: csvList(opts.agents),
+        devices: csvList(opts.device ?? opts.devices),
+        refresh: opts.refresh || opts.live,
+        json: opts.json,
+        local: opts.local,
+    });
+    const harnessesCmd = devicesCmd
+        .command('harnesses')
+        .description('Per device, one row per installed agent@version: account, signed-in, quota, and a single ready verdict. SSH-probes each online box.')
+        .option('--json', 'output machine-readable JSON (per-host rows)')
+        .option('--agents <csv>', 'only these agents (comma-separated)')
+        .option('--device <csv>', 'only these devices (comma-separated); default: every online box')
+        .option('--refresh', 'fetch live quota instead of the cached snapshot (slower)')
+        .option('--live', 'alias of --refresh')
+        .option('--local', "this host only: emit THIS box's rows (the per-host worker the fan-out reads over ssh)")
+        .action(async (opts) => {
+        await runDevicesHarnesses(harnessInvOpts(opts));
+    });
+    setHelpSections(harnessesCmd, {
+        examples: `
+agents devices harnesses                 # every box: agent@version · account · signed · quota · ready
+agents devices harnesses --agents claude,codex   # just these harnesses
+agents devices harnesses --device zion   # one box
+agents devices harnesses --refresh       # live quota (bypass the cached snapshot)
+agents devices harnesses --json          # machine-readable, per-host rows`,
+        notes: `
+"ready" = signed in AND not rate-limited — usable for a run right now.
+Quota is the cached usage snapshot (the daemon warms it); --refresh fetches live.
+Use \`agents devices accounts\` for the same data grouped by account.`,
+    });
+    const accountsCmd = devicesCmd
+        .command('accounts')
+        .description('Per device, one row per account: which harnesses share it, signed-in, quota, and ready. The identity lens on `agents devices harnesses`.')
+        .option('--json', 'output machine-readable JSON (per-host account groups)')
+        .option('--agents <csv>', 'only these agents (comma-separated)')
+        .option('--device <csv>', 'only these devices (comma-separated); default: every online box')
+        .option('--refresh', 'fetch live quota instead of the cached snapshot (slower)')
+        .option('--live', 'alias of --refresh')
+        .option('--local', "this host only: emit THIS box's account groups")
+        .action(async (opts) => {
+        await runDevicesAccounts(harnessInvOpts(opts));
+    });
+    setHelpSections(accountsCmd, {
+        examples: `
+agents devices accounts                  # every box: account · agents · signed · quota · ready
+agents devices accounts --device mac-mini
+agents devices accounts --json           # machine-readable, per-host account groups`,
+        notes: `
+Collapses the installs that share one account (e.g. five claude versions on one
+email) into a single row. Use \`agents devices harnesses\` for the per-install view.`,
+    });
     devicesCmd
         .command('login')
         .description('Log agent CLIs into fleet boxes over SSH: drive each box\'s device-code OAuth, scrape the URL + code, and surface every pending login in one local browser page. Default drives all codes at once; --interactive walks one box at a time (codes requested just-in-time so they don\'t expire).')
@@ -1281,15 +1450,19 @@ Typical workflow:
         .option('--auth <method>', 'key | password')
         .option('--bundle <bundle>', 'secrets bundle holding the password (for --auth password)')
         .option('--bundle-key <key>', "key within the bundle (default 'password')")
+        .option('--identity-file <path>', 'private-key path for --auth key')
+        .option('--clear-identity-file', 'return key auth to ssh-agent/default-key discovery')
         .action(async (name, opts) => {
         try {
             const existing = await mustGetDevice(name);
-            const auth = opts.auth || opts.bundle || opts.bundleKey
-                ? {
-                    method: opts.auth ?? existing.auth.method,
-                    bundle: opts.bundle ?? existing.auth.bundle,
-                    bundleKey: opts.bundleKey ?? existing.auth.bundleKey,
-                }
+            const nextMethod = opts.auth ?? existing.auth.method;
+            if (opts.identityFile && nextMethod !== 'key') {
+                throw new Error('--identity-file requires key auth; pass --auth key in the same command.');
+            }
+            const auth = opts.auth || opts.bundle || opts.bundleKey || opts.identityFile || opts.clearIdentityFile
+                ? nextMethod === 'key'
+                    ? { method: nextMethod, identityFile: opts.clearIdentityFile ? undefined : (opts.identityFile ?? existing.auth.identityFile) }
+                    : { method: nextMethod, bundle: opts.bundle ?? existing.auth.bundle, bundleKey: opts.bundleKey ?? existing.auth.bundleKey }
                 : undefined;
             const d = await upsertDevice(name, {
                 platform: opts.platform ?? undefined,

package/dist/commands/teams.js

@@ -17,7 +17,7 @@ import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } f
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
 import { resolveHost } from '../lib/hosts/registry.js';
-import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
+import { isDeviceAuto, resolveDeviceAuto } from '../lib/smart-launch.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { ensureHostReady } from '../lib/hosts/ready.js';
 import { remoteShellFor } from '../lib/hosts/remote-cmd.js';
@@ -1354,12 +1354,12 @@ export function registerTeamsCommands(program) {
             }
             return h ?? d ?? null;
         })();
-        // `auto` is the same affinity sentinel `agents run --device auto` resolves
+        // `auto` is the same live fleet sentinel `agents run --device auto` resolves
         // (RUSH-2185) — pick the concrete device name up front so the local-machine
         // check right below (and every dieFriction message further down) sees the
         // real target instead of the literal string "auto".
         if (explicitDevice && isDeviceAuto(explicitDevice)) {
-            const plan = resolveDeviceAffinity({});
+            const plan = await resolveDeviceAuto(parseTeammate(teammate).agent);
             const picked = plan.host ?? machineId();
             process.stderr.write(chalk.gray(`[teams] device=auto → ${picked === machineId() ? 'local' : picked}\n`));
             explicitDevice = picked;
@@ -1395,10 +1395,17 @@ export function registerTeamsCommands(program) {
             catch (err) {
                 dieFriction('teams', 'ssh-target-unresolvable', `Can't resolve an ssh target for "${host.name}": ${err.message}`);
             }
-            // Ensure agents-cli is present + version-matched on the host; surface
-            // (not fail on) an agent-not-installed warning, like the run --host path.
+            // Ensure agents-cli is present + the pin is installed on the host.
+            // Bare agent names still only warn; a concrete pin fails loud so
+            // `teams add --device` never stages a teammate the box cannot run
+            // (RUSH-2313). parseTeammate already resolves @latest/etc. to a concrete
+            // version when one is pinned on the teammate spec.
             try {
-                const { warnings } = ensureHostReady(host, { agent: parseTeammate(teammate).agent });
+                const parsed = parseTeammate(teammate);
+                const { warnings } = ensureHostReady(host, {
+                    agent: parsed.agent,
+                    version: parsed.version ?? undefined,
+                });
                 for (const w of warnings)
                     process.stderr.write(chalk.yellow(`[teams] warning: ${w}\n`));
             }
@@ -1417,7 +1424,9 @@ export function registerTeamsCommands(program) {
                 effectiveRepo = (await getRemoteUrl(process.cwd())) ?? '';
             }
             try {
-                hostRepoPath = ensureRemoteRepo(hostTarget, effectiveRepo, team);
+                hostRepoPath = ensureRemoteRepo(hostTarget, effectiveRepo, team, {
+                    extraSshArgs: host.identityFile ? ['-i', host.identityFile, '-o', 'IdentitiesOnly=yes'] : [],
+                });
             }
             catch (err) {
                 dieFriction('teams', 'repo-provision-failed', `Couldn't provision the repo on "${host.name}": ${err.message}\n` +
@@ -2018,11 +2027,12 @@ export function registerTeamsCommands(program) {
             try {
                 if (agent.hostName && agent.hostTarget && agent.repoPath) {
                     // Distributed teammate: guard + remove the worktree ON THE HOST.
-                    if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath)) {
+                    const ssh = { extraSshArgs: agent.hostIdentityFile ? ['-i', agent.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [] };
+                    if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath, ssh)) {
                         worktreeKept = true;
                     }
                     else {
-                        removeRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                        removeRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName, true, ssh);
                     }
                 }
                 else {
@@ -2231,11 +2241,12 @@ export function registerTeamsCommands(program) {
                 try {
                     if (agent.hostName && agent.hostTarget && agent.repoPath) {
                         // Distributed teammate: guard + remove the worktree ON THE HOST.
-                        if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath)) {
+                        const ssh = { extraSshArgs: agent.hostIdentityFile ? ['-i', agent.hostIdentityFile, '-o', 'IdentitiesOnly=yes'] : [] };
+                        if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath, ssh)) {
                             keptWorktrees.push(agent.worktreeName);
                         }
                         else {
-                            removeRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                            removeRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName, true, ssh);
                         }
                     }
                     else {

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -392,15 +392,15 @@ async function showWhatsNew(fromVersion, toVersion) {
 const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
 import { getUpdateCheckPath, getMigratedSentinelPath, getUserAgentsDir, getRuntimeStateDir } from './lib/state.js';
 import { resolveBrandName, disabledCommandsForActiveBrand } from './lib/brand.js';
-import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, findAgentsCliInstalls, resolveRunningPackageRoot, } from './lib/self-update.js';
+import { readUpdateCache, saveUpdateCheck, dismissUpdateVersion, shouldPromptUpgrade, buildMultiInstallInventory, findAgentsCliInstalls, resolveRunningPackageRoot, } from './lib/self-update.js';
 const UPDATE_CHECK_FILE = getUpdateCheckPath();
 /**
- * Warn once when PATH resolves `agents` to a different agents-cli install
- * than the copy that is currently running (or to several). Divergent installs
+ * Warn once when this machine contains a different agents-cli install than the
+ * copy that is currently running (or several). Divergent installs
  * are how self-updates "succeed" without changing the command the user types.
- * The warning re-fires only when the set of install roots changes; dev builds
- * (0.0.0-dev) are ignored because side-by-side dev installs are a supported
- * workflow.
+ * The warning re-fires only when the set of install roots or their helper-copy
+ * safety changes. Dev builds are included because old dev copies can still
+ * overwrite the shared macOS helper bundle non-atomically.
  */
 function maybeWarnMultiInstall() {
     const sentinel = path.join(getRuntimeStateDir(), 'multi-install-warned');
@@ -414,31 +414,26 @@ function maybeWarnMultiInstall() {
         // "/$bunfs" install. This warning is advisory — stay silent instead.
         return;
     }
-    const byRoot = new Map();
-    byRoot.set(runningRoot, { version: VERSION, note: 'running' });
-    for (const install of findAgentsCliInstalls(process.env.PATH || '')) {
-        if (install.version.startsWith('0.0.0-dev'))
-            continue;
-        if (!byRoot.has(install.packageRoot)) {
-            byRoot.set(install.packageRoot, { version: install.version, note: `agents on PATH: ${install.binPath}` });
-        }
-    }
-    if (byRoot.size < 2) {
+    const inventory = buildMultiInstallInventory(runningRoot, VERSION, findAgentsCliInstalls(process.env.PATH || ''));
+    if (inventory.length < 2) {
         try {
             fs.unlinkSync(sentinel);
         }
         catch { /* nothing recorded */ }
         return;
     }
-    const key = [...byRoot.keys()].sort().join('\n');
+    const key = inventory
+        .map((info) => `${info.packageRoot}\t${info.version}\t${info.note}`)
+        .sort()
+        .join('\n');
     try {
         if (fs.readFileSync(sentinel, 'utf-8') === key)
             return;
     }
     catch { /* not warned for this set yet */ }
     console.error(chalk.yellow('Multiple agents-cli installs detected:'));
-    for (const [root, info] of byRoot) {
-        console.error(chalk.gray(`  ${root}  ${info.version}  (${info.note})`));
+    for (const info of inventory) {
+        console.error(chalk.gray(`  ${info.packageRoot}  ${info.version}  (${info.note})`));
     }
     console.error(chalk.gray('Upgrades apply to the running copy. Remove a stale copy with: npm uninstall -g --prefix <prefix> @phnx-labs/agents-cli'));
     try {
@@ -967,6 +962,7 @@ async function registerAllEagerCommands() {
     await reg(loadCost);
     await reg(loadInsights);
     await reg(loadPerf);
+    await reg(loadBench);
     await reg(loadTrends);
     await reg(loadOutput);
     await reg(loadBudget);

package/dist/lib/activity.js

@@ -26,6 +26,7 @@ import { getActivityDir, getUserAgentsDir } from './state.js';
 import { normalizeHost } from './machine-id.js';
 import { projectKeyFromCwd } from './project-key.js';
 import { stampProvenance } from './event-provenance.js';
+import { pythonToolRegistryLiteral, pythonValueFlagsLiteral, } from './session/bash-command.js';
 /** The set of milestone events, for tier classification and ordering. */
 export const MILESTONE_EVENTS = [
     'plan.created',
@@ -730,115 +731,30 @@ def first_line(text, limit=140):
     return ""
 
 
-# Canonical command taxonomy for Bash tool calls. Mirrors the TypeScript
-# registry in lib/session/bash-command.ts; keep them in sync.
+# Canonical command taxonomy for Bash tool calls, generated from the single
+# source of truth in lib/session/bash-command.ts's TOOL_REGISTRY (#1889) so the
+# two can no longer drift — this hook runs standalone under python3 and can't
+# import that module, so the literal below is generated, not hand-duplicated.
 BASH_TOOL_REGISTRY = {
-    "git": {"category": "vcs", "action": "working in git"},
-    "gh": {"category": "vcs", "action": "using GitHub CLI"},
-    "bun": {"category": "build-test", "action": "running bun"},
-    "npm": {"category": "build-test", "action": "running npm"},
-    "pnpm": {"category": "build-test", "action": "running pnpm"},
-    "yarn": {"category": "build-test", "action": "running yarn"},
-    "vitest": {"category": "build-test", "action": "running vitest"},
-    "jest": {"category": "build-test", "action": "running jest"},
-    "mocha": {"category": "build-test", "action": "running mocha"},
-    "pytest": {"category": "build-test", "action": "running pytest"},
-    "cargo": {"category": "build-test", "action": "running cargo"},
-    "go": {"category": "build-test", "action": "running go"},
-    "tsc": {"category": "build-test", "action": "running tsc"},
-    "tsx": {"category": "build-test", "action": "running tsx"},
-    "node": {"category": "build-test", "action": "running node"},
-    "python": {"category": "build-test", "action": "running python"},
-    "python3": {"category": "build-test", "action": "running python"},
-    "make": {"category": "build-test", "action": "running make"},
-    "brew": {"category": "install", "action": "installing with brew"},
-    "pip": {"category": "install", "action": "installing with pip"},
-    "pip3": {"category": "install", "action": "installing with pip"},
-    "apt": {"category": "install", "action": "installing with apt"},
-    "apk": {"category": "install", "action": "installing with apk"},
-    "ssh": {"category": "remote", "action": "using ssh"},
-    "scp": {"category": "remote", "action": "using scp"},
-    "rsync": {"category": "remote", "action": "using rsync"},
-    "curl": {"category": "http", "action": "fetching with curl"},
-    "wget": {"category": "http", "action": "fetching with wget"},
-    "ffmpeg": {"category": "media", "action": "using ffmpeg"},
-    "ffprobe": {"category": "media", "action": "probing media"},
-    "magick": {"category": "media", "action": "using ImageMagick"},
-    "convert": {"category": "media", "action": "converting images"},
-    "composite": {"category": "media", "action": "compositing images"},
-    "montage": {"category": "media", "action": "montaging images"},
-    "identify": {"category": "media", "action": "identifying images"},
-    "realesrgan": {"category": "upscaling", "action": "upscaling with realesrgan"},
-    "realesrgan-ncnn-vulkan": {"category": "upscaling", "action": "upscaling with realesrgan"},
-    "waifu2x": {"category": "upscaling", "action": "upscaling with waifu2x"},
-    "waifu2x-caffe": {"category": "upscaling", "action": "upscaling with waifu2x"},
-    "waifu2x-converter-cpp": {"category": "upscaling", "action": "upscaling with waifu2x"},
-    "swin2sr": {"category": "upscaling", "action": "upscaling with swin2sr"},
-    "resdet": {"category": "upscaling", "action": "detecting upscale"},
-    "id3v2": {"category": "metadata", "action": "editing id3 tags"},
-    "exiftool": {"category": "metadata", "action": "editing exif metadata"},
-    "metaflac": {"category": "metadata", "action": "editing flac metadata"},
-    "vorbiscomment": {"category": "metadata", "action": "editing vorbis comments"},
-    # Shell
-    "rm": {"category": "shell", "action": "removing files"},
-    "mv": {"category": "shell", "action": "moving files"},
-    "cp": {"category": "shell", "action": "copying files"},
-    "mkdir": {"category": "shell", "action": "making directories"},
-    "touch": {"category": "shell", "action": "touching files"},
-    "echo": {"category": "shell", "action": "echoing"},
-    "printf": {"category": "shell", "action": "printing"},
-    "chmod": {"category": "shell", "action": "changing permissions"},
-    "ln": {"category": "shell", "action": "linking files"},
-    "awk": {"category": "shell", "action": "running awk"},
-    "sed": {"category": "shell", "action": "running sed"},
-    "tee": {"category": "shell", "action": "teeing output"},
-    "xargs": {"category": "shell", "action": "running xargs"},
-    # Probes
-    "ls": {"category": "probe", "action": "listing files"},
-    "cat": {"category": "probe", "action": "reading files"},
-    "head": {"category": "probe", "action": "reading files"},
-    "tail": {"category": "probe", "action": "reading files"},
-    "wc": {"category": "probe", "action": "counting"},
-    "stat": {"category": "probe", "action": "statting files"},
-    "file": {"category": "probe", "action": "inspecting files"},
-    "which": {"category": "probe", "action": "locating binaries"},
-    "tree": {"category": "probe", "action": "listing files"},
-    "pwd": {"category": "probe", "action": "printing pwd"},
-    # Search
-    "grep": {"category": "search", "action": "searching"},
-    "rg": {"category": "search", "action": "searching with ripgrep"},
-    "ag": {"category": "search", "action": "searching with the silver searcher"},
-    "fd": {"category": "search", "action": "searching files"},
-    "find": {"category": "search", "action": "finding files"},
-    # Wait
-    "sleep": {"category": "wait", "action": "sleeping"},
-    "wait": {"category": "wait", "action": "waiting"},
+${pythonToolRegistryLiteral()}
 }
 
 # Two-level tools mapped to the flags that consume the following token as their
-# value, per tool; the subcommand scan skips both. Missing a value flag mis-reads
-# the value as the subcommand; over-listing only drops the subcommand (safe). A
-# tool with no such leading flags maps to an empty set. Mirrors VALUE_FLAGS in
-# lib/session/bash-command.ts; TWO_LEVEL_TOOLS is derived from its keys.
+# value, per tool; the subcommand scan skips both. Generated from VALUE_FLAGS in
+# lib/session/bash-command.ts (#1889) — TWO_LEVEL_TOOLS is derived from its keys.
 VALUE_FLAGS = {
-    "git": {"-C", "-c", "--git-dir", "--work-tree"},
-    "gh": {"-R", "--repo"},
-    "bun": {"--cwd"},
-    "npm": {"--prefix", "-w", "--workspace"},
-    "pnpm": {"--filter", "-C", "--dir"},
-    "yarn": {"--cwd"},
-    "cargo": {"--manifest-path"},
-    "docker": {"-H", "--host", "-c", "--context", "--config", "-l", "--log-level"},
-    "kubectl": {"-n", "--namespace", "--kubeconfig", "--context", "--cluster", "--user", "-s", "--server", "--as", "--token", "--cache-dir", "--request-timeout"},
-    "rush": set(),
-    "openclaw": set(),
+${pythonValueFlagsLiteral()}
 }
 
 TWO_LEVEL_TOOLS = set(VALUE_FLAGS.keys())
 
 
 def _unwrap_command(cmd):
-    """Strip wrapper prefixes so the real executable is classified."""
+    """Strip wrapper prefixes so the real executable is classified.
+
+    Mirrors unwrapCommand() in lib/session/bash-command.ts — keep the shapes
+    aligned when extending either side (#1889).
+    """
     s = (cmd or "").strip()
     ssh = re.match(r'^ssh\s+\S+\s+["\']?(.+?)["\']?\s*(?:\|.*)?$', s)
     if ssh:
@@ -847,16 +763,46 @@ def _unwrap_command(cmd):
     env = re.match(r'^([A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|' + r"'[^']*'" + r'|\S+)\s+)+(.+)$', s)
     if env:
         return _unwrap_command(env.group(2))
+    # export VAR=value && command / export A=1 B=2; command
+    export_prefix = re.match(
+        r'^export\s+(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|' + r"'[^']*'" + r'|\S+)\s+)*'
+        r'[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|' + r"'[^']*'" + r'|\S+)\s*(?:&&|;|\n)\s*([\s\S]+)$',
+        s,
+    )
+    if export_prefix:
+        return _unwrap_command(export_prefix.group(1))
     # sudo / time prefix (value-taking flags such as -u user consume their argument)
     prefix = re.match(r'^(?:sudo|time)(?:\s+(?:-[uUgGhpCrtDR]\s+\S+|-\S+))*\s+(.+)$', s)
     if prefix:
         return _unwrap_command(prefix.group(1))
-    cd = re.match(r'^cd\s+\S+\s*&&\s*(.+)$', s)
+    # set -euo pipefail && command / set -x; command
+    set_prefix = re.match(r'^set\s+[^&;\n]+?(?:&&|;|\n)\s*([\s\S]+)$', s)
+    if set_prefix:
+        return _unwrap_command(set_prefix.group(1))
+    # cd foo && command  (also ; and newline separators)
+    cd = re.match(r'^cd\s+\S+\s*(?:&&|;|\n)\s*([\s\S]+)$', s)
     if cd:
         return _unwrap_command(cd.group(1))
     npx = re.match(r'^(?:npx|bunx)\s+(?:-\S+\s+)*(.+)$', s)
     if npx:
         return _unwrap_command(npx.group(1))
+    for_loop = re.match(r'^for\s+[\s\S]+?\bdo\b\s*([\s\S]+?)\s*;?\s*done\b[\s\S]*$', s)
+    if for_loop:
+        return _unwrap_command(for_loop.group(1))
+    until_loop = re.match(r'^until\s+[\s\S]+?\bdo\b\s*([\s\S]+?)\s*;?\s*done\b[\s\S]*$', s)
+    if until_loop:
+        return _unwrap_command(until_loop.group(1))
+    if_cond = re.match(
+        r'^if\s+[\s\S]+?\bthen\b\s*([\s\S]+?)\s*;?\s*(?:elif\b|else\b|fi\b)[\s\S]*$',
+        s,
+    )
+    if if_cond:
+        return _unwrap_command(if_cond.group(1))
+    subshell = re.match(r'^\(\s*([\s\S]+?)\s*\)\s*(?:&&|;|\|\|)[\s\S]*$', s) or re.match(
+        r'^\(\s*([\s\S]+?)\s*\)\s*$', s
+    )
+    if subshell:
+        return _unwrap_command(subshell.group(1))
     return s