@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/lib/fleet/capture.js

@@ -26,7 +26,22 @@ export function captureFleet(prev, inputs) {
     // Roster: explicit map of the captured names. A hand-authored override for a
     // device that still exists is preserved; a captured agent list only fills in
     // when the manifest didn't already pin one for that device.
+    //
+    // A device absent from `inputs.devices` drops OUT of the roster — that is the
+    // intended "live state is the source of truth for WHICH devices exist". But
+    // `fleet.devices.<name>.config` is also the operator-config store, and a
+    // capture run from a box whose registry has not seen a peer would silently
+    // erase that peer's settings. Observed for real: capturing on yosemite-s0
+    // deleted zion's whole config block from the shared agents.yaml. So carry a
+    // dropped device's `config:` forward — config only, never its roster fields.
     const devices = {};
+    for (const [name, prevOverride] of Object.entries(prevDevices)) {
+        if (inputs.devices.includes(name))
+            continue; // handled by the roster loop below
+        const config = prevOverride?.config;
+        if (config && Object.keys(config).length > 0)
+            devices[name] = { config };
+    }
     for (const name of inputs.devices) {
         const prevOverride = prevDevices[name] ?? {};
         const override = { ...prevOverride };

package/dist/lib/fleet/manifest.js

@@ -59,6 +59,15 @@ export function parseFleetManifest(raw) {
         for (const [name, ov] of Object.entries(o.devices)) {
             // An empty entry (`device: {}`) inherits defaults — represent as {}.
             const merged = ov == null ? {} : validateDefaults(ov, `devices.${name}`);
+            // `config:` is the operator-config block (`agents devices config`) —
+            // inert to the reconcile engine but part of the manifest shape.
+            const cfg = ov != null ? ov.config : undefined;
+            if (cfg !== undefined) {
+                if (typeof cfg !== 'object' || cfg === null || Array.isArray(cfg)) {
+                    throw new Error(`fleet: devices.${name}.config must be a mapping of config keys to values.`);
+                }
+                merged.config = cfg;
+            }
             map[name] = merged;
         }
         devices = map;

package/dist/lib/fleet/types.d.ts

@@ -33,6 +33,15 @@ export interface FleetDeviceOverride {
     agents?: string[];
     sync?: string[];
     login?: FleetLoginMode;
+    /**
+     * Operator config for this device, written by `agents devices config <name>`
+     * — the device-scope keys of the `lib/device-config.ts` registry (maxAgents,
+     * schedulerEnabled, ssh*, autoLaunch*, notes, …). This is the ONE store for
+     * per-device settings: central, synced, and backed up with agents.yaml.
+     * LEAK-FREE like the rest of the manifest — names and non-secret values only
+     * (a secrets-bundle NAME is fine; a credential value never is).
+     */
+    config?: Record<string, unknown>;
 }
 /**
  * The `fleet:` block as it appears in `agents.yaml` (or any `-f` file). `devices`

package/dist/lib/fleet-status.js

@@ -30,6 +30,7 @@ import * as path from 'path';
 import { getCacheDir } from './state.js';
 import { probeLocalStats } from './devices/health.js';
 import { getActiveSessions } from './session/active.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 /**
  * Tally running-agent workload from a host's live sessions. "running" is the
  * actively-working set (`status === 'running'`); `live` is every session the
@@ -95,14 +96,15 @@ export function readFleetStatus() {
 /** Merge rows into the mirror (best-effort; preserves other hosts' rows). */
 export function writeFleetStatusRows(entries) {
     try {
-        const dir = getCacheDir();
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        const merged = {
-            version: 1,
-            entries: { ...readFleetStatus(), ...entries },
-        };
-        fs.writeFileSync(mirrorPath(), JSON.stringify(merged, null, 2));
+        const target = mirrorPath();
+        ensureLockTarget(target, JSON.stringify({ version: 1, entries: {} }));
+        withFileLock(target, () => {
+            const merged = {
+                version: 1,
+                entries: { ...readFleetStatus(), ...entries },
+            };
+            atomicWriteFileSync(target, JSON.stringify(merged, null, 2));
+        });
     }
     catch {
         // best-effort; a failed write just means the reader sees an older union

package/dist/lib/git.d.ts

@@ -123,7 +123,7 @@ export declare function _resetSnapshotShaCacheForTest(): void;
  */
 export declare function getGitHubUsername(): Promise<string | null>;
 /**
- * Resolve the GitHub username synchronously for `agents share`. Order:
+ * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
  *   1. `AGENTS_SHARE_GITHUB_USER` env override
  *   2. `git config --global github.user`
  * Falls back to null so callers can decide whether to require auth or proceed
@@ -267,7 +267,9 @@ export declare function hasLocalChanges(dir: string): Promise<boolean>;
 export declare function displayHomePath(dir: string): string;
 /**
  * Pull changes in an existing repo.
- * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
+ * A dirty working tree no longer refuses outright: a fast-forward that touches
+ * no uncommitted path still runs (see `dirtyTreeRefusal`). It refuses when the
+ * branch has local commits to rebase, or when an incoming path is also dirty.
  *
  * Strategy (RUSH-2282):
  *   1. Fetch, then compare HEAD to the resolved tracking ref.
@@ -289,15 +291,27 @@ export declare function pullRepo(dir: string): Promise<{
  * Rebase a repo onto its remote, optionally pushing local commits back up.
  *
  * The one-repo counterpart to `pullRepo` used by `agents sync <repo>`:
- *   1. Refuse if the working tree is dirty (commit or discard first).
- *   2. `git fetch origin` then `git pull --rebase origin <branch>` — rebase, not
- *      merge, so a local commit lands cleanly on top of upstream with no merge
- *      bubble.
- *   3. When `push` is set, `git push origin <branch>` to send local commits up.
+ *   1. `git fetch origin`.
+ *   2. Clean tree → `git pull --rebase origin <branch>`: rebase, not merge, so a
+ *      local commit lands cleanly on top of upstream with no merge bubble.
+ *   3. Dirty tree → fast-forward instead, but only when that is provably safe:
+ *      no local commits ahead of upstream, and no incoming path collides with a
+ *      dirty one. Otherwise refuse, naming the paths that collided.
+ *   4. When `push` is set, `git push origin <branch>` to send local commits up.
  *
  * The branch is read from the repo's current HEAD (falls back to `main`) rather
  * than hardcoded. System repos pass `push: false` — they are pull-only mirrors
  * of the npm-shipped upstream.
+ *
+ * Why step 3 exists: refusing on *any* dirt strands merged changes indefinitely.
+ * A DotAgents repo accumulates unrelated local state — a modified `agents.yaml`,
+ * a session's scratch file, a machine-local dotfile — and under the old rule one
+ * such file froze that box's layer forever, silently. Measured 2026-08-10: a
+ * merged fix could not reach three of three boxes, each blocked by files the
+ * incoming commits never touched. A `--ff-only` merge is the safe primitive
+ * here: it cannot rewrite local commits, and git itself aborts rather than
+ * overwrite a modified file, so the path check is belt-and-braces, not the only
+ * guard.
  */
 export declare function syncRepoGit(dir: string, opts: {
     push: boolean;

package/dist/lib/git.js

@@ -437,7 +437,7 @@ function readGitConfigUser() {
     }
 }
 /**
- * Resolve the GitHub username synchronously for `agents share`. Order:
+ * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
  *   1. `AGENTS_SHARE_GITHUB_USER` env override
  *   2. `git config --global github.user`
  * Falls back to null so callers can decide whether to require auth or proceed
@@ -865,7 +865,9 @@ export function displayHomePath(dir) {
 }
 /**
  * Pull changes in an existing repo.
- * Refuses to pull if the working tree is dirty -- user must commit or discard changes first.
+ * A dirty working tree no longer refuses outright: a fast-forward that touches
+ * no uncommitted path still runs (see `dirtyTreeRefusal`). It refuses when the
+ * branch has local commits to rebase, or when an incoming path is also dirty.
  *
  * Strategy (RUSH-2282):
  *   1. Fetch, then compare HEAD to the resolved tracking ref.
@@ -914,11 +916,18 @@ export async function pullRepo(dir) {
             };
         }
         const status = await git.status();
-        if (!status.isClean()) {
+        // A dirty tree is not decided here: whether a fast-forward is safe depends
+        // on what is actually incoming, and that needs a fetched upstream ref. The
+        // gate therefore sits just before the integrate step below. The exception is
+        // a repo with no remote at all — there is nothing to fast-forward from, so
+        // the dirt is the whole answer and the resolution below would only fail
+        // with a less useful message.
+        const isDirty = !status.isClean();
+        if (isDirty && (await git.getRemotes()).length === 0) {
             return {
                 success: false,
                 commit: '',
-                error: `Blocked by local changes. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
+                error: `Blocked by local changes: the repo has no remote to pull from. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
             };
         }
         const branch = status.current || 'main';
@@ -978,6 +987,20 @@ export async function pullRepo(dir) {
             Number.isFinite(behindCount) &&
             aheadCount === 0 &&
             behindCount > 0;
+        // Dirty tree: same rule `syncRepoGit` applies, from the same function — a
+        // fast-forward that touches nothing the author is holding may proceed; a
+        // rebase or a colliding path may not. Refusing on any dirt at all is what
+        // used to strand merged changes on every box that had an unrelated edit.
+        if (isDirty) {
+            const refusal = await dirtyTreeRefusal(git, status, tracking);
+            if (refusal) {
+                return {
+                    success: false,
+                    commit: '',
+                    error: `Blocked by local changes: ${refusal}. Commit or discard them before pulling.\n\n  cd ${displayHomePath(dir)} && git status`,
+                };
+            }
+        }
         try {
             if (canFastForward) {
                 // Integrate the already-fetched tracking ref. No network, no FETCH_HEAD.
@@ -1017,19 +1040,92 @@ export async function pullRepo(dir) {
         return { success: false, commit: '', error: err.message };
     }
 }
+/**
+ * Every repo-relative path a status reports as locally touched, in one set.
+ *
+ * Reads `status.files`, which `simple-git` documents as "all files" and which is
+ * the same source `isClean()` is computed from — so this set and the decision to
+ * treat the tree as dirty can never disagree. The per-category arrays
+ * (`modified`, `staged`, `not_added`, …) are projections of that list; unioning
+ * them by hand means a category nobody thought of contributes nothing. `from`
+ * carries a rename's original path, and the incoming side may collide with
+ * either end.
+ */
+function dirtyPathSet(status) {
+    const out = new Set();
+    for (const f of status.files || []) {
+        if (f?.path)
+            out.add(f.path);
+        if (f?.from)
+            out.add(f.from);
+    }
+    return out;
+}
+/**
+ * Why a dirty working tree must NOT fast-forward to `upstreamRef` — or `null`
+ * when it safely can.
+ *
+ * The single home for that decision: `syncRepoGit` and `pullRepo` both integrate
+ * upstream and both meet dirty trees, and two copies of this rule would drift
+ * into two different answers for one question. Refusing outright is the thing
+ * being replaced — it strands merged changes behind unrelated local files —
+ * so the rule is narrow and stated once:
+ *
+ *   - local commits ahead of upstream → refuse (they need a rebase, which
+ *     requires a clean tree);
+ *   - an incoming path that is also dirty → refuse, and name it;
+ *   - otherwise the fast-forward touches nothing the author is holding.
+ *
+ * `-z` on the diff because `git diff --name-only` C-quotes paths containing
+ * unicode or control characters — `café.txt` comes back as `"caf\303\251.txt"`,
+ * while `status.files` reports it raw. Without `-z` the two sides are in
+ * different encodings and a collision on such a path silently misses. (A plain
+ * space does NOT trigger quoting; `my file.txt` is emitted as-is either way.)
+ */
+async function dirtyTreeRefusal(git, status, upstreamRef) {
+    const ahead = parseInt((await git.raw(['rev-list', '--count', `${upstreamRef}..HEAD`])).trim(), 10);
+    if (Number.isNaN(ahead))
+        return 'the upstream ref could not be compared with HEAD';
+    if (ahead > 0) {
+        return `the branch has ${ahead} local commit(s) to rebase, which needs a clean tree`;
+    }
+    const dirty = dirtyPathSet(status);
+    const incoming = (await git.raw(['diff', '--name-only', '-z', `HEAD..${upstreamRef}`]))
+        .split('\0')
+        .filter(Boolean);
+    const collisions = incoming.filter((p) => dirty.has(p));
+    if (collisions.length > 0) {
+        const shown = collisions.slice(0, 5).join(', ');
+        const more = collisions.length > 5 ? ` (+${collisions.length - 5} more)` : '';
+        return `incoming changes touch uncommitted paths: ${shown}${more}`;
+    }
+    return null;
+}
 /**
  * Rebase a repo onto its remote, optionally pushing local commits back up.
  *
  * The one-repo counterpart to `pullRepo` used by `agents sync <repo>`:
- *   1. Refuse if the working tree is dirty (commit or discard first).
- *   2. `git fetch origin` then `git pull --rebase origin <branch>` — rebase, not
- *      merge, so a local commit lands cleanly on top of upstream with no merge
- *      bubble.
- *   3. When `push` is set, `git push origin <branch>` to send local commits up.
+ *   1. `git fetch origin`.
+ *   2. Clean tree → `git pull --rebase origin <branch>`: rebase, not merge, so a
+ *      local commit lands cleanly on top of upstream with no merge bubble.
+ *   3. Dirty tree → fast-forward instead, but only when that is provably safe:
+ *      no local commits ahead of upstream, and no incoming path collides with a
+ *      dirty one. Otherwise refuse, naming the paths that collided.
+ *   4. When `push` is set, `git push origin <branch>` to send local commits up.
  *
  * The branch is read from the repo's current HEAD (falls back to `main`) rather
  * than hardcoded. System repos pass `push: false` — they are pull-only mirrors
  * of the npm-shipped upstream.
+ *
+ * Why step 3 exists: refusing on *any* dirt strands merged changes indefinitely.
+ * A DotAgents repo accumulates unrelated local state — a modified `agents.yaml`,
+ * a session's scratch file, a machine-local dotfile — and under the old rule one
+ * such file froze that box's layer forever, silently. Measured 2026-08-10: a
+ * merged fix could not reach three of three boxes, each blocked by files the
+ * incoming commits never touched. A `--ff-only` merge is the safe primitive
+ * here: it cannot rewrite local commits, and git itself aborts rather than
+ * overwrite a modified file, so the path check is belt-and-braces, not the only
+ * guard.
  */
 export async function syncRepoGit(dir, opts) {
     try {
@@ -1038,18 +1134,26 @@ export async function syncRepoGit(dir, opts) {
         }
         const git = simpleGit(dir);
         const status = await git.status();
-        if (!status.isClean()) {
-            return {
-                success: false,
-                commit: '',
-                pushed: false,
-                error: `Working tree has uncommitted changes. Commit or discard them first.\n\n  cd ${dir} && git status`,
-            };
-        }
         const branch = status.current || 'main';
         assertValidBranchName(branch);
         await git.fetch('origin');
-        await git.pull('origin', branch, { '--rebase': 'true' });
+        if (status.isClean()) {
+            await git.pull('origin', branch, { '--rebase': 'true' });
+        }
+        else {
+            // Dirty tree: a rebase would refuse outright, so fast-forward instead —
+            // but only when nothing local can be lost. One shared rule, see above.
+            const refusal = await dirtyTreeRefusal(git, status, `origin/${branch}`);
+            if (refusal) {
+                return {
+                    success: false,
+                    commit: '',
+                    pushed: false,
+                    error: `Working tree has uncommitted changes and ${refusal}. Commit or discard them first.\n\n  cd ${dir} && git status`,
+                };
+            }
+            await git.raw(['merge', '--ff-only', `origin/${branch}`]);
+        }
         installGithooksSymlinks(dir);
         let pushed = false;
         if (opts.push) {

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

@@ -13,6 +13,11 @@ import { type HostTask } from './tasks.js';
 import { type HostCredentials } from './credentials.js';
 import { deriveMirroredCwd, homeRemainder, remoteCdPrefix } from '../project-root.js';
 export { deriveMirroredCwd, homeRemainder, remoteCdPrefix };
+/**
+ * Diagnostic helper for RUSH-2441: log the requested agent and initial remote
+ * `agents run` argv without changing normal command output.
+ */
+export declare function logForwardedArgs(kind: string, agent: string, version: string | undefined, args: string[], hasPrompt: boolean): void;
 /**
  * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
  * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
@@ -73,10 +78,10 @@ export declare function terminateDispatchedTask(task: HostTask): void;
 export declare function buildStopRemoteCommand(pid: number, remoteExit: string): string;
 export declare function buildWindowsStopRemoteCommand(pid: number, remoteExit: string): string;
 /**
- * Stop a running host task from the origin machine (`agents hosts stop <id>`).
+ * Stop a running host task from the origin machine (`agents devices stop <id>`).
  *
  * Unlike {@link terminateDispatchedTask} (rollback cleanup after a failed
- * persist), this keeps the remote log so `agents hosts logs <id>` still works,
+ * persist), this keeps the remote log so `agents logs <id>` still works,
  * writes a terminal `.exit` marker only when we actually stopped a live group
  * (or no code existed), and never clobbers a real completed-run exit code.
  */
@@ -130,7 +135,7 @@ export interface DispatchOptions {
     sessionId?: string;
     /**
      * Durable `--name <slug>` handle, forwarded to the remote `agents run` and
-     * recorded on the local task so `agents hosts logs/ps <name>` resolve it.
+     * recorded on the local task so `agents logs <name>` / `agents devices ps` resolve it.
      */
     name?: string;
     /** Resume an existing session on the host by id (via `agents run --resume`). */

package/dist/lib/hosts/dispatch.js

@@ -26,6 +26,30 @@ import { RUN_AUTO_KEYWORD, RUN_AUTO_HOST_RESOLVED_ENV } from '../types.js';
 // shell builder (devices/connect.ts) as well as this dispatch layer. Re-exported
 // here so existing `hosts/dispatch.js` importers and tests keep resolving them.
 export { deriveMirroredCwd, homeRemainder, remoteCdPrefix };
+/**
+ * Diagnostic helper for RUSH-2441: log the requested agent and initial remote
+ * `agents run` argv without changing normal command output.
+ */
+export function logForwardedArgs(kind, agent, version, args, hasPrompt) {
+    if (!process.env.AGENTS_DISPATCH_DEBUG)
+        return;
+    const safeArgs = [...args];
+    if (safeArgs[0] === 'run' && safeArgs[2] && hasPrompt) {
+        safeArgs[2] = '<prompt>';
+    }
+    for (let i = 0; i < safeArgs.length; i++) {
+        if (safeArgs[i] === '--env' && safeArgs[i + 1]) {
+            const key = safeArgs[i + 1].split('=', 1)[0];
+            safeArgs[i + 1] = `${key}=<redacted>`;
+            i++;
+        }
+        else if (safeArgs[i] === '--') {
+            safeArgs.splice(i + 1, safeArgs.length - i - 1, '<passthrough redacted>');
+            break;
+        }
+    }
+    process.stderr.write(`[dispatch:${kind}] agent=${agent}${version ? `@${version}` : ''} args=${JSON.stringify(safeArgs)}\n`);
+}
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
@@ -189,10 +213,10 @@ export function buildWindowsStopRemoteCommand(pid, remoteExit) {
     return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
 }
 /**
- * Stop a running host task from the origin machine (`agents hosts stop <id>`).
+ * Stop a running host task from the origin machine (`agents devices stop <id>`).
  *
  * Unlike {@link terminateDispatchedTask} (rollback cleanup after a failed
- * persist), this keeps the remote log so `agents hosts logs <id>` still works,
+ * persist), this keeps the remote log so `agents logs <id>` still works,
  * writes a terminal `.exit` marker only when we actually stopped a live group
  * (or no code existed), and never clobbers a real completed-run exit code.
  */
@@ -313,7 +337,7 @@ async function launchDetached(host, target, opts) {
         remoteShell,
     });
     // -1 = the follow window closed while the run continues on the host. Leave the
-    // record 'running' (do NOT freeze it terminal) so a later `hosts ps`/`logs`
+    // record 'running' (do NOT freeze it terminal) so a later `agents devices ps` / `agents logs`
     // reconcile against the remote `.exit` resolves the true final status.
     const finished = exitCode === -1 ? task : (updateTask(id, terminalPatch(exitCode)) ?? task);
     return { task: finished, exitCode };
@@ -382,6 +406,7 @@ export function buildRunForwardedArgs(opts) {
         args.push('--emit-session-id');
     if (opts.passthroughArgs && opts.passthroughArgs.length > 0)
         args.push('--', ...opts.passthroughArgs);
+    logForwardedArgs('headless', opts.agent, opts.version, args, true);
     return args;
 }
 /**
@@ -438,6 +463,7 @@ export function buildInteractiveRunForwardedArgs(opts) {
     if (opts.passthroughArgs && opts.passthroughArgs.length > 0) {
         args.push('--', ...opts.passthroughArgs);
     }
+    logForwardedArgs('interactive', opts.agent, opts.version, args, Boolean(opts.prompt && opts.forceInteractive));
     return args;
 }
 /**

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

@@ -1,6 +1,6 @@
 /**
- * Shared host-task log viewer — the show-or-follow core behind both
- * `agents hosts logs <id>` and the top-level `agents logs <id>`.
+ * Shared host-task log viewer — the show-or-follow core behind the
+ * top-level `agents logs <id>`.
  *
  * A running task with follow re-enters the offset-tail (`followHostTask`).
  * Otherwise the view is **concise by default**: a bounded tail of the captured

package/dist/lib/hosts/logs.js

@@ -1,6 +1,6 @@
 /**
- * Shared host-task log viewer — the show-or-follow core behind both
- * `agents hosts logs <id>` and the top-level `agents logs <id>`.
+ * Shared host-task log viewer — the show-or-follow core behind the
+ * top-level `agents logs <id>`.
  *
  * A running task with follow re-enters the offset-tail (`followHostTask`).
  * Otherwise the view is **concise by default**: a bounded tail of the captured

package/dist/lib/hosts/option.js

@@ -12,7 +12,7 @@
 /** Attach the standard `--host` flag family to a command and return it (chainable). */
 export function addHostOption(cmd) {
     return cmd
-        .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, a registered host, user@host, or `all` to fan out across every registered device. See `agents devices` / `agents hosts`.')
+        .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, an ssh-config host, user@host, or `all` to fan out across every registered device. See `agents devices`.')
         .option('--device <name>', 'Alias of --host: run this command on a registered device (from `agents devices`), or `all` to run it across the whole fleet.')
         .option('--remote-cwd <dir>', "Working directory on the host for --host runs. Resolves on the REMOTE host — pass a '$HOME'-relative path (single-quoted so your local shell doesn't expand it) or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you). No effect on 'teams add'.")
         .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')

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

@@ -19,6 +19,8 @@
 import { type Host } from './types.js';
 import { type DeviceProfile, type DeviceRegistry } from '../devices/registry.js';
 import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
+/** Re-export for callers that historically imported flagValue from this module. */
+export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 /** Per-command remote behaviour. Absence from this map = not host-routable here. */
 interface RemoteSpec {
     /** Flags appended when running non-interactively (no local TTY / `--no-tty`). */
@@ -46,8 +48,6 @@ export declare const REMOTE_PASSTHROUGH: Record<string, RemoteSpec>;
  * these to {@link REMOTE_PASSTHROUGH}.
  */
 export declare const OWN_HOST_COMMANDS: Set<string>;
-/** 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;
 /** Injectable dependencies for {@link runFleetPassthrough} — used by tests. */
 export interface FleetPassthroughOptions {
     /** Override the device registry loader (tests). */
@@ -131,4 +131,3 @@ export declare function passthroughSshOptions(host: Host, interactive: boolean):
     multiplex: true;
     extraSshArgs: string[];
 };
-export {};

package/dist/lib/hosts/passthrough.js

@@ -23,13 +23,19 @@ import { sshTargetFor, hostIdentityArgs } from './types.js';
 import { dispatchAgentsCommand, withActorEnv } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, stripClixml, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
-import { machineId } from '../session/sync/config.js';
+// Leaf import: `session/sync/config.js` re-exports machineId from machine-id.js
+// but pulling the re-export path drags secrets/bundles (~140ms cold). Same value,
+// 6–7× cheaper graph (RUSH-2374 proposal 2).
+import { machineId } from '../machine-id.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
 import { platformGroupLabel } from '../devices/health-report.js';
 import { isKnownTopLevelCommand } from '../startup/command-registry.js';
+/** Re-export for callers that historically imported flagValue from this module. */
+export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 /**
  * First-class groups that run transparently on a remote via SSH when
  * `--host`/`--device` is present. Keep both canonical names and aliases
@@ -95,9 +101,7 @@ export const REMOTE_PASSTHROUGH = {
     worktree: {},
     events: {},
     audit: {},
-    lock: {},
     feedback: {},
-    wallet: {},
     pty: {},
     tmux: {},
     watchdog: {},
@@ -118,6 +122,7 @@ export const OWN_HOST_COMMANDS = new Set([
     'feed',
     'computer',
     'secrets',
+    'accounts', // `accounts sync --device` names the destination, not remote routing
     'logs',
     'hosts',
     'ssh',
@@ -135,21 +140,6 @@ const STRIP_SPECS = [
     { long: 'hosts', takesValue: true },
     { long: 'devices', takesValue: true },
 ];
-/** 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;
-}
 /** Synthesize a `Host` for a raw `user@host` / bare-alias target (not enrolled). */
 function syntheticHost(target) {
     const at = target.indexOf('@');
@@ -584,13 +574,9 @@ export async function maybeRunOnHost(command, allArgs, opts) {
  */
 export async function maybeRunStandaloneOnHost(command, opts) {
     const rawArgs = process.argv.slice(2);
-    const hasRoutingFlag = flagValue(rawArgs, 'host', 'H') !== undefined ||
-        flagValue(rawArgs, 'device') !== undefined ||
-        flagValue(rawArgs, 'hosts') !== undefined ||
-        flagValue(rawArgs, 'devices') !== undefined;
     // No routing flag → nothing to route or strip. Leave argv alone so a purely
     // local run keeps every flag it passed.
-    if (!hasRoutingFlag)
+    if (!hasHostRoutingFlag(rawArgs))
         return false;
     // Keep --help/--version local (docs must work without a reachable host), mirroring
     // index.ts's `helpOrVersionRequested` guard, but still strip the routing flags
@@ -626,7 +612,7 @@ export function streamAgentsOnHost(host, forwardedArgs, opts = {}) {
     const code = sshStream(target, remoteCmd, passthroughSshOptions(host, !!opts.interactive));
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +
-            chalk.gray(' Check: agents hosts check ' + host.name));
+            chalk.gray(' Check: agents devices status'));
     }
     return code;
 }

package/dist/lib/hosts/progress.js

@@ -243,7 +243,7 @@ export async function followHostTask(target, opts) {
     for (;;) {
         const remaining = deadline - Date.now();
         if (remaining <= 0) {
-            process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents hosts logs ' + opts.taskId + ' -f\n');
+            process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents logs ' + opts.taskId + ' -f\n');
             return -1;
         }
         const abort = new AbortController();
@@ -271,7 +271,7 @@ export async function followHostTask(target, opts) {
         // chunks were flushed as they arrived, so reconnect from the advanced offset.
         // If no bytes arrived, back off like the old idle poll.
         if (Date.now() > deadline) {
-            process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents hosts logs ' + opts.taskId + ' -f\n');
+            process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents logs ' + opts.taskId + ' -f\n');
             return -1;
         }
         // Reconnect quickly while output flows; ease toward maxMs when the stream

package/dist/lib/hosts/providers/devices.d.ts

@@ -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