@phnx-labs/agents-cli 1.22.37 → 1.22.39

package/dist/lib/migrate.d.ts

@@ -58,6 +58,42 @@ export declare function foldBrowserSessionsIntoProfiles(browserDir?: string): vo
  * can drive a fixture tree without touching the user's ~/.agents.
  */
 export declare function repairSelfReferentialBinShims(versionsRoot?: string, shimsDir?: string, historyDir?: string): void;
+/**
+ * Move the auto-detected `default` browser profile OUT of the committed central
+ * agents.yaml and into this machine's per-device file.
+ *
+ * `browser` is a CENTRAL key because named profiles a user creates are real fleet
+ * config, but the ONE `default` entry inside it is machine-local: its `binary` is
+ * an OS-specific path and its endpoint is a locally-chosen free port.
+ * `createProfile`/`updateProfile` already route that entry to `deviceBrowser`
+ * (`isMachineLocalProfile`, browser/profiles.ts) — but nothing ever removed the
+ * copy older versions had already written into the shared file, and
+ * `serializeCentral` cannot: it deletes whole KEYS that are device-scoped, and
+ * `browser` is not one.
+ *
+ * So the entry sat in the committed file and every box rewrote it with its own
+ * browser. Measured 2026-08-13, all three boxes on 1.22.38 (which HAS the writer
+ * fix) with an empty `deviceBrowser` and a machine-specific `default` in central:
+ *
+ *   zion         browser: chrome    binary: /Applications/Google Chrome.app/...
+ *   yosemite-s1  browser: brave     binary: /opt/brave.com/brave/brave
+ *   mark-1       (same shape)
+ *
+ * `agents repos pull user` refuses when an incoming change touches a locally
+ * modified path, so agents.yaml being permanently dirty wedged the fleet config
+ * sync outright — those boxes sat 5, 8 and 79 commits behind. (RUSH-2161)
+ *
+ * Idempotent: no-op once central carries no `default` entry. The device file is
+ * written FIRST so a crash between the two writes can never lose the profile,
+ * and an entry already in the device file wins (this machine's live value is
+ * newer than the stale central copy by construction).
+ *
+ * Central is edited through a `yaml.Document` rather than re-stringified, so the
+ * hand-written comments in the committed agents.yaml survive — a plain
+ * `yaml.stringify` would drop every one of them and rewrite the whole file,
+ * which is the same churn this migration exists to stop (see `serializeCentral`).
+ */
+export declare function migrateMachineLocalBrowserProfileOutOfCentral(userDir?: string, machine?: string): void;
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in

package/dist/lib/migrate.js

@@ -21,6 +21,10 @@ import { setConfigValue } from './device-config.js';
 import { enabledRoutineNames, replaceEnabledRoutines } from './routine-activation.js';
 import { evaluateActivationReadiness } from './routine-readiness.js';
 import { migrateDeviceConfigToCentral } from './devices/config-migration.js';
+// Two constants only, never the read/write API — migrations still operate on raw
+// YAML so they never take the meta lock or prime the meta cache mid-migration.
+import { DEFAULT_BROWSER_PROFILE_NAME } from './browser/profiles.js';
+import { META_HEADER as DEVICE_META_HEADER } from './state.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -1688,6 +1692,103 @@ function migrateSplitDeviceLocalMeta() {
         console.error('Split agents.yaml: agents: -> devices/, versions: -> .history/version-resources.json');
     }
 }
