@phnx-labs/agents-cli 1.22.52 → 1.22.54

package/dist/lib/browser/registry.js

@@ -2,34 +2,108 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import * as yaml from 'yaml';
-import { getUserAgentsDir, readMeta, updateMeta } from '../state.js';
+import { getUserAgentsDir, readMeta, updateMeta, withMetaLock, writeMetaUnlocked } from '../state.js';
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
-/** Leftover central `browser:` map from before per-device declarations. Empty when none remain. */
+/**
+ * The leftover central `browser:` tombstone from before per-device declarations.
+ * Empty when none remain — and `agents sync` now drains it automatically via
+ * {@link autoEvictCentralBrowserProfiles}, so on a synced box this is empty and
+ * {@link profileRegistry} is the single source of truth. It survives only to
+ * fold in migration and to explain an as-yet-unclaimed profile in a resolve
+ * error (a profile hostable on a peer that has not synced yet), never as a
+ * parallel store callers read for resolution.
+ */
 export function centralBrowserProfiles() {
     const central = readMeta().browser;
     if (!central || Object.keys(central).length === 0)
         return {};
     return { ...central };
 }
+/**
+ * Pick the central `browser:` entries this machine may fold into its device doc.
+ *
+ * A profile is claimable only when `canHostHere` accepts it — the endpoint or
+ * binary resolves to THIS machine — so a `cdp://localhost:*` profile owned by a
+ * peer is never claimed here (the logged-out-headless-browser bug this module
+ * exists to prevent). A name already declared locally with an IDENTICAL config
+ * is folded too, which just drops the redundant central copy. A name declared
+ * locally with a DIFFERENT config is a genuine conflict: `onConflict: 'throw'`
+ * (the explicit `claim` command) surfaces it; `onConflict: 'skip'` (automatic
+ * eviction on sync) leaves it central so a stray duplicate can never wedge a
+ * sync — an operator resolves it with an explicit claim.
+ */
+function selectClaimableCentral(central, local, canHostHere, opts) {
+    const toClaim = {};
+    const skipped = [];
+    for (const [profileName, config] of Object.entries(central)) {
+        if (opts.name && profileName !== opts.name)
+            continue;
+        if (!canHostHere(config)) {
+            skipped.push(profileName);
+            continue;
+        }
+        const existing = local[profileName];
+        if (existing && !isDeepStrictEqual(existing, config)) {
+            if (opts.onConflict === 'throw') {
+                throw new Error(`Cannot migrate browser profile "${profileName}": central agents.yaml and this device's ` +
+                    `agents.yaml declare different configurations. Resolve the duplicate before retrying.`);
+            }
+            skipped.push(profileName);
+            continue;
+        }
+        toClaim[profileName] = config;
+    }
+    return { toClaim, skipped };
+}
+/**
+ * Return `current` with `toClaim` moved out of the central `browser:` map and
+ * into this device's `deviceBrowser` doc. The central key is dropped entirely
+ * once drained, so the tombstone disappears rather than lingering as an empty
+ * map. Pure — the caller applies it under the meta lock.
+ */
+function buildEvictedMeta(current, toClaim) {
+    const legacy = current;
+    const remaining = {};
+    for (const [profileName, config] of Object.entries(legacy.browser ?? {})) {
+        if (!(profileName in toClaim))
+            remaining[profileName] = config;
+    }
+    const { browser: _removed, ...withoutCentralBrowser } = legacy;
+    return {
+        ...withoutCentralBrowser,
+        ...(Object.keys(remaining).length > 0 ? { browser: remaining } : {}),
+        deviceBrowser: { ...current.deviceBrowser, ...toClaim },
+    };
+}
+/**
+ * Commit a claim computed by the EXPLICIT path (`migrateCentralBrowserProfiles`).
+ * `toClaim` was selected from an unlocked snapshot — acceptable for that manual,
+ * deliberate command; the automatic path instead selects INSIDE the lock (see
+ * {@link autoEvictCentralBrowserProfiles}) so an unrelated concurrent write can
+ * never be clobbered by a stale selection.
+ */
+function commitCentralClaim(toClaim) {
+    updateMeta((current) => buildEvictedMeta(current, toClaim));
+}
 /**
  * Fold leftover central `browser:` entries into THIS device's declaration file.
  *
- * Never called implicitly, and that is the point. Every device can read the
- * central map, so an implicit claim races: whichever box happens to read first
- * claims the name, {@link profileKind} then reports it `identity`, and the
- * daemon tunnels to that box — which for a fleet-wide `cdp://localhost:*`
- * profile is a logged-out headless browser wearing a credentialed browser's
- * name. That is the exact bug this module exists to remove, and an implicit
- * migration would write it to disk as a stored fact.
+ * The EXPLICIT operator action (`agents browser profiles claim`), run on the
+ * machine that actually owns the browser. It is never called implicitly from a
+ * read, and that is the point: every device can read the central map, so an
+ * implicit claim races — whichever box reads first claims the name, {@link
+ * profileKind} then reports it `identity`, and the daemon tunnels to that box,
+ * which for a fleet-wide `cdp://localhost:*` profile is a logged-out headless
+ * browser wearing a credentialed browser's name. {@link autoEvictCentralBrowserProfiles}
+ * closes that race for the automatic path (host-gated + non-throwing on sync);
+ * this one is the manual, throw-on-conflict counterpart.
  *
- * The claim is an explicit operator action (`agents browser profiles claim`),
- * run on the machine that actually owns the browser. `canHostHere` is supplied
- * by the command layer so this module stays a leaf — it must not import
- * `isProfileLaunchableHere` (that would cycle through chrome.ts → profiles.ts).
- * Only profiles this machine can host are claimed; the rest stay central,
- * undeclared, and fail loudly on resolve.
+ * `canHostHere` is supplied by the command layer so this module stays a leaf —
+ * it must not import `isProfileLaunchableHere` (that would cycle through
+ * chrome.ts → profiles.ts). Only profiles this machine can host are claimed; the
+ * rest stay central, undeclared, and fail loudly on resolve.
  */
 export function migrateCentralBrowserProfiles(canHostHere, name) {
     const meta = readMeta();
@@ -53,42 +127,64 @@ export function migrateCentralBrowserProfiles(canHostHere, name) {
                 `(its browser/binary isn't installed here). Run this command on the machine that has that browser.`);
         }
     }
