@phnx-labs/agents-cli 1.20.49 → 1.20.50

package/dist/lib/teams/agents.js

@@ -20,9 +20,20 @@ import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
 import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
 import { AGENTS, getAccountInfo } from '../agents.js';
-import { resolveVersion, isVersionInstalled } from '../versions.js';
+import { resolveVersion, isVersionInstalled, verifyInstalledBinaryLaunches } from '../versions.js';
 import { sanitizeProcessEnv } from '../secrets/bundles.js';
 import { recordRunName } from '../session/run-names.js';
+import { sshExec, shellQuote } from '../ssh-exec.js';
+import { resolveHost } from '../hosts/registry.js';
+import { sshTargetFor } from '../hosts/types.js';
+import { dispatchAgentsCommand } from '../hosts/dispatch.js';
+import { ensureHostReady } from '../hosts/ready.js';
+import { remoteShellFor } from '../hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../hosts/remote-os.js';
+import { pullRemoteLogDelta, REMOTE_MIRROR_MAX_BYTES } from '../hosts/progress.js';
+import { createRemoteWorktree, ensureRemoteRepo } from './remoteWorktree.js';
+import { getTeam } from './registry.js';
+import { resolvePlacement } from './scheduler.js';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
 // large inactive+purgeable cache the kernel will reclaim under pressure, so
@@ -392,6 +403,50 @@ export function resolveSignInAdvisory(installed, running, probeSignedIn) {
         return { signedIn: null, running: false };
     return { signedIn: running ? true : probeSignedIn, running };
 }
