@phnx-labs/agents-cli 1.20.93 → 1.21.1

package/dist/lib/state.js

@@ -26,7 +26,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
+import { execFileSync } from 'child_process';
 import { ensureLockTarget, atomicWriteFileSync, withFileLock } from './fs-atomic.js';
+import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 import { machineId } from './machine-id.js';
 const HOME = process.env.HOME ?? os.homedir();
 /**
@@ -116,7 +118,6 @@ const PACKAGES_DIR = path.join(CACHE_DIR, 'packages');
 // They live at the user-root so they're git-tracked as source of truth.
 const PLUGINS_DIR = path.join(USER_AGENTS_DIR, 'plugins');
 const CLOUD_DIR = path.join(CACHE_DIR, 'cloud');
-const DRIVE_DIR = path.join(CACHE_DIR, 'drive');
 const TERMINALS_DIR = path.join(CACHE_DIR, 'terminals');
 const LOGS_DIR = path.join(CACHE_DIR, 'logs');
 /** Disposable performance samples (~/.agents/.cache/perf/) — safe to wipe. */
@@ -144,9 +145,16 @@ const USER_SUBAGENTS_DIR = path.join(USER_AGENTS_DIR, 'subagents');
 const USER_WORKFLOWS_DIR = path.join(USER_AGENTS_DIR, 'workflows');
 const USER_SECRETS_DIR = path.join(USER_AGENTS_DIR, 'secrets');
 const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yaml');