-    const toClaim = {};
-    const skipped = [];
-    for (const [profileName, config] of Object.entries(central)) {
-        if (name && profileName !== name)
-            continue;
-        if (!canHostHere(config)) {
-            skipped.push(profileName);
-            continue;
-        }
-        const existing = local[profileName];
-        if (existing && !isDeepStrictEqual(existing, config)) {
-            throw new Error(`Cannot migrate browser profile "${profileName}": central agents.yaml and this device's ` +
-                `agents.yaml declare different configurations. Resolve the duplicate before retrying.`);
-        }
-        toClaim[profileName] = config;
-    }
+    const { toClaim, skipped } = selectClaimableCentral(central, local, canHostHere, {
+        name,
+        onConflict: 'throw',
+    });
     const claimed = Object.keys(toClaim).sort();
     skipped.sort();
     if (claimed.length === 0)
         return { claimed, skipped };
-    updateMeta((current) => {
-        const legacy = current;
-        const remaining = {};
-        for (const [profileName, config] of Object.entries(legacy.browser ?? {})) {
-            if (!(profileName in toClaim))
-                remaining[profileName] = config;
-        }
-        const { browser: _removed, ...withoutCentralBrowser } = legacy;
-        return {
-            ...withoutCentralBrowser,
-            ...(Object.keys(remaining).length > 0 ? { browser: remaining } : {}),
-            deviceBrowser: { ...current.deviceBrowser, ...toClaim },
-        };
-    });
+    commitCentralClaim(toClaim);
     return { claimed, skipped };
 }
