@phnx-labs/agents-cli 1.20.49 → 1.20.50

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 1.20.50
+
+- **Distributed agent teams: teammates can now run on different machines across your fleet, not just the box running `teams start`.** A single team can place the backend teammate on a Linux box and the UI teammate on a Mac while one orchestrator still drives the DAG, polls status, and cleans up. One vocabulary, all optional (omit it and teams stay 100% local as before): `teams create --devices a,b,c` (alias `--hosts`) declares a pool the team may auto-schedule onto, `--repo <url|path>` (defaults to the local checkout's `origin`) says how each device gets the code, and `teams add --device X` (alias `--host`) pins one teammate to a host — which needs **no** pool, so "send just one teammate elsewhere" is zero-setup. Placement resolves top-down at launch: explicit `--device` pin → single-device pool (whole team there) → multi-device pool (least-loaded auto-schedule) → local. Remote teammates dispatch over SSH via the existing `agents devices`/host machinery (a third teammate backend beside local and cloud), are monitored by offset-tailing the remote log + `.exit` sentinel, and get the repo auto-provisioned per device (reuse an existing checkout, else clone into `~/.agents/repos/<team>`) with an optional per-teammate git worktree on the host. `teams status`/`teams logs` show each teammate's host and stream its output back with the local mirror capped (~512KB rolling tail) so a 10+-teammate fleet can't blow up the orchestrator. POSIX hosts only in v1 (Windows rejected with a clear message). Source: `apps/cli/src/lib/teams/{scheduler,remoteWorktree,agents,api,supervisor,registry}.ts`, `apps/cli/src/lib/hosts/{progress,passthrough}.ts`, `apps/cli/src/commands/teams.ts`, `apps/cli/docs/teams.md`.
+- **NEW: `agents doctor --devices` shows a cross-device agent-readiness matrix.** `agents doctor` could already run on one remote machine via `--host`, but checking the whole fleet meant running the command once per box. `--devices` fans out `agents teams doctor --json` to every registered device (plus the local machine), renders a device × agent matrix, and emits a stable JSON contract with `--json`. `--device <name>` or `--host <name>` scopes the same matrix to a single machine. The remote probe now bootstraps `PATH` with the canonical shim directories before running, so login shells that haven't sourced interactive rc files no longer report false "not installed" negatives. Source: `apps/cli/src/commands/doctor.ts`, `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/lib/hosts/{passthrough,remote-cmd}.ts`.
+- **`agents run codex` / `agents teams` now honor your configured Codex model instead of silently defaulting to `gpt-5.3-codex`.** Codex runs under a per-version `CODEX_HOME`, and your `model` preference (`~/.codex/config.toml`) lives only in the version-home that was active when you set it. A dispatch pinned to a different version read a home with no top-level `model`, so Codex fell back to its built-in default — which a ChatGPT-tier account isn't entitled to use, so the run died with `400: The 'gpt-5.3-codex' model is not supported when using Codex with a ChatGPT account` before doing any work, even though `ag view` reported Codex "signed in". When no explicit `--model` is passed, the model is now defaulted (for Codex) to the top-level `model` in your active `~/.codex/config.toml` and forwarded via `--model`; it's read-only (no file writes), so fanning out many parallel runs to one version-home can't race. Verified live on a box where Codex was 100% unusable: the request model changed `gpt-5.3-codex` → `gpt-5.5` and codex@0.142.0 returned successfully. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/shims.ts` (`readCodexConfiguredModel`).
+- **Fix: `agents add claude@<version>` now produces a runnable install — it no longer ships a half-built binary that dies with "claude native binary not installed."** `installVersion` runs `npm install --ignore-scripts` (the right posture for the dependency *tree* — never run arbitrary transitive postinstalls), but that also skipped the agent package's OWN postinstall, which for `@anthropic-ai/claude-code` is a required step: the package ships a ~500-byte stub at `bin/claude.exe` plus per-arch native binaries as optional deps, and its `postinstall` (`node install.cjs`) is what copies the correct ~231 MB native binary over the stub. Skipped, every launch died with `Error: claude native binary not installed`. The existing launch-health self-heal (#764, and its Windows/daemon extension) couldn't save it on two counts: the stub reports its breakage *politely* rather than with a raw `ENOENT`, so the probe's missing-binary signature didn't match and the gutted install read as healthy; and the repair path (`ensureAgentRunnable` → clean reinstall) re-ran the same `--ignore-scripts` install, so it never copied the binary either. `installVersion` now runs the **first-party** package's declared `postinstall` after the npm install (scoped to that one package — never the dependency tree, never claude-code's `exit 1` `prepare` guard), best-effort, before the integrity gate. Because `installVersion` is the single choke point for `agents add`, config refresh, run-time heal, and the daemon's proactive heal, this also revives the repair path for the whole class. `isMissingBinarySignature` was additionally widened to recognize the stub's polite phrases (`native binary not installed`, `postinstall did not run`, `optional dependency was not downloaded`) so the self-heal catches this failure mode if a postinstall ever silently no-ops. Verified end-to-end on linux-arm64: `installVersion('claude','2.1.186')` into a clean HOME runs the postinstall automatically, lands the 231,782,112-byte binary (not the stub), and `claude.exe --version` returns `2.1.186 (Claude Code)` — with no manual `install.cjs` step. Source: `apps/cli/src/lib/versions.ts` (`installVersion`, `isMissingBinarySignature`).
+
 ## 1.20.49
 
 - **`agents run --mode plan` no longer hard-fails on agents without a read-only mode (antigravity, cursor, kiro, …).** Those agents have no plan flag, so an explicit or default `--mode plan` used to abort with `does not support 'plan' mode` — breaking multi-agent scripts that pass a uniform plan flag, and diverging from `agents teams add` (default mode `edit`). `resolveMode` now degrades unsupported `plan` to the agent's safest native mode (`capabilities.modes[0]`, typically `edit`), matching the existing `auto` → `edit` degrade. The CLI prints a yellow warning when the user explicitly asked for plan (gray for the implicit default) so the elevation is never silent. `skip` still hard-fails when unsupported. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/commands/exec.ts`.