+/**
+ * Collect the same data `agents teams doctor` prints: per-agent install status,
+ * launch health, and advisory sign-in state. Kept in one place so `agents doctor
+ * --devices` can run it locally or compare it against remote JSON without
+ * duplicating the probe logic.
+ */
+export async function collectTeamsDoctorData() {
+    const info = checkAllClis();
+    // Deep integrity probe. `checkAllClis` reports presence (shim + stub guard),
+    // but a gutted native binary still passes that, so actually launch the default
+    // version and flip the agent to not-installed if it won't run.
+    await Promise.all(Object.entries(info).map(async ([name, entry]) => {
+        if (!entry.installed)
+            return;
+        const agent = name;
+        const version = resolveVersion(agent);
+        if (!version)
+            return;
+        const health = await verifyInstalledBinaryLaunches(agent, version);
+        if (!health.ok) {
+            entry.installed = false;
+            entry.path = null;
+            entry.error = `${AGENTS[agent]?.cliCommand ?? name}@${version} is installed but its binary won't launch`
+                + `${health.detail ? ` (${health.detail})` : ''}. Repair: agents add ${agent}@${version}`;
+        }
+    }));
+    // Advisory enrichment only. Sign-in detection is unreliable, so it never
+    // changes the authoritative installed/ready column — it annotates. A running
+    // teammate overrides a negative probe.
+    const running = new Set();
+    try {
+        for (const a of await new AgentManager().listRunning())
+            running.add(a.agentType);
+    }
+    catch { /* no teams yet — leave running empty */ }
+    const result = {};
+    await Promise.all(Object.entries(info).map(async ([name, entry]) => {
+        const isRunning = running.has(name);
+        const probe = entry.installed && !isRunning ? await checkCliSignedIn(name) : false;
+        const auth = resolveSignInAdvisory(entry.installed, isRunning, probe);
+        result[name] = { ...entry, ...auth };
+    }));
+    return result;
+}
 let AGENTS_DIR = null;
 /** Resolve and cache the base directory where teammate process data is stored. */
 export async function getAgentsDir() {
@@ -456,6 +511,29 @@ export class AgentProcess {
     // Worktree isolation: when non-null, this teammate runs in its own git worktree.
     worktreeName = null;
     worktreePath = null;
+    // Distributed teams: when hostName is non-null, this teammate runs on another
+    // machine over SSH (the "remote-host" backend), not as a local process. These
+    // are set post-construction (like startTime/pid) — placement config at add
+    // time (hostName/hostTarget/repoPath) and runtime handles at launch time
+    // (remotePid/remoteLog/remoteExit) — so the giant constructor stays untouched.
+    hostName = null;
+    hostTarget = null;
+    repoPath = null;
+    remotePid = null;
+    remoteLog = null;
+    remoteExit = null;
+    // Offset-tail cursor into the REMOTE log (bytes already pulled). Distinct from
+    // lastReadPos, which tracks the LOCAL mirror the parser consumes.
+    remoteLogOffset = 0;
+    // Per-wave batched-poll snapshot, refreshed each wave by the supervisor's
+    // one-ssh-per-host pre-pass (AgentManager.prefetchRemoteStatus) and read by
+    // isProcessAlive()/readNewEvents() so they skip their own SSH round-trip. It is
+    // set anew (and cleared for uncovered teammates) at the START of every prefetch,
+    // so it persists across BOTH poll passes within one wave (startReady's roster
+    // scan + the supervisor's listByTask) yet never carries into the next wave. Null
+    // outside a batched wave (e.g. a bare `teams status`), where a direct per-teammate
+    // SSH probe is the correctness fallback.
+    remotePollSnapshot = null;
     eventsCache = [];
     lastReadPos = 0;
     baseDir = null;
@@ -607,7 +685,72 @@ export class AgentProcess {
         }
         return latest;
     }
+    /**
+     * For a distributed (remote-host) teammate, pull NEW bytes of the host's log
+     * into the LOCAL mirror the parser consumes, advance the remote offset, and
+     * resolve terminal status from the remote `.exit` sentinel. Runs BEFORE the
+     * local read in readNewEvents(), so the existing stream-json parse path then
+     * runs unchanged over the freshly-mirrored bytes.
+     *
+     * Uses a per-wave batched snapshot (remotePollSnapshot) when the supervisor's
+     * one-ssh-per-host pre-pass populated it; otherwise falls back to its own
+     * round-trips so a bare `teams status`/`teams logs` is still correct.
+     */
+    async syncRemoteMirror() {
+        if (!this.hostName || !this.hostTarget || !this.remoteLog)
+            return;
+        // Pull the new remote bytes and append them to the local mirror the parser
+        // reads. One offset-tail round-trip; nothing to write when the log is quiet.
+        const delta = pullRemoteLogDelta(this.hostTarget, {
+            remoteLog: this.remoteLog,
+            offset: this.remoteLogOffset,
+        });
+        if (delta && delta.bytes.length > 0) {
+            const stdoutPath = await this.getStdoutPath();
+            try {
+                await fs.appendFile(stdoutPath, delta.bytes);
+                this.remoteLogOffset = delta.newOffset;
+            }
+            catch {
+                // best-effort mirror — leave the offset unadvanced so we retry next poll
+            }
+        }
+        // Resolve terminal status from the remote `.exit` sentinel (mirror
+        // reapProcess). Prefer this wave's batched snapshot; else fetch the exit file
+        // directly. The snapshot is left in place (refreshed each wave by prefetch),
+        // so a second poll pass within the same wave reuses it.
+        let exit = null;
+        const snap = this.remotePollSnapshot;
+        if (snap) {
+            exit = snap.exit;
+        }
+        else if (this.remoteExit) {
+            // UNQUOTED so `$HOME` in the dispatch exit path expands on the remote shell.
+            const res = sshExec(this.hostTarget, `cat ${this.remoteExit} 2>/dev/null`, {
+                timeoutMs: 8000,
+                multiplex: true,
+            });
+            exit = res.code === 0 && res.stdout.trim() !== '' ? res.stdout.trim() : null;
+        }
+        // Only latch terminal on a PARSEABLE exit code. A `.exit` that exists but is
+        // momentarily empty (created, not yet written) or garbage must NOT force a
+        // spurious FAILED — leave the teammate RUNNING and let the next poll resolve
+        // it once the code lands. Matches the direct-cat guard above.
+        if (exit !== null && exit.trim() !== '' && this.status === AgentStatus.RUNNING) {
+            const code = Number.parseInt(exit.trim(), 10);
+            if (Number.isFinite(code)) {
+                this.status = code === 0 ? AgentStatus.COMPLETED : AgentStatus.FAILED;
+                if (!this.completedAt)
+                    this.completedAt = new Date();
+            }
+        }
+    }
     async readNewEvents() {
+        // Distributed teammate: mirror the host's new log bytes locally first, then
+        // fall through to the identical local read+parse below.
+        if (this.hostName) {
+            await this.syncRemoteMirror();
+        }
         const stdoutPath = await this.getStdoutPath();
         try {
             const stats = await fs.stat(stdoutPath).catch(() => null);
@@ -663,6 +806,55 @@ export class AgentProcess {
         catch (err) {
             console.error(`Error reading events for agent ${this.agentId}:`, err);
         }
+        // Distributed teammate: keep the orchestrator bounded across 10+ remote
+        // teammates. The parser has already consumed everything up to lastReadPos
+        // (status/digest updated), so both the on-disk mirror tail and the in-memory
+        // event backlog are safe to trim. The host keeps the full log.
+        if (this.hostName) {
+            await this.capMirrorToTail();
+            this.capEventsCache();
+        }
+    }
+    /**
+     * Truncate the local mirror to its trailing REMOTE_MIRROR_MAX_BYTES and reset
+     * lastReadPos to the new (smaller) size so the parser doesn't re-read the kept
+     * tail. Only trims when over the cap — a normal-length log is untouched.
+     */
+    async capMirrorToTail() {
+        const stdoutPath = await this.getStdoutPath();
+        try {
+            const stats = await fs.stat(stdoutPath).catch(() => null);
+            if (!stats || stats.size <= REMOTE_MIRROR_MAX_BYTES)
+                return;
+            const keep = REMOTE_MIRROR_MAX_BYTES;
+            const fd = await fs.open(stdoutPath, 'r');
+            const buf = Buffer.alloc(keep);
+            const { bytesRead } = await fd.read(buf, 0, keep, stats.size - keep);
+            await fd.close();
+            await fs.writeFile(stdoutPath, buf.subarray(0, bytesRead));
+            // The parser consumed up to lastReadPos already; after truncation the file
+            // is `bytesRead` long, so clamp the cursor to the new EOF. It never needs
+            // to re-read the retained tail (events already cached).
+            this.lastReadPos = Math.min(this.lastReadPos, bytesRead);
+        }
+        catch {
+            // best-effort — a failed cap just leaves the mirror larger this wave
+        }
+    }
+    /** Cap on the in-memory event backlog kept per remote teammate. */
+    static REMOTE_EVENTS_MAX = 200;
+    /**
+     * Drop the oldest cached events for a remote teammate once past the cap. The
+     * status path only needs recent events (last N messages, recentToolCalls,
+     * terminal status) and the getDelta cursor filters by timestamp, so a bounded
+     * recent window preserves the digest while bounding the heap. Terminal status
+     * is already latched onto `this.status`, so trimming can't lose it.
+     */
+    capEventsCache() {
+        const max = AgentProcess.REMOTE_EVENTS_MAX;
+        if (this.eventsCache.length > max) {
+            this.eventsCache = this.eventsCache.slice(-max);
+        }
     }
     async saveMeta() {
         const agentDir = await this.getAgentDir();
@@ -697,6 +889,13 @@ export class AgentProcess {
             cloud_branch: this.cloudBranch,
             worktree_name: this.worktreeName,
             worktree_path: this.worktreePath,
+            host_name: this.hostName,
+            host_target: this.hostTarget,
+            repo_path: this.repoPath,
+            remote_pid: this.remotePid,
+            remote_log: this.remoteLog,
+            remote_exit: this.remoteExit,
+            remote_log_offset: this.remoteLogOffset,
         };
         const metaPath = await this.getMetaPath();
         await fs.writeFile(metaPath, JSON.stringify(meta, null, 2));
@@ -738,6 +937,15 @@ export class AgentProcess {
                 ? meta.task_type
                 : null, meta.cloud_repo || null, meta.cloud_branch || null, meta.worktree_name || null, meta.worktree_path || null, meta.profile_name || null);
             agent.startTime = typeof meta.start_time === 'string' ? meta.start_time : null;
+            // Distributed-team fields: set post-construction (like startTime) so the
+            // constructor signature stays fixed. Null on every pre-existing teammate.
+            agent.hostName = meta.host_name || null;
+            agent.hostTarget = meta.host_target || null;
+            agent.repoPath = meta.repo_path || null;
+            agent.remotePid = typeof meta.remote_pid === 'number' ? meta.remote_pid : null;
+            agent.remoteLog = meta.remote_log || null;
+            agent.remoteExit = meta.remote_exit || null;
+            agent.remoteLogOffset = typeof meta.remote_log_offset === 'number' ? meta.remote_log_offset : 0;
             return agent;
         }
         catch {
@@ -745,6 +953,27 @@ export class AgentProcess {
         }
     }
     isProcessAlive() {
+        // Distributed teammate: a local PID is meaningless. Alive = the remote `.exit`
+        // sentinel is absent AND `kill -0 <remotePid>` succeeds on the host, resolved
+        // in a single ssh round-trip. Prefer the supervisor's batched snapshot when
+        // present (consume it once so it can't go stale); otherwise probe directly.
+        if (this.hostName) {
+            // Prefer this wave's batched snapshot (persists across the wave's poll
+            // passes; the supervisor refreshes it each wave). Fall back to a direct
+            // probe outside a wave.
+            if (this.remotePollSnapshot)
+                return this.remotePollSnapshot.alive;
+            if (!this.hostTarget || !this.remotePid || !this.remoteExit)
+                return false;
+            // remoteExit is a dispatch `$HOME/.agents/.cache/hosts/<hex>.exit` path —
+            // interpolate UNQUOTED so `$HOME` expands (shellQuote would defeat it).
+            const probe = `test -f ${this.remoteExit} && echo DEAD || ` +
+                `(kill -0 ${this.remotePid} 2>/dev/null && echo ALIVE || echo DEAD)`;
+            const res = sshExec(this.hostTarget, probe, { timeoutMs: 8000, multiplex: true });
+            if (res.code === null)
+                return true; // transient ssh failure — don't reap early
+            return res.stdout.trim().endsWith('ALIVE');
+        }
         if (!this.pid)
             return false;
         try {
@@ -768,6 +997,19 @@ export class AgentProcess {
     }
     async updateStatusFromProcess() {
         if (!this.pid) {
+            // Distributed (remote-host) teammates have no local PID by design; their
+            // lifecycle lives on the host. readNewEvents() mirrors the remote log and
+            // resolves terminal status from the remote `.exit` sentinel (see
+            // syncRemoteMirror), so we just persist and return — never the local
+            // "RUNNING without a PID is impossible" fail path below.
+            if (this.hostName) {
+                await this.readNewEvents();
+                if (this.status !== AgentStatus.RUNNING && !this.completedAt) {
+                    this.completedAt = this.getLatestEventTime() || this.startedAt || new Date();
+                }
+                await this.saveMeta();
+                return;
+            }
             await this.readNewEvents();
             // Cloud-backed teammates have no local PID by design; their lifecycle
             // is driven by the remote provider instead of a local process.
@@ -997,7 +1239,7 @@ export class AgentManager {
         }
         debug(`Loaded ${loadedCount} agents from disk`);
     }
-    async spawn(taskName, agentType, prompt, cwd = null, mode = null, 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) {
+    async spawn(taskName, agentType, prompt, cwd = null, mode = null, 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) {
         await this.initialize();
         const resolvedMode = resolveMode(mode, this.defaultMode);
         // Enforce: teammate names are unique within a team.
@@ -1043,7 +1285,11 @@ export class AgentManager {
         // local CLI for them (the pod has its own). The caller has already
         // dispatched via the cloud provider and passed us the provider + session.
         const isCloudBacked = Boolean(cloudProvider);
-        if (!isCloudBacked) {
+        // Distributed teammates run on another machine over SSH — the agent CLI must
+        // be present on the HOST (checked via ensureHostReady in the command), not
+        // locally. So skip the local availability check for both remote backends.
+        const isRemoteBacked = Boolean(hostName);
+        if (!isCloudBacked && !isRemoteBacked) {
             // Profile-backed teammates still spawn through `agents run`, which
             // resolves the profile to its host harness — so the CLI we need to be
             // present is the underlying agentType, not the profile name.
@@ -1060,6 +1306,12 @@ export class AgentManager {
             ? AgentStatus.PENDING
             : AgentStatus.RUNNING;
         const agent = new AgentProcess(agentId, taskName, agentType, prompt, resolvedCwd, resolvedMode, null, initialStatus, new Date(), null, this.agentsDir, parentSessionId, workspaceDir, cloudSessionId, cloudProvider, null, version, null, name, cleanAfter, effort, model, envOverrides && Object.keys(envOverrides).length > 0 ? envOverrides : null, taskType, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
+        // Distributed-team placement: set post-construction (like startTime), so the
+        // giant constructor stays fixed. launchRemoteProcess() reads these to dispatch
+        // over SSH and fills in the runtime handles (remotePid/remoteLog/remoteExit).
+        agent.hostName = hostName;
+        agent.hostTarget = hostTarget;
+        agent.repoPath = repoPath;
         const agentDir = await agent.getAgentDir();
         try {
             await fs.mkdir(agentDir, { recursive: true });
@@ -1086,8 +1338,20 @@ export class AgentManager {
             await agent.saveMeta();
             debug(`Cloud-backed ${agentType} teammate via ${cloudProvider} (session=${cloudSessionId})`);
         }
+        else if (isRemoteBacked) {
+            // Distributed teammate that can run now (no unmet --after deps): dispatch
+            // it onto its host over SSH instead of a local spawn.
+            await this.launchRemoteProcess(agent);
+        }
         else {
-            await this.launchProcess(agent);
+            // Unpinned + launching now: consult the pool scheduler before defaulting to
+            // local, so an unpinned teammate on a --devices team auto-schedules even when
+            // added without --after (it wouldn't pass through startReady otherwise).
+            await this.maybeSchedulePlacement(agent, taskName);
+            if (agent.hostName)
+                await this.launchRemoteProcess(agent);
+            else
+                await this.launchProcess(agent);
         }
         await this.cleanupOldAgents();
         return agent;
@@ -1149,6 +1413,182 @@ export class AgentManager {
         }
         debug(`Launched agent ${agent.agentId} with PID ${agent.pid}`);
     }
+    /**
+     * Dispatch a distributed teammate onto its host over SSH — the remote-host
+     * analog of launchProcess(). Symmetric to the cloud path: no local process; the
+     * lifecycle lives on the host and is polled (isProcessAlive/readNewEvents over
+     * SSH via the remote `.exit` sentinel + offset-tailed log).
+     *
+     * When the team uses worktrees (agent.worktreeName set), a git worktree is first
+     * created ON THE HOST off the freshly-fetched default branch; the teammate runs
+     * there. Otherwise it runs in the host repo path directly.
+     */
+    async launchRemoteProcess(agent) {
+        if (!agent.hostName || !agent.hostTarget || !agent.repoPath) {
+            throw new Error(`Remote teammate ${agent.agentId} is missing host placement (host/target/repo).`);
+        }
+        // Re-resolve the device → Host at launch time (it may have moved / changed
+        // address since `add` staged the teammate), matching how the command resolved
+        // it. The target string on the agent stays the launch-time source of truth for
+        // subsequent polling.
+        const host = await resolveHost(agent.hostName);
+        if (!host) {
+            throw new Error(`Cannot launch remote teammate ${agent.agentId}: device "${agent.hostName}" no longer resolves.`);
+        }
+        // Ensure agents-cli is present + version-matched on the host; surface (not
+        // fail on) an agent-not-installed warning like dispatch.ts does.
+        try {
+            const { warnings } = ensureHostReady(host, { agent: agent.agentType });
+            for (const w of warnings)
+                process.stderr.write(`[teams] warning: ${w}\n`);
+        }
+        catch (err) {
+            throw new Error(`Host "${agent.hostName}" not ready for teammate ${agent.agentId}: ${err.message}`);
+        }
+        // Worktree isolation on the host, if the team enables it. createRemoteWorktree
+        // fetches origin and branches off origin/<default>, returning the host path.
+        let remoteCwd = agent.repoPath;
+        if (agent.worktreeName) {
+            const worktreePath = createRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+            agent.worktreePath = worktreePath;
+            remoteCwd = worktreePath;
+        }
+        // Same run argv the local path builds (shared buildRunArgv keeps the prompt
+        // scaffolding + flags from drifting); dispatched non-blocking (follow:false)
+        // — the supervisor polls the host, we don't block here.
+        const effort = agent.effort ?? 'medium';
+        const forwardedArgs = this.buildRunArgv(agent.agentType, agent.prompt, agent.mode, agent.model ?? null, effort, agent.version, agent.profileName);
+        try {
+            const { task } = await dispatchAgentsCommand(host, {
+                forwardedArgs,
+                remoteCwd,
+                follow: false,
+            });
+            agent.remotePid = task.pid ?? null;
+            agent.remoteLog = task.remoteLog ?? null;
+            agent.remoteExit = task.remoteExit ?? null;
+            agent.remoteLogOffset = 0;
+            agent.status = AgentStatus.RUNNING;
+            agent.startedAt = new Date();
+            await agent.saveMeta();
+        }
+        catch (err) {
+            console.error(`Failed to launch remote teammate ${agent.agentId} on ${agent.hostName}:`, err);
+            throw new Error(`Failed to launch remote teammate: ${err.message}`);
+        }
+        debug(`Launched remote agent ${agent.agentId} on ${agent.hostName} (remote pid ${agent.remotePid})`);
+    }
+    /**
+     * Resolve a scheduler-picked device to host placement fields on an unpinned
+     * teammate at LAUNCH time (the same resolution `teams add --device` runs, minus
+     * the fatal `die()` — a scheduling failure here is per-teammate, not per-add).
+     * Sets hostName/hostTarget/repoPath + persists, so the subsequent
+     * launchRemoteProcess dispatches over SSH. Mirrors the `add`-time pin path:
+     * resolve device → reject Windows (POSIX-only) → ssh target → ensure the repo
+     * is present on the host from the team's --repo (ensureRemoteRepo).
+     */
+    async resolveScheduledPlacement(agent, device, taskName) {
+        const host = await resolveHost(device);
+        if (!host) {
+            throw new Error(`Scheduler picked device "${device}" but it no longer resolves.`);
+        }
+        if (remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)) === 'powershell') {
+            throw new Error(`Scheduler picked Windows device "${host.name}", but distributed teammates are POSIX-only in v1.`);
+        }
+        const target = sshTargetFor(host);
+        const teamMeta = await getTeam(taskName);
+        const repoRoot = ensureRemoteRepo(target, teamMeta?.repo ?? '', taskName);
+        agent.hostName = host.name;
+        agent.hostTarget = target;
+        agent.repoPath = repoRoot;
+        await agent.saveMeta();
+    }
+    /**
+     * Place an UNPINNED, non-cloud teammate onto the team pool via the cascade
+     * (least-loaded), if the team declares one. A no-op for a pinned teammate
+     * (hostName already set from `--device`), a cloud teammate, or a poolless team —
+     * leaving hostName null so the local spawn runs unchanged. Shared by spawn()
+     * (immediate add-launch) and startReady() (staged launch) so an unpinned pool
+     * teammate schedules identically no matter how it was fired.
+     */
+    async maybeSchedulePlacement(agent, taskName) {
+        if (agent.hostName || agent.cloudProvider)
+            return;
+        const teamMeta = await getTeam(taskName);
+        if (!teamMeta)
+            return;
+        const roster = await this.listByTask(taskName);
+        const { device } = resolvePlacement(teamMeta, null, roster);
+        if (device)
+            await this.resolveScheduledPlacement(agent, device, taskName);
+    }
+    /**
+     * One-ssh-per-host batched liveness/exit pre-pass for a team's remote teammates.
+     * The supervisor calls this each wave BEFORE listByTask() so the per-teammate
+     * isProcessAlive()/readNewEvents() consume a cached snapshot instead of each
+     * issuing its own SSH handshake — avoiding N round-trips per wave at 10+ remote
+     * teammates. Groups by hostTarget and, for each host, checks every teammate's
+     * `.exit` + `kill -0` in a single ssh call over the shared ControlMaster socket.
+     */
+    async prefetchRemoteStatus(taskName) {
+        await this.initialize();
+        // Read the in-memory roster directly — going through listByTask()/listAll()
+        // would poll each teammate first (an SSH round-trip apiece), defeating the
+        // batch. The caller (supervisor) has already rescanned from disk this wave.
+        const remotes = Array.from(this.agents.values()).filter((a) => a.taskName === taskName && a.hostName);
+        // Fresh snapshots each wave: clear stale ones first so a teammate that has
+        // since finished (dropped from the RUNNING filter below) can't carry an old
+        // ALIVE reading into this wave's poll.
+        for (const a of remotes)
+            a.remotePollSnapshot = null;
+        const teammates = remotes.filter((a) => a.hostTarget && a.remotePid && a.remoteExit &&
+            a.status === AgentStatus.RUNNING);
+        if (teammates.length === 0)
+            return;
+        const byTarget = new Map();
+        for (const a of teammates) {
+            const arr = byTarget.get(a.hostTarget) || [];
+            arr.push(a);
+            byTarget.set(a.hostTarget, arr);
+        }
+        for (const [target, agents] of byTarget) {
+            // Emit one line per teammate: "<agentId> ALIVE|DEAD <exitOrEmpty>". A single
+            // round-trip over the multiplexed socket, regardless of teammate count.
+            const parts = agents.map((a) => {
+                const id = a.agentId;
+                // remoteExit is a dispatch `$HOME/.agents/.cache/hosts/<hex>.exit` path —
+                // interpolate UNQUOTED so `$HOME` expands (shellQuote would make `[ -f ]`
+                // always miss, so a finished teammate would never resolve terminal).
+                const exitFile = a.remoteExit;
+                // exit code (if the sentinel exists) OR empty, then liveness.
+                return (`printf '%s ' ${shellQuote(id)}; ` +
+                    `if [ -f ${exitFile} ]; then printf 'DEAD '; cat ${exitFile} 2>/dev/null | tr -d '\\n'; printf '\\n'; ` +
+                    `elif kill -0 ${a.remotePid} 2>/dev/null; then printf 'ALIVE\\n'; ` +
+                    `else printf 'DEAD\\n'; fi`);
+            });
+            const res = sshExec(target, parts.join('; '), { timeoutMs: 12000, multiplex: true });
+            if (res.code === null)
+                continue; // transient ssh failure — skip this wave, no snapshot
+            const snapshots = new Map();
+            for (const line of res.stdout.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const [id, state, exit] = trimmed.split(/\s+/);
+                if (!id)
+                    continue;
+                snapshots.set(id, {
+                    alive: state === 'ALIVE',
+                    exit: state === 'DEAD' ? (exit ?? '') : null,
+                });
+            }
+            for (const a of agents) {
+                const snap = snapshots.get(a.agentId);
+                if (snap)
+                    a.remotePollSnapshot = snap;
+            }
+        }
+    }
     /**
      * Fire any pending teammates in the given team whose `after` deps have all
      * completed. Returns the list of teammates just launched. Repeatable:
@@ -1169,8 +1609,24 @@ export class AgentManager {
             });
             if (!depsReady)
                 continue;
+            // Auto-scheduling: an UNPINNED teammate (no explicit --device at add time)
+            // gets placed now via the pool cascade — same helper spawn() uses so the
+            // immediate-add and staged paths agree. A null pick keeps hostName null →
+            // local spawn, unchanged. Cloud teammates never schedule.
+            try {
+                await this.maybeSchedulePlacement(agent, taskName);
+            }
+            catch (err) {
+                console.error(`Could not schedule ${agent.agentId} onto the team pool:`, err);
+                continue;
+            }
             try {
-                if (agent.cloudProvider) {
+                if (agent.hostName) {
+                    // Distributed teammate: dispatch onto its host over SSH.
+                    await this.launchRemoteProcess(agent);
+                    launched.push(agent);
+                }
+                else if (agent.cloudProvider) {
                     if (!this.cloudDispatcher) {
                         console.error(`Cannot start cloud-backed teammate ${agent.agentId}: no dispatcher registered.`);
                         continue;
@@ -1200,7 +1656,20 @@ export class AgentManager {
      * exec path (src/lib/exec.ts). The team runner just supplies prompt + mode
      * and reads stream-json events off stdout.
      */
-    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
+    /**
+     * Build the `agents run …` argv AFTER the `agents` binary — the flags + prompt
+     * scaffolding shared by the LOCAL launch (buildCommand, which prefixes
+     * process.execPath + the agents CLI path) and the REMOTE launch
+     * (launchRemoteProcess, which prefixes `agents` on the host via dispatch). Kept
+     * in one place so the PROMPT_SUFFIX / CLAUDE_PLAN_MODE_PREFIX scaffolding and the
+     * flag set can never drift between the two backends.
+     *
+     * `cwd` is intentionally NOT emitted here: the local path passes it as
+     * `--cwd`/`--add-dir` (below), while the remote path `cd`s into the host cwd
+     * before invoking `agents`. `sessionId` is likewise local-only (the remote run
+     * mints its own session on the host).
+     */
+    buildRunArgv(agentType, prompt, mode, model, effort, version, profileName) {
         // Compose the prompt: a plan-mode prefix for Claude (clarifying headless
         // plan-mode restrictions) and a universal summary suffix. These are
         // team-specific prompt scaffolding — `agents run` does not apply them.
@@ -1212,10 +1681,7 @@ export class AgentManager {
         // host harness, version pin, and env injection in one place. Plain
         // version pins only apply when no profile is selected.
         const target = profileName ?? (version ? `${agentType}@${version}` : agentType);
-        const agentsCli = process.argv[1];
-        const cmd = [
-            process.execPath,
-            agentsCli,
+        const args = [
             'run',
             target,
             fullPrompt,
@@ -1226,7 +1692,16 @@ export class AgentManager {
             '--quiet',
         ];
         if (model)
-            cmd.push('--model', model);
+            args.push('--model', model);
+        return args;
+    }
+    buildCommand(agentType, prompt, mode, model, cwd = null, sessionId = null, effort = 'medium', version = null, profileName = null) {
+        const agentsCli = process.argv[1];
+        const cmd = [
+            process.execPath,
+            agentsCli,
+            ...this.buildRunArgv(agentType, prompt, mode, model, effort, version, profileName),
+        ];
         if (cwd)
             cmd.push('--cwd', cwd);
         // Pin Claude's session UUID to our agent_id so its session file lands at
@@ -1339,6 +1814,31 @@ export class AgentManager {
         if (!agent) {
             return false;
         }
+        // Distributed teammate: no local PID — signal it over SSH. Try the process
+        // GROUP first (negative pid, matching local `kill(-pid)`) to catch the
+        // detached `agents run` and its children; but the remote launcher is
+        // `nohup bash -lc … &` under a non-interactive shell where job control is off,
+        // so `&` may NOT open a new group — fall back to signalling the wrapper pid
+        // directly. Best-effort either way; the `.exit` sentinel is the durable
+        // terminal-status source if a grandchild lingers.
+        if (agent.hostName && agent.status === AgentStatus.RUNNING) {
+            if (agent.hostTarget && agent.remotePid) {
+                try {
+                    sshExec(agent.hostTarget, `kill -TERM -- -${agent.remotePid} 2>/dev/null || kill -TERM ${agent.remotePid} 2>/dev/null`, {
+                        timeoutMs: 10000,
+                        multiplex: true,
+                    });
+                }
+                catch {
+                    // best-effort — record the stop regardless
+                }
+            }
+            agent.status = AgentStatus.STOPPED;
+            agent.completedAt = new Date();
+            await agent.saveMeta();
+            debug(`Stopped remote agent ${agentId} on ${agent.hostName}`);
+            return true;
+        }
         if (agent.pid && agent.status === AgentStatus.RUNNING) {
             // PID-reuse guard: if the PID we recorded at spawn no longer maps to
             // our process (start-time mismatch), the OS has recycled it. Sending