+/**
+ * Automatic, self-draining counterpart to {@link migrateCentralBrowserProfiles}:
+ * fold every lingering central `browser:` profile THIS machine can host into its
+ * device doc and clear it from central, so the tombstone drains itself on
+ * `agents sync` with no manual `agents browser profiles claim`.
+ *
+ * Safe to call implicitly, unlike a claim at registry-read time (which races —
+ * see the `profileRegistry does not claim central declarations` guard), but the
+ * CALLER owns one ordering invariant: invoke it AFTER the sync's repo pull. Two
+ * boxes can both host the same profile (`canHostHere` is launchability, not
+ * ownership), so a box acting on a PRE-pull view of central could re-claim a
+ * profile a peer already drained and pushed — both writes land in different
+ * device files with no git conflict, and the profile flips identity->fungible.
+ * Running post-pull means central already reflects peers' drains, so the tombstone
+ * is gone locally before this box looks. The selection is also computed INSIDE
+ * the meta lock, and the path never throws — an unhostable profile or one that
+ * conflicts with an existing local declaration is left central for an explicit
+ * claim rather than wedging the sync. After it runs, {@link profileRegistry} is
+ * the single source of truth: a claimed profile lives in the device doc alone,
+ * never double-counted across the two stores.
+ */
+export function autoEvictCentralBrowserProfiles(canHostHere) {
+    // Read fresh, select, and commit inside ONE meta-lock acquisition. Reading
+    // central before the lock and committing after (the manual path's shape) leaves
+    // a window where a concurrent write on THIS machine changes central/deviceBrowser
+    // between snapshot and commit, so the stale selection would be merged over the
+    // fresher value. Selecting from the state the lock just handed us closes that
+    // window. We write ONLY when something is claimed, so a no-op sync never touches
+    // any doc (writeMetaUnlocked would otherwise re-serialize the device doc every
+    // run). This mirrors updateMeta's own body, minus the unconditional write.
+    return withMetaLock(() => {
+        const meta = readMeta();
+        const central = meta.browser;
+        if (!central || Object.keys(central).length === 0)
+            return { claimed: [], skipped: [] };
+        const local = meta.deviceBrowser ?? {};
+        const { toClaim, skipped } = selectClaimableCentral(central, local, canHostHere, {
+            onConflict: 'skip',
+        });
+        const claimed = Object.keys(toClaim).sort();
+        skipped.sort();
+        if (claimed.length === 0)
+            return { claimed, skipped };
+        writeMetaUnlocked(buildEvictedMeta(meta, toClaim));
+        return { claimed, skipped };
+    });
+}
 /**
  * Every profile any device declares, keyed by name to all declaring devices.
  * Reads every `devices/<name>/agents.yaml`; declarations never overwrite.

package/dist/lib/browser/remote-control.d.ts

@@ -2,11 +2,13 @@
  * Consent gate for driving THIS machine's browser from another fleet machine.
  *
  * `browser --device <device>` routes a browser command to `<device>` over SSH (the
- * fleet passthrough) and runs `agents browser ...` there. Every such remote
- * invocation carries the {@link FLEET_REMOTE_ENV} marker, set once at the fleet
- * dispatch site (`maybeRunOnHost`). A machine only accepts being driven when its
- * owner has opted in via `agents browser remote-control on` (the device-scope
- * `browser.remote-control` config key, never synced).
+ * fleet passthrough) and runs `agents browser ...` there. `agents ssh <device>
+ * agents browser …` is the same remote drive through the ssh wrapper. Every such
+ * remote invocation carries the {@link FLEET_REMOTE_ENV} marker, set at the fleet
+ * dispatch site (`maybeRunOnHost` / `streamAgentsOnHost`) and on the ssh wrapper
+ * (`buildSshInvocation` via `markFleetRemote`). A machine only accepts being driven
+ * when its owner has opted in via `agents browser remote-control on` (the
+ * device-scope `browser.remote-control` config key, never synced).
  *
  * Local invocations (no marker) are never gated — this only governs cross-machine
  * drives. Read-only queries are not gated.
@@ -21,9 +23,9 @@
  * the attach paths ungated (RUSH-3064). {@link assertRemoteControlAllowed} remains
  * as a fast-fail CLI-side check so a refused `start` never auto-creates a profile.
  */
