@phnx-labs/agents-cli 1.20.48 → 1.20.50

package/dist/commands/teams.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
-import { AgentManager, checkAllClis, checkCliSignedIn, getAgentsDir, resolveSignInAdvisory, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { AgentManager, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
 import { debug } from '../lib/teams/debug.js';
@@ -11,7 +11,15 @@ import { handleSpawn, handleStatus, handleStop, handleTasks, toTaskStatusSummary
 import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
-import { isVersionInstalled, resolveVersion, resolveVersionAlias, resolveVersionAliasLoose, verifyInstalledBinaryLaunches } from '../lib/versions.js';
+import { resolveHost } from '../lib/hosts/registry.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
+import { ensureHostReady } from '../lib/hosts/ready.js';
+import { remoteShellFor } from '../lib/hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
+import { remoteWorktreeDirty, removeRemoteWorktree, ensureRemoteRepo } from '../lib/teams/remoteWorktree.js';
+import { getRemoteUrl } from '../lib/git.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { isVersionInstalled, resolveVersionAlias, resolveVersionAliasLoose } from '../lib/versions.js';
 import { AGENTS, warnAgentDeprecated } from '../lib/agents.js';
 import { discoverSessions, parseTimeFilter, resolveSessionById } from '../lib/session/discover.js';
 import { renderSessionLog } from './sessions.js';
@@ -486,6 +494,9 @@ function printAgentDetail(a, session) {
     if (a.after && a.after.length) {
         console.log(`    ${chalk.gray('after   ')} ${a.after.join(', ')}`);
     }
+    if (a.host) {
+        console.log(`    ${chalk.gray('host    ')} ${chalk.cyan(a.host)}`);
+    }
     // If the agent's internal session id differs from ours (non-Claude), show
     // it as a hint for `agents sessions <id>`.
     if (a.remote_session_id && a.remote_session_id !== a.agent_id) {
@@ -569,7 +580,8 @@ function printAgentSummary(s) {
     const duration = s.duration ? `${chalk.gray(' · ')}${chalk.white(s.duration)}` : '';
     const errBadge = s.has_errors ? chalk.red(' !') : '';
     const tools = chalk.gray(` · ${s.tool_count} tools`);
-    console.log(`  ${chalk.cyan(handle.padEnd(14))} ${ident.padEnd(11)} ${label}${duration}${tools}${errBadge}`);
+    const hostBadge = s.host ? chalk.gray(' · on ') + chalk.cyan(s.host) : '';
+    console.log(`  ${chalk.cyan(handle.padEnd(14))} ${ident.padEnd(11)} ${label}${duration}${tools}${hostBadge}${errBadge}`);
     // Files: counts + basenames. Read is count only.
     const fileLines = [];
     const renderCat = (label, cat) => {
@@ -965,13 +977,55 @@ export function registerTeamsCommands(program) {
         .option('-d, --description <text>', 'One-line summary of what this team is working on')
         .option('--enable-worktrees', 'Each teammate works in its own git worktree (requires --worktree on add)')
         .option('--use-worktree <path>', 'All teammates share this existing worktree path (mutually exclusive with --enable-worktrees)')
+        .option('--devices <list>', 'Pool of machines this team may run teammates on (comma-separated). Enables distributed auto-scheduling.')
+        .option('--hosts <list>', 'Alias for --devices.')
+        .option('--repo <urlOrPath>', 'How each device gets the code (git URL to clone, or a path). Defaults to the local checkout origin.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         try {
+            // --devices / --hosts are aliases; commander can't express a two-name
+            // option that isn't a short flag, so merge them here. Split on comma,
+            // trim, drop blanks, dedupe (preserving first-seen order).
+            const rawPool = [opts.devices, opts.hosts].filter(Boolean).join(',');
+            const devices = [];
+            for (const d of rawPool.split(',').map((s) => s.trim()).filter(Boolean)) {
+                if (!devices.includes(d))
+                    devices.push(d);
+            }
+            // Validate every pooled device resolves + is POSIX (v1 remote monitor is
+            // POSIX-only). A device equal to the local machine is fine (runs local),
+            // so skip the resolve/POSIX check for it.
+            for (const name of devices) {
+                if (name.toLowerCase() === machineId())
+                    continue;
+                const host = await resolveHost(name);
+                if (!host) {
+                    die(`Couldn't resolve pool device "${name}". Register it with \`agents devices\`, ` +
+                        `enroll it with \`agents hosts add ${name}\`, or pass user@host.`);
+                }
+                if (remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)) === 'powershell') {
+                    die(`Distributed teams on Windows device "${host.name}" are not supported yet — ` +
+                        `the teams remote monitor is POSIX-only. Use a Linux/macOS device.`);
+                }
+            }
+            // --repo: how each device gets the code. Default to the local checkout's
+            // origin when a pool is declared and we're inside a git repo, so the user
+            // never hand-manages a path per box. A poolless team leaves repo unset.
+            let repo = opts.repo;
+            if (!repo && devices.length > 0) {
+                const cwd = process.cwd();
+                if (await isGitRepo(cwd)) {
+                    const origin = await getRemoteUrl(cwd);
+                    if (origin)
+                        repo = origin;
+                }
+            }
             const meta = await createTeam(team, {
                 description: opts.description,
                 enableWorktrees: opts.enableWorktrees,
                 useWorktree: opts.useWorktree,
+                devices,
+                repo,
             });
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify({ team, ...meta }, null, 2));
@@ -984,6 +1038,10 @@ export function registerTeamsCommands(program) {
                 console.log(chalk.gray(`  worktrees: per-teammate`));
             if (meta.use_worktree)
                 console.log(chalk.gray(`  worktree: ${meta.use_worktree}`));
+            if (meta.devices && meta.devices.length)
+                console.log(chalk.gray(`  devices: ${meta.devices.join(', ')}`));
+            if (meta.repo)
+                console.log(chalk.gray(`  repo: ${meta.repo}`));
             console.log();
             console.log(chalk.gray('Add your first teammate:'));
             if (meta.enable_worktrees) {
@@ -1039,9 +1097,88 @@ export function registerTeamsCommands(program) {
                 die(`--cloud rush requires --repo <owner/repo>`);
             }
         }
+        // Auto-create the team if it doesn't exist yet (friendlier UX than erroring),
+        // then load its metadata — needed here for the distributed --repo (how each
+        // device gets the code) before we resolve a per-teammate --device pin.
+        await ensureTeam(team);
+        const teamMeta = await getTeam(team);
+        // `--device`/`--host` are aliases (addHostOption registers both). For `teams
+        // add` the passthrough special-cases them as PLACEMENT, not routing, so the
+        // local action reads them here. Reject a conflicting pair.
+        const explicitDevice = (() => {
+            const h = opts.host;
+            const d = opts.device;
+            if (h && d && h !== d) {
+                die('Conflicting --host/--device values — pass just one.');
+            }
+            return h ?? d ?? null;
+        })();
+        // Distributed teams: --device <name> PINS this teammate to a machine over
+        // SSH. Resolve + validate the placement here so a bad target fails at `add`
+        // time, not silently at launch. Persisted (hostName/hostTarget/repoPath) so
+        // startReady()/launchRemoteProcess dispatch over SSH. Unpinned teammates
+        // leave these null — the launch-time scheduler resolves the pool cascade.
+        let hostName = null;
+        let hostTarget = null;
+        let hostRepoPath = null;
+        if (explicitDevice && explicitDevice.toLowerCase() !== machineId()) {
+            if (cloudProviderId) {
+                die(`--device and --cloud are mutually exclusive (two different remote backends). Pick one.`);
+            }
+            const host = await resolveHost(explicitDevice);
+            if (!host) {
+                die(`Couldn't resolve --device "${explicitDevice}". Register it with \`agents devices\`, ` +
+                    `enroll it with \`agents hosts add ${explicitDevice}\`, or pass user@host.`);
+            }
+            // POSIX-only in v1: the remote follow/monitor layer offset-tails the log
+            // with tail/cat/kill, which don't exist under PowerShell. Refuse Windows
+            // up front, mirroring dispatch.ts launchDetached.
+            if (remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)) === 'powershell') {
+                die(`Distributed teammates on Windows host "${host.name}" are not supported yet — ` +
+                    `the teams remote monitor is POSIX-only (offset-tails the remote log with tail/cat/kill). ` +
+                    `Use a Linux/macOS host, or run this teammate locally.`);
+            }
+            try {
+                hostTarget = sshTargetFor(host);
+            }
+            catch (err) {
+                die(`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.
+            try {
+                const { warnings } = ensureHostReady(host, { agent: parseTeammate(teammate).agent });
+                for (const w of warnings)
+                    process.stderr.write(chalk.yellow(`[teams] warning: ${w}\n`));
+            }
+            catch (err) {
+                die(`Host "${host.name}" is not ready: ${err.message}`);
+            }
+            // Provision the repo on the host from the team's --repo (clone into
+            // ~/.agents/repos/<team> or reuse an existing checkout), resolving to the
+            // ABSOLUTE git root so every later remote command works from an absolute
+            // path (dispatch `cd`, worktree create, polling). When the team has no
+            // --repo (the common "just send one teammate elsewhere" case, created
+            // without a pool), fall back to THIS checkout's origin so the headline case
+            // works with zero extra flags whenever you run `add` inside a git repo.
+            let effectiveRepo = teamMeta?.repo ?? '';
+            if (!effectiveRepo && (await isGitRepo(process.cwd()))) {
+                effectiveRepo = (await getRemoteUrl(process.cwd())) ?? '';
+            }
+            try {
+                hostRepoPath = ensureRemoteRepo(hostTarget, effectiveRepo, team);
+            }
+            catch (err) {
+                die(`Couldn't provision the repo on "${host.name}": ${err.message}\n` +
+                    `  Set how each device gets the code with: agents teams create ${team} --repo <url|path>`);
+            }
+            hostName = host.name;
+        }
         const { agent, version, profileName } = parseTeammate(teammate);
         warnAgentDeprecated(agent);
-        if (version && !isVersionInstalled(agent, version)) {
+        // Version-installed check is about the LOCAL machine — a distributed (--on)
+        // teammate's agent/version lives on the host, verified by ensureHostReady.
+        if (version && !hostName && !isVersionInstalled(agent, version)) {
             die(`${AGENT_NAMES[agent]} ${version} isn't installed.\n` +
                 `  Install it:  agents add ${agent}@${version}\n` +
                 `  Or see what's installed (incl. @latest):  agents view ${agent}`);
@@ -1049,7 +1186,8 @@ export function registerTeamsCommands(program) {
         // Advisory sign-in check: warn but NEVER block. Detection is unreliable
         // for opaque-cred agents, so a false negative must not stop a team. Cloud
         // dispatch authenticates through the provider, not the local CLI — skip it.
-        if (!opts.force && !cloudProviderId && !(await checkCliSignedIn(agent))) {
+        // Distributed (--on) teammates authenticate on the host, not locally — skip.
+        if (!opts.force && !cloudProviderId && !hostName && !(await checkCliSignedIn(agent))) {
             console.error(chalk.yellow(`⚠ ${AGENT_NAMES[agent]} may not be signed in (detection is unreliable). Adding anyway.`) +
                 chalk.gray(`\n  If it fails to start, run \`${AGENTS[agent].cliCommand}\` to log in, or pass --force to silence this.`));
         }
@@ -1058,7 +1196,7 @@ export function registerTeamsCommands(program) {
         // out-of-credits / signed-out account (see throttleWarningLine). Skip bare
         // targets (rotation handles them), profiles (auth-injected account isn't
         // the version-home one we can read), and cloud dispatch. Warn, never block.
-        if (!opts.force && !cloudProviderId && !profileName && version) {
+        if (!opts.force && !cloudProviderId && !hostName && !profileName && version) {
             const readiness = await checkRunAccountReadiness(agent, version);
             if (!readiness.ready)
                 console.error(throttleWarningLine(agent, version, readiness));
@@ -1086,15 +1224,34 @@ export function registerTeamsCommands(program) {
         catch (err) {
             die(err.message);
         }
-        // Auto-create the team if it doesn't exist yet (friendlier UX than erroring).
-        await ensureTeam(team);
-        // Check if team has worktrees enabled or a shared worktree
-        const teamMeta = await getTeam(team);
+        // Team already ensured + loaded above (teamMeta) for the --repo provisioning.
         const worktreesEnabled = teamMeta?.enable_worktrees ?? false;
         const sharedWorktree = teamMeta?.use_worktree ?? null;
         let worktreeName = null;
         let worktreePath = null;
-        if (sharedWorktree) {
+        if (hostName) {
+            // Distributed teammate: the checkout lives on the host, so we NEVER touch
+            // the local filesystem here. A shared local worktree makes no sense for a
+            // remote teammate; a per-teammate worktree is created ON THE HOST at launch
+            // (createRemoteWorktree in launchRemoteProcess) — we just capture its name.
+            if (sharedWorktree) {
+                die(`Team '${team}' uses a shared local --use-worktree, which can't apply to a --device (remote) teammate.`);
+            }
+            if (worktreesEnabled) {
+                if (!opts.worktree) {
+                    die(`Team '${team}' has worktrees enabled. Use --worktree <name> for the remote teammate (created on ${hostName}).`);
+                }
+                if (!opts.name) {
+                    die(`Team '${team}' has worktrees enabled. Use --name <name> to identify this teammate.`);
+                }
+                worktreeName = opts.worktree;
+            }
+            else if (opts.worktree) {
+                die(`--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
+            }
+            // Local cwd stays null — the remote cwd is repoPath / the remote worktree.
+        }
+        else if (sharedWorktree) {
             // Team uses a shared worktree for all teammates
             const fsp = await import('fs/promises');
             try {
@@ -1133,7 +1290,10 @@ export function registerTeamsCommands(program) {
         else if (opts.worktree) {
             die(`--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
         }
-        const cwd = worktreePath ?? opts.cwd ?? process.cwd();
+        // Distributed teammates have no LOCAL cwd — their working dir lives on the
+        // host (repoPath / the remote worktree). Local teammates default to the
+        // worktree path, then --cwd, then the current directory.
+        const cwd = hostName ? null : (worktreePath ?? opts.cwd ?? process.cwd());
         const mgr = mkManager();
         // Factory teammates: prepend the worker-skill preamble to every task
         // prompt so implementers/testers/reviewers know about the Ledger, the
@@ -1182,7 +1342,7 @@ export function registerTeamsCommands(program) {
             }
         }
         try {
-            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath, profileName);
+            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath, profileName, hostName, hostTarget, hostRepoPath);
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
                 return;
@@ -1200,7 +1360,10 @@ export function registerTeamsCommands(program) {
             console.log(`  ${chalk.gray('agent_id')}  ${chalk.cyan(shortId(result.agent_id))} ${chalk.gray(`(${result.agent_id})`)}`);
             console.log(`  ${chalk.gray('status  ')}  ${statusColor(result.status)(result.status)}`);
             console.log(`  ${chalk.gray('mode    ')}  ${opts.mode}`);
-            console.log(`  ${chalk.gray('working ')}  ${cwd}`);
+            console.log(`  ${chalk.gray('working ')}  ${hostName ? hostRepoPath : cwd}`);
+            if (hostName) {
+                console.log(`  ${chalk.gray('host    ')}  ${chalk.cyan(hostName)}${chalk.gray(` (${hostTarget})`)}`);
+            }
             if (worktreeName) {
                 console.log(`  ${chalk.gray('worktree')}  ${chalk.cyan(worktreeName)}`);
             }
@@ -1300,6 +1463,7 @@ export function registerTeamsCommands(program) {
                     started_at: a.startedAt.toISOString(),
                     cwd: a.cwd,
                     version: a.version,
+                    host: a.hostName,
                 })) }, null, 2));
             return;
         }
@@ -1317,7 +1481,10 @@ export function registerTeamsCommands(program) {
             console.log(chalk.bold(`Team ${chalk.cyan(team)}  ${chalk.gray(`(${agents.length} working)`)}`));
             for (const a of agents) {
                 const ident = a.name || shortId(a.agentId);
-                const pidStr = a.pid ? chalk.yellow(`pid ${a.pid}`) : chalk.gray('pid ?');
+                // A distributed teammate has no local pid; show its host + remote pid.
+                const pidStr = a.hostName
+                    ? chalk.cyan(`on ${a.hostName}`) + (a.remotePid ? chalk.gray(` (pid ${a.remotePid})`) : '')
+                    : a.pid ? chalk.yellow(`pid ${a.pid}`) : chalk.gray('pid ?');
                 const started = chalk.gray(relTime(a.startedAt.toISOString()));
                 console.log(`  ${chalk.magenta(padRight(fullName(a.agentType, a.version), 18))}  ${chalk.white(padRight(ident, 20))}  ${pidStr}  ${started}`);
             }
@@ -1544,13 +1711,24 @@ export function registerTeamsCommands(program) {
         let worktreeKept = false;
         if (agent?.worktreeName && agent?.worktreePath) {
             try {
-                const dirty = await hasUncommittedChanges(agent.worktreePath);
-                if (dirty) {
-                    worktreeKept = true;
+                if (agent.hostName && agent.hostTarget && agent.repoPath) {
+                    // Distributed teammate: guard + remove the worktree ON THE HOST.
+                    if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath)) {
+                        worktreeKept = true;
+                    }
+                    else {
+                        removeRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                    }
                 }
                 else {
-                    const baseCwd = process.cwd();
-                    await removeWorktree(baseCwd, agent.worktreeName);
+                    const dirty = await hasUncommittedChanges(agent.worktreePath);
+                    if (dirty) {
+                        worktreeKept = true;
+                    }
+                    else {
+                        const baseCwd = process.cwd();
+                        await removeWorktree(baseCwd, agent.worktreeName);
+                    }
                 }
             }
             catch {
@@ -1667,12 +1845,23 @@ export function registerTeamsCommands(program) {
             const agent = await mgr.get(a.agent_id);
             if (agent?.worktreeName && agent?.worktreePath) {
                 try {
-                    const dirty = await hasUncommittedChanges(agent.worktreePath);
-                    if (dirty) {
-                        keptWorktrees.push(agent.worktreeName);
+                    if (agent.hostName && agent.hostTarget && agent.repoPath) {
+                        // Distributed teammate: guard + remove the worktree ON THE HOST.
+                        if (remoteWorktreeDirty(agent.hostTarget, agent.worktreePath)) {
+                            keptWorktrees.push(agent.worktreeName);
+                        }
+                        else {
+                            removeRemoteWorktree(agent.hostTarget, agent.repoPath, agent.worktreeName);
+                        }
                     }
                     else {
-                        await removeWorktree(baseCwd, agent.worktreeName);
+                        const dirty = await hasUncommittedChanges(agent.worktreePath);
+                        if (dirty) {
+                            keptWorktrees.push(agent.worktreeName);
+                        }
+                        else {
+                            await removeWorktree(baseCwd, agent.worktreeName);
+                        }
                     }
                 }
                 catch { /* best-effort */ }
@@ -1778,58 +1967,16 @@ export function registerTeamsCommands(program) {
         .description('Check which agents are installed and available to join a team. Verifies CLI paths and shows an advisory sign-in hint.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
-        const info = checkAllClis();
-        // Deep integrity probe. `checkAllClis` reports presence (shim + stub guard),
-        // but a GUTTED native binary (JS wrapper present, platform binary missing —
-        // the codex/kimi optional-dep partial-extract failure) still passes that. So
-        // actually launch the resolved default version and, if it won't run, flip the
-        // agent to not-installed with a repair hint — otherwise doctor says "ready"
-        // and the teammate ENOENTs at spawn. Parallel; win32 is treated as healthy by
-        // verifyInstalledBinaryLaunches.
-        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. And an
-        // agent that is actually running in a team is treated as signed in
-        // regardless of the probe, so doctor never reports a working agent as
-        // logged out ("don't show wrong stuff").
-        const running = new Set();
-        try {
-            for (const a of await mkManager().listRunning())
-                running.add(a.agentType);
-        }
-        catch { /* no teams yet — leave running empty */ }
-        const auth = {};
-        await Promise.all(Object.entries(info).map(async ([name, entry]) => {
-            const isRunning = running.has(name);
-            const probe = entry.installed && !isRunning ? await checkCliSignedIn(name) : false;
-            auth[name] = resolveSignInAdvisory(entry.installed, isRunning, probe);
-        }));
+        const data = await collectTeamsDoctorData();
         if (isJsonMode(opts)) {
-            const merged = {};
-            for (const [name, entry] of Object.entries(info))
-                merged[name] = { ...entry, ...auth[name] };
-            console.log(JSON.stringify(merged, null, 2));
+            console.log(JSON.stringify(data, null, 2));
             return;
         }
         console.log(chalk.bold('Who can join a team:'));
-        for (const [name, entry] of Object.entries(info)) {
+        for (const [name, entry] of Object.entries(data)) {
             const pretty = AGENT_NAMES[name] || name;
             if (entry.installed) {
-                const { signedIn, running: isRunning } = auth[name];
+                const { signedIn, running: isRunning } = entry;
                 const hint = isRunning
                     ? chalk.gray('in use')
                     : signedIn

package/dist/lib/cloud/rush.js

@@ -525,7 +525,11 @@ export class RushCloudProvider {
     }
     async cancel(taskId) {
         const token = readToken();
-        const res = await api('DELETE', `/api/v1/cloud-runs/${encodeURIComponent(taskId)}`, token);
+        // The cancel ACTION endpoint (POST .../cancel) is what the backend implements;
+        // it works on paused runs too (queued / needs_review / input_required). A bare
+        // DELETE on the run 404s, so `agents cloud cancel` silently failed on anything
+        // that wasn't actively running.
+        const res = await api('POST', `/api/v1/cloud-runs/${encodeURIComponent(taskId)}/cancel`, token);
         if (!res.ok) {
             throw new Error(`Failed to cancel task (${res.status}).`);
         }

package/dist/lib/exec.d.ts

@@ -40,10 +40,16 @@ export declare function headlessPlanStallCommand(args: {
  *
  * - `auto` on an agent without auto support silently degrades to `edit`
  *   (every agent supports edit-like behavior as its default).
+ * - `plan` on an agent without a read-only mode degrades to the agent's
+ *   safest native mode (`capabilities.modes[0]`, typically `edit`). Agents
+ *   like antigravity/cursor/kiro have no plan flag; hard-failing made
+ *   multi-agent scripts (`--mode plan` for everyone) unusable and diverged
+ *   from `agents teams add`, which already defaults to `edit`. Callers that
+ *   care (the `agents run` CLI) must surface a warning when requested ≠
+ *   resolved so the elevation is not silent.
  * - `skip` on an agent without skip support throws with a clear message
  *   naming the agent's supported modes. No silent fallback — the user
  *   explicitly asked to bypass permissions; pretending we did is unsafe.
- * - `plan` on an agent without plan support throws the same way.
  */
 export declare function resolveMode(agent: AgentId, requested: Mode): Mode;
 /**
@@ -54,10 +60,8 @@ export declare function resolveMode(agent: AgentId, requested: Mode): Mode;
  * supports." Agents that include `plan` list it first; agents like
  * antigravity that have no read-only mode list `edit` first.
  *
- * Use this when the user did not pass `--mode` explicitly. When the user
- * *did* pass `--mode plan` and the agent doesn't support it, call
- * `resolveMode` instead so the user sees a loud error rather than a silent
- * elevation from read-only to writable.
+ * Prefer this over a hard-coded `'plan'` when the agent is known. `resolveMode`
+ * also maps an unsupported `'plan'` request onto this same value.
  */
 export declare function defaultModeFor(agent: AgentId): Mode;
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */

package/dist/lib/exec.js

@@ -16,6 +16,7 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
+import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
@@ -75,10 +76,16 @@ export function headlessPlanStallCommand(args) {
  *
  * - `auto` on an agent without auto support silently degrades to `edit`
  *   (every agent supports edit-like behavior as its default).
+ * - `plan` on an agent without a read-only mode degrades to the agent's
+ *   safest native mode (`capabilities.modes[0]`, typically `edit`). Agents
+ *   like antigravity/cursor/kiro have no plan flag; hard-failing made
+ *   multi-agent scripts (`--mode plan` for everyone) unusable and diverged
+ *   from `agents teams add`, which already defaults to `edit`. Callers that
+ *   care (the `agents run` CLI) must surface a warning when requested ≠
+ *   resolved so the elevation is not silent.
  * - `skip` on an agent without skip support throws with a clear message
  *   naming the agent's supported modes. No silent fallback — the user
  *   explicitly asked to bypass permissions; pretending we did is unsafe.
- * - `plan` on an agent without plan support throws the same way.
  */
 export function resolveMode(agent, requested) {
     const supported = AGENTS[agent].capabilities.modes;
@@ -89,6 +96,12 @@ export function resolveMode(agent, requested) {
         // at least 'edit' in its modes table, since that's the default behavior).
         return 'edit';
     }
+    if (requested === 'plan') {
+        // No read-only mode on this agent. modes[0] is the declared safest mode
+        // (edit for antigravity/cursor/kiro/…). Prefer that over hard-fail so
+        // uniform multi-agent `--mode plan` dispatches still run.
+        return supported[0];
+    }
     throw new Error(`${agent} does not support '${requested}' mode. Supported modes: ${supported.join(', ')}.`);
 }
 /**
@@ -99,10 +112,8 @@ export function resolveMode(agent, requested) {
  * supports." Agents that include `plan` list it first; agents like
  * antigravity that have no read-only mode list `edit` first.
  *
- * Use this when the user did not pass `--mode` explicitly. When the user
- * *did* pass `--mode plan` and the agent doesn't support it, call
- * `resolveMode` instead so the user sees a loud error rather than a silent
- * elevation from read-only to writable.
+ * Prefer this over a hard-coded `'plan'` when the agent is known. `resolveMode`
+ * also maps an unsupported `'plan'` request onto this same value.
  */
 export function defaultModeFor(agent) {
     return AGENTS[agent].capabilities.modes[0];
@@ -541,7 +552,8 @@ export function buildExecCommand(options) {
     }
     // Resolve the requested mode against the agent's capability table.
     // - `auto` on an agent without auto support → silently degrades to `edit`
-    // - `skip`/`plan` on an unsupported agent → throws a clear error
+    // - `plan` on an agent without a read-only mode → degrades to modes[0]
+    // - `skip` on an unsupported agent → throws a clear error
     // After resolveMode, the chosen mode is guaranteed to be in template.modeFlags.
     const resolvedMode = resolveMode(options.agent, normalizeMode(options.mode));
     const modeFlags = template.modeFlags[resolvedMode];
@@ -599,18 +611,25 @@ export function buildExecCommand(options) {
     else if (options.sessionId && options.agent === 'claude') {
         cmd.push('--session-id', options.sessionId);
     }
-    // Add model (only if explicitly provided by user)
-    if (options.model && template.modelFlag) {
+    // Add model. Prefer the user's explicit --model. Otherwise, for Codex, fall
+    // back to the model configured in the user's active ~/.codex/config.toml:
+    // Codex runs under a per-version CODEX_HOME (see buildExecEnv) that may not
+    // carry that setting, so without this it silently defaults to gpt-5.3-codex,
+    // which a ChatGPT-tier account can't use (HTTP 400). Forwarding keeps the
+    // user's default model setup for both `agents run` and `agents teams`.
+    const effectiveModel = options.model
+        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined);
+    if (effectiveModel && template.modelFlag) {
         const effectiveVersion = options.version || resolveVersion(options.agent, options.cwd || process.cwd());
         if (effectiveVersion) {
-            const resolved = resolveModel(options.agent, effectiveVersion, options.model);
+            const resolved = resolveModel(options.agent, effectiveVersion, effectiveModel);
             if (resolved.warning) {
                 process.stderr.write(`[agents] ${resolved.warning}\n`);
             }
             cmd.push(template.modelFlag, resolved.forwarded);
         }
         else {
-            cmd.push(template.modelFlag, options.model);
+            cmd.push(template.modelFlag, effectiveModel);
         }
     }
     // Add JSON output flags if requested

package/dist/lib/hosts/passthrough.js

@@ -91,6 +91,20 @@ export async function maybeRunOnHost(command, allArgs) {
     const spec = REMOTE_PASSTHROUGH[command];
     if (!spec)
         return false;
+    // Placement, not routing: `teams add`/`teams create` read `--device`/`--devices`
+    // (and `--host`/`--hosts`) as WHERE to place a teammate / the team pool — the
+    // command itself always runs locally on the orchestrator. Bail before the
+    // generic teams routing below so those flags reach the local action. Every
+    // other teams subcommand (`status`/`logs`/`stop`/…) keeps `--host` routing.
+    // Find the subcommand = the first non-flag token AFTER `teams` (robust to any
+    // leading global flags), then bail for the add/create aliases.
+    if (command === 'teams') {
+        const teamsIdx = allArgs.indexOf('teams');
+        const sub = teamsIdx >= 0 ? allArgs.slice(teamsIdx + 1).find((a) => !a.startsWith('-')) : undefined;
+        if (sub === 'add' || sub === 'a' || sub === 'create' || sub === 'c' || sub === 'new') {
+            return false;
+        }
+    }
     // `--device` is a first-class alias of `--host` (mirrors `agents run`); the
     // device registry is the source of truth for machine identity. Reject a
     // conflicting pair rather than silently preferring one — same rule as run.
@@ -101,6 +115,11 @@ export async function maybeRunOnHost(command, allArgs) {
         process.exitCode = 1;
         return true;
     }
+    // `--devices` / `--hosts` fan out to every registered device locally; don't
+    // let a per-host passthrough turn it into a cascading remote fan-out.
+    const fleetFlag = allArgs.includes('--devices') || allArgs.includes('--hosts');
+    if (fleetFlag)
+        return false;
     const hostName = hostFlag ?? deviceFlag;
     if (!hostName)
         return false;
@@ -142,7 +161,17 @@ export async function maybeRunOnHost(command, allArgs) {
         }
         return true;
     }
-    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, resolveRemoteOsSync(host.name));
+    // Doctor commands probe the agent CLIs; remote POSIX login shells often don't
+    // have the agents shims on PATH, which produces false "not installed" negatives.
+    // Bootstrap PATH with the canonical shim locations before the remote command.
+    // Windows is skipped: PowerShell usually has the shim dir via the install
+    // profile, and single-quoted env values would not expand $HOME/$PATH.
+    const isDoctorCommand = command === 'doctor' || (command === 'teams' && forwarded[1] === 'doctor');
+    const remoteOs = resolveRemoteOsSync(host.name);
+    const env = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
+        ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
+        : undefined;
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +