@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/lib/smart-launch.js

@@ -1,5 +1,5 @@
 /**
- * Device placement for `--device auto` / `--host auto`.
+ * Device placement for `--device auto`.
  *
  * Explicit auto placement probes live fleet health and harness readiness.
  * Historical affinity remains for generic host resolution callers.
@@ -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,13 @@ 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.
+    // Roster on `pool` so a fleet-wide role default reaches a doc-less device
+    // in this error's own candidate set, not just the ones with a doc.
+    const marked = describeAutoPool({ roster: pool });
+    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 +127,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 +177,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 `--device 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 +190,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',
@@ -187,7 +244,7 @@ export function isDeviceAuto(value) {
 }
 const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
 /**
- * Apply `--device auto` / `--host auto` (and deprecated `--smart`) onto run options.
+ * Apply `--device auto` (and deprecated `--smart`) onto run options.
  * Mutates `options` in place. Placement failures propagate without rewriting
  * `auto`, so callers fail loud instead of silently launching locally.
  */

package/dist/lib/snapshot.d.ts

@@ -1,5 +1,5 @@
 /**
- * `agents snapshot` — one-process fleet consumer snapshot.
+ * `agents devices snapshot` — one-process fleet consumer snapshot.
  *
  * Consumers (Factory watchdog, menubar, fleet scripts) used to fork:
  *   agents view <agent> --json  × N harnesses
@@ -13,11 +13,11 @@
  * Stores are not merged — inventory still comes from view, active rows from
  * sessions, blocks from feed. Only the reader is consolidated.
  */
-import { type OpenBlock } from './feed.js';
+import { type OpenBlock } from './feed/feed.js';
 import { type FleetAgentCounts } from './fleet-status.js';
 import type { AgentId } from './types.js';
 import type { UnifiedSyncStatus } from './sync-status.js';