-/** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
+/** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation` and `markFleetRemote`. */
 export declare const FLEET_REMOTE_ENV = "AGENTS_FLEET_REMOTE";
-/** True when this process was dispatched to this machine by a fleet `--device` run. */
+/** True when this process was dispatched to this machine by a fleet `--device` or `agents ssh … agents browser` run. */
 export declare function isFleetRemoteInvocation(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Whether this machine allows other fleet machines to drive its browser. Reads

package/dist/lib/browser/remote-control.js

@@ -2,11 +2,13 @@
  * Consent gate for driving THIS machine's browser from another fleet machine.
  *
  * `browser --device <device>` routes a browser command to `<device>` over SSH (the
- * fleet passthrough) and runs `agents browser ...` there. Every such remote
- * invocation carries the {@link FLEET_REMOTE_ENV} marker, set once at the fleet
- * dispatch site (`maybeRunOnHost`). A machine only accepts being driven when its
- * owner has opted in via `agents browser remote-control on` (the device-scope
- * `browser.remote-control` config key, never synced).
+ * fleet passthrough) and runs `agents browser ...` there. `agents ssh <device>
+ * agents browser …` is the same remote drive through the ssh wrapper. Every such
+ * remote invocation carries the {@link FLEET_REMOTE_ENV} marker, set at the fleet
+ * dispatch site (`maybeRunOnHost` / `streamAgentsOnHost`) and on the ssh wrapper
+ * (`buildSshInvocation` via `markFleetRemote`). A machine only accepts being driven
+ * when its owner has opted in via `agents browser remote-control on` (the
+ * device-scope `browser.remote-control` config key, never synced).
  *
  * Local invocations (no marker) are never gated — this only governs cross-machine
  * drives. Read-only queries are not gated.
@@ -22,9 +24,9 @@
  * as a fast-fail CLI-side check so a refused `start` never auto-creates a profile.
  */
 import { getConfigValue } from '../device-config.js';
-/** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation`. */
+/** Env marker set on every remote `agents` invocation by `buildRemoteAgentsInvocation` and `markFleetRemote`. */
 export const FLEET_REMOTE_ENV = 'AGENTS_FLEET_REMOTE';
-/** True when this process was dispatched to this machine by a fleet `--device` run. */
+/** True when this process was dispatched to this machine by a fleet `--device` or `agents ssh … agents browser` run. */
 export function isFleetRemoteInvocation(env = process.env) {
     return env[FLEET_REMOTE_ENV] === '1';
 }

package/dist/lib/claude-account-token.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Reserved FILE-BASED secrets bundle holding long-lived, non-rotating Claude
+ * setup-tokens. Usage/probe reads authenticate with these instead of Claude
+ * Code's ACL-bound login item, so they never pop Touch ID. Keyed strictly
+ * per-account (`CLAUDE_CODE_OAUTH_TOKEN_<slug>` from the account email) — never a
+ * bare key, so one account's token can't be misapplied to another in a
+ * multi-account fleet.
+ */
+/** Alias of the secrets-layer reserved name so mint/seed shares one source of truth. */
+export declare const AUTH_BUNDLE = "auth";
 /** True only for a clean, single-line `sk-ant-oat01-…` token — see {@link SETUP_TOKEN_RE}. */
 export declare function isValidClaudeSetupToken(value: string): boolean;
 /** The per-account key an email maps to inside the `auth` bundle. */

package/dist/lib/claude-account-token.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { bundleBackend, bundleExists, readAndResolveBundleEnv } from './secrets/bundles.js';
+import { AUTH_BUNDLE_NAME, ReservedBundleWrongBackendError, bundleBackend, bundleExists, readAndResolveBundleEnv, } from './secrets/bundles.js';
 import { fileStoreItemPath } from './secrets/filestore.js';
 import { secretsKeychainItem } from './secrets/index.js';
 /**
@@ -12,7 +12,8 @@ import { secretsKeychainItem } from './secrets/index.js';
  * bare key, so one account's token can't be misapplied to another in a
  * multi-account fleet.
  */