+/**
+ * Move the auto-detected `default` browser profile OUT of the committed central
+ * agents.yaml and into this machine's per-device file.
+ *
+ * `browser` is a CENTRAL key because named profiles a user creates are real fleet
+ * config, but the ONE `default` entry inside it is machine-local: its `binary` is
+ * an OS-specific path and its endpoint is a locally-chosen free port.
+ * `createProfile`/`updateProfile` already route that entry to `deviceBrowser`
+ * (`isMachineLocalProfile`, browser/profiles.ts) — but nothing ever removed the
+ * copy older versions had already written into the shared file, and
+ * `serializeCentral` cannot: it deletes whole KEYS that are device-scoped, and
+ * `browser` is not one.
+ *
+ * So the entry sat in the committed file and every box rewrote it with its own
+ * browser. Measured 2026-08-13, all three boxes on 1.22.38 (which HAS the writer
+ * fix) with an empty `deviceBrowser` and a machine-specific `default` in central:
+ *
+ *   zion         browser: chrome    binary: /Applications/Google Chrome.app/...
+ *   yosemite-s1  browser: brave     binary: /opt/brave.com/brave/brave
+ *   mark-1       (same shape)
+ *
+ * `agents repos pull user` refuses when an incoming change touches a locally
+ * modified path, so agents.yaml being permanently dirty wedged the fleet config
+ * sync outright — those boxes sat 5, 8 and 79 commits behind. (RUSH-2161)
+ *
+ * Idempotent: no-op once central carries no `default` entry. The device file is
+ * written FIRST so a crash between the two writes can never lose the profile,
+ * and an entry already in the device file wins (this machine's live value is
+ * newer than the stale central copy by construction).
+ *
+ * Central is edited through a `yaml.Document` rather than re-stringified, so the
+ * hand-written comments in the committed agents.yaml survive — a plain
+ * `yaml.stringify` would drop every one of them and rewrite the whole file,
+ * which is the same churn this migration exists to stop (see `serializeCentral`).
+ */
+export function migrateMachineLocalBrowserProfileOutOfCentral(userDir = USER_DIR, machine = machineId()) {
+    const metaFile = path.join(userDir, 'agents.yaml');
+    if (!fs.existsSync(metaFile))
+        return;
+    let doc;
+    try {
+        doc = yaml.parseDocument(fs.readFileSync(metaFile, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    if (doc.errors.length > 0)
+        return;
+    const central = doc.toJSON() ?? {};
+    const browser = central.browser;
+    if (!browser || typeof browser !== 'object' || Array.isArray(browser))
+        return;
+    const entry = browser[DEFAULT_BROWSER_PROFILE_NAME];
+    if (entry === undefined)
+        return;
+    // Device file first — a crash before central is rewritten leaves a harmless
+    // duplicate, while the reverse order would drop the profile entirely.
+    const devicePath = path.join(userDir, 'devices', machine, 'agents.yaml');
+    let deviceDoc = {};
+    try {
+        deviceDoc = yaml.parse(fs.readFileSync(devicePath, 'utf-8')) || {};
+    }
+    catch { /* absent — first write */ }
+    const deviceBrowser = (deviceDoc.browser && typeof deviceDoc.browser === 'object' && !Array.isArray(deviceDoc.browser))
+        ? deviceDoc.browser
+        : {};
+    if (deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] === undefined) {
+        deviceBrowser[DEFAULT_BROWSER_PROFILE_NAME] = entry;
+        deviceDoc.browser = deviceBrowser;
+        fs.mkdirSync(path.dirname(devicePath), { recursive: true });
+        atomicWriteFileSync(devicePath, DEVICE_META_HEADER + yaml.stringify(deviceDoc));
+    }
+    // Then strip it from the synced file, dropping `browser:` entirely when the
+    // machine-local entry was its only member.
+    doc.deleteIn(['browser', DEFAULT_BROWSER_PROFILE_NAME]);
+    if (Object.keys(browser).length === 1) {
+        const itemsOf = () => (doc.contents?.items) ?? [];
+        const idx = itemsOf().findIndex((pair) => pair.key?.value === 'browser');
+        const orphaned = idx >= 0 ? itemsOf()[idx]?.key?.commentBefore ?? undefined : undefined;
+        doc.delete('browser');
+        if (orphaned) {
+            // Deleting shifted the following pair down into `idx`.
+            const next = itemsOf()[idx]?.key;
+            if (next)
+                next.commentBefore = next.commentBefore ? `${orphaned}\n${next.commentBefore}` : orphaned;
+            else
+                doc.commentBefore = orphaned;
+        }
+    }
+    // Everything cleared -> header only, never a bare `{}`. stringifyDoc emits a
+    // FLOW empty map for an empty root, and a later parseDocument inherits that
+    // flow and renders the whole rewritten file inline. serializeCentral guards
+    // the identical case (state.ts, `isEmpty ? META_HEADER : stringifyDoc(doc)`).
+    const remaining = Object.keys(doc.toJSON() ?? {}).length;
+    atomicWriteFileSync(metaFile, remaining === 0 ? DEVICE_META_HEADER : stringifyDoc(doc));
+    console.error(`Migrated agents.yaml: browser '${DEFAULT_BROWSER_PROFILE_NAME}' profile -> devices/${machine}/agents.yaml`);
+}
 /**
  * Rename the legacy `extras-extras/` plugin-marketplace dir to `agents-extras/`
  * inside every installed agent version-home, and rewrite cross-references in
@@ -2299,6 +2400,12 @@ export async function runMigration() {
     // agents.yaml. After migrateVersionResourcesToPatterns so versions: is already
     // in pattern form when it moves to the history file.
     migrateSplitDeviceLocalMeta();
+    // Same split, one level deeper: `browser` stays central (named profiles are
+    // fleet config) but its auto-detected `default` entry is machine-local and was
+    // left behind in the synced file, keeping every box dirty. After
+    // migrateSplitDeviceLocalMeta so the device file is already in its canonical
+    // location before this merges an entry into it.
+    migrateMachineLocalBrowserProfileOutOfCentral();
     // Fold per-device operator config (device-doc config:/defaultBrowserProfile
     // and .history/devices/auto-launch.json) into the central
     // fleet.devices.<name>.config block. After migrateSplitDeviceLocalMeta so the

package/dist/lib/routines.d.ts

@@ -79,7 +79,9 @@ export interface LinearJobTrigger {
     teamKey?: string;
     /** Required issue label name. */
     label?: string;
-    /** Current Linear state name that must match (e.g. `Plan`). */
+    /** Fire on a transition INTO this Linear state (e.g. `Plan`): the current state
+     *  must match AND the delivery's `updatedFrom` must record a state change, so a
+     *  later edit that leaves the issue in this state does not re-fire (RUSH-2539). */
     stateTo?: string;
     /** Previous Linear state name that must match (e.g. `Triage`). */
     stateFrom?: string;

package/dist/lib/share/analytics.js

@@ -1,4 +1,4 @@
-// Cloudflare Web Analytics injection for `agents share`.
+// Cloudflare Web Analytics injection for `agents artifacts share`.
 //
 // The beacon is cookieless and privacy-first, which matters because a lot of shared
 // content (games, kid-facing pages) should avoid GA4-style tracking. The token is

package/dist/lib/share/capture.d.ts

@@ -1,7 +1,7 @@
 /**
  * Render an HTML file to a 1200×630 PNG — the Open Graph cover for a shared plan.
  *
- * When `agents share plan.html` runs, we screenshot the plan's own hero and use it
+ * When `agents artifacts share plan.html` runs, we screenshot the plan's own hero and use it
  * as the `og:image`, so the link unfurls into a card in Slack / iMessage / Twitter /
  * Discord. No AI, no central render service: it's a headless screenshot on the
  * publisher's machine, so it works identically for us and for any user, and costs

package/dist/lib/share/capture.js

@@ -1,7 +1,7 @@
 /**
  * Render an HTML file to a 1200×630 PNG — the Open Graph cover for a shared plan.
  *
- * When `agents share plan.html` runs, we screenshot the plan's own hero and use it
+ * When `agents artifacts share plan.html` runs, we screenshot the plan's own hero and use it
  * as the `og:image`, so the link unfurls into a card in Slack / iMessage / Twitter /
  * Discord. No AI, no central render service: it's a headless screenshot on the
  * publisher's machine, so it works identically for us and for any user, and costs
@@ -112,7 +112,7 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
         // A silently-dropped cover reads as "the CLI decided this page needs none",
         // when in fact no headless browser was found. Say so and point at the escape
         // hatch instead of leaving the publish coverless with no explanation.
-        process.stderr.write('[agents share] no headless browser found for the OG cover — install Chrome/Chromium ' +
+        process.stderr.write('[agents artifacts share] no headless browser found for the OG cover — install Chrome/Chromium ' +
             'or set AGENTS_SHARE_BROWSER=/path/to/chrome. Publishing without a preview image.\n');
         return null;
     }
@@ -159,7 +159,7 @@ export async function captureCover(htmlPath, timeoutMs = 15_000) {
     }
     // Every candidate ran but none yielded a cover — surface the last reason so a
     // missing preview card is diagnosable (timeout, crash, bad binary) rather than silent.
-    process.stderr.write(`[agents share] OG cover capture failed (${lastFailure || 'unknown error'}) — ` +
+    process.stderr.write(`[agents artifacts share] OG cover capture failed (${lastFailure || 'unknown error'}) — ` +
         'publishing without a preview image. Set AGENTS_SHARE_BROWSER to override.\n');
     return null;
 }

package/dist/lib/share/config.d.ts

@@ -22,7 +22,7 @@ export declare const DEFAULT_BUCKET_NAME = "agents-share";
 export declare const DEFAULT_SHARE_DOMAIN = "share.agents-cli.sh";
 /** The write token may be injected ephemerally into fleet/cloud agents. */
 export declare function readWriteTokenEnv(env?: NodeJS.ProcessEnv): string | null;
-/** Read the persisted endpoint config, or null if `agents share setup`/`join` never ran. */
+/** Read the persisted endpoint config, or null if `agents artifacts setup` / `agents artifacts share join` never ran. */
 export declare function readShareConfig(): ShareConfig | null;
 /** Persist the endpoint config to `agents.yaml` (syncs across the fleet). */
 export declare function writeShareConfig(cfg: ShareConfig): void;
@@ -46,7 +46,7 @@ export declare function readWriteToken(): string;
  * launch. The read is now always `agentOnly` — it resolves the token only from the
  * injected env or an already-held / no-ACL bundle, and silently returns undefined
  * otherwise (the caller runs without auto-share; the agent can still publish via
- * its own `agents share`). To get zero-friction auto-share with no prompt: unlock
+ * its own `agents artifacts share`). To get zero-friction auto-share with no prompt: unlock
  * once (`agents secrets unlock share`) or make it no-ACL (`agents secrets policy
  * share never`). */
 export declare function shareRuntimeEnv(): Record<string, string> | undefined;

package/dist/lib/share/config.js

@@ -1,4 +1,4 @@
-// Config + credential glue for `agents share`.
+// Config + credential glue for `agents artifacts share`.
 //
 // - The endpoint config (base URL, account, worker/bucket names) lives in
 //   `agents.yaml` under `share:` (Meta.share) so it syncs fleet-wide via
@@ -23,7 +23,7 @@ export function readWriteTokenEnv(env = process.env) {
     const token = env[SHARE_TOKEN_ENV_KEY]?.trim();
     return token ? token : null;
 }
-/** Read the persisted endpoint config, or null if `agents share setup`/`join` never ran. */
+/** Read the persisted endpoint config, or null if `agents artifacts setup` / `agents artifacts share join` never ran. */
 export function readShareConfig() {
     const s = readMeta().share;
     if (!s?.baseUrl || !s.accountId || !s.workerName || !s.bucketName)
@@ -56,7 +56,7 @@ export function storeWriteToken(token) {
     catch {
         bundle = {
             name: SHARE_BUNDLE,
-            description: 'agents share — write token for the R2 share endpoint',
+            description: 'agents artifacts share — write token for the R2 share endpoint',
             // A NEW share bundle defaults to the `never` tier (no biometry ACL). The R2
             // write token is low-sensitivity automation infra that is auto-read on EVERY
             // `agents run` (shareRuntimeEnv) — a biometry ACL there is what produced the
@@ -83,7 +83,7 @@ export function readWriteTokenFromBundle() {
     const token = env[SHARE_TOKEN_KEY];
     if (!token) {
         throw new Error(`No ${SHARE_TOKEN_KEY} in the '${SHARE_BUNDLE}' secrets bundle. ` +
-            `Run 'agents share setup' (to provision your own endpoint) or 'agents share join' (to use an existing one).`);
+            `Run 'agents artifacts setup' (to provision your own endpoint) or 'agents artifacts share join' (to use an existing one).`);
     }
     return token;
 }
@@ -102,7 +102,7 @@ export function readWriteToken() {
  * launch. The read is now always `agentOnly` — it resolves the token only from the
  * injected env or an already-held / no-ACL bundle, and silently returns undefined
  * otherwise (the caller runs without auto-share; the agent can still publish via
- * its own `agents share`). To get zero-friction auto-share with no prompt: unlock
+ * its own `agents artifacts share`). To get zero-friction auto-share with no prompt: unlock
  * once (`agents secrets unlock share`) or make it no-ACL (`agents secrets policy
  * share never`). */
 export function shareRuntimeEnv() {

package/dist/lib/share/delete.js

@@ -1,4 +1,4 @@
-// The delete path for `agents share delete` / `agents unshare` — an authed DELETE
+// The delete path for `agents artifacts share delete` / `agents unshare` — an authed DELETE
 // to the Worker, which already implements it (worker-template.ts). Mirrors
 // publish.ts: pure target-resolution logic is exported for tests, the network
 // calls (a status check + a delete) sit behind an injectable DI seam.
@@ -76,7 +76,7 @@ export async function deleteObject(endpoint, key, opts = {}) {
     const existedBefore = before.status !== 404;
     const r = await del(url, { authorization: `Bearer ${endpoint.token}` });
     if (!r.ok) {
-        throw new Error(`Delete failed (${r.status}) for ${url}. Check the write token, or that 'agents share setup' completed.`);
+        throw new Error(`Delete failed (${r.status}) for ${url}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
     const after = await check(url);
     const verified404 = after.status === 404;
@@ -88,7 +88,7 @@ export async function deleteObject(endpoint, key, opts = {}) {
 export async function deleteShare(target, 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).");
     }
     const token = opts.writeToken ?? readWriteToken();
     const resolved = await resolveDeleteTarget(target, { githubUser: opts.githubUser });

package/dist/lib/share/provision.js

@@ -1,4 +1,4 @@
-// Cloudflare provisioning for `agents share setup` — plain `fetch` against the CF
+// Cloudflare provisioning for `agents artifacts setup` — plain `fetch` against the CF
 // REST API (the repo has no CF wrapper). Creates the R2 bucket, configures its
 // lifecycle, uploads the Worker (with an R2 binding), sets the WRITE_TOKEN secret,
 // enables the free `*.workers.dev` subdomain, and — when the token owns the zone —
@@ -134,14 +134,14 @@ export async function updateWorker(apiToken, accountId, workerName, bucketName,
     await deployWorker(apiToken, accountId, workerName, script, bucketName, opts);
     // Script upload clears bindings/secrets (see JSDoc above). If re-applying
     // WRITE_TOKEN fails here, the live Worker has no write token — every
-    // `agents share` publish/delete 401s until a re-run of `agents share update`
+    // `agents artifacts share` publish/delete 401s until a re-run of `agents artifacts share update`
     // completes both steps. Surface that explicitly instead of the raw CF error.
     try {
         await setWorkerSecret(apiToken, accountId, workerName, writeToken, opts);
     }
     catch (e) {
         const detail = e instanceof Error ? e.message : String(e);
-        throw new Error(`Worker deployed but the write token failed to re-apply — re-run \`agents share update\` to fix this before publishing/deleting anything. (${detail})`);
+        throw new Error(`Worker deployed but the write token failed to re-apply — re-run \`agents artifacts share update\` to fix this before publishing/deleting anything. (${detail})`);
     }
     return { templateHash, skipped: false };
 }

package/dist/lib/share/publish.d.ts

@@ -19,7 +19,7 @@ export interface PublishOptions {
     expire?: string;
     contentType?: string;
     /**
-     * Hide this page from the public `/<user>` gallery and `agents share list`
+     * Hide this page from the public `/<user>` gallery and `agents artifacts share list`
      * (metadata `visibility=unlisted`). The direct URL is still world-readable —
      * unlisted, not secret (RUSH-2443). Alias of `--private` on the CLI.
      */

package/dist/lib/share/publish.js

@@ -1,4 +1,4 @@
-// The publish path for `agents share <file>` — an authed PUT to the Worker.
+// The publish path for `agents artifacts share <file>` — an authed PUT to the Worker.
 // Pure logic (slug, expiry) is exported for tests; the network call is behind a DI seam.
 //
 // For HTML publishes it also captures a 1200×630 cover (the page's own hero) and
@@ -255,7 +255,7 @@ export function buildShareKey(username, slugPart) {
 export async function publishFile(filePath, 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).");
     }
     const token = opts.writeToken ?? readWriteToken();
     const username = await resolveShareUsername(opts);
@@ -318,7 +318,7 @@ export async function publishToEndpoint(filePath, endpoint, opts = {}) {
     }
     const r = await put(pageUrl, body, authHeaders(opts.contentType ?? guessContentType(filePath)));
     if (!r.ok) {
-        throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents share setup' completed.`);
+        throw new Error(`Publish failed (${r.status}) for ${pageUrl}. Check the write token, or that 'agents artifacts setup' completed.`);
     }
     return {
         url: r.url ?? pageUrl,

package/dist/lib/share/worker-template.d.ts

@@ -1,2 +1,13 @@
-/** Render the Worker source. Pure — the R2 binding + token are wired at deploy time. */
+/**
+ * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.
+ *
+ * The literal below still spells the CLI `agents share` in its provenance comment,
+ * its root response, and its gallery title, even though the command is now
+ * `agents artifacts share` (RUSH-2580). That is deliberate: `hashWorkerScript` of
+ * this exact text is what `shareTemplateStatus` compares a provisioned endpoint's
+ * recorded `templateHash` against, so editing ANY byte here marks every already-
+ * deployed endpoint `outdated` — which makes `agents artifacts share list` refuse
+ * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
+ * worth that; change this text only alongside a real Worker behavior change.
+ */
 export declare function renderWorkerScript(): string;

package/dist/lib/share/worker-template.js

@@ -9,7 +9,7 @@
 //     sweeper; this is the immediate gate.
 //   - GET  /<username>         — public gallery of that user's shares (HTML).
 //   - GET  /<username>?format=json — public machine-readable listing of that user's
-//     ACTIVE shares (`agents share list`). Same single-segment path as the HTML
+//     ACTIVE shares (`agents artifacts share list`). Same single-segment path as the HTML
 //     gallery and gated on the SAME "does <username>/ hold any object" check, so it
 //     only intercepts a genuine namespace — a legacy flat slug with ?format=json
 //     still serves its real content, never a fake empty listing.
@@ -19,7 +19,18 @@
 // Emitted as a string (mirrors src/lib/serve/page.ts `renderPage()`), so it compiles
 // into `dist/**` and ships with no package.json#files change. `provision.ts` uploads
 // this verbatim as an ES-module Worker with a BUCKET (R2) binding + a WRITE_TOKEN secret.
-/** Render the Worker source. Pure — the R2 binding + token are wired at deploy time. */
+/**
+ * Render the Worker source. Pure — the R2 binding + token are wired at deploy time.
+ *
+ * The literal below still spells the CLI `agents share` in its provenance comment,
+ * its root response, and its gallery title, even though the command is now
+ * `agents artifacts share` (RUSH-2580). That is deliberate: `hashWorkerScript` of
+ * this exact text is what `shareTemplateStatus` compares a provisioned endpoint's
+ * recorded `templateHash` against, so editing ANY byte here marks every already-
+ * deployed endpoint `outdated` — which makes `agents artifacts share list` refuse
+ * until its owner re-runs `agents artifacts share update`. Cosmetic renames are not
+ * worth that; change this text only alongside a real Worker behavior change.
+ */
 export function renderWorkerScript() {
     return `// GENERATED by agents-cli agents share setup — do not edit here; edit
 // src/lib/share/worker-template.ts and re-run setup.

package/dist/lib/smart-launch.d.ts

@@ -25,14 +25,32 @@ export declare function affinityWeights(rows: AffinityRow[], alpha?: number): We
  * Pure — inject `rng` for tests.
  */
 export declare function sampleWeighted(candidates: WeightedCandidate[], rng?: () => number): string | null;
-/** Online device names from the local registry (+ always include local). */
+/**
+ * Online device names from the local registry (+ local), narrowed to the
+ * automatic-placement pool.
+ *
+ * The pool rule lives in `devices/pool.ts` and is an allowlist once any device
+ * is marked `role=worker`: this is the single place both automatic-placement
+ * paths (`resolveDeviceAuto`, `resolveDeviceAffinity`) get their candidates, so
+ * marking workers moves every `--device auto` at once instead of one surface.
+ *
+ * Paired cockpits (`role: control` in the device registry) are dropped here,
+ * where the registry is already being read — they are control surfaces, not
+ * compute. It CAN return an empty list — a fleet where every marked worker is
+ * offline, or where this box is the only candidate and is marked `personal`. That is a
+ * real answer, and both callers fail loud on it rather than falling back to the
+ * local machine (which would be the exact box the operator marked personal to
+ * keep agents off).
+ */
 export declare function listOnlineDeviceNames(localName?: string): string[];
 export interface DeviceAffinityOptions {
     sinceDays?: number;
     alpha?: number;
     /**
-     * Eligible hosts (normalized). Defaults to online devices + local.
-     * Empty after filter → fall back to local.
+     * Eligible hosts (normalized). Defaults to the automatic-placement pool
+     * (online devices + local, narrowed by device roles). An explicitly empty
+     * list falls back to local — the caller supplied it; an empty DEFAULT pool
+     * throws, because roles emptied it on purpose.
      */
     eligibleHosts?: string[];
     localMachine?: string;
@@ -59,6 +77,12 @@ export interface DeviceAutoPlan {
     }>;
     pickedDeviceKey: string;
 }
+/**
+ * The error both automatic-placement resolvers raise when device roles leave no
+ * candidate at all. Fail loud: the alternative — quietly running on the local
+ * machine — puts the agent on the box the operator marked `personal`.
+ */
+export declare function formatEmptyAutoPoolError(): string;
 export declare function formatNoHealthyDeviceError(pool: string[], signals: Map<string, DevicePlacementSignal>, agent?: string): string;
 /**
  * Pick the least-loaded healthy device that can run `agent` when the harness is
@@ -74,6 +98,12 @@ export declare function resolveDeviceAuto(agent?: string, opts?: {
 }): Promise<DeviceAutoPlan>;
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
+ *
+ * Draws from the same automatic-placement pool as {@link resolveDeviceAuto}, so
+ * `agents ssh auto`, the generic `--host auto` passthrough, and `matchHost`'s
+ * `auto` sentinel honour device roles too. Throws when roles leave the pool
+ * empty — a `null` host here means "run locally", which for a box marked
+ * `personal` is the outcome the mark exists to prevent.
  */
 export declare function resolveDeviceAffinity(opts?: DeviceAffinityOptions): DeviceAffinityPlan;
 /** True when a host flag value means affinity pick. */

package/dist/lib/smart-launch.js

@@ -7,7 +7,8 @@
  */
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
-import { loadDevicesSync } from './devices/registry.js';
+import { isControlDevice, loadDevicesSync } from './devices/registry.js';
+import { describeAutoPool, filterAutoPool, isAutoPoolMember } from './devices/pool.js';
 import { normalizeHost } from './machine-id.js';
 import { probePoolSignals } from './teams/placement-probe.js';
 import { pickBestDevice } from './teams/scheduler.js';
@@ -45,7 +46,23 @@ export function sampleWeighted(candidates, rng = Math.random) {
     }
     return candidates[candidates.length - 1].key;
 }
-/** Online device names from the local registry (+ always include local). */
+/**
+ * Online device names from the local registry (+ local), narrowed to the
+ * automatic-placement pool.
+ *
+ * The pool rule lives in `devices/pool.ts` and is an allowlist once any device
+ * is marked `role=worker`: this is the single place both automatic-placement
+ * paths (`resolveDeviceAuto`, `resolveDeviceAffinity`) get their candidates, so
+ * marking workers moves every `--device auto` at once instead of one surface.
+ *
+ * Paired cockpits (`role: control` in the device registry) are dropped here,
+ * where the registry is already being read — they are control surfaces, not
+ * compute. It CAN return an empty list — a fleet where every marked worker is
+ * offline, or where this box is the only candidate and is marked `personal`. That is a
+ * real answer, and both callers fail loud on it rather than falling back to the
+ * local machine (which would be the exact box the operator marked personal to
+ * keep agents off).
+ */
 export function listOnlineDeviceNames(localName = localMachineId()) {
     const names = new Set([normalizeHost(localName)]);
     try {
@@ -57,13 +74,27 @@ export function listOnlineDeviceNames(localName = localMachineId()) {
             // No tailscale snapshot → treat as candidate (registry-only box).
             if (online === false)
                 continue;
+            // A paired cockpit (iPhone/iPad) is a control surface, not compute — it
+            // is never dialed for a session, so it is never a placement candidate.
+            if (isControlDevice(d))
+                continue;
             names.add(normalizeHost(name));
         }
     }
     catch {
         /* registry missing — local only */
     }
-    return [...names];
+    return filterAutoPool([...names]);
+}
+/**
+ * The error both automatic-placement resolvers raise when device roles leave no
+ * candidate at all. Fail loud: the alternative — quietly running on the local
+ * machine — puts the agent on the box the operator marked `personal`.
+ */
+export function formatEmptyAutoPoolError() {
+    const marked = describeAutoPool();
+    return (`agents: no device is eligible for automatic placement${marked ? ` (${marked})` : ''} — ` +
+        'mark one with `agents devices role <name> worker`, or widen the pool with `agents config set auto.pool all`.');
 }
 export function formatNoHealthyDeviceError(pool, signals, agent) {
     const excluded = pool.map((key) => {
@@ -78,7 +109,11 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
         return `${key} (${reason})`;
     }).join(', ');
     const target = agent ? `can run ${agent}` : "for 'run auto'";
-    return `agents: no healthy device ${target} — excluded: ${excluded}; earliest window resets unknown`;
+    // Name the role narrowing when there is one: a fleet where every box but two
+    // is filtered out by a worker mark reads as "the fleet is down" without it.
+    const marked = describeAutoPool();
+    const poolNote = marked ? ` [pool: ${marked}]` : '';
+    return `agents: no healthy device ${target}${poolNote} — excluded: ${excluded}; earliest window resets unknown`;
 }
 /**
  * Pick the least-loaded healthy device that can run `agent` when the harness is
@@ -90,8 +125,13 @@ export function formatNoHealthyDeviceError(pool, signals, agent) {
 export async function resolveDeviceAuto(agent, opts = {}) {
     const local = normalizeHost(opts.localMachine ?? localMachineId());
     const pool = [...new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost))];
-    if (!pool.includes(local))
+    // The local machine participates in the same probe as every peer — unless a
+    // role excludes it. Adding it unconditionally would put agents back on the box
+    // the operator marked `personal` precisely to keep them off it.
+    if (!pool.includes(local) && isAutoPoolMember(local))
         pool.push(local);
+    if (pool.length === 0)
+        throw new Error(formatEmptyAutoPoolError());
     const signals = await (opts.probe ?? probePoolSignals)(pool, agent);
     if (!agent && !opts.probe) {
         const { collectFleetHarnesses } = await import('../commands/ssh.js');
@@ -135,6 +175,12 @@ export async function resolveDeviceAuto(agent, opts = {}) {
 }
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
+ *
+ * Draws from the same automatic-placement pool as {@link resolveDeviceAuto}, so
+ * `agents ssh auto`, the generic `--host auto` passthrough, and `matchHost`'s
+ * `auto` sentinel honour device roles too. Throws when roles leave the pool
+ * empty — a `null` host here means "run locally", which for a box marked
+ * `personal` is the outcome the mark exists to prevent.
  */
 export function resolveDeviceAffinity(opts = {}) {
     const local = normalizeHost(opts.localMachine ?? localMachineId());
@@ -142,9 +188,18 @@ export function resolveDeviceAffinity(opts = {}) {
     const rng = opts.rng ?? Math.random;
     const sinceDays = opts.sinceDays ?? 14;
     const sinceMs = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
+    // `listOnlineDeviceNames` always contained the local machine before device
+    // roles existed, so an empty default list can only mean roles excluded
+    // everything — fail loud, exactly as resolveDeviceAuto does. An explicitly
+    // empty `eligibleHosts` is the caller's own list and keeps the historical
+    // degrade-to-local behavior.
+    const usingDefaultPool = opts.eligibleHosts === undefined;
     const eligible = new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost));
-    if (eligible.size === 0)
+    if (eligible.size === 0) {
+        if (usingDefaultPool)
+            throw new Error(formatEmptyAutoPoolError());
         eligible.add(local);
+    }
     const deviceRows = opts.deviceAffinity ??
         queryAffinityRollup({
             groupBy: 'machine',