@phnx-labs/agents-cli 1.22.47 → 1.22.50

package/dist/commands/share.js

@@ -1,18 +1,21 @@
-// `agents artifacts share` — publish an HTML file to your own Cloudflare R2
-// behind a tiny Worker, and get a shareable link (~$0). See apps/cli/docs/share.md.
+// `agents artifacts share` — publish an HTML file to a shareable link. Signed-in
+// users hit the managed endpoint (share.agents-cli.sh) with the Phoenix bearer;
+// otherwise the existing BYO Cloudflare R2 + Worker path. See cli/docs/observability.md.
 //
 // Registered under the `artifacts` group by commands/artifacts.ts; the
 // provisioning door lives beside it at `agents artifacts setup`
 // (commands/artifacts-setup.ts), which calls `runShareProvision` below.
 import { existsSync } from 'node:fs';
 import { formatBytes } from '../lib/format.js';
+import { Option } from 'commander';
 import chalk from 'chalk';
 import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
-import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, updateWorker, setWorkerSecret, } from '../lib/share/provision.js';
-import { publishFile, resolveShareUsername, parseMetaEntries } from '../lib/share/publish.js';
+import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
+import { publishFile, resolveShareUsername, parseMetaEntries, resolveShareVisibility, } from '../lib/share/publish.js';
 import { deleteShare, resolveDeleteTarget } from '../lib/share/delete.js';
 import { renderWorkerScript } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
