@phnx-labs/agents-cli 1.22.37 → 1.22.39

package/dist/commands/share.d.ts

@@ -57,8 +57,8 @@ interface ShareDeleteCliOpts {
     githubUser?: string;
     json?: boolean;
 }
-/** Shared handler for `agents share delete <targets...>` and the top-level
- * `agents unshare <targets...>` alias. Deletes each target independently and
+/** Shared handler for `agents artifacts share delete <targets...>` and the
+ * top-level `agents unshare <targets...>` alias. Deletes each target independently and
  * continues past a failed one (rm-style), reporting all results and exiting
  * non-zero if any target failed to verify as gone.
  *
@@ -66,10 +66,23 @@ interface ShareDeleteCliOpts {
  * never exposed as a CLI flag, only used to inject a fake config/checker/deleter
  * without touching the keychain or a live endpoint. */
 export declare function runShareDelete(targets: string[], opts: ShareDeleteCliOpts, deleteFn?: typeof deleteShare): Promise<void>;
-export declare function registerShareCommands(program: Command): void;
+/**
+ * Register the `share` subtree under its parent group — `agents artifacts share`
+ * (see commands/artifacts.ts). The top-level `agents unshare` alias is a sibling
+ * registration on the ROOT program, so it is {@link registerUnshareCommand}, not
+ * part of this subtree.
+ */
+export declare function registerShareCommands(artifactsCmd: Command): void;
+/**
+ * Register the top-level `agents unshare <targets...>` alias of
+ * `agents artifacts share delete`. It takes the ROOT program (not the artifacts
+ * group) because it is deliberately a top-level convenience verb — taking a page
+ * down is the one artifact action typed often enough to keep at the root.
+ */
+export declare function registerUnshareCommand(program: Command): void;
 /** Provision a fresh R2 bucket + Worker on the user's Cloudflare and persist the
- * endpoint config + write token. Shared by `agents share setup` and the unified
- * `agents setup share` wizard. */
+ * endpoint config + write token. Shared by both modes of `agents artifacts setup`
+ * (the flag-driven provision and the interactive wizard). */
 export declare function runShareProvision(opts: {
     bundle: string;
     worker: string;
@@ -101,8 +114,8 @@ export declare function runShareUpdate(opts?: {
     request?: CloudflareRequester;
 }): Promise<ShareUpdateResult>;
 /** Join an existing share endpoint (no provisioning): prompt for the endpoint
- * details + write token and persist them. Shared by `agents share join` and the
- * unified `agents setup share` wizard. */
+ * details + write token and persist them. Shared by `agents artifacts share join`
+ * and the `agents artifacts setup` wizard. */
 export declare function runShareJoin(baseUrl?: string, opts?: {
     token?: string;
 }): Promise<void>;

package/dist/commands/share.js

@@ -1,5 +1,9 @@
-// `agents 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 your own Cloudflare R2
+// behind a tiny Worker, and get a shareable link (~$0). See apps/cli/docs/share.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 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';
@@ -35,10 +39,10 @@ export function shareTemplateStatus(cfg) {
 }
 /** Shown whenever the deployed Worker has no `?format=json` listing route — an
  * endpoint provisioned before this feature. Points at the RUSH-2449 update path
- * (`agents share update`) instead of letting the caller hit a 404 or an HTML body
- * and get a confusing parse error. */
-const OUTDATED_TEMPLATE_HINT = 'Your deployed share Worker has no machine-readable listing route — it predates `agents share list`. ' +
-    'Run `agents share update` to deploy the current Worker template, then retry (`agents share status` shows whether an update is due).';
+ * (`agents artifacts share update`) instead of letting the caller hit a 404 or an
+ * HTML body and get a confusing parse error. */
+const OUTDATED_TEMPLATE_HINT = 'Your deployed share Worker has no machine-readable listing route — it predates `agents artifacts share list`. ' +
+    'Run `agents artifacts share update` to deploy the current Worker template, then retry (`agents artifacts share status` shows whether an update is due).';
 async function defaultListingFetch(url) {
     const res = await fetch(url, { headers: { accept: 'application/json' } });
     return { status: res.status, contentType: res.headers.get('content-type') ?? '', body: await res.text() };
@@ -80,7 +84,7 @@ export function parseShareListing(user, body) {
 export async function runShareList(opts = {}) {
     const cfg = opts.config ?? readShareConfig();
     if (!cfg) {
-        throw new Error("Not set up yet. Run 'agents share setup' (provision your own endpoint) or 'agents share join' (use an existing one).");
+        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
@@ -100,14 +104,14 @@ 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 share update`.
+        // at `agents artifacts share update`.
         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 share setup' completed.`);
+        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
         // A 200 that isn't JSON means the old Worker ignored ?format=json and served
@@ -157,8 +161,8 @@ export function formatShareDeleteResult(result, json = false) {
     }
     return lines.join('\n');
 }
-/** Shared handler for `agents share delete <targets...>` and the top-level
- * `agents unshare <targets...>` alias. Deletes each target independently and
+/** Shared handler for `agents artifacts share delete <targets...>` and the
+ * top-level `agents unshare <targets...>` alias. Deletes each target independently and
  * continues past a failed one (rm-style), reporting all results and exiting
  * non-zero if any target failed to verify as gone.
  *
@@ -200,10 +204,10 @@ function registerShareDeleteOptions(cmd) {
 }
 const SHARE_DELETE_EXAMPLES = `
       # Delete by full URL — also takes down the sibling OG cover
-      agents share delete https://share.agents-cli.sh/octocat/my-plan-a1b2
+      agents artifacts share delete https://share.agents-cli.sh/octocat/my-plan-a1b2
 
       # Delete by <user>/<slug>, or a bare slug in your own namespace
-      agents share delete octocat/my-plan-a1b2
+      agents artifacts share delete octocat/my-plan-a1b2
       agents unshare my-plan-a1b2
 
       # Several at once
@@ -220,17 +224,23 @@ const SHARE_DELETE_NOTES = `
   Worker's DELETE is idempotent and returns {"ok":true} even for a key that was
   never there, so that response alone is never proof of a takedown.
 
-  agents share delete === agents unshare (same command, different name).
+  agents artifacts share delete === agents unshare (same command, different name).
 `;
-export function registerShareCommands(program) {
-    const shareCmd = program
+/**
+ * Register the `share` subtree under its parent group — `agents artifacts share`
+ * (see commands/artifacts.ts). The top-level `agents unshare` alias is a sibling
+ * registration on the ROOT program, so it is {@link registerUnshareCommand}, not
+ * part of this subtree.
+ */
+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).')
         .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('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
-        .option('--unlisted', 'hide from the public gallery and `agents share list` (direct URL still works)')
+        .option('--unlisted', 'hide from the public gallery and `agents artifacts share list` (direct URL still works)')
         .option('--private', 'alias of --unlisted')
         .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)')
@@ -266,30 +276,30 @@ export function registerShareCommands(program) {
     setHelpSections(shareCmd, {
         examples: `
       # Publish an HTML file — auto OG cover, default 30d expiry, shareable link
-      agents share ./out/plan.html
+      agents artifacts share ./out/plan.html
 
       # Hide from the public gallery (direct URL still works) and expire sooner
-      agents share ./out/report.html --unlisted --expire 12h
+      agents artifacts share ./out/report.html --unlisted --expire 12h
 
       # Permanent public page (opt out of the default 30d expiry)
-      agents share ./out/landing.html --slug landing --expire never
+      agents artifacts share ./out/landing.html --slug landing --expire never
 
       # Custom slug, expiring in 7 days
-      agents share ./out/report.html --slug q3-report --expire 7d
+      agents artifacts share ./out/report.html --slug q3-report --expire 7d
 ${SHARE_DELETE_EXAMPLES}
       # One-time setup (or join an existing endpoint)
-      agents share setup
-      agents share join https://share.agents-cli.sh
+      agents artifacts setup
+      agents artifacts share join https://share.agents-cli.sh
 
       # Push a worker-template.ts change out to an already-provisioned endpoint
-      agents share update
+      agents artifacts share update
     `,
         notes: `
   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 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.
+  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.
 ${SHARE_DELETE_NOTES}
     `,
     });
@@ -300,32 +310,6 @@ ${SHARE_DELETE_NOTES}
     shareDeleteCmd.action(async (targets, opts) => {
         await runShareDelete(targets, opts);
     });
-    const unshareCmd = registerShareDeleteOptions(program
-        .command('unshare <targets...>')
-        .description('Alias of `agents share delete` — take down a published page (and by default its OG cover).'));
-    setHelpSections(unshareCmd, { examples: SHARE_DELETE_EXAMPLES, notes: SHARE_DELETE_NOTES });
-    unshareCmd.action(async (targets, opts) => {
-        await runShareDelete(targets, opts);
-    });
-    shareCmd
-        .command('setup')
-        .description('One-time: provision an R2 bucket + Worker on your Cloudflare and save the config.')
-        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
-        .option('--worker <name>', 'Worker name', DEFAULT_WORKER_NAME)
-        .option('--bucket <name>', 'R2 bucket name', DEFAULT_BUCKET_NAME)
-        .option('--account <id>', 'Cloudflare account id (else read from the bundle / prompt)')
-        .option('--token <t>', 'Cloudflare API token (else read from the --bundle)')
-        .option('--domain <host>', `custom domain to map (default: ${DEFAULT_SHARE_DOMAIN}; workers.dev if zone is not visible)`)
-        .option('--analytics-token <token>', 'Cloudflare Web Analytics token to inject into published HTML pages')
-        .action(async (opts) => {
-        try {
-            await runShareProvision(opts);
-        }
-        catch (e) {
-            console.error(chalk.red(e.message));
-            process.exitCode = 1;
-        }
-    });
     shareCmd
         .command('join')
         .description('Use an existing synced share endpoint and write token (no provisioning).')
@@ -370,15 +354,15 @@ ${SHARE_DELETE_NOTES}
     setHelpSections(shareUpdateCmd, {
         examples: `
       # Push a worker-template.ts change out to your already-provisioned endpoint
-      agents share update
+      agents artifacts share update
 
       # Force a re-deploy even though the template hash already matches
-      agents share update --force
+      agents artifacts share update --force
     `,
         notes: `
-  Reuses the existing account/worker/bucket from 'agents share status' and the
+  Reuses the existing account/worker/bucket from 'agents artifacts share status' and the
   existing write token — it never re-provisions a bucket, touches routes, or
-  regenerates the token. See 'agents share status' for whether an update is due.
+  regenerates the token. See 'agents artifacts share status' for whether an update is due.
     `,
     });
     shareCmd
@@ -387,7 +371,7 @@ ${SHARE_DELETE_NOTES}
         .action(async () => {
         const cfg = readShareConfig();
         if (!cfg) {
-            console.log(chalk.dim("Not configured. Run 'agents share setup' or 'agents share join'."));
+            console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
             return;
         }
         console.log(`${chalk.bold('endpoint')}  ${chalk.green(cfg.baseUrl)}`);
@@ -399,8 +383,8 @@ ${SHARE_DELETE_NOTES}
         const templateLabel = templateStatus === 'current'
             ? chalk.green('current')
             : templateStatus === 'outdated'
-                ? chalk.yellow('outdated — run `agents share update`')
-                : chalk.dim("unknown — provisioned before version tracking; run `agents share update` to adopt it");
+                ? chalk.yellow('outdated — run `agents artifacts share update`')
+                : chalk.dim("unknown — provisioned before version tracking; run `agents artifacts share update` to adopt it");
         console.log(`${chalk.bold('template')}  ${templateLabel}`);
     });
     const shareListCmd = shareCmd
@@ -421,21 +405,21 @@ ${SHARE_DELETE_NOTES}
     setHelpSections(shareListCmd, {
         examples: `
       # Everything you've published, newest first
-      agents share list
+      agents artifacts share list
 
       # Machine-readable — e.g. pull every still-public URL with jq
-      agents share list --json | jq -r '.objects[].url'
+      agents artifacts share list --json | jq -r '.objects[].url'
 
       # List another namespace
-      agents share list --github-user octocat
+      agents artifacts share list --github-user octocat
     `,
         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 share
-  update' (RUSH-2449) rather than returning a wrong or empty result — see 'agents
-  share status' for whether an update is due.
+  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.
     `,
     });
     shareCmd
@@ -444,7 +428,7 @@ ${SHARE_DELETE_NOTES}
         .action(async () => {
         const cfg = readShareConfig();
         if (!cfg) {
-            console.log(chalk.dim("Not configured. Run 'agents share setup' or 'agents share join'."));
+            console.log(chalk.dim("Not configured. Run 'agents artifacts setup' or 'agents artifacts share join'."));
             return;
         }
         if (!analyticsEnabled(cfg)) {
@@ -464,9 +448,24 @@ ${SHARE_DELETE_NOTES}
         }
     });
 }
+/**
+ * Register the top-level `agents unshare <targets...>` alias of
+ * `agents artifacts share delete`. It takes the ROOT program (not the artifacts
+ * group) because it is deliberately a top-level convenience verb — taking a page
+ * down is the one artifact action typed often enough to keep at the root.
+ */
+export function registerUnshareCommand(program) {
+    const unshareCmd = registerShareDeleteOptions(program
+        .command('unshare <targets...>')
+        .description('Alias of `agents artifacts share delete` — take down a published page (and by default its OG cover).'));
+    setHelpSections(unshareCmd, { examples: SHARE_DELETE_EXAMPLES, notes: SHARE_DELETE_NOTES });
+    unshareCmd.action(async (targets, opts) => {
+        await runShareDelete(targets, opts);
+    });
+}
 /** Provision a fresh R2 bucket + Worker on the user's Cloudflare and persist the
- * endpoint config + write token. Shared by `agents share setup` and the unified
- * `agents setup share` wizard. */
+ * endpoint config + write token. Shared by both modes of `agents artifacts setup`
+ * (the flag-driven provision and the interactive wizard). */
 export async function runShareProvision(opts) {
     const { default: ora } = await import('ora');
     const { input } = await import('@inquirer/prompts');
@@ -521,7 +520,7 @@ export async function runShareProvision(opts) {
         writeShareConfig(cfg);
         storeWriteToken(token);
         console.log(chalk.green(`\nShare endpoint ready → ${chalk.bold(baseUrl)}`));
-        console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents share <file>'));
+        console.log(chalk.dim('Publish with:  ') + chalk.cyan('agents artifacts share <file>'));
         console.log(chalk.dim(`Fleet: push the token with 'agents secrets export share --host <box>' and pull config with 'agents repo pull'.`));
     }
     catch (e) {
@@ -539,7 +538,7 @@ export async function runShareProvision(opts) {
 export async function runShareUpdate(opts = {}) {
     const cfg = readShareConfig();
     if (!cfg) {
-        throw new Error("Not configured. Run 'agents share setup' (to provision) or 'agents share join' first.");
+        throw new Error("Not configured. Run 'agents artifacts setup' (to provision) or 'agents artifacts share join' first.");
     }
     const { apiToken, accountId: acctFromBundle } = readCloudflareCreds(opts.bundle ?? DEFAULT_CF_BUNDLE, {
         apiToken: opts.token,
@@ -568,14 +567,14 @@ function cleanHostname(domain) {
     }
 }
 /** Join an existing share endpoint (no provisioning): prompt for the endpoint
- * details + write token and persist them. Shared by `agents share join` and the
- * unified `agents setup share` wizard. */
+ * details + write token and persist them. Shared by `agents artifacts share join`
+ * and the `agents artifacts setup` wizard. */
 export async function runShareJoin(baseUrl, opts = {}) {
     const { password, input } = await import('@inquirer/prompts');
     const existing = readShareConfig();
     const clean = baseUrl?.replace(/\/+$/, '');
     if (!clean && !existing) {
-        throw new Error("No synced share endpoint found. Pull config first with 'agents repo pull', or pass the endpoint URL: agents share join <baseUrl>.");
+        throw new Error("No synced share endpoint found. Pull config first with 'agents repo pull', or pass the endpoint URL: agents artifacts share join <baseUrl>.");
     }
     let cfg;
     if (existing && (!clean || clean === existing.baseUrl)) {
@@ -608,5 +607,5 @@ export async function runShareJoin(baseUrl, opts = {}) {
         throw new Error('A write token is required to join.');
     writeShareConfig(cfg);
     storeWriteToken(token);
-    console.log(chalk.green(`Joined ${chalk.bold(cfg.baseUrl)} — publish with `) + chalk.cyan('agents share <file>'));
+    console.log(chalk.green(`Joined ${chalk.bold(cfg.baseUrl)} — publish with `) + chalk.cyan('agents artifacts share <file>'));
 }

package/dist/commands/ssh.js

@@ -56,7 +56,8 @@ import { crabboxList, crabboxFind, crabboxSshArgv } from '../lib/crabbox/cli.js'
 import { boxAddress, boxStatus, fmtIdleShort, fmtExpiresShort, registerLeaseCommand } from './lease.js';
 import { authCellColor, formatCheckedAge, isDeadVerdict, readAuthHealthCache, summarizeHostAuth, summarizeVerdicts, verdictColor, verdictLabel, writeFleetAuthRows, } from '../lib/auth-health.js';
 import { runFleetLogin } from '../lib/fleet/remote-login.js';
-import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec } from '../lib/device-config.js';
+import { getConfigValue, listConfig, setConfigValue, unsetConfigValue, configKeySpec, autoPoolMode, configuredDeviceRole, listConfiguredDeviceRoles, setConfiguredDeviceRole, } from '../lib/device-config.js';
+import { filterAutoPool, listWorkerDevices } from '../lib/devices/pool.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 /** One-line summary of a device for `list`. `isSelf` marks the machine this
  * command is running on so it stands out from the rest of the tailnet.
@@ -77,7 +78,20 @@ function deviceSummary(d, isSelf = false, stats, isInteractive = false) {
     const name = isSelf ? chalk.bold.cyan(d.name.padEnd(16)) : chalk.bold(d.name.padEnd(16));
     const here = isSelf ? chalk.cyan('  ← this machine') : '';
     const interactive = isInteractive ? chalk.yellow('  ★ interactive') : '';
-    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}`;
+    const role = roleTag(d.name, listConfiguredDeviceRoles());
+    return `${marker}${name} ${String(d.platform).padEnd(8)} ${(d.user ? d.user + '@' : '') + addr}  ${online}${reach}${here}${interactive}${role}`;
+}
+/** The fleet-wide role mark, rendered for a device row. Empty when unmarked —
+ * an unmarked device is the common case and must not add a column of noise. */
+function roleTag(name, roles) {
+    const role = roles[name];
+    if (!role)
+        return '';
+    if (role === 'worker')
+        return chalk.green('  worker');
+    if (role === 'personal')
+        return chalk.yellow('  personal');
+    return chalk.gray('  control');
 }
 const HEADROOM_BADGE = {
     idle: chalk.green('○ idle'),
@@ -107,6 +121,7 @@ function pctCell(v, width) {
 function renderDeviceTable(reg, names, self, statsMap, full = false, interactiveHost) {
     if (!statsMap)
         return names.map((n) => deviceSummary(reg[n], n === self, undefined, n === interactiveHost));
+    const deviceRoles = listConfiguredDeviceRoles();
     const lines = [];
     const head = '  ' +
         chalk.gray('device'.padEnd(16)) +
@@ -149,7 +164,7 @@ function renderDeviceTable(reg, names, self, statsMap, full = false, interactive
         const badge = HEADROOM_BADGE[headroom(stats)];
         const here = isSelf ? chalk.cyan('  ← this machine') : '';
         const interactive = name === interactiveHost ? chalk.yellow('  ★ interactive') : '';
-        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}`);
+        lines.push(`${marker}${label}${plat} ${cores}${load}${mem}${freeTotal}  ${badge}${relay}${here}${interactive}${roleTag(name, deviceRoles)}`);
     }
     // Fleet capacity summary — total cores + how much RAM is free right now.
     const cap = fleetCapacity(statsMap.values());
@@ -1161,6 +1176,84 @@ function registerDevicesCommands(program) {
         }
         await runDevicesConfigMenu(name);
     };
+    /**
+     * The `devices role` engine — read or write the fleet-wide role mark, and say
+     * what it does to automatic placement.
+     *
+     * A role written here lands in the SHARED block (`fleet.devices.<name>.config.role`)
+     * because every box has to agree on it. The vocabulary is deliberately
+     * `worker | personal` only: a paired cockpit's `control` role lives in the
+     * per-machine device registry, is written by `agents devices pair-ios`, and is
+     * what the existing dial-exclusion filters (`isControlDevice`) read. Accepting
+     * `control` here too would promise a fleet-wide dial exclusion this key cannot
+     * deliver — those filters read each box's own registry, so the mark would only
+     * hold on the machine that ran the command.
+     */
+    const runDevicesRole = async (name, role, opts) => {
+        if (!name) {
+            if (role)
+                throw new Error('Name a device: agents devices role <name> <worker|personal>');
+            const roles = listConfiguredDeviceRoles();
+            const mode = autoPoolMode();
+            const reg = await loadDevices();
+            const online = Object.entries(reg)
+                .filter(([, d]) => d?.tailscale?.online !== false)
+                .map(([n]) => n);
+            const pool = filterAutoPool(online, { mode, roles });
+            if (opts.json) {
+                writeJson({ mode, roles, autoPool: pool });
+                return;
+            }
+            const marked = Object.entries(roles);
+            if (marked.length === 0) {
+                console.log(chalk.gray('No device is marked. `--device auto` considers every online device.'));
+            }
+            else {
+                for (const [device, r] of marked) {
+                    const tint = r === 'worker' ? chalk.green : r === 'personal' ? chalk.yellow : chalk.gray;
+                    console.log(`  ${device.padEnd(20)} ${tint(r)}`);
+                }
+            }
+            console.log();
+            console.log(chalk.bold('--device auto picks from: ') + (pool.length > 0 ? pool.join(', ') : chalk.red('nothing — no eligible device')));
+            if (mode === 'all')
+                console.log(chalk.gray('auto.pool=all — worker marks are ignored (a personal device is still excluded).'));
+            return;
+        }
+        await mustGetDevice(name);
+        if (opts.clear || role === 'none') {
+            setConfiguredDeviceRole(name, undefined);
+            if (opts.json)
+                writeJson({ device: name, role: null });
+            else
+                console.log(chalk.green(`Cleared the role on '${name}'.`));
+            return;
+        }
+        if (!role) {
+            const current = configuredDeviceRole(name);
+            if (opts.json)
+                writeJson({ device: name, role: current ?? null });
+            else
+                console.log(`  ${name.padEnd(20)} ${current ? chalk.cyan(current) : chalk.gray('— (unmarked)')}`);
+            return;
+        }
+        // configuredDeviceRole's key spec validates the value; a bad one throws with
+        // the accepted list, which the command's catch turns into exit 1.
+        setConfiguredDeviceRole(name, role);
+        if (opts.json) {
+            writeJson({ device: name, role, autoPoolWorkers: listWorkerDevices() });
+            return;
+        }
+        console.log(chalk.green(`Marked '${name}' role=${role}.`));
+        const workers = listWorkerDevices();
+        if (workers.length > 0) {
+            console.log(chalk.gray(`\`--device auto\` now picks only from: ${workers.join(', ')}`));
+        }
+        else {
+            console.log(chalk.gray('No device is marked worker, so `--device auto` still considers every online device.'));
+        }
+        console.log(chalk.gray('Sync it to the fleet with `agents repo push`.'));
+    };
     /** The interactive settings menu: pick a key, edit it, repeat. TTY-only. */
     const runDevicesConfigMenu = async (name) => {
         const { select, input, confirm } = await import('@inquirer/prompts');
@@ -1250,22 +1343,27 @@ function registerDevicesCommands(program) {
       agents devices config win-mini ssh.auth password          # password auth…
       agents devices config win-mini ssh.bundle muqsit          # …from this secrets bundle
       agents devices config worker ssh.identity-file ~/.ssh/worker_ed25519
+      agents devices config mac-mini role worker                 # same as \`agents devices role mac-mini worker\`
       agents devices config mac-mini auto-launch.enabled off    # exclude from AGI EXT auto-launch
       agents devices config mac-mini auto-launch.preferred on   # boost in auto-launch ranking
       agents devices config zion interactive.host zion          # user scope: where agents show YOU artifacts
       agents devices config mac-mini --json                     # machine-readable
     `,
         notes: `
-      Keys: agents.max-concurrent, scheduler.enabled, daemon.enabled,
-      watchdog.enabled, browser.remote-control, browser.profile, notes,
-      ssh.user, ssh.auth (key|password), ssh.bundle, ssh.bundle-key,
+      Keys: role (worker|personal), see 'agents devices role',
+      agents.max-concurrent, scheduler.enabled, daemon.enabled,
+      watchdog.enabled, tmux.enabled, browser.remote-control, browser.profile,
+      notes, ssh.user, ssh.auth (key|password), ssh.bundle, ssh.bundle-key,
       ssh.identity-file, platform (windows|linux|macos|unknown),
       auto-launch.enabled, auto-launch.preferred — plus the user-scope
       interactive.host (stored centrally; the device name is syntax only).
 
       Booleans take on/off (or true/false). 'notes' appends one entry per
-      invocation. Values land in ~/.agents/agents.yaml under
-      fleet.devices.<name>.config and sync with 'agents repo push/pull'.
+      invocation. Values a PEER reads land in ~/.agents/agents.yaml under
+      fleet.devices.<name>.config and sync with 'agents repo push/pull'. The
+      keys only the owning box reads — scheduler.enabled, daemon.enabled,
+      tmux.enabled, browser.remote-control, browser.profile — stay in that
+      machine's own doc, never sync, and can only be set on the device itself.
       ssh.* / platform / user overlay the discovered registry profile at dial
       time. scheduler.enabled / daemon.enabled take effect when the daemon
       reloads or restarts on that device.
@@ -1274,6 +1372,49 @@ function registerDevicesCommands(program) {
       set, set-interactive, enable, disable, prefer, unprefer.
     `,
     });
+    const roleCmd = devicesCmd
+        .command('role [name] [role]')
+        .description('Show or set what a device is for: worker (agents run here) or personal (you sit here — never picked automatically). ' +
+        'Marking any device worker makes `--device auto` an allowlist over the marked workers.')
+        .option('--clear', 'remove the mark, returning the device to unmarked')
+        .option('--json', 'output machine-readable JSON')
+        .action(async (name, role, opts) => {
+        try {
+            await runDevicesRole(name, role, opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(roleCmd, {
+        examples: `
+      agents devices role                          # who is marked what, and what --device auto would pick
+      agents devices role yosemite-s0 worker       # agents spin up here
+      agents devices role yosemite-s1 worker       # …and here; auto now rotates over these two only
+      agents devices role zion personal            # your laptop — keep automatic placement off it
+      agents devices role yosemite-s0 --clear      # unmark
+      agents devices role --json                   # machine-readable
+    `,
+        notes: `
+      Roles are stored fleet-wide in ~/.agents/agents.yaml under
+      fleet.devices.<name>.config.role and travel with 'agents repo push/pull',
+      so a mark set on one box is the whole fleet's answer.
+
+      Effect on '--device auto' (agents run, teams, agents ssh auto, and the AGI
+      EXT launch commands, which all resolve placement through the CLI):
+        no device marked  -> every online device, as before
+        any worker marked -> ONLY the marked workers
+        personal          -> never picked, under either state
+
+      Turn the allowlist off with 'agents config set auto.pool all'; a personal
+      box stays excluded, since that is what the mark is for.
+
+      A paired iPhone/iPad cockpit is a separate role: 'agents devices pair-ios'
+      marks it control in that box's device registry, and the fleet never dials
+      it — including for placement. This command does not set that role.
+    `,
+    });
     /** Deprecation notice for a retired subcommand — STDERR only, so a --json consumer's stdout stays parseable. */
     const configTombstoneNotice = (retired, replacement) => {
         console.error(chalk.yellow(`Deprecated: "agents devices ${retired}" is now "agents devices ${replacement}". Running that for you.\n`));
@@ -1493,12 +1634,19 @@ function registerDevicesCommands(program) {
                 await writeReachability(collectReachabilityWriteBacks(reg, statsMap)).catch(() => { });
         }
         if (opts.json) {
+            const jsonRoles = listConfiguredDeviceRoles();
+            const autoPool = new Set(filterAutoPool(names, { roles: jsonRoles }));
             process.stdout.write(JSON.stringify(names.map((name) => {
                 const config = deviceConfigJson(name);
                 const health = statsMap?.get(name);
                 return {
                     ...resolveDeviceProfile(reg[name]),
                     interactive: name === interactiveHost,
+                    // Roles as machine-readable fields: `role` is what the operator
+                    // marked (absent when unmarked), `autoPool` is the answer that
+                    // matters to a caller — may `--device auto` pick this box.
+                    ...(jsonRoles[name] ? { role: jsonRoles[name] } : {}),
+                    autoPool: autoPool.has(name),
                     ...(config ? { config } : {}),
                     ...(health ? { health: { ...health, headroom: headroom(health) } } : {}),
                 };