-const AUTH_BUNDLE = 'auth';
+/** Alias of the secrets-layer reserved name so mint/seed shares one source of truth. */
+export const AUTH_BUNDLE = AUTH_BUNDLE_NAME;
 /**
  * A well-formed Claude OAuth setup-token: the `sk-ant-oat01-` prefix followed by
  * token-safe characters only, on a single line. `claude setup-token` mints exactly
@@ -82,8 +83,15 @@ export function resolveClaudeSetupToken(home) {
         const email = readClaudeAccountEmail(home);
         if (!email)
             return null;
-        if (!bundleExists(AUTH_BUNDLE) || bundleBackend(AUTH_BUNDLE) !== 'file')
+        if (!bundleExists(AUTH_BUNDLE))
             return null;
+        const backend = bundleBackend(AUTH_BUNDLE);
+        if (backend !== 'file') {
+            // SEC-GAP-3: a keychain/vault-backed `auth` used to return null here, so
+            // usage/probe fell through to the interactive login (Touch ID) with no
+            // hint that the seeded setup-token was being ignored.
+            throw new ReservedBundleWrongBackendError(AUTH_BUNDLE, backend);
+        }
         const cacheKey = home ?? os.homedir();
         const item = secretsKeychainItem(AUTH_BUNDLE, claudeAccountTokenKey(email));
         const credentialPath = fileStoreItemPath(item);
@@ -110,7 +118,9 @@ export function resolveClaudeSetupToken(home) {
         // than return a token whose current file fingerprint was never observed.
         return null;
     }
-    catch {
+    catch (err) {
+        if (err instanceof ReservedBundleWrongBackendError)
+            throw err;
         return null;
     }
 }

package/dist/lib/config-drift.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Config drift: has THIS box drained its device-scoped state into its own
+ * `devices/<host>/agents.yaml`, or is it still carrying per-box state in the
+ * shared top-level `agents.yaml`?
+ *
+ * PHNX-3315 P1 heals a frozen top-level header and drains the central `browser:`
+ * tombstone; P2 folds `fleet.discovery` / `fleet.ignored`, the `hosts:` registry,
+ * and device-scoped native `accounts:` out of central and into the device doc.
+ * Each fold-and-delete migration is idempotent and runs on config access / daemon
+ * boot / install — so a converged box shows NO drift. A box that has NOT run the
+ * fold yet (stale checkout, never re-synced) still holds those blocks centrally,
+ * and until now that was INVISIBLE: `agents sync status` only reported per-agent
+ * "N missing", so an un-drained box was discovered the hard way — as a mystery
+ * `agents repo pull` conflict when two boxes rewrote the same shared map.
+ *
+ * This detector is READ-ONLY and must NOT trigger the migration (that would drain
+ * the very leak it is trying to surface): it reads the raw top-level user file
+ * directly, never `readMeta()` (system-merged) and never the migration hook.
+ */
+export interface ConfigDrift {
+    /** Top-level `agents.yaml` header != the current META_HEADER (the P1 case). */
+    staleHeader: boolean;
+    /**
+     * Labels of central blocks that should have folded into this box's device doc
+     * but still linger — the P1 `browser` tombstone and the P2 `fleet` / `hosts` /
+     * `accounts` device-scoped writers. Empty on a drained box.
+     */
+    centralLeaks: string[];
+}
+/**
+ * Inspect this box's on-disk state for config drift. Pure read — no migration, no
+ * writes. Mirrors the gather step of {@link migrateDeviceConfigStores} (plus the
+ * browser tombstone) so a leak here is exactly what a fold would drain.
+ */
+export declare function detectConfigDrift(): ConfigDrift;
+/** True when either drift class is present. */
+export declare function hasConfigDrift(d: ConfigDrift): boolean;

package/dist/lib/config-drift.js