-import type { ViewJsonAgent } from '../commands/view.js';
+import type { ViewJsonAgent } from './view-types.js';
 /** One open-block row in the optional feed summary (no full question bodies). */
 export interface SnapshotFeedBlock {
     blockId: string;
@@ -44,7 +44,7 @@ export type SnapshotSessionRow = {
     [key: string]: unknown;
 };
 /**
- * Stable machine-readable contract for `agents snapshot --json`.
+ * Stable machine-readable contract for `agents devices snapshot --json`.
  * Bump `version` only on breaking shape changes.
  */
 export interface FleetSnapshot {

package/dist/lib/snapshot.js

@@ -1,5 +1,5 @@
 /**
- * `agents snapshot` — one-process fleet consumer snapshot.
+ * `agents devices snapshot` — one-process fleet consumer snapshot.
  *
  * Consumers (Factory watchdog, menubar, fleet scripts) used to fork:
  *   agents view <agent> --json  × N harnesses
@@ -14,7 +14,7 @@
  * sessions, blocks from feed. Only the reader is consolidated.
  */
 import { machineId } from './machine-id.js';
-import { listBlocks } from './feed.js';
+import { listBlocks } from './feed/feed.js';
 import { computeAgentCounts } from './fleet-status.js';
 /** Summarize open blocks for the snapshot feed slice. Pure / unit-testable. */
 export function summarizeFeedBlocks(blocks, limit = 50) {

package/dist/lib/ssh-exec.d.ts

@@ -2,7 +2,7 @@
  * Shared SSH exec primitive — the single hardened choke point for running a
  * command on a remote host over the system `ssh`.
  *
- * `agents run --host` dispatch and the browser driver both go through here so the
+ * `agents run --device` dispatch and the browser driver both go through here so the
  * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
  * target-injection guard live in exactly one place. Target validation is the
  * canonical definition; `commands/secrets.ts` re-exports it.

package/dist/lib/ssh-exec.js

@@ -2,7 +2,7 @@
  * Shared SSH exec primitive — the single hardened choke point for running a
  * command on a remote host over the system `ssh`.
  *
- * `agents run --host` dispatch and the browser driver both go through here so the
+ * `agents run --device` dispatch and the browser driver both go through here so the
  * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
  * target-injection guard live in exactly one place. Target validation is the
  * canonical definition; `commands/secrets.ts` re-exports it.
@@ -83,7 +83,7 @@ export class RemoteUtf8Accumulator {
  * OpenSSH connection-multiplexing options. The first connection to a host opens
  * a control socket; subsequent connections (even from a *separate* `agents`
  * invocation) reuse it, skipping the TCP+auth handshake — so repeated
- * `--host <name>` calls to the same box feel local instead of paying ~100-300ms
+ * `--device <name>` calls to the same box feel local instead of paying ~100-300ms
  * each. `ControlPersist=60s` keeps the master alive briefly after the last
  * client exits. `%C` (a short fixed-length hash of local-host/remote/port/user)
  * keeps the socket path well under macOS's 104-char `sun_path` limit.

package/dist/lib/ssh-tunnel.d.ts

@@ -5,7 +5,7 @@
  *
  *  1. `startSSHTunnel` — the generic `ssh -L localPort:127.0.0.1:remotePort -N`
  *     spawn, extracted verbatim from the browser CDP driver so both the browser
- *     and `agents computer --host` reach a remote loopback service through one
+ *     and `agents computer --device` reach a remote loopback service through one
  *     hardened tunnel. Behavior for the browser caller is unchanged (default,
  *     foreground, stderr-captured).
  *
@@ -21,8 +21,8 @@ import { type DeviceProfile } from './devices/registry.js';
 export interface StartTunnelOptions {
     /**
      * Detach the tunnel so it OUTLIVES this CLI process. Used by
-     * `agents computer start --host` — the tunnel must persist across separate
-     * verb invocations (`apps`, `click`, …) until `stop --host` tears it down.
+     * `agents computer start --device` — the tunnel must persist across separate
+     * verb invocations (`apps`, `click`, …) until `stop --device` tears it down.
      * The browser driver leaves this false: it holds the tunnel for the lifetime
      * of one CDP session and kills it on cleanup.
      */
@@ -83,12 +83,12 @@ export declare function sha256File(file: string): Promise<string>;
  */
 export declare function downloadWinHelperExe(version: string): Promise<string>;
 /**
- * Resolve the helper exe for `setup --host`: local build outputs first (repo
+ * Resolve the helper exe for `setup --device`: local build outputs first (repo
  * checkout / bundled), then the checksum-verified release-asset download for
  * the running CLI version. Throws with the tag it checked when neither exists.
  */
 export declare function ensureWinHelperExe(version?: string): Promise<string>;
-/** Persisted per-device tunnel state so verbs can reconnect after `start --host`. */
+/** Persisted per-device tunnel state so verbs can reconnect after `start --device`. */
 export interface RemoteTunnelState {
     device: string;
     target: string;
@@ -106,7 +106,7 @@ export declare function writeRemoteState(state: RemoteTunnelState): void;
 export declare function clearRemoteState(device: string): void;
 /**
  * Local file holding the shared-secret token for a device's helper daemon.
- * Written at `setup --host` (0600), read at `start --host` so the RPC client
+ * Written at `setup --device` (0600), read at `start --device` so the RPC client
  * authenticates. The remote daemon reads the same value from its own
  * `--token-file`; the CLI is the source of truth and never round-trips it back.
  */
@@ -154,7 +154,7 @@ export declare function scpRemotePath(remotePath: string): string;
  */
 export declare function buildScpArgs(target: string, remotePath: string, filePath: string, extraSshArgs?: string[]): string[];
 /**
- * `setup --host`: push the exe, then register + start the LOGON task. Remote
+ * `setup --device`: push the exe, then register + start the LOGON task. Remote
  * PowerShell hops go through `sshExec` (BatchMode key auth — the same hardening
  * the browser driver and `agents ssh` use), and the large exe rides a binary
  * scp transfer. Throws with the remote stderr on any failure.
@@ -166,13 +166,13 @@ export declare function setupRemoteHelper(name: string): Promise<{
 /** Reserve a free local TCP port by binding :0 and reading the assigned port. */
 export declare function pickFreePort(): Promise<number>;
 /**
- * `start --host`: open a detached ssh -L tunnel to the remote daemon, verify it
+ * `start --device`: open a detached ssh -L tunnel to the remote daemon, verify it
  * answers over TCP, and persist the tunnel state so verbs can reconnect. Returns
  * the state (and leaves the tunnel running in the background).
  */
 export declare function startRemoteTunnel(name: string): Promise<RemoteTunnelState>;
 /**
- * `stop --host`: kill the local tunnel, unregister the remote task (best-effort
+ * `stop --device`: kill the local tunnel, unregister the remote task (best-effort
  * — the box may be offline), and clear the persisted state.
  */
 export declare function stopRemoteHelper(name: string): Promise<{
@@ -182,7 +182,7 @@ export declare function stopRemoteHelper(name: string): Promise<{
 /**
  * Point this process's RPC client at a device's live tunnel by setting
  * COMPUTER_HELPER_TCP / COMPUTER_HELPER_TOKEN from persisted state. Called for
- * remote verbs (`apps --host`, `click --host`, …) so the shared
+ * remote verbs (`apps --device`, `click --device`, …) so the shared
  * openComputerClient() transparently selects the TcpClient transport — no
  * per-verb wiring. Exits with guidance when there is no active tunnel.
  */

package/dist/lib/ssh-tunnel.js

@@ -5,7 +5,7 @@
  *
  *  1. `startSSHTunnel` — the generic `ssh -L localPort:127.0.0.1:remotePort -N`
  *     spawn, extracted verbatim from the browser CDP driver so both the browser
- *     and `agents computer --host` reach a remote loopback service through one
+ *     and `agents computer --device` reach a remote loopback service through one
  *     hardened tunnel. Behavior for the browser caller is unchanged (default,
  *     foreground, stderr-captured).
  *
@@ -199,7 +199,7 @@ export async function downloadWinHelperExe(version) {
     return cached;
 }
 /**
- * Resolve the helper exe for `setup --host`: local build outputs first (repo
+ * Resolve the helper exe for `setup --device`: local build outputs first (repo
  * checkout / bundled), then the checksum-verified release-asset download for
  * the running CLI version. Throws with the tag it checked when neither exists.
  */
@@ -239,7 +239,7 @@ export function clearRemoteState(device) {
 }
 /**
  * Local file holding the shared-secret token for a device's helper daemon.
- * Written at `setup --host` (0600), read at `start --host` so the RPC client
+ * Written at `setup --device` (0600), read at `start --device` so the RPC client
  * authenticates. The remote daemon reads the same value from its own
  * `--token-file`; the CLI is the source of truth and never round-trips it back.
  */
@@ -275,7 +275,7 @@ export async function resolveRemoteDevice(name) {
         throw new Error(`Unknown device '${name}'. Register it with \`agents devices add\` / \`agents devices sync\`, then retry.`);
     }
     if (device.platform !== 'windows') {
-        throw new Error(`Device '${name}' is ${device.platform}, not windows. \`agents computer --host\` drives the Windows computer-helper daemon.`);
+        throw new Error(`Device '${name}' is ${device.platform}, not windows. \`agents computer --device\` drives the Windows computer-helper daemon.`);
     }
     const target = sshTargetFor(device); // validates address + injection guard
     const host = hostNameFor(device); // sshTargetFor already threw if absent
@@ -392,7 +392,7 @@ function copyFileOverScp(target, remotePath, filePath, extraSshArgs = [], timeou
     });
 }
 /**
- * `setup --host`: push the exe, then register + start the LOGON task. Remote
+ * `setup --device`: push the exe, then register + start the LOGON task. Remote
  * PowerShell hops go through `sshExec` (BatchMode key auth — the same hardening
  * the browser driver and `agents ssh` use), and the large exe rides a binary
  * scp transfer. Throws with the remote stderr on any failure.
@@ -441,7 +441,7 @@ export async function setupRemoteHelper(name) {
     if (reg.code !== 0) {
         throw new Error(`registering scheduled task on '${name}' failed (exit ${reg.code ?? 'null'}): ${reg.stderr.trim() || reg.stdout.trim()}`);
     }
-    // Persist the token locally so `start --host` authenticates to the daemon.
+    // Persist the token locally so `start --device` authenticates to the daemon.
     writeHelperToken(name, token);
     return { target, taskName: REMOTE_TASK_NAME };
 }
@@ -458,7 +458,7 @@ export function pickFreePort() {
     });
 }
 /**
- * `start --host`: open a detached ssh -L tunnel to the remote daemon, verify it
+ * `start --device`: open a detached ssh -L tunnel to the remote daemon, verify it
  * answers over TCP, and persist the tunnel state so verbs can reconnect. Returns
  * the state (and leaves the tunnel running in the background).
  */
@@ -514,8 +514,8 @@ export async function startRemoteTunnel(name) {
         }
         catch { /* gone */ }
         const hint = token
-            ? `Is it installed? Run: agents computer setup --host ${name}`
-            : `No auth token on record for '${name}' — re-run: agents computer setup --host ${name}`;
+            ? `Is it installed? Run: agents computer setup --device ${name}`
+            : `No auth token on record for '${name}' — re-run: agents computer setup --device ${name}`;
         throw new Error(`tunnel to '${name}' opened but the daemon did not answer (${probeErr}). ${hint}`);
     }
     const state = {
@@ -532,7 +532,7 @@ export async function startRemoteTunnel(name) {
     return state;
 }
 /**
- * `stop --host`: kill the local tunnel, unregister the remote task (best-effort
+ * `stop --device`: kill the local tunnel, unregister the remote task (best-effort
  * — the box may be offline), and clear the persisted state.
  */
 export async function stopRemoteHelper(name) {
@@ -566,7 +566,7 @@ export async function stopRemoteHelper(name) {
 /**
  * Point this process's RPC client at a device's live tunnel by setting
  * COMPUTER_HELPER_TCP / COMPUTER_HELPER_TOKEN from persisted state. Called for
- * remote verbs (`apps --host`, `click --host`, …) so the shared
+ * remote verbs (`apps --device`, `click --device`, …) so the shared
  * openComputerClient() transparently selects the TcpClient transport — no
  * per-verb wiring. Exits with guidance when there is no active tunnel.
  */
@@ -574,7 +574,7 @@ export function hydrateRemoteEnvFromState(name) {
     const state = readRemoteState(name);
     if (!state) {
         console.error(`No active remote tunnel for '${name}'.`);
-        console.error(`Run:  agents computer start --host ${name}`);
+        console.error(`Run:  agents computer start --device ${name}`);
         process.exit(1);
     }
     process.env.COMPUTER_HELPER_TCP = `127.0.0.1:${state.localPort}`;

package/dist/lib/staleness/checkers/hooks.d.ts

@@ -2,7 +2,7 @@
  * Hooks staleness — one executable file per hook. Project layer is EXCLUDED
  * by design: a cloned public repo with `.agents/hooks/foo` must not plant a
  * hook that fires next time the user runs an agent inside it (see
- * `src/lib/versions.ts:1832-1836`). Only user + system + extras count.
+ * `src/lib/installations/versions.ts:1832-1836`). Only user + system + extras count.
  *
  * Auxiliary files (README.md, promptcuts.yaml) live in hooks/ but are not
  * hooks — the executable bit on the source distinguishes them. This matches

package/dist/lib/staleness/checkers/hooks.js

@@ -2,7 +2,7 @@
  * Hooks staleness — one executable file per hook. Project layer is EXCLUDED
  * by design: a cloned public repo with `.agents/hooks/foo` must not plant a
  * hook that fires next time the user runs an agent inside it (see
- * `src/lib/versions.ts:1832-1836`). Only user + system + extras count.
+ * `src/lib/installations/versions.ts:1832-1836`). Only user + system + extras count.
  *
  * Auxiliary files (README.md, promptcuts.yaml) live in hooks/ but are not
  * hooks — the executable bit on the source distinguishes them. This matches

package/dist/lib/staleness/detectors/permissions.js

@@ -142,28 +142,6 @@ function buildGrokDetector() {
         },
     };
 }
-function buildGooseDetector() {
-    return {
-        kind: 'permissions',
-        agent: 'goose',
-        list({ versionHome }) {
-            const permissionsPath = path.join(versionHome, '.config', 'goose', 'permission.yaml');
-            if (!fs.existsSync(permissionsPath))
-                return [];
-            try {
-                const config = yaml.parse(fs.readFileSync(permissionsPath, 'utf-8'));
-                const user = config?.user;
-                const count = (Array.isArray(user?.always_allow) ? user.always_allow.length : 0) +
-                    (Array.isArray(user?.ask_before) ? user.ask_before.length : 0) +
-                    (Array.isArray(user?.never_allow) ? user.never_allow.length : 0);
-                if (count > 0)
-                    return discoverPermissionGroups().map(g => g.name);
-            }
-            catch { /* parse fail */ }
-            return [];
-        },
-    };
-}
 function buildKimiDetector() {
     return {
         kind: 'permissions',
@@ -315,7 +293,6 @@ const handlers = {
     opencode: buildOpenCodeDetector,
     antigravity: buildAntigravityDetector,
     grok: buildGrokDetector,
-    goose: buildGooseDetector,
     kimi: buildKimiDetector,
     cursor: buildCursorDetector,
     droid: buildDroidDetector,

package/dist/lib/staleness/detectors/plugins.js

@@ -1,5 +1,5 @@
 import { capableAgents } from '../../capabilities.js';
-import { discoverPlugins, isPluginSynced } from '../../plugins.js';
+import { discoverPlugins, isPluginSynced } from '../../plugins/plugins.js';
 import { lazyAgentMap } from '../writers/lazy-map.js';
 function buildPluginsDetector(agent) {
     return {

package/dist/lib/staleness/fingerprint.js

@@ -23,7 +23,7 @@ export function fingerprintFile(filePath) {
 /**
  * Names we never fingerprint: OS metadata, VCS bookkeeping, dep caches,
  * build outputs. Matches the SKILL_COPY_IGNORE set used by the sync writer
- * in `src/lib/versions.ts`.
+ * in `src/lib/installations/versions.ts`.
  *
  * Important: this is an allowlist of noise, NOT a blanket "skip every
  * dot-prefixed entry". Plugins keep their manifest at

package/dist/lib/staleness/layers.d.ts

@@ -7,7 +7,7 @@
  *   - "first-wins" (commands, skills, mcp, subagents, workflows, plugins):
  *     project > user > system > extras. Same-named entries shadow.
  *   - "first-wins, no project" (hooks): security exclusion — see
- *     `src/lib/versions.ts:1832-1836` for the rationale. User > system > extras.
+ *     `src/lib/installations/versions.ts:1832-1836` for the rationale. User > system > extras.
  *   - "merged" (permissions): every layer contributes; first-wins on name.
  *   - "composed" (rules): preset + subrules resolved per-name across layers.
  */

package/dist/lib/staleness/layers.js

@@ -7,7 +7,7 @@
  *   - "first-wins" (commands, skills, mcp, subagents, workflows, plugins):
  *     project > user > system > extras. Same-named entries shadow.
  *   - "first-wins, no project" (hooks): security exclusion — see
- *     `src/lib/versions.ts:1832-1836` for the rationale. User > system > extras.
+ *     `src/lib/installations/versions.ts:1832-1836` for the rationale. User > system > extras.
  *   - "merged" (permissions): every layer contributes; first-wins on name.
  *   - "composed" (rules): preset + subrules resolved per-name across layers.
  */

package/dist/lib/staleness/writers/mcp.js

@@ -7,7 +7,9 @@ function buildMcpWriter(agent) {
         agent,
         write({ version, versionHome, selection, cwd }) {
             const r = installMcpServers(agent, version, versionHome, selection, { cwd });
-            return { synced: r.applied };
+            // Forward r.errors: dropping them is what let a harness with no config
+            // writer report a clean sync while writing nothing (RUSH-2677).
+            return { synced: r.applied, ...(r.errors.length ? { errors: r.errors } : {}) };
         },
     };
 }

package/dist/lib/staleness/writers/plugins.js

@@ -1,5 +1,5 @@
 import { capableAgents } from '../../capabilities.js';
-import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphanedPluginSkills } from '../../plugins.js';
+import { discoverPlugins, syncPluginToVersion, pluginSupportsAgent, cleanOrphanedPluginSkills } from '../../plugins/plugins.js';
 import { lazyAgentMap } from './lazy-map.js';
 function buildPluginsWriter(agent) {
     return {

package/dist/lib/staleness/writers/types.d.ts

@@ -28,6 +28,14 @@ export interface WriteArgs<Sel> {
 export interface WriteResult {
     /** Names actually written. Empty array = write produced nothing (not an error). */
     synced: string[];
+    /**
+     * Per-item failures the writer could not complete, as user-facing sentences.
+     *
+     * `synced: []` alone cannot distinguish "nothing to do" from "refused to
+     * write and said why", which is how an unwritable harness reported success
+     * for its whole life (RUSH-2677). A writer that declines MUST say so here.
+     */
+    errors?: string[];
 }
 /**
  * Inverse of a write: locate and delete the materialized artifact for one