+import { phoenixIdBaseForDeploy, resolveShareBackend, } from '../lib/share/backend.js';
 import { resolveGitHubUsername } from '../lib/git.js';
 import { setHelpSections } from '../lib/help.js';
 export function formatSharePublishResult(result, json = false) {
@@ -29,8 +32,16 @@ export function formatSharePublishResult(result, json = false) {
         lines.push(chalk.dim(`  expires ${new Date(result.expiresAt).toLocaleString()}`));
     else
         lines.push(chalk.dim('  expires never'));
-    if (result.unlisted)
-        lines.push(chalk.dim('  unlisted (hidden from gallery / share list)'));
+    const visibility = result.visibility ?? (result.unlisted ? 'unlisted' : 'public');
+    if (visibility === 'unlisted') {
+        lines.push(chalk.dim('  visibility: unlisted (noindex, hidden from gallery)'));
+    }
+    else if (visibility === 'me' || visibility === 'org') {
+        lines.push(chalk.dim(`  visibility: ${visibility} (login required, hidden from gallery)`));
+    }
+    else {
+        lines.push(chalk.dim(`  visibility: ${visibility}`));
+    }
     return lines.join('\n');
 }
 /** Compare the configured endpoint's last-deployed template hash against the
@@ -100,25 +111,42 @@ export function parseShareListing(user, body) {
     });
     return { user, count: objects.length, objects };
 }
+/** Namespace for list/revisions: managed uses the Phoenix handle (email
+ * local-part); BYO still resolves GitHub username (gh / git config / --for-user). */
+async function namespaceForBackend(backend, githubUser) {
+    if (backend.kind === 'managed')
+        return backend.namespace;
+    return resolveShareUsername({ githubUser: githubUser || backend.namespace || undefined });
+}
 /** Fetch and parse the machine-readable listing of the caller's namespace from the
  * Worker's `?format=json` route. Fails loud when share was never configured, when
  * the deployed template is known-outdated (RUSH-2449 templateHash), or when the
  * live response proves the route is absent (404 or a non-JSON 200 = the old HTML
- * gallery) — never a silent empty/wrong result. */
+ * gallery) — never a silent empty/wrong result. Signed-in users hit the managed
+ * endpoint; BYO still uses `readShareConfig()`. */
 export async function runShareList(opts = {}) {
-    const cfg = opts.config ?? readShareConfig();
-    if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
-    }
-    // A known-stale template can't have the listing route — say so before any network
-    // call. 'unknown' (provisioned before templateHash tracking) is attempted, then
-    // caught by the response checks below if the route turns out to be absent.
-    const templateStatus = shareTemplateStatus(cfg);
-    if (templateStatus === 'outdated') {
-        throw new Error(OUTDATED_TEMPLATE_HINT);
+    const backend = resolveShareBackend({
+        githubUser: opts.githubUser,
+        config: opts.config,
+        writeToken: opts.writeToken,
+        byo: opts.byo,
+        session: opts.phoenixSession,
+        requireToken: false,
+    });
+    // Managed: the platform Worker is current; skip the BYO template-hash gate.
+    // A known-stale BYO template can't have the listing route — say so before any
+    // network call. 'unknown' (provisioned before templateHash tracking) is
+    // attempted, then caught by the response checks below if the route is absent.
+    let templateStatus = 'current';
+    if (backend.kind === 'byo') {
+        const cfg = opts.config ?? readShareConfig();
+        templateStatus = cfg ? shareTemplateStatus(cfg) : 'unknown';
+        if (templateStatus === 'outdated') {
+            throw new Error(OUTDATED_TEMPLATE_HINT);
+        }
     }
-    const user = await resolveShareUsername({ githubUser: opts.githubUser });
-    const listUrl = `${cfg.baseUrl.replace(/\/+$/, '')}/${encodeURIComponent(user)}?format=json`;
+    const user = await namespaceForBackend(backend, opts.githubUser);
+    const listUrl = `${backend.baseUrl.replace(/\/+$/, '')}/${encodeURIComponent(user)}?format=json`;
     const fetchListing = opts.fetchListing ?? defaultListingFetch;
     const res = await fetchListing(listUrl);
     if (res.status === 404) {
@@ -128,18 +156,22 @@ export async function runShareList(opts = {}) {
         // endpoint predates the listing route entirely. The recorded templateHash
         // disambiguates: a 'current' template HAS the route, so its 404 means an empty
         // namespace ("nothing published"); otherwise the route may be absent, so point
-        // at `agents artifacts share update`.
+        // at `agents artifacts share update`. Managed is always 'current'.
         if (templateStatus === 'current') {
             return { user, count: 0, objects: [] };
         }
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
     if (res.status !== 200) {
-        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' completed.`);
+        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
         // A 200 that isn't JSON means the old Worker ignored ?format=json and served
-        // the HTML gallery — the deployed template is outdated.
+        // the HTML gallery — the deployed template is outdated. Managed never hits
+        // this (platform Worker is current); fail loud if it somehow does.
+        if (backend.kind === 'managed') {
+            throw new Error(`Managed listing at ${listUrl} did not return JSON (${res.contentType || 'no content-type'}).`);
+        }
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
     const parsed = parseShareListing(user, res.body);
@@ -239,22 +271,34 @@ export function parseShareRevisions(key, body) {
  * or a bare slug resolved against the caller's own namespace) — reuses
  * {@link resolveDeleteTarget} rather than re-deriving the key. */
 export async function runShareRevisions(target, opts = {}) {
-    const cfg = opts.config ?? readShareConfig();
-    if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents artifacts setup' (provision your own endpoint) or 'agents artifacts share join' (use an existing one).");
-    }
-    const templateStatus = shareTemplateStatus(cfg);
-    if (templateStatus === 'outdated') {
-        throw new Error(OUTDATED_TEMPLATE_HINT);
+    const backend = resolveShareBackend({
+        githubUser: opts.githubUser,
+        config: opts.config,
+        writeToken: opts.writeToken,
+        byo: opts.byo,
+        session: opts.session,
+        requireToken: false,
+    });
+    if (backend.kind === 'byo') {
+        const cfg = opts.config ?? readShareConfig();
+        if (cfg && shareTemplateStatus(cfg) === 'outdated') {
+            throw new Error(OUTDATED_TEMPLATE_HINT);
+        }
     }
-    const { key } = await resolveDeleteTarget(target, { githubUser: opts.githubUser });
-    const revUrl = `${cfg.baseUrl.replace(/\/+$/, '')}/${key}?revisions=json`;
+    const githubUser = backend.kind === 'managed'
+        ? backend.namespace
+        : opts.githubUser || backend.namespace || undefined;
+    const { key } = await resolveDeleteTarget(target, { githubUser });
+    const revUrl = `${backend.baseUrl.replace(/\/+$/, '')}/${key}?revisions=json`;
     const fetchListing = opts.fetchListing ?? defaultListingFetch;
     const res = await fetchListing(revUrl);
     if (res.status !== 200) {
-        throw new Error(`Revisions lookup failed (${res.status}) for ${revUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' completed.`);
+        throw new Error(`Revisions lookup failed (${res.status}) for ${revUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
+        if (backend.kind === 'managed') {
+            throw new Error(`Managed revisions at ${revUrl} did not return JSON (${res.contentType || 'no content-type'}).`);
+        }
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
     return parseShareRevisions(key, res.body);
@@ -390,13 +434,16 @@ const SHARE_DELETE_NOTES = `
 export function registerShareCommands(artifactsCmd) {
     const shareCmd = artifactsCmd
         .command('share')
-        .description('Publish an HTML file to your own Cloudflare R2 and get a shareable link (~$0).')
+        .description('Publish an HTML file to a shareable link — managed if signed in, otherwise your Cloudflare R2.')
         .argument('[file]', 'file to publish (HTML or any static asset)')
-        .option('--slug <slug>', 'custom URL slug under your namespace (default: <project>-<feature>-<hash>)')
-        .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config)')
+        .option('--slug <slug>', 'custom URL slug under your namespace (default: <feature>-<16hex>)')
+        .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config; ignored on the managed endpoint)')
         .option('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
-        .option('--unlisted', 'hide from the public gallery and `agents artifacts share list` (direct URL still works)')
-        .option('--private', 'alias of --unlisted')
+        .addOption(new Option('--visibility <level>', 'public | unlisted | me | org (default public). unlisted is a capability URL; me/org require a Phoenix session and are hidden from the gallery')
+        .choices(['public', 'unlisted', 'me', 'org'])
+        .default('public'))
+        .addOption(new Option('--unlisted', 'hidden alias of --visibility unlisted').hideHelp())
+        .addOption(new Option('--private', 'hidden alias of --visibility unlisted').hideHelp())
         .option('--force', 'publish even when the file contains emails or credential-shaped strings')
         .option('--no-cover', 'skip the OG preview image (HTML pages get one by default)')
         .option('--no-analytics', 'skip injecting the Cloudflare Web Analytics beacon')
@@ -417,11 +464,16 @@ export function registerShareCommands(artifactsCmd) {
         }
         try {
             const meta = parseMetaEntries(opts.meta);
+            const visibility = resolveShareVisibility({
+                visibility: opts.visibility,
+                unlisted: opts.unlisted === true || opts.private === true,
+            });
             const result = await publishFile(file, {
                 slug: opts.slug,
                 githubUser: opts.githubUser,
                 expire: opts.expire,
-                unlisted: opts.unlisted === true || opts.private === true,
+                visibility,
+                unlisted: visibility === 'unlisted',
                 force: opts.force,
                 cover: opts.cover,
                 analytics: opts.analytics,
@@ -438,11 +490,12 @@ export function registerShareCommands(artifactsCmd) {
     });
     setHelpSections(shareCmd, {
         examples: `
-      # Publish an HTML file — auto OG cover, default 30d expiry, shareable link
+      # Signed in? Just publish — no Cloudflare setup (managed endpoint)
+      agents auth login
       agents artifacts share ./out/plan.html
 
-      # Hide from the public gallery (direct URL still works) and expire sooner
-      agents artifacts share ./out/report.html --unlisted --expire 12h
+      # Hide from the public gallery (direct URL still works, noindex) and expire sooner
+      agents artifacts share ./out/report.html --visibility unlisted --expire 12h
 
       # Permanent public page (opt out of the default 30d expiry)
       agents artifacts share ./out/landing.html --slug landing --expire never
@@ -464,11 +517,21 @@ ${SHARE_DELETE_EXAMPLES}
       agents artifacts share update
     `,
         notes: `
+  Signed-in users publish to the managed endpoint (share.agents-cli.sh/<handle>/…)
+  with the Phoenix session — no Cloudflare account, bucket, or write token. The
+  handle is the local-part of the signed-in email; the default slug is
+  <readable>-<16hex>. Without a session, the existing BYO Cloudflare path still
+  applies (setup / join). HTML is stored as one object: local images are inlined
+  and Chrome-saved file:// TOC links become in-page hashes.
+
   Default expiry is 30d so an accidental publish decays. Pass --expire never for
-  a permanent link. --unlisted / --private hides the page from the public gallery
-  and agents artifacts share list; the direct URL is still world-readable
-  (unlisted, not secret). A pre-publish scan refuses emails and credential-shaped
-  strings unless --force is passed.
+  a permanent link. --visibility unlisted (hidden aliases: --unlisted / --private)
+  hides the page from the public gallery and agents artifacts share list; the
+  direct URL is still world-readable (unlisted, not secret) and GET sends
+  X-Robots-Tag: noindex. --visibility me requires a Phoenix session and is only
+  visible to the signed-in owner; --visibility org requires the same and is
+  visible to members of the same Phoenix organization. A pre-publish scan
+  refuses emails and credential-shaped strings unless --force is passed.
 
   Every publish carries provenance auto-captured from the exec env/git/clock
   (agent, session, host, repo, date) — never invented, only sent when present —
@@ -549,11 +612,27 @@ ${SHARE_DELETE_NOTES}
         .command('status')
         .description('Show the configured share endpoint and namespace.')
         .action(async () => {
+        let backend;
+        try {
+            backend = resolveShareBackend({ requireToken: false });
+        }
+        catch (e) {
+            console.log(chalk.dim(e.message));
+            return;
+        }
+        if (backend.kind === 'managed') {
+            console.log(`${chalk.bold('backend')}   ${chalk.green('managed')}`);
+            console.log(`${chalk.bold('endpoint')}  ${chalk.green(backend.baseUrl)}`);
+            console.log(`${chalk.bold('namespace')} ${chalk.cyan(`${backend.baseUrl}/${backend.namespace}`)}`);
+            console.log(chalk.dim("Phoenix session — no Cloudflare setup. Force BYO with AGENTS_SHARE_BACKEND=byo."));
+            return;
+        }
         const cfg = readShareConfig();
         if (!cfg) {
             console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
             return;
         }
+        console.log(`${chalk.bold('backend')}   ${chalk.green('byo')}`);
         console.log(`${chalk.bold('endpoint')}  ${chalk.green(cfg.baseUrl)}`);
         console.log(chalk.dim(`worker ${cfg.workerName} · bucket ${cfg.bucketName} · account ${cfg.accountId || 'missing'}`));
         if (!cfg.accountId) {
@@ -620,9 +699,10 @@ ${SHARE_DELETE_NOTES}
     `,
         notes: `
   Lists the ACTIVE pages in your namespace — expired links and the sibling .png OG
-  covers are omitted (it mirrors the public gallery). It reads the endpoint's JSON
-  listing route, which ships with the current Worker template. If your deployed
-  Worker predates this feature the command says so and points you at 'agents
+  covers are omitted (it mirrors the public gallery). Signed-in users list the
+  managed endpoint (share.agents-cli.sh/<handle>); otherwise BYO. It reads the
+  endpoint's JSON listing route, which ships with the current Worker template. If
+  a BYO Worker predates this feature the command says so and points you at 'agents
   artifacts share update' (RUSH-2449) rather than returning a wrong or empty result
   — see 'agents artifacts share status' for whether an update is due.
 
@@ -669,13 +749,27 @@ ${SHARE_DELETE_NOTES}
   (pass --no-revision at publish time to skip it) — this is history, never
   shown on the public gallery or in 'agents artifacts share list' beyond its
   count. Each revision's own URL is still directly reachable and honors its own
-  recorded expiry.
+  recorded expiry. Signed-in users resolve a bare slug against the managed
+  Phoenix namespace; otherwise BYO (GitHub username / --for-user).
     `,
     });
     shareCmd
         .command('analytics')
         .description('Show the Cloudflare Web Analytics status for this share endpoint.')
         .action(async () => {
+        let backend;
+        try {
+            backend = resolveShareBackend({ requireToken: false });
+        }
+        catch (e) {
+            console.log(chalk.dim(e.message));
+            return;
+        }
+        if (backend.kind === 'managed') {
+            console.log(chalk.yellow('Cloudflare Web Analytics is a BYO feature.'));
+            console.log(chalk.dim(`You're on the managed endpoint (${backend.baseUrl}). Per-page analytics for the managed endpoint is not in this release — provision your own Cloudflare with 'agents artifacts setup --analytics-token <token>', or force BYO with AGENTS_SHARE_BACKEND=byo.`));
+            return;
+        }
         const cfg = readShareConfig();
         if (!cfg) {
             console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
@@ -755,6 +849,11 @@ export async function runShareProvision(opts) {
                 spin.warn(`Zone for ${requestedDomain} not visible to this token — staying on workers.dev`);
             }
         }
+        const phoenixIdBase = phoenixIdBaseForDeploy({ managed: opts.managed }, { baseUrl, domain });
+        if (phoenixIdBase) {
+            await putWorkerSecret(apiToken, accountId, workerName, WORKER_PHOENIX_ID_BASE_SECRET, phoenixIdBase, provisionOpts);
+            spin.text = `Worker '${workerName}' Phoenix ID base set`;
+        }
         spin.succeed('Provisioned');
         const cfg = {
             baseUrl,
@@ -780,9 +879,10 @@ export async function runShareProvision(opts) {
  * current `worker-template.ts`. Reuses the existing account/worker/bucket and
  * write token from `readShareConfig()`/the `share` bundle — never creates a
  * bucket, touches routes/domains, or regenerates the token (see
- * `updateWorker` in `lib/share/provision.ts` for how the token survives the
- * re-upload). Idempotent: no-ops when the deployed hash already matches
- * unless `force`. */
+ * `updateWorker` in `lib/share/provision.ts` for how the token — and, on a
+ * managed endpoint, `PHOENIX_ID_BASE` — survives the re-upload). Idempotent:
+ * no-ops the script upload when the deployed hash already matches unless
+ * `force`; a managed endpoint still re-applies `PHOENIX_ID_BASE`. */
 export async function runShareUpdate(opts = {}) {
     const cfg = readShareConfig();
     if (!cfg) {
@@ -798,7 +898,12 @@ export async function runShareUpdate(opts = {}) {
     }
     const writeToken = readWriteToken();
     const script = renderWorkerScript();
-    const provisionOpts = { ...(opts.request ? { request: opts.request } : {}), force: opts.force };
+    const phoenixIdBase = phoenixIdBaseForDeploy({ managed: opts.managed }, cfg);
+    const provisionOpts = {
+        ...(opts.request ? { request: opts.request } : {}),
+        force: opts.force,
+        ...(phoenixIdBase !== undefined ? { phoenixIdBase } : {}),
+    };
     const result = await updateWorker(apiToken, accountId, cfg.workerName, cfg.bucketName, script, writeToken, cfg.templateHash, provisionOpts);
     if (!result.skipped) {
         writeShareConfig({ ...cfg, accountId, templateHash: result.templateHash });

package/dist/commands/ssh.js

@@ -124,11 +124,18 @@ function pctCell(v, width) {
  * header — which defeats the scannability this column exists for. */
 const SPEC_WIDTH_MIN = 12;
 /** The static hardware as one compact cell — `12c 64G 1T`: cores, total RAM,
- * total root disk via fmtBytes. `—` when the probe never saw the box (specs
- * ride the long-TTL static tier, so a warm cache almost always has them).
+ * total root disk via fmtBytes. `—` only when no probe has ever seen the box.
+ *
+ * Deliberately NOT gated on `reachable`: hardware does not change while a
+ * machine is down, so an offline device keeps rendering the spec from its last
+ * successful probe (`retainHardwareFacts`, RUSH-3096) rather than blanking a
+ * fact that is still true. The volatile columns beside it — load, mem, disk
+ * used — stay `—`, and `fleetCapacity` still counts only reachable boxes, so
+ * a down machine never contributes to usable capacity.
+ *
  * Unpadded; {@link renderDeviceTable} pads to the measured column width. */
 function specText(stats) {
-    if (!stats?.reachable || !stats.ncpu)
+    if (!stats?.ncpu)
         return '—';
     return `${stats.ncpu}c ${fmtBytes(stats.memTotalBytes)} ${fmtBytes(stats.diskTotalBytes)}`;
 }
@@ -225,7 +232,17 @@ export function renderDeviceTable(reg, names, self, statsMap, full = false, inte
         // "offline" while its live load/mem sit one column over (RUSH-1965).
         const offline = deviceOnlineState(d, stats) === 'offline';
         if (offline) {
-            lines.push(fitDeviceRow(`${marker}${label}${plat} ${chalk.gray('offline')}`, role, desc, width));
+            // The spec cell rides the offline row: hardware is what the box IS, not
+            // what it is doing, so it stays legible while the machine is down
+            // (RUSH-3096). The live columns are omitted rather than dashed — there is
+            // no current load/mem/disk to report for a box that did not answer.
+            //
+            // The explicit gap is load-bearing: `specCell` pads to the MEASURED
+            // column width, so the widest spec on the fleet pads to nothing and the
+            // marker would collide with it ("455Goffline"). An online row gets its
+            // separation for free from `pctCell`'s right-alignment; this one has no
+            // numeric cell to lean on.
+            lines.push(fitDeviceRow(`${marker}${label}${plat} ${specCell(stats, specWidth)}  ${chalk.gray('offline')}`, role, desc, width));
             continue;
         }
         const relay = !isSelf && d.tailscale?.online && !d.tailscale.direct ? chalk.yellow(' relay') : '';
@@ -1085,7 +1102,7 @@ function registerDevicesCommands(program) {
     registerLeaseCommand(devicesCmd);
     registerSnapshotCommand(devicesCmd);
     registerCommandGroups(devicesCmd, [
-        { title: 'Discover & register', names: ['sync', 'register', 'add', 'ignore', 'unignore', 'ignored', 'rm'] },
+        { title: 'Discover & register', names: ['sync', 'register', 'add', 'ignore', 'unignore', 'ignored', 'remove'] },
         { title: 'Inspect', names: ['list', 'show', 'status', 'ping', 'harnesses', 'accounts', 'snapshot'] },
         { title: 'Disposable devices', names: ['lease'] },
         { title: 'Configure a device', names: ['config', 'describe', 'render'] },
@@ -1997,6 +2014,36 @@ function registerDevicesCommands(program) {
         await runFleetPing({ ...opts, verbose });
     });
     const csvList = (s) => s ? s.split(',').map((x) => x.trim()).filter(Boolean) : undefined;
+    devicesCmd
+        .command('pick')
+        .description('Print the device automatic placement would choose for offloaded machine work (the suite, a build) — least-loaded, reachable, POSIX, never the box you are sitting at. Writes just the name to stdout so scripts can consume it.')
+        .option('--json', 'output the pick plus every candidate and exclusion reason')
+        .option('--platform <list>', 'comma-separated platforms to allow (default: linux,macos)')
+        .action(async (opts) => {
+        const { resolveWorkerDevice } = await import('../lib/devices/worker-pick.js');
+        let plan;
+        try {
+            plan = await resolveWorkerDevice({ platforms: csvList(opts.platform) });
+        }
+        catch (err) {
+            // Fail loud with the resolver's own message. Never print a device name
+            // we did not actually pick: a caller reading stdout would ship a tree to it.
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(plan, null, 2));
+            return;
+        }
+        // stdout is the name alone (`box="$(agents devices pick)"`); the human
+        // detail goes to stderr so it never pollutes that capture.
+        const detail = plan.candidates
+            .map((c) => `${c.device}:${c.loadPercent === undefined ? '?' : `${Math.round(c.loadPercent)}%`}`)
+            .join(' ');
+        console.error(chalk.gray(`[agents] worker=${plan.device}${plan.isLocal ? ' (this machine)' : ''}  candidates: ${detail}`));
+        console.log(plan.device);
+    });
     const harnessInvOpts = (opts) => ({
         agents: csvList(opts.agents),
         devices: csvList(opts.device ?? opts.devices),
@@ -2156,8 +2203,8 @@ email) into a single row. Use \`agents devices harnesses\` for the per-install v
         }
     });
     devicesCmd
-        .command('rm <name>')
-        .alias('remove')
+        .command('remove <name>')
+        .alias('rm')
         .description('Remove a device from the registry.')
         .action(async (name) => {
         const ok = await removeDevice(name);

package/dist/commands/teams.d.ts

@@ -7,9 +7,11 @@
  */
 import type { Command } from 'commander';
 import { AgentManager, AgentStatus, type TaskType } from '../lib/teams/agents.js';
+import type { DispatchOptions } from '../lib/cloud/types.js';
 import { type TaskInfo } from '../lib/teams/api.js';
 import { type TeamRow } from './teams-picker.js';
 import { type TeamSpawner } from '../lib/session/db.js';
+import type { AgentProcess } from '../lib/teams/agents.js';
 type TeamRegistry = Record<string, {
     created_at: string;
     description?: string;
@@ -106,6 +108,16 @@ export declare function staleRepoError(params: {
  * the teammate itself so we don't need the original --cloud CLI args.
  */
 export declare function wireCloudDispatcher(mgr: AgentManager): void;
+export declare function cloudDispatchOptions(agent: Pick<AgentProcess, 'prompt' | 'agentType' | 'cloudRepo' | 'cloudBranch' | 'model'>): DispatchOptions;
+/**
+ * Single-wave start used by `teams start` without --watch. startReady()
+ * terminalizes a placement/spawn/cloud/dependency failure to FAILED with
+ * evidence rather than leaving it PENDING, so a teammate that failed this wave
+ * appears in neither `launched` nor `still_pending` — it must be diffed against
+ * the pre-wave roster and reported explicitly, or the wave reads as a success.
+ * A wave that only produced failures sets a non-zero exit code.
+ */
+export declare function runOneWave(mgr: AgentManager, team: string, json: boolean): Promise<void>;
 export declare function buildTeamRowsFromSnapshots(registry: TeamRegistry, agents: TeamListAgentSnapshot[], 
 /** team name -> the session that spawned it (see teamSpawners). */
 spawners?: Map<string, TeamSpawner>): {