@phnx-labs/agents-cli 1.20.49 → 1.20.50

package/dist/lib/teams/api.d.ts

@@ -20,6 +20,8 @@ export interface SpawnResult {
     task_type?: TaskType | null;
     cloud_provider?: string | null;
     cloud_session_id?: string | null;
+    /** Device name the teammate runs on for a distributed (--on) teammate; null for local. */
+    host?: string | null;
 }
 /** Detailed status of a single teammate, including file ops, commands, and a cursor for delta polling. */
 export interface AgentStatusDetail {
@@ -50,6 +52,8 @@ export interface AgentStatusDetail {
     name?: string | null;
     after?: string[];
     task_type?: TaskType | null;
+    /** Device name the teammate runs on for a distributed (--on) teammate; null for local. */
+    host?: string | null;
 }
 /** Aggregated status of all teammates in a task, with per-status counts and a global cursor. */
 export interface TaskStatusResult {
@@ -107,6 +111,8 @@ export interface AgentStatusSummary {
     bash_commands: string[];
     /** Last 3 messages, each body trimmed to ~400 chars. */
     last_messages: string[];
+    /** Device name for a distributed (--on) teammate; null for local. */
+    host: string | null;
     /** ISO timestamp — feed back via --since for delta polling. */
     cursor: string;
 }
@@ -156,7 +162,7 @@ export interface TasksResult {
     tasks: TaskInfo[];
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null): Promise<SpawnResult>;
+export declare function handleSpawn(manager: AgentManager, taskName: string, agentType: AgentType, prompt: string, cwd: string | null, mode: string | null, effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto' | null, parentSessionId?: string | null, workspaceDir?: string | null, version?: string | null, name?: string | null, after?: string[], model?: string | null, envOverrides?: Record<string, string> | null, taskType?: TaskType | null, cloudProvider?: string | null, cloudSessionId?: string | null, cloudRepo?: string | null, cloudBranch?: string | null, worktreeName?: string | null, worktreePath?: string | null, profileName?: string | null, hostName?: string | null, hostTarget?: string | null, repoPath?: string | null): Promise<SpawnResult>;
 /** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
 export declare function handleStatus(manager: AgentManager, taskName: string | null | undefined, filter?: string, since?: string, // Optional ISO timestamp - return only events after this time
 parentSessionId?: string | null): Promise<TaskStatusResult>;

package/dist/lib/teams/api.js

@@ -121,6 +121,7 @@ export function toAgentStatusSummary(detail) {
         last_messages: detail.last_messages
             .slice(-SUMMARY_MAX_MESSAGES)
             .map((m) => trimMessage(m)),
+        host: detail.host ?? null,
         cursor: detail.cursor,
     };
 }
@@ -134,7 +135,7 @@ export function toTaskStatusSummary(result) {
     };
 }
 /** Spawn a new teammate in a task and return its initial metadata. */
-export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null) {
+export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mode, effort = 'medium', parentSessionId = null, workspaceDir = null, version = null, name = null, after = [], model = null, envOverrides = null, taskType = null, cloudProvider = null, cloudSessionId = null, cloudRepo = null, cloudBranch = null, worktreeName = null, worktreePath = null, profileName = null, hostName = null, hostTarget = null, repoPath = null) {
     const defaultMode = manager.getDefaultMode();
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
@@ -159,7 +160,7 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
             throw new Error(`[budget] BLOCKED teammate "${taskName}" (${agentType}): ${gate.decision.reason}`);
         }
     }
-    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
+    const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName, hostName, hostTarget, repoPath);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {
         task_name: taskName,
@@ -175,6 +176,7 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
         task_type: agent.taskType,
         cloud_provider: agent.cloudProvider,
         cloud_session_id: agent.cloudSessionId,
+        host: agent.hostName,
     };
 }
 /** Retrieve the current status of all teammates in a task, with optional timestamp-based delta filtering. */