@@ -0,0 +1,72 @@
+/**
+ * Config drift: has THIS box drained its device-scoped state into its own
+ * `devices/<host>/agents.yaml`, or is it still carrying per-box state in the
+ * shared top-level `agents.yaml`?
+ *
+ * PHNX-3315 P1 heals a frozen top-level header and drains the central `browser:`
+ * tombstone; P2 folds `fleet.discovery` / `fleet.ignored`, the `hosts:` registry,
+ * and device-scoped native `accounts:` out of central and into the device doc.
+ * Each fold-and-delete migration is idempotent and runs on config access / daemon
+ * boot / install — so a converged box shows NO drift. A box that has NOT run the
+ * fold yet (stale checkout, never re-synced) still holds those blocks centrally,
+ * and until now that was INVISIBLE: `agents sync status` only reported per-agent
+ * "N missing", so an un-drained box was discovered the hard way — as a mystery
+ * `agents repo pull` conflict when two boxes rewrote the same shared map.
+ *
+ * This detector is READ-ONLY and must NOT trigger the migration (that would drain
+ * the very leak it is trying to surface): it reads the raw top-level user file
+ * directly, never `readMeta()` (system-merged) and never the migration hook.
+ */
+import { hasStaleMetaHeader, readTopLevelUserMeta } from './state.js';
+function isMap(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/**
+ * Inspect this box's on-disk state for config drift. Pure read — no migration, no
+ * writes. Mirrors the gather step of {@link migrateDeviceConfigStores} (plus the
+ * browser tombstone) so a leak here is exactly what a fold would drain.
+ */
+export function detectConfigDrift() {
+    const staleHeader = hasStaleMetaHeader();
+    const raw = readTopLevelUserMeta();
+    const centralLeaks = [];
+    if (raw) {
+        // P1: the leftover central `browser:` tombstone (should fold into deviceBrowser).
+        if (isMap(raw.browser) && Object.keys(raw.browser).length > 0) {
+            centralLeaks.push('browser');
+        }
+        // P2: fleet.discovery / fleet.ignored, and the short-lived per-device config
+        // store under fleet.devices.<name>.config — all fold into the device doc.
+        const fleet = isMap(raw.fleet) ? raw.fleet : undefined;
+        if (fleet) {
+            if (isMap(fleet.discovery) && Object.keys(fleet.discovery).length > 0) {
+                centralLeaks.push('fleet.discovery');
+            }
+            if (Array.isArray(fleet.ignored) && fleet.ignored.length > 0) {
+                centralLeaks.push('fleet.ignored');
+            }
+            if (isMap(fleet.devices)) {
+                const anyDeviceConfig = Object.values(fleet.devices).some((ov) => isMap(ov) && isMap(ov.config) && Object.keys(ov.config).length > 0);
+                if (anyDeviceConfig)
+                    centralLeaks.push('fleet.devices.*.config');
+            }
+        }
+        // P2: the central `hosts:` registry (should fold into deviceHosts).
+        if (isMap(raw.hosts) && Object.keys(raw.hosts).length > 0) {
+            centralLeaks.push('hosts');
+        }
+        // P2: central native accounts marked scope:'device' — identity PII that
+        // belongs in the device doc, off the git-tracked shared file. Fleet-shared /
+        // version-scoped identities stay central and are NOT a leak.
+        const accounts = isMap(raw.accounts) ? raw.accounts : undefined;
+        const native = accounts && isMap(accounts.native) ? accounts.native : undefined;
+        if (native && Object.values(native).some((a) => isMap(a) && a.scope === 'device')) {
+            centralLeaks.push('accounts (device-scoped)');
+        }
+    }
+    return { staleHeader, centralLeaks };
+}
+/** True when either drift class is present. */
+export function hasConfigDrift(d) {
+    return d.staleHeader || d.centralLeaks.length > 0;
+}

package/dist/lib/daemon/auth-sync-service.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reserved `auth` bundle fleet sync as a `PeriodicService` (PHNX-2371).
+ *
+ * Each daemon that has a local file-backed `auth` bundle pushes it to pinned
+ * fleet devices that do not yet have it. The destination auto-provisions its
+ * own machine-local key; no passphrase is forwarded. Single-executor per
+ * destination: this process only writes the remote's own store.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class AuthSyncService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    readonly startupDelayMs = 60000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/auth-sync-service.js

@@ -0,0 +1,34 @@
+/**
+ * Reserved `auth` bundle fleet sync as a `PeriodicService` (PHNX-2371).
+ *
+ * Each daemon that has a local file-backed `auth` bundle pushes it to pinned
+ * fleet devices that do not yet have it. The destination auto-provisions its
+ * own machine-local key; no passphrase is forwarded. Single-executor per
+ * destination: this process only writes the remote's own store.
+ */
+import { BasePeriodicService } from './service.js';
+const AUTH_SYNC_TICK_MS = 15 * 60_000;
+const AUTH_SYNC_DEADLINE_MS = 2 * 60_000;
+const AUTH_SYNC_KICKOFF_MS = 60_000;
+export class AuthSyncService extends BasePeriodicService {
+    id = 'auth-sync';
+    intervalMs = AUTH_SYNC_TICK_MS;
+    deadlineMs = AUTH_SYNC_DEADLINE_MS;
+    startupDelayMs = AUTH_SYNC_KICKOFF_MS;
+    async onStart(_ctx) {
+        // No connections to open — each tick re-reads the local bundle + registry.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup.
+    }
+    async onTick(ctx) {
+        const { syncReservedAuthBundle } = await import('../secrets/reserved-sync.js');
+        const result = syncReservedAuthBundle();
+        if (result.pushed.length > 0) {
+            ctx.log('INFO', `auth-sync: pushed auth to ${result.pushed.join(', ')}`);
+        }
+        for (const err of result.errors) {
+            ctx.log('WARN', `auth-sync: ${err.device}: ${err.message}`);
+        }
+    }
+}

package/dist/lib/daemon/daemon.js

@@ -28,6 +28,7 @@ import { startHostedWebhookReceivers } from '../daemon-webhooks.js';
 import { secretsBrokerSocketPath, brokerPidAlive } from '../secrets/agent.js';
 import { redactSecrets } from '../redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from '../cli-entry.js';
+import { localBinDir } from '../platform/posixpath.js';
 import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled, resolveBrowserTaskIdleMs } from '../device-config.js';
 import { reapTerminalRoutineProcesses } from '../routine-process-cleanup.js';
 import { recordSubsystemOk, recordSubsystemError, recordSubsystemErrorReason, readSubsystemHealth, SUBSYSTEM_DAEMON_START } from '../daemon-health.js';