-const META_HEADER = `# agents-cli metadata
+/**
+ * Header prepended to every agents.yaml the CLI writes (central and per-device
+ * docs). Carries the yaml-language-server schema hint so editors validate the
+ * file against `schema/agents-yaml.schema.json`. Exported so
+ * `lib/device-config.ts` writes a sibling device's doc with the same header.
+ */
+export const META_HEADER = `# agents-cli metadata
 # Auto-generated - do not edit manually
 # https://github.com/phnx-labs/agents-cli
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json
 
 `;
 // ─── Root getters ─────────────────────────────────────────────────────────────
@@ -190,13 +198,69 @@ export function getOptionalUserAgentsDir() {
     }
     return USER_AGENTS_DIR;
 }
+/**
+ * Origin `owner/repo` slug (lowercased, `.git` stripped) of a git checkout, or
+ * null when `dir` isn't a git repo / has no origin. Extracts the slug from any
+ * remote URL form: `git@host:owner/repo.git`, `https://host/owner/repo.git`,
+ * `ssh://git@host/owner/repo`. Sync (mirrors readGitConfigUser in git.ts) so it
+ * can be used from the synchronous getProjectAgentsDir walk.
+ */
+function gitOriginSlug(dir) {
+    let url;
+    try {
+        url = execFileSync('git', ['-C', dir, 'config', '--get', 'remote.origin.url'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).toString().trim();
+    }
+    catch {
+        return null;
+    }
+    if (!url)
+        return null;
+    const m = url.replace(/\.git$/i, '').match(/[:/]([^/:]+\/[^/]+)$/);
+    return m ? m[1].toLowerCase() : null;
+}
+/** Slugs of the user + system DotAgents repos — a checkout of any of these is not a project layer. */
+function canonicalDotAgentsRepoSlugs() {
+    const slugs = new Set([systemRepoSlug(DEFAULT_SYSTEM_REPO).toLowerCase()]);
+    for (const dir of [USER_AGENTS_DIR, SYSTEM_AGENTS_DIR]) {
+        const slug = gitOriginSlug(dir);
+        if (slug)
+            slugs.add(slug);
+    }
+    return slugs;
+}
+/**
+ * True when `agentsPath` is itself a git checkout of the user's or system's
+ * DotAgents repo — i.e. a *clone* of the very repo whose rules already load as
+ * the user/system layer (e.g. `git clone …/.agents.git ~/src/github.com/<you>/.agents`).
+ * Such a clone must NOT also be treated as a *project* layer: because project
+ * outranks user, a stale clone would silently shadow the live user rules by
+ * filename and plant a compiled AGENTS.md in an ancestor dir (RUSH-2037).
+ *
+ * A legitimate project layer is a plain subdirectory of a project and is never
+ * itself a git-repo root, so the cheap `.git` gate skips the (git-spawning)
+ * origin comparison for the common case — only a `.agents/` that is its own
+ * checkout pays it, and even then it's kept unless its origin matches the
+ * user/system DotAgents repo (an unrelated repo checked out at `.agents/`,
+ * or a project's own versioned `.agents/`, stays a valid project layer).
+ */
+function isUserOrSystemRepoCheckout(agentsPath) {
+    if (!fs.existsSync(path.join(agentsPath, '.git')))
+        return false;
+    const origin = gitOriginSlug(agentsPath);
+    if (!origin)
+        return false;
+    return canonicalDotAgentsRepoSlugs().has(origin);
+}
 /** Walk up from startPath to find a project-scoped .agents/ directory (skipping both roots). */
 export function getProjectAgentsDir(startPath = process.cwd()) {
     let dir = path.resolve(startPath);
     while (true) {
         const agentsPath = path.join(dir, '.agents');
         if (fs.existsSync(agentsPath) && fs.statSync(agentsPath).isDirectory()) {
-            if (!isSamePath(agentsPath, SYSTEM_AGENTS_DIR) && !isSamePath(agentsPath, USER_AGENTS_DIR)) {
+            if (!isSamePath(agentsPath, SYSTEM_AGENTS_DIR) && !isSamePath(agentsPath, USER_AGENTS_DIR)
+                && !isUserOrSystemRepoCheckout(agentsPath)) {
                 return agentsPath;
             }
         }
@@ -418,8 +482,6 @@ export function getProjectPluginsDir(cwd = process.cwd()) {
         return null;
     return path.join(projectAgentsDir, 'plugins');
 }
-/** Path to synced remote session data (~/.agents/.cache/drive/). */
-export function getDriveDir() { return DRIVE_DIR; }
 /** Path to soft-deleted resources (~/.agents/.history/trash/). */
 export function getTrashDir() { return TRASH_DIR; }
 /** Path to local session indexer storage (~/.agents/.history/sessions/). */
@@ -673,8 +735,9 @@ function writeIfChanged(filePath, content) {
 /**
  * Partition the in-memory Meta across three files by sync-domain:
  *   - central  `~/.agents/agents.yaml`             — portable, everything else
+ *              (including the user-scope `config:` block)
  *   - device   `~/.agents/devices/<machine>/agents.yaml` — `agents:` pins +
- *              `defaultBrowserProfile:` (both per-device)
+ *              `defaultBrowserProfile:` + device-scope `config:` (all per-device)
  *   - history  `~/.agents/.history/version-resources.json` — `versions:` (machine-local)
  * All callers funnel through writeMeta → here, so nothing else changes. Empty
  * `agents:` / `versions:` are not written (no empty committed files).
@@ -736,7 +799,7 @@ function serializeCentral(central) {
     return isEmpty ? META_HEADER : doc.toString({ collectionStyle: 'block' });
 }
 function writeMetaUnlocked(meta) {
-    const { agents, isolatedAgents, versions, defaultBrowserProfile, ...central } = meta;
+    const { agents, isolatedAgents, versions, defaultBrowserProfile, deviceConfig, ...central } = meta;
     // Write the machine-local files FIRST, then strip central — so a crash mid-write
     // never removes pins/versions from central before they're persisted elsewhere.
     const devicePath = getDeviceMetaPath();
@@ -747,9 +810,13 @@ function writeMetaUnlocked(meta) {
     // it does not have.
     const hasIsolatedAgents = !!isolatedAgents && Object.keys(isolatedAgents).length > 0;
     const hasDefaultBrowser = !!defaultBrowserProfile;
-    if (hasAgents || hasIsolatedAgents || hasDefaultBrowser) {
-        // Device-local doc carries `agents:` pins and `defaultBrowserProfile:` — both
-        // are per-machine and must never land in central agents.yaml (which syncs).
+    // Device-scope config (`maxAgents`, `schedulerEnabled`, …) is per-machine, so it
+    // rides the device doc under `config:` — never the central doc that syncs.
+    const hasDeviceConfig = !!deviceConfig && Object.keys(deviceConfig).length > 0;
+    if (hasAgents || hasIsolatedAgents || hasDefaultBrowser || hasDeviceConfig) {
+        // Device-local doc carries `agents:` pins, `defaultBrowserProfile:`, and the
+        // device-scope `config:` — all per-machine and must never land in central
+        // agents.yaml (which syncs).
         const deviceDoc = {};
         if (hasAgents)
             deviceDoc.agents = agents;
@@ -757,6 +824,8 @@ function writeMetaUnlocked(meta) {
             deviceDoc.isolatedAgents = isolatedAgents;
         if (hasDefaultBrowser)
             deviceDoc.defaultBrowserProfile = defaultBrowserProfile;
+        if (hasDeviceConfig)
+            deviceDoc.config = deviceConfig;
         fs.mkdirSync(path.dirname(devicePath), { recursive: true });
         writeIfChanged(devicePath, META_HEADER + yaml.stringify(deviceDoc));
     }
@@ -782,6 +851,10 @@ function writeMetaUnlocked(meta) {
  *     still has pins)
  *   - `defaultBrowserProfile:` from the device file (device is the sole source;
  *     the field is stripped from central on write, so nothing to merge against)
+ *   - `config:` from the device file into `deviceConfig` (device is the sole
+ *     source for device-scope config, same routing as `defaultBrowserProfile`;
+ *     the in-memory field is named `deviceConfig` so it can never collide with
+ *     the user-scope `config:` central carries)
  *   - `versions:` from the history JSON (wholesale replace; falls back to
  *     whatever central carried when the history file doesn't exist yet)
  */
@@ -796,6 +869,8 @@ function overlayMachineLocal(meta) {
                 meta.isolatedAgents = { ...meta.isolatedAgents, ...dm.isolatedAgents };
             if (dm?.defaultBrowserProfile)
                 meta.defaultBrowserProfile = dm.defaultBrowserProfile;
+            if (dm?.config)
+                meta.deviceConfig = dm.config;
         }
         catch { /* ignore malformed device file */ }
     }

package/dist/lib/sync-umbrella.d.ts

@@ -2,25 +2,23 @@
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
  * Bare `agents sync` fetches the config repos then reconciles them into every
- * installed agent's version home. Secrets and sessions are opt-in stages
- * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
- * default. Each stage is an existing exported library function; this module only
- * sequences them and decides — from the flags — which stages run. The planner is
- * pure so the flag matrix is unit-tested without any I/O.
+ * installed agent's version home. Secrets are an opt-in stage (`--secrets`) —
+ * see `planUmbrellaStages` for why it's off by default. Each stage is an
+ * existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run. The planner is pure so the
+ * flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
  *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
  *               cleanly when none is available — tokenized non-interactive auth
  *               arrives with `agents login`, #366/#367)
- *   sessions -> syncSessions(), gated by the session-sync beta opt-in + isSyncConfigured(), like the daemon
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
-/** The five umbrella flags off `agents sync`. */
+/** The umbrella flags off `agents sync`. */
 export interface UmbrellaFlags {
     repos?: boolean;
     secrets?: boolean;
-    sessions?: boolean;
     cloud?: boolean;
     local?: boolean;
 }
@@ -28,7 +26,6 @@ export interface UmbrellaFlags {
 export interface UmbrellaPlan {
     fetchRepos: boolean;
     fetchSecrets: boolean;
-    fetchSessions: boolean;
     reconcile: boolean;
 }
 /**
@@ -36,14 +33,12 @@ export interface UmbrellaPlan {
  *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
  *   --cloud                fetch repos (or the selected subset), skip reconcile
- *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ *   --repos/--secrets      fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
  *
- * Secrets and sessions are NOT part of the bare default — they are opt-in via
- * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
- * bare `agents sync` is more blast radius than the verb should carry by
- * default, and session transcripts are queryable on demand (`agents sessions
- * --host <machine>`) so they don't need eager mirroring.
+ * Secrets are NOT part of the bare default — they are opt-in via `--secrets`.
+ * Pulling every secret bundle onto the machine on a bare `agents sync` is more
+ * blast radius than the verb should carry by default.
  */
 export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
 export interface UmbrellaResult {
@@ -58,13 +53,6 @@ export interface UmbrellaResult {
         reason?: string;
         errors: string[];
     };
-    sessions?: {
-        ran: boolean;
-        pushed: number;
-        pulled: number;
-        merged: number;
-        error?: string;
-    };
     devices?: {
         synced: number;
         pending: number;
@@ -82,7 +70,7 @@ export interface RunUmbrellaArgs {
     passphrase?: string;
 }
 /**
- * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * Execute the planned stages in order: repos -> secrets -> reconcile.
  * A failure in one fetch stage is recorded and does not abort the others or the
  * reconcile — `agents sync` should make as much current as it can in one pass.
  */

package/dist/lib/sync-umbrella.js

@@ -2,18 +2,17 @@
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
  * Bare `agents sync` fetches the config repos then reconciles them into every
- * installed agent's version home. Secrets and sessions are opt-in stages
- * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
- * default. Each stage is an existing exported library function; this module only
- * sequences them and decides — from the flags — which stages run. The planner is
- * pure so the flag matrix is unit-tested without any I/O.
+ * installed agent's version home. Secrets are an opt-in stage (`--secrets`) —
+ * see `planUmbrellaStages` for why it's off by default. Each stage is an
+ * existing exported library function; this module only sequences them and
+ * decides — from the flags — which stages run. The planner is pure so the
+ * flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
  *   secrets  -> listRemoteBundles + pullBundle (needs a passphrase; skipped
  *               cleanly when none is available — tokenized non-interactive auth
  *               arrives with `agents login`, #366/#367)
- *   sessions -> syncSessions(), gated by the session-sync beta opt-in + isSyncConfigured(), like the daemon
  *   reconcile-> refresh({ skipPrompts }) — re-materialize resources into homes
  */
 import { pullRepo } from './git.js';
@@ -24,34 +23,31 @@ import { listRemoteBundles, pullBundle } from './secrets/sync.js';
  *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
  *   --cloud                fetch repos (or the selected subset), skip reconcile
- *   --repos/--secrets/...  fetch only the selected types, then reconcile
+ *   --repos/--secrets      fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
  *
- * Secrets and sessions are NOT part of the bare default — they are opt-in via
- * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
- * bare `agents sync` is more blast radius than the verb should carry by
- * default, and session transcripts are queryable on demand (`agents sessions
- * --host <machine>`) so they don't need eager mirroring.
+ * Secrets are NOT part of the bare default — they are opt-in via `--secrets`.
+ * Pulling every secret bundle onto the machine on a bare `agents sync` is more
+ * blast radius than the verb should carry by default.
  */
 export function planUmbrellaStages(f) {
     if (f.local) {
-        return { fetchRepos: false, fetchSecrets: false, fetchSessions: false, reconcile: true };
+        return { fetchRepos: false, fetchSecrets: false, reconcile: true };
     }
-    const anySelector = !!(f.repos || f.secrets || f.sessions);
+    const anySelector = !!(f.repos || f.secrets);
     if (anySelector) {
         return {
             fetchRepos: !!f.repos,
             fetchSecrets: !!f.secrets,
-            fetchSessions: !!f.sessions,
             reconcile: !f.cloud,
         };
     }
     // No per-type selector: bare = repos + reconcile; --cloud = repos, no
-    // reconcile. Secrets/sessions stay off unless explicitly selected above.
-    return { fetchRepos: true, fetchSecrets: false, fetchSessions: false, reconcile: !f.cloud };
+    // reconcile. Secrets stay off unless explicitly selected above.
+    return { fetchRepos: true, fetchSecrets: false, reconcile: !f.cloud };
 }
 /**
- * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
+ * Execute the planned stages in order: repos -> secrets -> reconcile.
  * A failure in one fetch stage is recorded and does not abort the others or the
  * reconcile — `agents sync` should make as much current as it can in one pass.
  */
@@ -110,33 +106,6 @@ export async function runUmbrellaSync(args) {
             result.secrets = { pulled, skipped: false, errors };
         }
     }
-    if (plan.fetchSessions) {
-        // Gate exactly like the daemon: without the `session-sync` beta opt-in (or
-        // with a missing r2.backups bundle) this is a clean no-op, not an error that
-        // fails the whole sync.
-        const { isBetaEnabled } = await import('./beta.js');
-        const { isSyncConfigured } = await import('./session/sync/config.js');
-        if (isBetaEnabled('session-sync') && isSyncConfigured()) {
-            const { syncSessions } = await import('./session/sync/sync.js');
-            // Record a failure here instead of letting it throw: like the fetchSecrets
-            // block above, a failure in one fetch stage must not abort the others or
-            // the reconcile below (see this function's doc comment). Without this,
-            // syncSessions() throwing — e.g. via the C1 containment reject on a
-            // malicious peer manifest — would skip `plan.reconcile` entirely.
-            try {
-                const r = await syncSessions();
-                result.sessions = { ran: true, pushed: r.pushed, pulled: r.pulled, merged: r.merged };
-                log(`sessions: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}`);
-            }
-            catch (err) {
-                result.sessions = { ran: false, pushed: 0, pulled: 0, merged: 0, error: err.message };
-                log(`sessions: failed — ${err.message}`);
-            }
-        }
-        else {
-            result.sessions = { ran: false, pushed: 0, pulled: 0, merged: 0 };
-        }
-    }
     if (plan.reconcile) {
         const { refresh } = await import('./refresh.js');
         await refresh({ skipPrompts: yes });

package/dist/lib/teams/agents.d.ts

@@ -218,13 +218,30 @@ export declare class AgentProcess {
      * Uses a per-wave batched snapshot (remotePollSnapshot) when the supervisor's
      * one-ssh-per-host pre-pass populated it; otherwise falls back to its own
      * round-trips so a bare `teams status`/`teams logs` is still correct.
+     *
+     * Only polls a teammate that is plausibly still RUNNING (RUSH-2118). Once a
+     * remote teammate reaches a terminal status, the poll that resolved it already
+     * mirrored the final log bytes and read the `.exit` sentinel in this SAME
+     * function (delta pulled before the exit check below) — the underlying process
+     * is gone and can never write more, so there is nothing left to fetch. Without
+     * this guard every finished remote teammate still cost one ssh round-trip on
+     * EVERY `--active`/`listAll` poll forever, which is what made `agents sessions
+     * --active --local` take ~4.3s on a box with 30 completed teammates.
      */
     private syncRemoteMirror;
     /** Reset the local stdout cursor for a newly truncated resume log. */
     resetLogReadPosition(): number;
     /** Restore the cursor when a resume transaction puts the prior log back. */
     restoreLogReadPosition(position: number): void;
-    readNewEvents(): Promise<void>;
+    /**
+     * @param opts.skipRemote A `--local` caller (RUSH-2118): never dial a
+     *   remote-host teammate, not even a still-RUNNING one — report its
+     *   last-persisted meta.json state as-is. A local-only query is by definition
+     *   this-machine-only, so it must not issue an ssh round-trip at all.
+     */
+    readNewEvents(opts?: {
+        skipRemote?: boolean;
+    }): Promise<void>;
     /**
      * Truncate the local mirror to its trailing REMOTE_MIRROR_MAX_BYTES and reset
      * lastReadPos to the new (smaller) size so the parser doesn't re-read the kept
@@ -244,7 +261,14 @@ export declare class AgentProcess {
     saveMeta(): Promise<void>;
     static loadFromDisk(agentId: string, baseDir?: string | null): Promise<AgentProcess | null>;
     isProcessAlive(): boolean;
-    updateStatusFromProcess(): Promise<void>;
+    /**
+     * @param opts.skipRemote A `--local` caller (RUSH-2118): a distributed
+     *   teammate is never dialed — its in-memory state (already loaded from
+     *   meta.json) stands as-is, no ssh, no re-save.
+     */
+    updateStatusFromProcess(opts?: {
+        skipRemote?: boolean;
+    }): Promise<void>;
     /**
      * Recover the teammate's exit status after its process is gone.
      *
@@ -298,8 +322,16 @@ export declare class AgentManager {
     private defaultMode;
     private initPromise;
     private cloudDispatcher;
+    /**
+     * A `--local` caller (RUSH-2118): every poll this manager issues skips the
+     * ssh round-trip for a distributed (remote-host) teammate, reporting its
+     * last-persisted meta.json state instead. Set once at construction so the
+     * INITIAL load in doInitialize()/loadExistingAgents() — which polls every
+     * teammate before listRunning()/listAll() ever run — honors it too.
+     */
+    private localOnly;
     private constructorAgentsDir;
-    constructor(maxAgents?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number);
+    constructor(maxAgents?: number, agentsDir?: string | null, defaultMode?: Mode | null, filterByCwd?: string | null, cleanupAgeDays?: number, localOnly?: boolean);
     private initialize;
     private doInitialize;
     getDefaultMode(): Mode;

package/dist/lib/teams/agents.js

@@ -34,7 +34,9 @@ import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { pullRemoteLogDelta, REMOTE_MIRROR_MAX_BYTES } from '../hosts/progress.js';
 import { createRemoteWorktree, ensureRemoteRepo } from './remoteWorktree.js';
 import { getTeam } from './registry.js';
-import { resolvePlacement } from './scheduler.js';
+import { resolvePlacement, cappedDevices } from './scheduler.js';
+import { readMaxConcurrentCaps } from '../device-config.js';
+import chalk from 'chalk';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
 // large inactive+purgeable cache the kernel will reclaim under pressure, so
@@ -669,10 +671,21 @@ export class AgentProcess {
      * Uses a per-wave batched snapshot (remotePollSnapshot) when the supervisor's
      * one-ssh-per-host pre-pass populated it; otherwise falls back to its own
      * round-trips so a bare `teams status`/`teams logs` is still correct.
+     *
+     * Only polls a teammate that is plausibly still RUNNING (RUSH-2118). Once a
+     * remote teammate reaches a terminal status, the poll that resolved it already
+     * mirrored the final log bytes and read the `.exit` sentinel in this SAME
+     * function (delta pulled before the exit check below) — the underlying process
+     * is gone and can never write more, so there is nothing left to fetch. Without
+     * this guard every finished remote teammate still cost one ssh round-trip on
+     * EVERY `--active`/`listAll` poll forever, which is what made `agents sessions
+     * --active --local` take ~4.3s on a box with 30 completed teammates.
      */
     async syncRemoteMirror() {
         if (!this.hostName || !this.hostTarget || !this.remoteLog)
             return;
+        if (this.status !== AgentStatus.RUNNING)
+            return;
         // Pull the new remote bytes and append them to the local mirror the parser
         // reads. One offset-tail round-trip; nothing to write when the log is quiet.
         const delta = pullRemoteLogDelta(this.hostTarget, {
@@ -729,7 +742,15 @@ export class AgentProcess {
     restoreLogReadPosition(position) {
         this.lastReadPos = position;
     }
-    async readNewEvents() {
+    /**
+     * @param opts.skipRemote A `--local` caller (RUSH-2118): never dial a
+     *   remote-host teammate, not even a still-RUNNING one — report its
+     *   last-persisted meta.json state as-is. A local-only query is by definition
+     *   this-machine-only, so it must not issue an ssh round-trip at all.
+     */
+    async readNewEvents(opts = {}) {
+        if (this.hostName && opts.skipRemote)
+            return;
         // Distributed teammate: mirror the host's new log bytes locally first, then
         // fall through to the identical local read+parse below.
         if (this.hostName) {
@@ -984,7 +1005,12 @@ export class AgentProcess {
         }
         return true;
     }
-    async updateStatusFromProcess() {
+    /**
+     * @param opts.skipRemote A `--local` caller (RUSH-2118): a distributed
+     *   teammate is never dialed — its in-memory state (already loaded from
+     *   meta.json) stands as-is, no ssh, no re-save.
+     */
+    async updateStatusFromProcess(opts = {}) {
         if (!this.pid) {
             // Distributed (remote-host) teammates have no local PID by design; their
             // lifecycle lives on the host. readNewEvents() mirrors the remote log and
@@ -992,6 +1018,8 @@ export class AgentProcess {
             // syncRemoteMirror), so we just persist and return — never the local
             // "RUNNING without a PID is impossible" fail path below.
             if (this.hostName) {
+                if (opts.skipRemote)
+                    return;
                 await this.readNewEvents();
                 if (this.status !== AgentStatus.RUNNING && !this.completedAt) {
                     this.completedAt = this.getLatestEventTime() || this.startedAt || new Date();
@@ -1160,12 +1188,21 @@ export class AgentManager {
     defaultMode;
     initPromise = null;
     cloudDispatcher = null;
+    /**
+     * A `--local` caller (RUSH-2118): every poll this manager issues skips the
+     * ssh round-trip for a distributed (remote-host) teammate, reporting its
+     * last-persisted meta.json state instead. Set once at construction so the
+     * INITIAL load in doInitialize()/loadExistingAgents() — which polls every
+     * teammate before listRunning()/listAll() ever run — honors it too.
+     */
+    localOnly;
     constructorAgentsDir = null;
-    constructor(maxAgents = 50, agentsDir = null, defaultMode = null, filterByCwd = null, cleanupAgeDays = 7) {
+    constructor(maxAgents = 50, agentsDir = null, defaultMode = null, filterByCwd = null, cleanupAgeDays = 7, localOnly = false) {
         this.maxAgents = maxAgents;
         this.constructorAgentsDir = agentsDir;
         this.filterByCwd = filterByCwd;
         this.cleanupAgeDays = cleanupAgeDays;
+        this.localOnly = localOnly;
         const resolvedDefaultMode = defaultMode ? normalizeModeValue(defaultMode) : defaultModeFromEnv();
         if (!resolvedDefaultMode) {
             throw new Error(`Invalid default_mode '${defaultMode}'. Use plan, edit, auto, or skip.`);
@@ -1272,7 +1309,7 @@ export class AgentManager {
                     continue;
                 }
             }
-            await agent.updateStatusFromProcess();
+            await agent.updateStatusFromProcess({ skipRemote: this.localOnly });
             this.agents.set(agentId, agent);
             loadedCount++;
         }
@@ -1726,7 +1763,14 @@ export class AgentManager {
         if (!teamMeta)
             return;
         const roster = await this.listByTask(taskName);
-        const { device } = resolvePlacement(teamMeta, null, roster);
+        const pool = teamMeta.devices ?? [];
+        const maxConcurrent = pool.length > 1 ? readMaxConcurrentCaps(pool) : undefined;
+        if (maxConcurrent) {
+            for (const c of cappedDevices(pool, roster, maxConcurrent)) {
+                console.error(chalk.dim(`[placement] '${c.device}' excluded from auto-pick — at its agents.max-concurrent cap (${c.running}/${c.cap} running)`));
+            }
+        }
+        const { device } = resolvePlacement(teamMeta, null, roster, { maxConcurrent });
         if (device)
             await this.resolveScheduledPlacement(agent, device, taskName);
     }
@@ -1990,8 +2034,8 @@ export class AgentManager {
         await this.initialize();
         const agents = Array.from(this.agents.values());
         for (const agent of agents) {
-            await agent.readNewEvents();
-            await agent.updateStatusFromProcess();
+            await agent.readNewEvents({ skipRemote: this.localOnly });
+            await agent.updateStatusFromProcess({ skipRemote: this.localOnly });
         }
         return agents;
     }

package/dist/lib/teams/scheduler.d.ts

@@ -2,6 +2,19 @@
 export interface PlacementTeam {
     devices?: string[];
 }
+/**
+ * Optional placement inputs beyond the team + roster. `maxConcurrent` maps a
+ * device name to its `agents.max-concurrent` cap (from the device doc — read
+ * locally via `readMaxConcurrentCaps`, never probed over SSH). Teams counts
+ * the team's OWN roster against the cap (device-global counting would need an
+ * SSH probe per candidate — out of the hot path; Factory auto-launch is the
+ * device-wide counter). Only the least-loaded AUTO-PICK (cascade step 3)
+ * honors caps: an explicit pin or a pool of one is the user's own choice and
+ * is never second-guessed.
+ */
+export interface PlacementOptions {
+    maxConcurrent?: Record<string, number>;
+}
 /**
  * A roster entry the load counter reads — the shape any teammate satisfies
  * (AgentProcess included). `status` is compared against `'running'` (the
@@ -11,19 +24,33 @@ export interface RosterEntry {
     hostName: string | null;
     status: string;
 }
+/**
+ * Pool devices excluded from auto-pick because they are at (or over) their
+ * `agents.max-concurrent` cap. Returned with the live counts so the caller can
+ * state the reason to the user instead of the device silently never winning.
+ */
+export declare function cappedDevices(devices: string[], roster: RosterEntry[], maxConcurrent: Record<string, number>): Array<{
+    device: string;
+    running: number;
+    cap: number;
+}>;
 /**
  * Pick the least-loaded device from the pool — the one with the fewest RUNNING
  * teammates currently assigned to it. Ties break by pool order (first wins), so
  * an empty pool fills round-robin-ish as teammates launch. Pure: counts the
  * roster, no I/O.
+ *
+ * With `maxConcurrent`, devices at their cap are excluded; if EVERY device is
+ * capped this throws naming each cap and the fix — a loud failure beats a
+ * teammate silently landing on a machine its operator capped.
  */
-export declare function pickLeastLoaded(devices: string[], roster: RosterEntry[]): string;
+export declare function pickLeastLoaded(devices: string[], roster: RosterEntry[], maxConcurrent?: Record<string, number>): string;
 /**
  * Resolve where a teammate runs. Returns `{ device: null }` for a local run
  * (no pin, no pool, or the chosen device is the local machine) and
  * `{ device: <name> }` for a remote placement. See the cascade in the module
  * header.
  */
-export declare function resolvePlacement(team: PlacementTeam, explicitDevice: string | null, roster: RosterEntry[]): {
+export declare function resolvePlacement(team: PlacementTeam, explicitDevice: string | null, roster: RosterEntry[], opts?: PlacementOptions): {
     device: string | null;
 };