@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/hosts/providers/devices.js

@@ -4,9 +4,9 @@
  * Bridges the devices registry (`agents devices`, ~/.agents/.history/devices/
  * registry.json) into the host pool behind the same `HostProvider` seam as
  * `local` — the "tailscale provider" fast-follow named in docs/hosts.md. With
- * it, a machine registered once via `agents devices sync` shows up in
- * `agents hosts list`, participates in capability routing, and is enumerable
- * by target pickers — not just resolvable by exact name.
+ * it, a machine registered once via `agents devices sync` becomes a resolvable
+ * `--host`/`--device` dispatch target, participates in capability routing, and
+ * is enumerable by target pickers — not just resolvable by exact name.
  *
  * Password-auth devices are listed (the pool stays honest about what exists)
  * but marked `dispatchable: false`; resolving one for dispatch throws the same
@@ -18,6 +18,7 @@
  * order, exactly like the old tier-2 devices fall-through in resolveHost.
  */
 import { loadDevices, getDevice, isControlDevice } from '../../devices/registry.js';
+import { resolveDeviceProfile } from '../../devices/resolve-profile.js';
 import { DeviceOffloadUnsupportedError } from '../types.js';
 /** Tailscale's own presence bit, when the sync captured one. */
 function statusOf(device) {
@@ -28,17 +29,19 @@ function statusOf(device) {
 /**
  * Bridge a device profile into a `Host`. dnsName (stable across IP churn) is
  * preferred over ip; `source: 'inline'` makes `sshTargetFor` emit `user@address`.
- * Capability tags attach by enrolling the device (`agents hosts add <device>
- * --cap …` sources the target from this profile) — the enrolled entry then
- * shadows this row by provider precedence, carrying the caps.
+ * Capability tags come from an enrolled overlay entry for the device in
+ * agents.yaml (`Meta.hosts`) — that entry shadows this row by provider
+ * precedence, carrying the caps.
  */
-function deviceToPoolHost(device) {
+function deviceToPoolHost(rawDevice) {
     // A control device (a cockpit, e.g. a paired iPhone) drives the fleet but
     // never runs agents — it must never enter the host pool or be resolvable as a
     // dispatch target, whatever platform it reports (an iPhone syncs as `unknown`,
     // which remoteShellFor would otherwise default to POSIX and try to SSH).
-    if (isControlDevice(device))
+    if (isControlDevice(rawDevice))
         return null;
+    // Effective profile: central config (ssh.*/platform) overlays discovery.
+    const device = resolveDeviceProfile(rawDevice);
     const address = device.address.dnsName ?? device.address.ip;
     if (!address)
         return null; // unreachable profile — nothing to dispatch to
@@ -72,15 +75,18 @@ export class DevicesHostProvider {
         return out.sort((a, b) => a.name.localeCompare(b.name));
     }
     async resolve(name) {
-        const device = await getDevice(name);
-        if (!device)
+        const raw = await getDevice(name);
+        if (!raw)
             return null;
         // Resolving is asking to dispatch. A control device can't run agents — fail
         // loud with a clear message instead of attempting an SSH dispatch onto a
         // phone (which remoteShellFor would treat as a POSIX host).
-        if (isControlDevice(device)) {
-            throw new Error(`Device "${device.name}" is a control device (a cockpit), not an executor — it can't run agents. Dispatch to a worker device instead.`);
+        if (isControlDevice(raw)) {
+            throw new Error(`Device "${raw.name}" is a control device (a cockpit), not an executor — it can't run agents. Dispatch to a worker device instead.`);
         }
+        // Effective profile: central config (ssh.*/platform) overlays discovery —
+        // the password-auth refusal and the dial shape both follow the config.
+        const device = resolveDeviceProfile(raw);
         // Keep the long-standing typed refusal for password auth (BatchMode=yes
         // can't answer a prompt).
         if (device.auth.method === 'password') {

package/dist/lib/hosts/ready.d.ts

@@ -88,7 +88,11 @@ export declare function viewAgentVersions(view: string, agent: string): string[]
 export declare function viewHasAgentVersion(view: string, agent: string, version: string): boolean | undefined;
 /** Actionable fail-loud message for a missing remote pin (RUSH-2313). */
 export declare function missingPinnedVersionMessage(hostName: string, agent: string, version: string, installed?: string[]): string;
-/** Read the requested harness's sign-in verdict from `agents view --json`. */
+/**
+ * Read whether the requested harness has at least one launch-eligible account
+ * from `agents view --json`. Signed-in accounts that are rate-limited or out of
+ * credits are deliberately false so automatic placement cannot select them.
+ */
 export declare function viewAgentSignedIn(view: string, agent: string): boolean | undefined;
 export interface EnsureReadyOptions {
     agent: string;

package/dist/lib/hosts/ready.js

@@ -207,7 +207,11 @@ export function missingPinnedVersionMessage(hostName, agent, version, installed)
     return (`Pinned ${agent}@${version} is not installed on "${hostName}".${installedHint} ` +
         `Install it on that box: agents ssh ${hostName} -- agents add ${agent}@${version}`);
 }
-/** Read the requested harness's sign-in verdict from `agents view --json`. */
+/**
+ * Read whether the requested harness has at least one launch-eligible account
+ * from `agents view --json`. Signed-in accounts that are rate-limited or out of
+ * credits are deliberately false so automatic placement cannot select them.
+ */
 export function viewAgentSignedIn(view, agent) {
     try {
         const rows = JSON.parse(view);
@@ -215,7 +219,9 @@ export function viewAgentSignedIn(view, agent) {
         if (!row)
             return undefined;
         const verdicts = (row.versions ?? [])
-            .map((version) => version.signedIn)
+            .map((version) => typeof version.signedIn === 'boolean'
+            ? version.signedIn && version.usageStatus !== 'rate_limited' && version.usageStatus !== 'out_of_credits'
+            : undefined)
             .filter((value) => typeof value === 'boolean');
         return verdicts.length === 0 ? undefined : verdicts.some(Boolean);
     }
@@ -270,7 +276,7 @@ export function ensureHostReady(host, opts) {
         throw new Error(`Host "${host.name}" (${target}) is not reachable over SSH. Check it's online and key auth works.`);
     }
     if (!probe.version) {
-        throw new Error(`agents-cli is not installed on "${host.name}". Enroll it first: agents hosts add ${host.name} (bootstraps agents-cli).`);
+        throw new Error(`agents-cli is not installed on "${host.name}". Install it there first — e.g. \`agents devices update\` to roll it out to registered devices.`);
     }
     return evaluateHostAgentInstall(probe.view, opts, host.name);
 }

package/dist/lib/hosts/reconcile.d.ts

@@ -6,7 +6,7 @@
  * the SSH connection drops mid-follow. When that happens the local record is
  * left at `status:'running'` forever, because the only path that finalizes it
  * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
- * remote `.exit` on demand — from `agents hosts ps` / `logs` — and heals the
+ * remote `.exit` on demand — from `agents devices ps` / `agents logs` — and heals the
  * record. We only ever CONFIRM completion; an unreachable host or an absent
  * `.exit` leaves the record `running` (we never guess failure).
  */
@@ -43,7 +43,7 @@ export declare function readRemoteExit(target: string, remoteExit: string, timeo
  */
 export declare function reconcileTask(task: HostTask): HostTask;
 /**
- * Heal a list of records for a listing (`agents hosts ps`). Only `running` tasks
+ * Heal a list of records for a listing (`agents devices ps`). Only `running` tasks
  * are probed; each host is reachability-checked ONCE (deduped by target) so a
  * down host costs a single short timeout instead of one per task, and its tasks
  * are left `running` rather than falsely failed. Sequential by design — with the

package/dist/lib/hosts/reconcile.js

@@ -6,7 +6,7 @@
  * the SSH connection drops mid-follow. When that happens the local record is
  * left at `status:'running'` forever, because the only path that finalizes it
  * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
- * remote `.exit` on demand — from `agents hosts ps` / `logs` — and heals the
+ * remote `.exit` on demand — from `agents devices ps` / `agents logs` — and heals the
  * record. We only ever CONFIRM completion; an unreachable host or an absent
  * `.exit` leaves the record `running` (we never guess failure).
  */
@@ -60,7 +60,7 @@ export function reconcileTask(task) {
     return updateTask(task.id, terminalPatch(st.code)) ?? task;
 }
 /**
- * Heal a list of records for a listing (`agents hosts ps`). Only `running` tasks
+ * Heal a list of records for a listing (`agents devices ps`). Only `running` tasks
  * are probed; each host is reachability-checked ONCE (deduped by target) so a
  * down host costs a single short timeout instead of one per task, and its tasks
  * are left `running` rather than falsely failed. Sequential by design — with the

package/dist/lib/hosts/registry.js

@@ -25,6 +25,7 @@ import { readMeta } from '../state.js';
 import { isSshConfigHost } from './ssh-config.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices, isControlDevice } from '../devices/registry.js';
+import { resolveDeviceProfile } from '../devices/resolve-profile.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
 import { localMachineId } from '../session/origin-machine.js';
 // Re-export so existing importers (tests, commands) keep their path; the class
@@ -87,20 +88,24 @@ function deviceStatus(device) {
  * device can never be made dispatchable by shadowing it with an inline entry.
  */
 function deviceHost(device, user, overlay) {
-    const address = device.address.dnsName ?? device.address.ip;
+    // Effective profile: the central config's ssh.*/platform keys overlay the
+    // discovery record, so an operator edit via `agents devices config` is
+    // honored at dispatch time.
+    const resolved = resolveDeviceProfile(device);
+    const address = resolved.address.dnsName ?? resolved.address.ip;
     return {
-        name: device.name,
+        name: resolved.name,
         provider: 'devices',
         source: 'inline',
         ...(address ? { address } : {}),
-        user: user ?? device.user,
-        identityFile: device.auth.identityFile,
-        os: device.platform !== 'unknown' ? device.platform : overlay?.os,
+        user: user ?? resolved.user,
+        identityFile: resolved.auth.identityFile,
+        os: resolved.platform !== 'unknown' ? resolved.platform : overlay?.os,
         ...(overlay?.caps?.length ? { caps: overlay.caps } : {}),
         enrolled: true,
-        status: deviceStatus(device),
-        dispatchable: device.auth.method !== 'password',
-        device,
+        status: deviceStatus(resolved),
+        dispatchable: resolved.auth.method !== 'password',
+        device: resolved,
     };
 }
 /** Build a Host from a bare overlay entry (inline or ssh-config), applying any
@@ -270,7 +275,7 @@ export async function resolveHostByCap(cap, any = false) {
     // must never be picked as a run target.
     const matches = (await listAllHosts()).filter((h) => h.caps?.includes(cap) && h.dispatchable !== false);
     if (matches.length === 0)
-        throw new Error(`No host tagged "${cap}". Tag one with: agents hosts add <name> --cap ${cap}`);
+        throw new Error(`No host tagged "${cap}". See registered devices: agents devices list`);
     if (matches.length > 1 && !any) {
         throw new Error(`Multiple hosts tagged "${cap}": ${matches.map((h) => h.name).join(', ')}. Name one, or pass --any.`);
     }

package/dist/lib/hosts/remote-cmd.js

@@ -140,7 +140,7 @@ export const RUN_OPTION_FORWARDING = {
 export const RUN_OPTION_REJECT_MESSAGES = {
     terminal: '--terminal opens a tab on THIS machine; it cannot be combined with --host. ' +
         'Drop --terminal to dispatch to the host, or drop --host to open the tab here. ' +
-        'To watch a remote run in a terminal, dispatch it and follow with `agents sessions focus <id>`.',
+        'To watch a remote run in a terminal, dispatch it and follow with `agents sessions resume <id>`.',
     secrets: '--secrets cannot cross the SSH boundary — Keychain values are never sent to a host implicitly. ' +
         'Provision the bundle on the host first (agents secrets export --host <name>), then run without --secrets; ' +
         'workflow frontmatter secrets resolve from the HOST\'s own keychain.',

package/dist/lib/hosts/remote-os.d.ts

@@ -3,15 +3,18 @@
  * shell dialect (POSIX `bash -lc` vs Windows PowerShell). See `remoteShellFor`
  * in `remote-cmd.ts` for how the string is consumed.
  *
- * Two sources, in priority order:
- *   1. The device registry `platform` (`windows`/`linux`/`macos`), which is
+ * Three sources, in priority order:
+ *   1. The central config `platform` key (`fleet.devices.<name>.config.platform`
+ *      in agents.yaml) — the operator's explicit override, set with
+ *      `agents devices config <name> platform <os>`.
+ *   2. The device registry `platform` (`windows`/`linux`/`macos`), which is
  *      populated fleet-wide by Tailscale sync — the reliable answer for a box
  *      like `win-mini` that was discovered, not hand-enrolled.
- *   2. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
- *      at `agents hosts add` time), for hosts that live only in that overlay.
+ *   3. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
+ *      when the overlay entry was written), for hosts that live only in that overlay.
  *
- * Missing/unknown from both → `undefined`, which `remoteShellFor` maps to POSIX.
- * Kept synchronous so the sync `agents sessions --host` fan-out can use it.
+ * Missing/unknown from all three → `undefined`, which `remoteShellFor` maps to
+ * POSIX. Kept synchronous so the sync `agents sessions --host` fan-out can use it.
  */
 /** Resolve the OS/platform string for a host name, or undefined if unknown. */
 export declare function resolveRemoteOsSync(name: string): string | undefined;

package/dist/lib/hosts/remote-os.js

@@ -3,21 +3,28 @@
  * shell dialect (POSIX `bash -lc` vs Windows PowerShell). See `remoteShellFor`
  * in `remote-cmd.ts` for how the string is consumed.
  *
- * Two sources, in priority order:
- *   1. The device registry `platform` (`windows`/`linux`/`macos`), which is
+ * Three sources, in priority order:
+ *   1. The central config `platform` key (`fleet.devices.<name>.config.platform`
+ *      in agents.yaml) — the operator's explicit override, set with
+ *      `agents devices config <name> platform <os>`.
+ *   2. The device registry `platform` (`windows`/`linux`/`macos`), which is
  *      populated fleet-wide by Tailscale sync — the reliable answer for a box
  *      like `win-mini` that was discovered, not hand-enrolled.
- *   2. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
- *      at `agents hosts add` time), for hosts that live only in that overlay.
+ *   3. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
+ *      when the overlay entry was written), for hosts that live only in that overlay.
  *
- * Missing/unknown from both → `undefined`, which `remoteShellFor` maps to POSIX.
- * Kept synchronous so the sync `agents sessions --host` fan-out can use it.
+ * Missing/unknown from all three → `undefined`, which `remoteShellFor` maps to
+ * POSIX. Kept synchronous so the sync `agents sessions --host` fan-out can use it.
  */
 import { loadDevicesSync } from '../devices/registry.js';
+import { readDeviceConfigValues } from '../device-config.js';
 import { readMeta } from '../state.js';
 /** Resolve the OS/platform string for a host name, or undefined if unknown. */
 export function resolveRemoteOsSync(name) {
     try {
+        const configured = readDeviceConfigValues(name).platform;
+        if (typeof configured === 'string' && configured !== 'unknown')
+            return configured;
         const platform = loadDevicesSync()[name]?.platform;
         if (platform && platform !== 'unknown')
             return platform;

package/dist/lib/hosts/routing-flag.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Leaf argv helpers for host/device routing flags.
+ *
+ * Zero imports on purpose. `bootstrap.ts` gates the dynamic
+ * `import('./lib/hosts/passthrough.js')` on {@link hasHostRoutingFlag} so the
+ * ~187 ms passthrough module graph is never loaded when no routing flag is
+ * present (the majority of CLI invocations). That gate must not itself drag
+ * in passthrough, remote-cmd, ssh-exec, or the device registry (RUSH-2374).
+ *
+ * `flagValue` lives here (not in passthrough.ts) for the same reason: the gate
+ * and the function body that later reads flag values share one implementation.
+ */
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
+/**
+ * True when argv carries any host/device routing flag that {@link maybeRunOnHost}
+ * inspects: `--host`/`-H`, `--device`, `--hosts`, `--devices` (space, `=`, or
+ * glued short form).
+ *
+ * Presence-only — does not validate values. Used by bootstrap before loading
+ * passthrough, and by `maybeRunStandaloneOnHost` before strip/route work.
+ */
+export declare function hasHostRoutingFlag(args: string[]): boolean;

package/dist/lib/hosts/routing-flag.js

@@ -0,0 +1,41 @@
+/**
+ * Leaf argv helpers for host/device routing flags.
+ *
+ * Zero imports on purpose. `bootstrap.ts` gates the dynamic
+ * `import('./lib/hosts/passthrough.js')` on {@link hasHostRoutingFlag} so the
+ * ~187 ms passthrough module graph is never loaded when no routing flag is
+ * present (the majority of CLI invocations). That gate must not itself drag
+ * in passthrough, remote-cmd, ssh-exec, or the device registry (RUSH-2374).
+ *
+ * `flagValue` lives here (not in passthrough.ts) for the same reason: the gate
+ * and the function body that later reads flag values share one implementation.
+ */
+/** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
+export function flagValue(args, long, short) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === `--${long}` || (short && a === `-${short}`))
+            return args[i + 1];
+        if (a.startsWith(`--${long}=`))
+            return a.slice(long.length + 3);
+        if (short && a.startsWith(`-${short}=`))
+            return a.slice(short.length + 2);
+        if (short && new RegExp(`^-${short}(.+)`).test(a))
+            return a.slice(2);
+    }
+    return undefined;
+}
+/**
+ * True when argv carries any host/device routing flag that {@link maybeRunOnHost}
+ * inspects: `--host`/`-H`, `--device`, `--hosts`, `--devices` (space, `=`, or
+ * glued short form).
+ *
+ * Presence-only — does not validate values. Used by bootstrap before loading
+ * passthrough, and by `maybeRunStandaloneOnHost` before strip/route work.
+ */
+export function hasHostRoutingFlag(args) {
+    return (flagValue(args, 'host', 'H') !== undefined ||
+        flagValue(args, 'device') !== undefined ||
+        flagValue(args, 'hosts') !== undefined ||
+        flagValue(args, 'devices') !== undefined);
+}

package/dist/lib/hosts/run-target.js

@@ -50,7 +50,7 @@ export async function resolveHostRunTarget(name, opts = {}) {
         }
     }
     if (!host)
-        throw new HostResolutionError(`Unknown host "${name}". List hosts: agents hosts list`);
+        throw new HostResolutionError(`Unknown host "${name}". List devices: agents devices list`);
     return host;
 }
 /** Resolve the id the remote host will adopt for a fresh Claude session. */

package/dist/lib/hosts/session-index.js

@@ -46,7 +46,7 @@ export function hostSessionMeta(task, ctx) {
         machine: normalizeHost(task.host),
         topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
         // The run's `--name` seeds the label (resolves `agents sessions <name>` and
-        // `agents hosts logs <name>`); an unnamed host run falls back to the
+        // `agents logs <name>`); an unnamed host run falls back to the
         // `[host/<name>]` indicator, mirroring the cloud path's `[cloud/<status>]`.
         label: task.name || `[host/${task.host}]`,
     };

package/dist/lib/hosts/tasks.d.ts

@@ -2,7 +2,7 @@
  * Local record of dispatched host tasks.
  *
  * Each dispatch writes a `<id>.json` sidecar next to its `<id>.log` (and the
- * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents hosts ps/logs`
+ * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents devices ps` / `agents logs`
  * can list runs and follow output across CLI invocations. (Folding these into
  * the cloud SQLite store so `agents cloud ps` sees them is a fast-follow — it
  * needs care around the cloud status-refresh path.)
@@ -20,8 +20,8 @@ export interface HostTask {
     pid?: number;
     /**
      * The durable `agents run --name <slug>` handle for this dispatch, if given.
-     * Chosen at launch and agent-agnostic (unlike sessionId), so `agents hosts
-     * ps/logs <name>` and the dispatch tip can reference the run by a stable name
+     * Chosen at launch and agent-agnostic (unlike sessionId), so `agents devices
+     * ps` / `agents logs <name>` and the dispatch tip can reference the run by a stable name
      * even for agents that never expose a session id up front. Absent when the
      * run was launched without `--name`.
      */
@@ -68,14 +68,14 @@ export declare function listTasks(): HostTask[];
  */
 export declare function findTaskBySessionId(sessionId: string): HostTask | null;
 /**
- * Find the newest host task launched with `--name <name>`, so `agents hosts
- * logs/ps <name>` and resolve-by-handle can address a run by its durable name.
+ * Find the newest host task launched with `--name <name>`, so `agents logs
+ * <name>` / `agents devices ps` and resolve-by-handle can address a run by its durable name.
  * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
  * reused across dispatches.
  */
 export declare function findTaskByName(name: string): HostTask | null;
 /**
- * Resolve a host-task reference the way `agents hosts ps/logs/stop` do: a raw
+ * Resolve a host-task reference the way `agents devices ps`, `agents logs`, and `agents devices stop` do: a raw
  * dispatch id first, then a `--name` handle, then the remote agent/session id.
  * Shared so any other caller resolving "does this ref name a detached --device
  * dispatch?" (e.g. `agents message`) uses the identical three-way lookup.

package/dist/lib/hosts/tasks.js

@@ -2,7 +2,7 @@
  * Local record of dispatched host tasks.
  *
  * Each dispatch writes a `<id>.json` sidecar next to its `<id>.log` (and the
- * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents hosts ps/logs`
+ * remote's `<id>.exit`) under ~/.agents/.cache/hosts/, so `agents devices ps` / `agents logs`
  * can list runs and follow output across CLI invocations. (Folding these into
  * the cloud SQLite store so `agents cloud ps` sees them is a fast-follow — it
  * needs care around the cloud status-refresh path.)
@@ -86,8 +86,8 @@ export function findTaskBySessionId(sessionId) {
     return null;
 }
 /**
- * Find the newest host task launched with `--name <name>`, so `agents hosts
- * logs/ps <name>` and resolve-by-handle can address a run by its durable name.
+ * Find the newest host task launched with `--name <name>`, so `agents logs
+ * <name>` / `agents devices ps` and resolve-by-handle can address a run by its durable name.
  * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
  * reused across dispatches.
  */
@@ -102,7 +102,7 @@ export function findTaskByName(name) {
     return null;
 }
 /**
- * Resolve a host-task reference the way `agents hosts ps/logs/stop` do: a raw
+ * Resolve a host-task reference the way `agents devices ps`, `agents logs`, and `agents devices stop` do: a raw
  * dispatch id first, then a `--name` handle, then the remote agent/session id.
  * Shared so any other caller resolving "does this ref name a detached --device
  * dispatch?" (e.g. `agents message`) uses the identical three-way lookup.

package/dist/lib/hosts/types.js

@@ -20,8 +20,7 @@ export class DeviceOffloadUnsupportedError extends Error {
     constructor(name) {
         super(`Device "${name}" uses password auth, which --host offload can't use yet ` +
             `(runs go over ssh with BatchMode=yes). Switch it to key auth with ` +
-            `\`agents devices set ${name} --auth key\`, or enroll it as a host with ` +
-            `\`agents hosts add ${name}\`.`);
+            `\`agents devices config ${name} ssh.auth key\`.`);
         this.name = 'DeviceOffloadUnsupportedError';
     }
 }

package/dist/lib/installations/resolve.js

@@ -1,4 +1,3 @@
-import { resolveAccountLabel } from '../account-labels.js';
 import { AGENTS } from '../agents.js';
 import { getGlobalDefault } from '../versions.js';
 import { listInstallations } from './store.js';
@@ -37,7 +36,7 @@ export class InstallationAmbiguousError extends Error {
     constructor(agent, selector, candidates) {
         super(`'${selector ?? agent}' matches ${candidates.length} ${AGENTS[agent].name} installations `
             + `(${candidates.map((i) => describeInstallation(i)).join(', ')}). `
-            + `Name one by its installation label, or disambiguate with --account <label>.`);
+            + `Select one by its installation label.`);
         this.agent = agent;
         this.selector = selector;
         this.candidates = candidates;
@@ -63,12 +62,7 @@ export async function resolveInstallation(agent, selector, options = {}) {
         throw new InstallationNotFoundError(agent, selector, all);
     let candidates = all;
     if (options.account) {
-        // resolveAccountLabel answers with the version-dir label of the install that
-        // is signed into that account — i.e. an installation label.
-        const label = await resolveAccountLabel(agent, options.account);
-        candidates = candidates.filter((i) => i.label === label);
-        if (candidates.length === 0)
-            throw new InstallationNotFoundError(agent, selector, all);
+        throw new Error("--account no longer selects an installation. Account names are durable credentials used by 'agents run --account'; select the installation by its label instead.");
     }
     if (selector) {
         const byLabel = candidates.filter((i) => i.label === selector);

package/dist/lib/isolation-boundary-report.js

@@ -14,7 +14,6 @@ export function explainIsolationBoundary(err) {
     console.error(chalk.gray('\n  To keep the sandbox and act inside it:'));
     console.error(chalk.gray(`    agents add ${err.agent}@<version> --isolated    # another isolated copy`));
     console.error(chalk.gray(`    agents use ${err.agent}@<version>               # pick which one 'agents run ${err.agent}' uses`));
-    console.error(chalk.gray(`    agents export ${err.agent}                      # copy its config out to your real config dir`));
     console.error(chalk.gray('\n  To manage this agent normally instead, remove the isolated copies first:'));
     for (const v of versions) {
         console.error(chalk.gray(`    agents remove ${err.agent}@${v} --isolated`));

package/dist/lib/linear-cache.d.ts

@@ -34,6 +34,13 @@
  */
 /** Matches `SKILL_INDEX_TTL_MS` (`lib/registry.ts`) — the repo's TTL convention. */
 export declare const LINEAR_CACHE_TTL_MS: number;
+/**
+ * Resolve the Linear API key from the `LINEAR_API_KEY` env var, falling back to
+ * the macOS keychain generic-password `linear-api-key` (how the rest of the
+ * stack stores it). Null if none is resolvable. The shared resolver for every
+ * Linear-touching surface (project counts, session discovery).
+ */
+export declare function resolveLinearApiKey(): string | null;
 /** What a lookup found, and how much to trust it. */
 export interface CacheHit<T> {
     value: T;

package/dist/lib/linear-cache.js

@@ -32,19 +32,46 @@
  * populated chip to empty — and it is the fix for the card silently losing its
  * Linear line mid-session when the request budget ran out.
  */
+import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
 /** Matches `SKILL_INDEX_TTL_MS` (`lib/registry.ts`) — the repo's TTL convention. */
 export const LINEAR_CACHE_TTL_MS = 10 * 60_000;
+/**
+ * Resolve the Linear API key from the `LINEAR_API_KEY` env var, falling back to
+ * the macOS keychain generic-password `linear-api-key` (how the rest of the
+ * stack stores it). Null if none is resolvable. The shared resolver for every
+ * Linear-touching surface (project counts, session discovery).
+ */
+export function resolveLinearApiKey() {
+    const fromEnv = process.env.LINEAR_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    if (process.platform === 'darwin') {
+        try {
+            const out = execFileSync('security', ['find-generic-password', '-s', 'linear-api-key', '-w'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            const key = out.trim();
+            if (key)
+                return key;
+        }
+        catch {
+            // not in keychain — fall through
+        }
+    }
+    return null;
+}
 const CACHE_SUBDIR = 'linear-projects';
 /** Sits beside the per-project files; its own file, so it cannot be clobbered by them. */
 const RATE_LIMIT_FILE = 'rate-limit.json';
 /**
- * Where the snapshot lives. `AGENTS_LINEAR_CACHE_PATH` overrides the directory,
- * mirroring `AGENTS_FACTORY_PROJECTS_PATH` (`auto-dispatch.ts`) — `getCacheDir()`
- * resolves `HOME` once at module load, so a test that swaps `process.env.HOME`
- * afterwards would otherwise read and WRITE the developer's real cache.
+ * Where the snapshot lives. `AGENTS_LINEAR_CACHE_PATH` overrides the directory.
+ * `getCacheDir()` resolves `HOME` once at module load, so a test that swaps
+ * `process.env.HOME` afterwards would otherwise read and WRITE the developer's
+ * real cache.
  */
 function cacheDir() {
     return process.env.AGENTS_LINEAR_CACHE_PATH ?? path.join(getCacheDir(), CACHE_SUBDIR);

package/dist/lib/linear-project-counts.d.ts

@@ -5,7 +5,7 @@
  * `agents projects link <name> --linear`), the card shows one outcome line —
  * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
  * TYPE (triage / backlog / unstarted / started / completed / canceled), never
- * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ * hardcoded state names.
  *
  * The same fetch also yields the **next milestone** — the earliest-dated
  * milestone with unfinished issues — because each issue node carries its

package/dist/lib/linear-project-counts.js

@@ -5,7 +5,7 @@
  * `agents projects link <name> --linear`), the card shows one outcome line —
  * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
  * TYPE (triage / backlog / unstarted / started / completed / canceled), never
- * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ * hardcoded state names.
  *
  * The same fetch also yields the **next milestone** — the earliest-dated
  * milestone with unfinished issues — because each issue node carries its
@@ -27,8 +27,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { resolveLinearApiKey } from './auto-dispatch-linear.js';
-import { isRateLimited, noteRateLimited, parseRateLimitReset, readCached, writeCached } from './linear-cache.js';
+import { isRateLimited, noteRateLimited, parseRateLimitReset, readCached, writeCached, resolveLinearApiKey } from './linear-cache.js';
 const LINEAR_API = 'https://api.linear.app/graphql';
 /** Overall budget across all pages — the card must never hang on Linear. */
 const TIMEOUT_MS = 8_000;

package/dist/lib/linear-projects.js

@@ -6,7 +6,7 @@
 // key so they compare equal, and matchLinearProject() binds a repo/folder to the
 // Linear project the user most likely means.
 //
-// Ported from apps/factory/src/core/linearProjects.ts (no cross-package imports —
+// Ported from apps/ext/src/core/linearProjects.ts (no cross-package imports —
 // repo rule); keep the two in sync. The matcher half is PURE so it unit-tests
 // without a live `linear` binary; the `linear projects --json` shell-out lives at
 // the bottom (listLinearProjects) and fails LOUD — it's behind an explicit user

package/dist/lib/loop.d.ts

@@ -6,7 +6,7 @@
  * can spawn subagents freely). Every guard — `max_iterations`, `budget`, the
  * `until: signal` condition, SIGINT/SIGTERM — lives OUTSIDE the agent, so the
  * agent cannot vote past a kill-switch (the standard answer to runaway-loop and
- * runaway-cost failure modes; see docs/07-entrypoints-and-loops.md).
+ * runaway-cost failure modes; see docs/entrypoints-and-loops.md).
  *
  * Structure mirrors the teams supervisor (`runSupervisor` in teams/supervisor.ts):
  * a bounded for-loop with a hard cap, a SIGINT/SIGTERM trap that flips a stop
@@ -21,7 +21,7 @@
 import type { AgentId } from './types.js';
 import type { ExecOptions } from './exec.js';
 import { type Checkpoint } from './checkpoint.js';
-/** Loop block config (docs/07-entrypoints-and-loops.md → "The loop block"). */
+/** Loop block config (docs/entrypoints-and-loops.md → "The loop block"). */
 export interface LoopConfig {
     /** Stop condition. `signal` reads loop-signal.json; absence is fail-closed. */
     until?: 'signal';

package/dist/lib/loop.js

@@ -6,7 +6,7 @@
  * can spawn subagents freely). Every guard — `max_iterations`, `budget`, the
  * `until: signal` condition, SIGINT/SIGTERM — lives OUTSIDE the agent, so the
  * agent cannot vote past a kill-switch (the standard answer to runaway-loop and
- * runaway-cost failure modes; see docs/07-entrypoints-and-loops.md).
+ * runaway-cost failure modes; see docs/entrypoints-and-loops.md).
  *
  * Structure mirrors the teams supervisor (`runSupervisor` in teams/supervisor.ts):
  * a bounded for-loop with a hard cap, a SIGINT/SIGTERM trap that flips a stop

package/dist/lib/mailbox-target.d.ts

@@ -52,7 +52,7 @@ export type HostTaskRoute = {
  * local/cloud session (RUSH-2366 follow-up): `getActiveSessions()` has no
  * visibility into a detached `agents run --device <host> --no-follow`
  * dispatch, whose only local record is the `~/.agents/.cache/hosts/<id>.json`
- * sidecar `agents hosts ps` reads. Pure — the caller does the actual lookup
+ * sidecar `agents devices ps` reads. Pure — the caller does the actual lookup
  * (`resolveTaskRef`) and I/O (the ssh reroute).
  *
  * `remoteRef` prefers the remote agent's OWN identity (its captured session id