package/README.md

@@ -307,6 +307,9 @@ agents logs <id> --full                 # the full raw transcript / stdout (toke
 agents logs <id> -f                     # re-attach to a running one and follow
 agents view claude --host gpu-box       # inspect the remote install
 agents sync --host gpu-box              # make the remote machine current
+agents doctor --devices                 # readiness matrix for every registered device
+agents doctor --devices --json          # machine-readable fleet readiness
+agents doctor --device mac-mini         # same matrix, scoped to one device
 
 # Your Tailscale fleet, auto-discovered
 agents devices sync                     # ingest `tailscale status`

package/dist/commands/doctor.js

@@ -1,6 +1,12 @@
 import { addHostOption } from '../lib/hosts/option.js';
+import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
+import { loadDevices } from '../lib/devices/registry.js';
+import { resolveHost } from '../lib/hosts/registry.js';
+import { sshExec } from '../lib/ssh-exec.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
+import { machineId } from '../lib/session/sync/config.js';
 import chalk from 'chalk';
-import { checkAllClis } from '../lib/teams/agents.js';
+import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
 import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
@@ -203,6 +209,121 @@ function renderExecPolicyAdvisory() {
         console.log(chalk.gray(`           ${line}`));
     }
 }
+const AGENT_ORDER = ['claude', 'codex', 'kimi', 'grok', 'antigravity', 'opencode', 'cursor', 'gemini', 'droid'];
+function shortAgentHeader(name) {
+    return name.slice(0, 4).padEnd(4);
+}
+function agentCell(entry) {
+    if (!entry)
+        return chalk.gray('-   ');
+    if (entry.installed) {
+        const signedInHint = entry.signedIn ? '*' : ' ';
+        return chalk.green(`rdy${signedInHint}`.padEnd(4));
+    }
+    if (entry.error)
+        return chalk.red('err '.padEnd(4));
+    return chalk.gray('no  '.padEnd(4));
+}
+async function resolveFleetTargets(opts) {
+    const singleName = opts.host || opts.device;
+    if (singleName) {
+        // --device / --host as a single-device filter: resolve through the device
+        // registry first, then the general host registry, then ad-hoc user@host.
+        const registry = await loadDevices();
+        const deviceProfile = registry[singleName];
+        if (deviceProfile) {
+            return [{
+                    name: deviceProfile.name,
+                    sshTarget: deviceProfile.name,
+                    os: deviceProfile.platform !== 'unknown' ? deviceProfile.platform : undefined,
+                }];
+        }
+        const host = await resolveHost(singleName);
+        if (host) {
+            return [{ name: singleName, sshTarget: sshTargetFor(host), os: host.os }];
+        }
+        console.error(chalk.red(`Unknown host or device '${singleName}'.`));
+        process.exit(1);
+    }
+    const registry = await loadDevices();
+    const localName = machineId();
+    return Object.values(registry)
+        .filter((d) => d.name.toLowerCase() !== localName)
+        .map((d) => ({
+        name: d.name,
+        sshTarget: d.name,
+        os: d.platform !== 'unknown' ? d.platform : undefined,
+    }));
+}
+async function probeFleetTarget(target) {
+    const forwarded = ['teams', 'doctor', '--json'];
+    const isWin = /^win/i.test((target.os ?? '').trim());
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, undefined, isWin ? 'windows' : undefined, 
+    // POSIX login shells often lack the shims dir; Windows PowerShell usually
+    // has it via the install profile, and our single-quote escaping would
+    // prevent $HOME expansion there, so skip the bootstrap on Windows.
+    isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' });
+    const res = sshExec(target.sshTarget, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    if (res.code !== 0) {
+        return {
+            name: target.name,
+            online: false,
+            error: res.timedOut ? 'timed out' : (res.stderr || `exit ${res.code ?? 'unknown'}`),
+            agents: {},
+        };
+    }
+    try {
+        const agents = JSON.parse(res.stdout);
+        return { name: target.name, online: true, agents };
+    }
+    catch (err) {
+        const stderrHint = res.stderr ? ` stderr: ${res.stderr.trim()}` : '';
+        return {
+            name: target.name,
+            online: true,
+            error: `invalid JSON (${err?.message ?? 'parse error'})${stderrHint}`,
+            agents: {},
+        };
+    }
+}
+async function runDevicesDoctor(opts) {
+    const singleName = opts.host || opts.device;
+    const targets = await resolveFleetTargets(opts);
+    const localName = machineId();
+    const results = [];
+    // Local machine first, directly.
+    if (!singleName) {
+        results.push({ name: localName, online: true, agents: await collectTeamsDoctorData() });
+    }
+    // Remote targets in parallel.
+    const remoteResults = await Promise.all(targets.map(probeFleetTarget));
+    results.push(...remoteResults);
+    if (opts.json) {
+        console.log(JSON.stringify({ devices: results }, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log(chalk.gray('No registered devices. Run `agents devices` to register some.'));
+        return;
+    }
+    const agentsToShow = AGENT_ORDER.filter((a) => results.some((r) => r.agents[a] !== undefined));
+    console.log(chalk.bold('Agent readiness by device'));
+    if (agentsToShow.length === 0) {
+        console.log(chalk.gray('  (no agent data collected)'));
+        return;
+    }
+    const nameWidth = Math.max(...results.map((r) => r.name.length));
+    const header = `  ${'Device'.padEnd(nameWidth)}  ${agentsToShow.map(shortAgentHeader).join('  ')}`;
+    console.log(chalk.gray(header));
+    for (const row of results) {
+        const status = row.online ? chalk.green('online ') : chalk.red('offline');
+        const errorSuffix = row.error ? `  ${chalk.gray(row.error)}` : '';
+        const cells = agentsToShow.map((a) => agentCell(row.agents[a])).join('  ');
+        console.log(`  ${row.name.padEnd(nameWidth)}  ${status}  ${cells}${errorSuffix}`);
+    }
+    console.log();
+    console.log(chalk.gray('  rdy* = installed and signed in · rdy = installed · no = not installed · err = probe failed · - = offline'));
+}
 function parseTargetArg(arg) {
     const at = arg.indexOf('@');
     const agentPart = at === -1 ? arg : arg.slice(0, at);
@@ -484,7 +605,9 @@ export function registerDoctorCommand(program) {
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
         .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
-        .option('--release <agent>', 'Undo --adopt: restore the native launcher agents-cli previously adopted');
+        .option('--release <agent>', 'Undo --adopt: restore the native launcher agents-cli previously adopted')
+        .option('--devices', 'Check agent readiness on every registered device (alias --hosts)')
+        .option('--hosts', 'Alias of --devices');
     setHelpSections(doctorCmd, {
         examples: `
       # Overview: CLI availability + sync status + orphans across all defaults
@@ -511,6 +634,14 @@ export function registerDoctorCommand(program) {
     });
     doctorCmd.action(async (target, opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        if (opts.devices || opts.hosts) {
+            if (target) {
+                console.error(chalk.red('Cannot combine --devices with a target argument.'));
+                process.exit(1);
+            }
+            await runDevicesDoctor(opts);
+            return;
+        }
         // Launcher adoption escape hatch. `--adopt <agent>` forces the take-over
         // even for a non-default agent; `--release <agent>` reverses it.
         if (opts.adopt || opts.release) {

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