@@ -245,6 +247,7 @@ parentSessionId) {
             name: agent.name,
             after: agent.after,
             task_type: agent.taskType,
+            host: agent.hostName,
             mode: agent.mode,
             cloud_session_id: agent.cloudSessionId,
             cloud_provider: agent.cloudProvider,

package/dist/lib/teams/registry.d.ts

@@ -5,6 +5,19 @@ export interface TeamMeta {
     enable_worktrees?: boolean;
     /** Shared worktree path for all teammates (mutually exclusive with enable_worktrees). */
     use_worktree?: string;
+    /**
+     * Distributed teams: the pool of devices this team may auto-schedule teammates
+     * onto (from `agents devices`). One device → the whole team runs there; many →
+     * unpinned teammates are least-loaded-scheduled across them; empty/absent →
+     * every teammate runs locally (today's behavior).
+     */
+    devices?: string[];
+    /**
+     * Distributed teams: how each device gets the code — a git URL to clone or a
+     * path that already exists on the host. Defaults to the local checkout's
+     * `origin` at create time. Used by `ensureRemoteRepo` to provision the repo.
+     */
+    repo?: string;
 }
 /** Map of team name to team metadata. */
 export type TeamRegistry = Record<string, TeamMeta>;
@@ -20,6 +33,10 @@ export interface CreateTeamOptions {
     enableWorktrees?: boolean;
     /** Path to an existing worktree for all teammates to share. */
     useWorktree?: string;
+    /** Distributed pool of devices this team may auto-schedule teammates onto. */
+    devices?: string[];
+    /** How each device gets the code (git URL to clone, or a path on the host). */
+    repo?: string;
 }
 /** Create a new team. Throws if a team with the same name already exists. */
 export declare function createTeam(name: string, options?: CreateTeamOptions): Promise<TeamMeta>;

package/dist/lib/teams/registry.js

@@ -109,6 +109,8 @@ export async function createTeam(name, options) {
             ...(options?.description ? { description: options.description } : {}),
             ...(options?.enableWorktrees ? { enable_worktrees: true } : {}),
             ...(options?.useWorktree ? { use_worktree: options.useWorktree } : {}),
+            ...(options?.devices && options.devices.length ? { devices: options.devices } : {}),
+            ...(options?.repo ? { repo: options.repo } : {}),
         };
         reg[name] = m;
         await saveTeams(reg);

package/dist/lib/teams/remoteWorktree.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Render a path for safe interpolation into a REMOTE shell, expanding a leading
+ * `~`/`~/` to `"$HOME"` so it resolves on the host. A plain `shellQuote('~/x')`
+ * single-quotes the tilde and the remote shell leaves it literal (the same
+ * reason dispatch.ts uses `$HOME`, not `~`). Everything after the tilde is still
+ * single-quoted, so odd path characters stay safe.
+ */
+export declare function remotePathExpr(p: string): string;
+/**
+ * Resolve the ABSOLUTE git top-level for a (possibly `~`-relative) repo path on
+ * the host, or null when it isn't a git repo / the host is unreachable. Used by
+ * `ensureRemoteRepo` to both VALIDATE and CANONICALIZE a repo location, so every
+ * downstream remote command (launch `cd`, worktree create, polling) works from an
+ * absolute path with no tilde-expansion hazard.
+ */
+export declare function resolveRemoteRepoRoot(target: string, repoPath: string): string | null;
+/** True when `repoPath` is a git working tree on the host. */
+export declare function isRemoteGitRepo(target: string, repoPath: string): boolean;
+/**
+ * Resolve the host repo's default branch name (origin/HEAD → `main`/`master`/…).
+ * Falls back to `main` when origin/HEAD isn't set, matching the local recipe's
+ * `remote set-head` step.
+ */
+export declare function remoteDefaultBranch(target: string, repoPath: string): string;
+/**
+ * Create a worktree on the host for a teammate, branched off the freshly-fetched
+ * default branch. Returns the absolute worktree path on the host.
+ *
+ * Mirrors local `createWorktree`, with two deliberate differences: it fetches
+ * origin first (the orchestrator can't reach into the host's tree to do it), and
+ * it bases the branch on `origin/<default>` rather than local `HEAD` so a stale
+ * checkout on the host can't fork the teammate off old code.
+ */
+export declare function createRemoteWorktree(target: string, repoPath: string, worktreeName: string): string;
+/**
+ * Ensure the team's repo is present on the host and return its absolute git
+ * root. The canonical location is `~/.agents/repos/<slug>` (slug = sanitized
+ * team name). Resolution, in order:
+ *
+ *   1. `~/.agents/repos/<slug>` already a git repo  → `git fetch origin`, use it.
+ *   2. `repo` is a path that exists on the host as a git repo → use it in place.
+ *   3. `repo` is a URL (or a non-existent path)      → `git clone` into the
+ *      canonical location, then use it.
+ *
+ * `$HOME`-prefixed paths interpolate UNQUOTED (remotePathExpr) so the host shell
+ * expands `$HOME` — single-quoting the tilde would defeat expansion, the same
+ * hazard dispatch.ts avoids.
+ */
+export declare function ensureRemoteRepo(target: string, repo: string, slug: string): string;
+/** True when the host worktree has uncommitted changes (staged or unstaged). */
+export declare function remoteWorktreeDirty(target: string, worktreePath: string): boolean;
+/**
+ * Remove a host worktree and (optionally) its branch. Best-effort: prunes on a
+ * "not a working tree" error and ignores a missing branch, matching local
+ * `removeWorktree` semantics so cleanup never throws on a half-gone worktree.
+ */
+export declare function removeRemoteWorktree(target: string, repoPath: string, worktreeName: string, deleteBranch?: boolean): void;

package/dist/lib/teams/remoteWorktree.js

@@ -0,0 +1,213 @@
+/**
+ * Remote git-worktree utilities for distributed teams — the SSH analog of
+ * `teams/worktree.ts`. Each function runs the SAME git argv the local helper
+ * runs, but over SSH on the host that owns the teammate's checkout, so a
+ * distributed teammate gets its own branch/worktree without a shared local tree.
+ *
+ * The repo is provisioned on the host by `ensureRemoteRepo` (reuse an existing
+ * checkout or clone the team's `--repo`); we fetch origin and branch the worktree
+ * off `origin/<default>` so remote teammates build on the freshly-fetched default
+ * branch, mirroring the local git-workflow.
+ */
+import { sshExec, shellQuote, assertValidSshTarget } from '../ssh-exec.js';
+import { assertSafeGitTransport } from '../git.js';
+// Same allowlist as the local helper — worktree names land in a branch name and
+// a path, so keep them injection-safe (no shell metacharacters).
+const WORKTREE_NAME_RE = /^[A-Za-z0-9_-]+$/;
+function assertName(worktreeName) {
+    if (!WORKTREE_NAME_RE.test(worktreeName)) {
+        throw new Error(`Invalid worktree name: ${worktreeName}`);
+    }
+}
+/**
+ * Render a path for safe interpolation into a REMOTE shell, expanding a leading
+ * `~`/`~/` to `"$HOME"` so it resolves on the host. A plain `shellQuote('~/x')`
+ * single-quotes the tilde and the remote shell leaves it literal (the same
+ * reason dispatch.ts uses `$HOME`, not `~`). Everything after the tilde is still
+ * single-quoted, so odd path characters stay safe.
+ */
+export function remotePathExpr(p) {
+    if (p === '~')
+        return '"$HOME"';
+    if (p.startsWith('~/'))
+        return '"$HOME"/' + shellQuote(p.slice(2));
+    return shellQuote(p);
+}
+/**
+ * Resolve the ABSOLUTE git top-level for a (possibly `~`-relative) repo path on
+ * the host, or null when it isn't a git repo / the host is unreachable. Used by
+ * `ensureRemoteRepo` to both VALIDATE and CANONICALIZE a repo location, so every
+ * downstream remote command (launch `cd`, worktree create, polling) works from an
+ * absolute path with no tilde-expansion hazard.
+ */
+export function resolveRemoteRepoRoot(target, repoPath) {
+    assertValidSshTarget(target);
+    const cmd = `git -C ${remotePathExpr(repoPath)} rev-parse --show-toplevel 2>/dev/null`;
+    const res = sshExec(target, cmd, { timeoutMs: 15000, multiplex: true });
+    const root = res.stdout.trim();
+    return res.code === 0 && root ? root : null;
+}
+/** Run one git command in `repoPath` on the host; throw with stderr on failure. */
+function remoteGit(target, repoPath, args, timeoutMs = 60000) {
+    const cmd = ['git', '-C', repoPath, ...args].map(shellQuote).join(' ');
+    const res = sshExec(target, cmd, { timeoutMs, multiplex: true });
+    if (res.code !== 0) {
+        throw new Error(`remote git failed on ${target} (${args[0]}): ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
+    }
+    return res.stdout.trim();
+}
+/** True when `repoPath` is a git working tree on the host. */
+export function isRemoteGitRepo(target, repoPath) {
+    assertValidSshTarget(target);
+    // remotePathExpr so a `~`/`$HOME`-relative path (the canonical repos dir) expands
+    // on the host — plain shellQuote would single-quote the tilde into a literal,
+    // making an existing checkout look absent and forcing a doomed re-clone.
+    const cmd = `git -C ${remotePathExpr(repoPath)} rev-parse --git-dir 2>/dev/null`;
+    const res = sshExec(target, cmd, { timeoutMs: 15000, multiplex: true });
+    return res.code === 0;
+}
+/**
+ * Resolve the host repo's default branch name (origin/HEAD → `main`/`master`/…).
+ * Falls back to `main` when origin/HEAD isn't set, matching the local recipe's
+ * `remote set-head` step.
+ */
+export function remoteDefaultBranch(target, repoPath) {
+    assertValidSshTarget(target);
+    try {
+        // Refresh origin/HEAD first so a repo cloned before the default was set resolves.
+        sshExec(target, ['git', '-C', repoPath, 'remote', 'set-head', 'origin', '--auto'].map(shellQuote).join(' '), { timeoutMs: 20000, multiplex: true });
+        const ref = remoteGit(target, repoPath, ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+        return ref.replace(/^origin\//, '') || 'main';
+    }
+    catch {
+        return 'main';
+    }
+}
+/**
+ * Create a worktree on the host for a teammate, branched off the freshly-fetched
+ * default branch. Returns the absolute worktree path on the host.
+ *
+ * Mirrors local `createWorktree`, with two deliberate differences: it fetches
+ * origin first (the orchestrator can't reach into the host's tree to do it), and
+ * it bases the branch on `origin/<default>` rather than local `HEAD` so a stale
+ * checkout on the host can't fork the teammate off old code.
+ */
+export function createRemoteWorktree(target, repoPath, worktreeName) {
+    assertValidSshTarget(target);
+    assertName(worktreeName);
+    const gitRoot = remoteGit(target, repoPath, ['rev-parse', '--show-toplevel']);
+    const base = remoteDefaultBranch(target, gitRoot);
+    const worktreePath = `${gitRoot}/.agents/worktrees/${worktreeName}`;
+    const branchName = `agents/${worktreeName}`;
+    remoteGit(target, gitRoot, ['fetch', 'origin'], 120000);
+    remoteGit(target, gitRoot, ['worktree', 'add', '-b', branchName, worktreePath, `origin/${base}`], 120000);
+    return worktreePath;
+}
+// Team-name → repos-dir slug: same allowlist a worktree name uses, so it lands
+// safely in a path (`~/.agents/repos/<slug>`) with no shell metacharacters.
+const SLUG_RE = /[^A-Za-z0-9_-]/g;
+/** Sanitize a team name into a repos-directory slug (`[A-Za-z0-9_-]` only). */
+function repoSlug(name) {
+    const s = name.replace(SLUG_RE, '-');
+    if (!s)
+        throw new Error(`Cannot derive a repo slug from team name: ${name}`);
+    return s;
+}
+/**
+ * Ensure the team's repo is present on the host and return its absolute git
+ * root. The canonical location is `~/.agents/repos/<slug>` (slug = sanitized
+ * team name). Resolution, in order:
+ *
+ *   1. `~/.agents/repos/<slug>` already a git repo  → `git fetch origin`, use it.
+ *   2. `repo` is a path that exists on the host as a git repo → use it in place.
+ *   3. `repo` is a URL (or a non-existent path)      → `git clone` into the
+ *      canonical location, then use it.
+ *
+ * `$HOME`-prefixed paths interpolate UNQUOTED (remotePathExpr) so the host shell
+ * expands `$HOME` — single-quoting the tilde would defeat expansion, the same
+ * hazard dispatch.ts avoids.
+ */
+export function ensureRemoteRepo(target, repo, slug) {
+    assertValidSshTarget(target);
+    const safeSlug = repoSlug(slug);
+    const canonical = `~/.agents/repos/${safeSlug}`;
+    // 1. Canonical checkout already exists → fetch and reuse.
+    if (isRemoteGitRepo(target, canonical)) {
+        // Best-effort refresh; a fetch failure (offline origin) shouldn't block reuse.
+        sshExec(target, `git -C ${remotePathExpr(canonical)} fetch origin`, { timeoutMs: 120000, multiplex: true });
+        const root = resolveRemoteRepoRoot(target, canonical);
+        if (!root)
+            throw new Error(`Repo at ${canonical} on ${target} vanished mid-provision.`);
+        return root;
+    }
+    // 2. `repo` is a path that already exists on the host as a git repo → use it.
+    if (repo && !looksLikeUrl(repo)) {
+        const existing = resolveRemoteRepoRoot(target, repo);
+        if (existing) {
+            sshExec(target, `git -C ${remotePathExpr(existing)} fetch origin`, { timeoutMs: 120000, multiplex: true });
+            return existing;
+        }
+    }
+    // 3. Clone the URL (or a path-that-wasn't-there) into the canonical location.
+    if (!repo) {
+        throw new Error(`No repo configured for team on ${target}: set \`teams create --repo <url|path>\` ` +
+            `or run this teammate from a git checkout so origin can be inferred.`);
+    }
+    // A `--repo` is a git-transport source that clones ON THE REMOTE HOST — guard it
+    // like the local clone path (plugins.ts) does: reject remote-helper transports
+    // (`ext::sh -c …` runs arbitrary commands at clone time) and a leading `-`, then
+    // pass `--` so a leftover `-` can't be parsed as a git option. shellQuote only
+    // blocks *shell* injection and is orthogonal to *git-transport* injection.
+    assertSafeGitTransport(repo);
+    const clone = sshExec(target, `mkdir -p ${remotePathExpr('~/.agents/repos')} && ` +
+        `git clone -- ${shellQuote(repo)} ${remotePathExpr(canonical)}`, { timeoutMs: 600000, multiplex: true });
+    if (clone.code !== 0) {
+        throw new Error(`git clone ${repo} into ${canonical} on ${target} failed: ` +
+            `${(clone.stderr || clone.stdout).trim() || 'ssh error'}`);
+    }
+    const root = resolveRemoteRepoRoot(target, canonical);
+    if (!root)
+        throw new Error(`Cloned ${repo} into ${canonical} on ${target} but it isn't a git repo.`);
+    return root;
+}
+/** Heuristic: does `repo` look like a git URL (vs a filesystem path)? */
+function looksLikeUrl(repo) {
+    return (/^(https?|git|ssh):\/\//.test(repo) ||
+        /^[^/\s]+@[^/\s]+:/.test(repo) || // scp-style: git@github.com:owner/repo.git
+        repo.startsWith('git@'));
+}
+/** True when the host worktree has uncommitted changes (staged or unstaged). */
+export function remoteWorktreeDirty(target, worktreePath) {
+    assertValidSshTarget(target);
+    const cmd = ['git', '-C', worktreePath, 'status', '--porcelain'].map(shellQuote).join(' ');
+    const res = sshExec(target, cmd, { timeoutMs: 20000, multiplex: true });
+    if (res.code !== 0)
+        return false;
+    return res.stdout.trim().length > 0;
+}
+/**
+ * Remove a host worktree and (optionally) its branch. Best-effort: prunes on a
+ * "not a working tree" error and ignores a missing branch, matching local
+ * `removeWorktree` semantics so cleanup never throws on a half-gone worktree.
+ */
+export function removeRemoteWorktree(target, repoPath, worktreeName, deleteBranch = true) {
+    assertValidSshTarget(target);
+    assertName(worktreeName);
+    const gitRoot = remoteGit(target, repoPath, ['rev-parse', '--show-toplevel']);
+    const worktreePath = `${gitRoot}/.agents/worktrees/${worktreeName}`;
+    const branchName = `agents/${worktreeName}`;
+    const rm = sshExec(target, ['git', '-C', gitRoot, 'worktree', 'remove', '--force', worktreePath].map(shellQuote).join(' '), { timeoutMs: 60000, multiplex: true });
+    if (rm.code !== 0 && /is not a working tree/.test(rm.stderr + rm.stdout)) {
+        sshExec(target, ['git', '-C', gitRoot, 'worktree', 'prune'].map(shellQuote).join(' '), {
+            timeoutMs: 30000,
+            multiplex: true,
+        });
+    }
+    if (deleteBranch) {
+        // Branch may not exist (removed already, or never created) — ignore failure.
+        sshExec(target, ['git', '-C', gitRoot, 'branch', '-D', branchName].map(shellQuote).join(' '), {
+            timeoutMs: 20000,
+            multiplex: true,
+        });
+    }
+}

package/dist/lib/teams/scheduler.d.ts

@@ -0,0 +1,29 @@
+/** Team fields the placement cascade reads (a subset of TeamMeta). */
+export interface PlacementTeam {
+    devices?: string[];
+}
+/**
+ * A roster entry the load counter reads — the shape any teammate satisfies
+ * (AgentProcess included). `status` is compared against `'running'` (the
+ * AgentStatus.RUNNING value) without importing the enum, keeping this leaf pure.
+ */
+export interface RosterEntry {
+    hostName: string | null;
+    status: string;
+}
+/**
+ * Pick the least-loaded device from the pool — the one with the fewest RUNNING
+ * teammates currently assigned to it. Ties break by pool order (first wins), so
+ * an empty pool fills round-robin-ish as teammates launch. Pure: counts the
+ * roster, no I/O.
+ */
+export declare function pickLeastLoaded(devices: string[], roster: RosterEntry[]): string;
+/**
+ * Resolve where a teammate runs. Returns `{ device: null }` for a local run
+ * (no pin, no pool, or the chosen device is the local machine) and
+ * `{ device: <name> }` for a remote placement. See the cascade in the module
+ * header.
+ */
+export declare function resolvePlacement(team: PlacementTeam, explicitDevice: string | null, roster: RosterEntry[]): {
+    device: string | null;
+};

package/dist/lib/teams/scheduler.js

@@ -0,0 +1,78 @@
+/**
+ * Placement scheduler for distributed teams.
+ *
+ * Decides WHERE an unpinned teammate runs, resolving the create→pin→pool→local
+ * cascade from the team's device pool and the live roster. Kept pure and
+ * I/O-free (plain data in, a device name or null out) so it is trivially
+ * testable and can be called from the hot launch path without SSH round-trips.
+ *
+ *   1. teammate has an explicit `--device` pin      → that device
+ *   2. else the team pool has exactly one device     → that device (whole team)
+ *   3. else the team pool has many devices           → least-loaded pick
+ *   4. else (no pin, no pool)                         → null == run local
+ *
+ * A device whose name equals the local machine id is treated as "local" — it
+ * resolves to a null placement so the existing local spawn path runs unchanged,
+ * letting the local machine participate in a pool as just another member.
+ */
+import { machineId } from '../session/sync/config.js';
+/** True when `device` names the local machine (case-insensitive). */
+function isLocalDevice(device) {
+    return device.toLowerCase() === machineId();
+}
+/**
+ * Pick the least-loaded device from the pool — the one with the fewest RUNNING
+ * teammates currently assigned to it. Ties break by pool order (first wins), so
+ * an empty pool fills round-robin-ish as teammates launch. Pure: counts the
+ * roster, no I/O.
+ */
+export function pickLeastLoaded(devices, roster) {
+    if (devices.length === 0) {
+        throw new Error('pickLeastLoaded called with an empty device pool');
+    }
+    const load = new Map();
+    for (const d of devices)
+        load.set(d, 0);
+    for (const r of roster) {
+        if (!r.hostName)
+            continue;
+        if (r.status !== 'running')
+            continue;
+        if (load.has(r.hostName))
+            load.set(r.hostName, (load.get(r.hostName) ?? 0) + 1);
+    }
+    // Iterate the pool in declared order so the first device wins ties.
+    let best = devices[0];
+    let bestLoad = load.get(best) ?? 0;
+    for (const d of devices) {
+        const l = load.get(d) ?? 0;
+        if (l < bestLoad) {
+            best = d;
+            bestLoad = l;
+        }
+    }
+    return best;
+}
+/**
+ * Resolve where a teammate runs. Returns `{ device: null }` for a local run
+ * (no pin, no pool, or the chosen device is the local machine) and
+ * `{ device: <name> }` for a remote placement. See the cascade in the module
+ * header.
+ */
+export function resolvePlacement(team, explicitDevice, roster) {
+    // 1. Explicit pin wins — even without a pool.
+    if (explicitDevice) {
+        return { device: isLocalDevice(explicitDevice) ? null : explicitDevice };
+    }
+    const pool = team.devices ?? [];
+    // 4. No pool → local, exactly like today.
+    if (pool.length === 0)
+        return { device: null };
+    // 2. Pool of one → the whole team runs there.
+    if (pool.length === 1) {
+        return { device: isLocalDevice(pool[0]) ? null : pool[0] };
+    }
+    // 3. Many → least-loaded across the pool.
+    const picked = pickLeastLoaded(pool, roster);
+    return { device: isLocalDevice(picked) ? null : picked };
+}

package/dist/lib/teams/supervisor.js

@@ -17,6 +17,13 @@ export async function runSupervisor(mgr, opts) {
             // `agents teams add` calls). Without this the supervisor only ever
             // sees teammates it created itself.
             await mgr.rescanFromDisk();
+            // Distributed teammates: one ssh-per-host liveness/exit pre-pass BEFORE any
+            // polling this wave, so every subsequent per-teammate status read
+            // (startReady's roster scan + listByTask below) consumes a cached snapshot
+            // instead of each opening its own SSH handshake — no N-round-trips-per-wave
+            // blowup at 10+ remote teammates. No-op for all-local teams. Reads the
+            // in-memory roster directly, so it doesn't itself trigger a poll.
+            await mgr.prefetchRemoteStatus(team);
             const launched = await mgr.startReady(team);
             const all = await mgr.listByTask(team);
             let pending = 0, running = 0, completed = 0, failed = 0;

package/dist/lib/versions.d.ts

@@ -304,6 +304,13 @@ export declare function getInstalledVersion(agent: AgentId, version: string): Pr
  * Deliberately narrow: only the missing-file signature counts. An agent that
  * merely dislikes `--version` (nonzero exit, ordinary error text) or ignores it
  * (times out) must NOT match, so a healthy install is never falsely condemned.
+ *
+ * The trailing phrases catch a gutted install that reports its own breakage
+ * *politely* rather than with a raw ENOENT: @anthropic-ai/claude-code's stub
+ * (run when its postinstall never copied the native binary in) prints "native
+ * binary not installed / postinstall did not run / … optional dependency was not
+ * downloaded" and exits nonzero — which the generic patterns above miss. Anchored
+ * tightly so a healthy `--version` can never emit them.
  */
 export declare function isMissingBinarySignature(output: string): boolean;
 /**

package/dist/lib/versions.js

@@ -1226,6 +1226,40 @@ export async function installVersion(agent, version, onProgress, opts) {
                 /* non-fatal; the install itself succeeded */
             }
         }
+        // The `npm install` above ran with `--ignore-scripts` — the right posture for
+        // the dependency TREE (never run arbitrary transitive postinstalls), but it
+        // also skips the agent package's OWN postinstall, which for some agents is a
+        // required install step. @anthropic-ai/claude-code ships a ~500-byte stub at
+        // `bin/claude.exe` plus per-arch native binaries as optional deps; its
+        // `postinstall` (`node install.cjs`) is what copies the correct native binary
+        // over the stub. Skip it and every launch dies with "native binary not
+        // installed". So run the first-party package's declared postinstall here —
+        // scoped to that one package, never `prepare` (claude-code's `prepare` is an
+        // unconditional `exit 1` publish guard). Same precedent as the keychain-helper
+        // postinstall re-run after a `--ignore-scripts` upgrade (see index.ts).
+        // Best-effort: the integrity gate below is the real backstop — a still-broken
+        // binary (postinstall failed, or a platform with no published native dep)
+        // fails there with the correct message rather than throwing here.
+        if (agentConfig.npmPackage) {
+            // Recompute from installedVersion, not the (possibly renamed) `versionDir`:
+            // the `latest` branch above may have renamed the dir to its concrete version.
+            const pkgRoot = path.join(getVersionDir(agent, installedVersion), 'node_modules', agentConfig.npmPackage);
+            try {
+                const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
+                const postinstall = pkg?.scripts?.postinstall;
+                if (typeof postinstall === 'string' && postinstall.trim()) {
+                    onProgress?.(`Running ${agentConfig.name} postinstall...`);
+                    // The declared postinstall is a shell command string (e.g. `node
+                    // install.cjs`), so it must run through a shell on ALL platforms —
+                    // shell:true, empty args. cwd is the package root; install.cjs anchors
+                    // its paths to __dirname, so that is correct and sufficient.
+                    await execFileAsync(postinstall, [], { cwd: pkgRoot, shell: true });
+                }
+            }
+            catch {
+                /* non-fatal; the integrity gate below catches a still-broken binary */
+            }
+        }
         // Integrity gate: confirm the install actually launches, not just that the
         // JS wrapper landed. A gutted install (wrapper present, native platform
         // binary missing) otherwise gets silently pinned as the default and crashes
@@ -1603,9 +1637,16 @@ export async function getInstalledVersion(agent, version) {
  * Deliberately narrow: only the missing-file signature counts. An agent that
  * merely dislikes `--version` (nonzero exit, ordinary error text) or ignores it
  * (times out) must NOT match, so a healthy install is never falsely condemned.
+ *
+ * The trailing phrases catch a gutted install that reports its own breakage
+ * *politely* rather than with a raw ENOENT: @anthropic-ai/claude-code's stub
+ * (run when its postinstall never copied the native binary in) prints "native
+ * binary not installed / postinstall did not run / … optional dependency was not
+ * downloaded" and exits nonzero — which the generic patterns above miss. Anchored
+ * tightly so a healthy `--version` can never emit them.
  */
 export function isMissingBinarySignature(output) {
-    return /\bENOENT\b|no such file|cannot find|command not found|is not recognized/i.test(output);
+    return /\bENOENT\b|no such file|cannot find|command not found|is not recognized|native binary not installed|postinstall did not run|optional dependency was not downloaded/i.test(output);
 }
 /**
  * Verify a freshly-installed agent can actually LAUNCH — not merely that its JS

package/package.json

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