@@ -43,6 +44,7 @@ import { WatchdogService } from './watchdog-service.js';
 import { DeviceProbeService } from './device-probe-service.js';
 import { SelfHealService } from './self-heal-service.js';
 import { KeychainReapService } from './keychain-reap-service.js';
+import { AuthSyncService } from './auth-sync-service.js';
 import { StateDirCheckService } from './state-dir-check-service.js';
 import { emit, emitRoutineEnd } from '../feed/events.js';
 import { readDaemonServicesConfig, drainDaemonServiceRestartQueue } from '../daemon-services.js';
@@ -934,6 +936,10 @@ export async function runDaemon() {
         supervisor.register(new KeychainReapService());
     else
         log('INFO', 'Keychain-reap service disabled');
+    if (isEnabled('auth-sync'))
+        supervisor.register(new AuthSyncService());
+    else
+        log('INFO', 'Auth-sync service disabled');
     await supervisor.startAll({ log });
     activeServiceSupervisor = supervisor;
     // scheduler.enabled=false in this machine's device doc means NO routines fire
@@ -1800,10 +1806,23 @@ export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
 function daemonNodeBinDir() {
     return path.dirname(process.execPath);
 }
+/**
+ * Login-shell user-bin dirs a service-manager-started daemon would otherwise
+ * miss. systemd/launchd pin PATH and never source `~/.profile`, so they never
+ * see `~/.rush/bin` (where `rush` lands) or `~/.local/bin` (XDG user-bin).
+ * Monitor `notify` and dispatched `agents run` children inherit this PATH;
+ * without these dirs the rush-backed owner channel fails with
+ * `rush CLI not found on PATH` (PHNX-3075) while an interactive shell on the
+ * same box succeeds. Uses the same HOME the manifest bakes (RUSH-2639).
+ */
+function daemonUserBinDirs() {
+    const home = serviceManifestHomeEnv().HOME;
+    return [path.join(home, '.rush', 'bin'), localBinDir(home)];
+}
 /**
  * The full PATH value the daemon service manifest pins, in order: the directory
- * of the `agents` shim itself FIRST, then the Node runtime dir, then the
- * platform's system dirs.
+ * of the `agents` shim itself FIRST, then the Node runtime dir, then login-shell
+ * user-bin dirs (`~/.rush/bin`, `~/.local/bin`), then the platform's system dirs.
  *
  * The shim's own dir must lead so a scheduled `command` routine that shells out
  * to the bare name `agents` (`/bin/sh -c 'agents repo pull system'`) resolves the
@@ -1814,12 +1833,19 @@ function daemonNodeBinDir() {
  *
  * The Node runtime dir stays second so the shim's shebang (`#!/usr/bin/env node`)
  * still resolves the exact Node that installed the service — never an ancient
- * system node or a pruned nvm version. Deduped across the whole list, so a
+ * system node or a pruned nvm version. User-bin dirs sit after that pair so a
+ * `~/.local/bin/agents` cannot shadow the daemon binary, but `rush` (and other
+ * login-shell CLIs) still resolve. Deduped across the whole list, so a
  * Node/shim dir that already appears among the system dirs (e.g. a
  * `/usr/local/bin` install) never doubles.
  */
 function daemonPathValue(agentsBin, systemDirs) {
-    return [...new Set([path.dirname(agentsBin), daemonNodeBinDir(), ...systemDirs])].join(':');
+    return [...new Set([
+            path.dirname(agentsBin),
+            daemonNodeBinDir(),
+            ...daemonUserBinDirs(),
+            ...systemDirs,
+        ])].join(':');
 }
 /**
  * Build the argv to relaunch the `agents` CLI with the given subcommand args.

package/dist/lib/daemon/runner.js

@@ -1313,10 +1313,17 @@ async function executeJobPlaced(config, deps, attempt) {
     // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
     // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
     // (command jobs branched out earlier, so config.agent is set on the non-workflow path.)
+    // Custom harness/profile name (e.g. `deepseek`) stays on harnessName; the
+    // HOST CLI is effectiveAgent. The loop path spawns in-process via runLoop
+    // and never re-enters `agents run`, so it must stamp harnessName itself
+    // (PHNX-2935) — same field commands/exec.ts sets on ExecOptions.
+    const harnessName = !config.workflow && config.agent && isCustomHarnessName(config.agent)
+        ? config.agent
+        : undefined;
     const effectiveAgent = config.workflow
         ? 'claude'
-        : isCustomHarnessName(config.agent)
-            ? readProfile(config.agent).host.agent
+        : harnessName
+            ? readProfile(harnessName).host.agent
             : config.agent;
     if (!dispatchesViaAgentsRun(config)) {
         const { findUnifiedAccount, resolveAccountSelection, resolveCredentialAccount } = await import('../account-registry.js');
@@ -1377,6 +1384,7 @@ async function executeJobPlaced(config, deps, attempt) {
         const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone, overlayHome);
         const execOptions = {
             agent: effectiveAgent,
+            harnessName,
             // Routine-supported self-updating CLIs (Cursor/Droid) use one global
             // binary; a versioned shim would point at a nonexistent isolated install.
             version: isSelfUpdatingAgent(effectiveAgent) ? undefined : primaryVersion,

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -72,6 +72,11 @@ export const DAEMON_SERVICES = [
         title: 'Session-index warm',
         description: 'Keeps this host\'s transcript index current so a locally-started session is discoverable within seconds.',
     },
+    {
+        id: 'auth-sync',
+        title: 'Auth bundle sync',
+        description: 'Pushes the reserved file-backed auth bundle (setup-tokens) to pinned fleet devices that do not yet have it.',
+    },
 ];
 /** Stable order of service IDs. */
 export const DAEMON_SERVICE_IDS = DAEMON_SERVICES.map((s) => s.id);