@phnx-labs/agents-cli 1.22.56 → 1.22.58

package/dist/lib/daemon/runner.js

@@ -21,7 +21,7 @@ import { getCliLaunch, getAgentsBinDir } from '../cli-entry.js';
 import { resolveJobPrompt, parseTimeout, writeRunMeta, listRuns, getJobRunsDir, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, resolveJobExecutionContext, slotRunId, claimRunSlot, readRunMeta, resolveHostStrategy, } from '../scheduling/routines.js';
 import { getRunsDir, getUserAgentsDir, readMeta, getDaemonDir } from '../state.js';
 import { shortCodexHome } from '../codex-home.js';
-import { prepareJobHome, buildSpawnEnv, getJobHomePath, assertSandboxForwardsHostGhAuth } from '../sandbox.js';
+import { prepareJobHome, buildSpawnEnv, getJobHomePath, assertSandboxForwardsHostGhAuth, linkVersionAuth } from '../sandbox.js';
 import { resolveModel, buildReasoningFlags } from '../models.js';
 import { createTimer, redactPrompt, emitRoutineEnd } from '../feed/events.js';
 import { resolveHarnessAdapter } from '../harness/index.js';
@@ -37,9 +37,7 @@ import { walkForFiles } from '../fs-walk.js';
 import { getBinaryPath, isVersionInstalled, resolveVersion, getVersionHomePath } from '../installations/versions.js';
 import { resolveClaudeSetupToken } from '../claude-account-token.js';
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, formatNoHealthyAccountError, } from '../accounting/rotate.js';
-import { readAuthHealth, isDeadVerdict } from '../auth-health.js';
-import { machineId } from '../machine-id.js';
-import { selfConfiguredDeviceRole } from '../device-config.js';
+import { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../device-config.js';
 import { isSelfUpdatingAgent, ROUTINE_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
 import { isCustomHarnessName, readProfile } from '../profiles.js';
 export class RoutineAlreadyRunningError extends Error {
@@ -860,6 +858,27 @@ function readCommandExitCode(runDir) {
         return null;
     }
 }
+/** Claude's own local auth check; unlike account metadata it cannot mistake identity for a usable login. */
+export function claudeVersionIsAuthenticated(version) {
+    if (!isVersionInstalled('claude', version))
+        return true; // synthetic/unit plans are validated at spawn
+    const binary = getBinaryPath('claude', version);
+    if (!binary)
+        return false;
+    const home = getVersionHomePath('claude', version);
+    try {
+        const raw = execFileSync(binary, ['auth', 'status', '--json'], {
+            encoding: 'utf8',
+            timeout: 5_000,
+            env: { ...process.env, HOME: process.env.AGENTS_REAL_HOME || os.homedir(), CLAUDE_CONFIG_DIR: path.join(home, '.claude') },
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return JSON.parse(raw).loggedIn === true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Resolve the version/account chain for a routine the same way `agents run`
  * does: honor an explicit `version:` pin; otherwise use the configured run
@@ -890,7 +909,7 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
         : false;
     const selectedCredential = config.account
         ? (explicitCredential ? config.account : undefined)
-        : resolveAccountSelection(undefined, agent, meta);
+        : resolveAccountSelection(undefined, agent, meta)?.id;
     if (selectedCredential) {
         // A default/binding may resolve to a native account — never route that
         // through the provider credential path (it has no bundle to resolve).
@@ -980,6 +999,24 @@ export async function resolveRoutineLaunch(config, cwd = process.cwd(), deps = {
     if (!version) {
         version = resolveVersion(agent, cwd) ?? undefined;
     }
+    if (agent === 'claude' && version) {
+        const checkClaudeAuth = deps.claudeVersionIsAuthenticated ?? claudeVersionIsAuthenticated;
+        const authenticatedHealthy = rotation?.healthy.filter((candidate) => checkClaudeAuth(candidate.version));
+        const authenticated = authenticatedHealthy?.find((candidate) => candidate.version === version) ?? authenticatedHealthy?.[0];
+        if (rotation && (!authenticated || authenticatedHealthy.length === 0)) {
+            throw new Error(`Routine '${config.name}' found no authenticated Claude account; run \`claude /login\` for an installed version or pin a provider profile.`);
+        }
+        if (!rotation && !checkClaudeAuth(version)) {
+            throw new Error(`Routine '${config.name}' found no authenticated Claude account at claude@${version}; run \`claude /login\` for that version or remove the pin.`);
+        }
+        if (rotation && authenticated) {
+            const rejected = rotation.healthy.filter((candidate) => !authenticatedHealthy.includes(candidate));
+            if (rejected.length > 0 || rotation.picked !== authenticated) {
+                rotation = { ...rotation, picked: authenticated, healthy: authenticatedHealthy, excluded: [...rotation.excluded, ...rejected] };
+            }
+            version = authenticated.version;
+        }
+    }
     if (!version) {
         process.stderr.write(`[agents] routine ${config.name}: no version of ${agent} configured — ` +
             `run: agents add ${agent}@<version> && agents use ${agent} <version>\n`);
@@ -1121,13 +1158,14 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayH
     const setupToken = agent === 'claude' && version
         ? resolveClaudeSetupToken(getVersionHomePath('claude', version))
         : null;
-    // A `personal` device (the user's own interactive box) uses the per-version
-    // login for EVERY run, routines included — the setup-token is a worker-only
-    // credential (RUSH-2395, mirrors the claude adapter's personal-device branch).
-    // On a personal box, only strip an inherited copy of the account's OWN
-    // setup-token by value so a leaked ambient value can't override the login; a
-    // token the user set deliberately is a different string and survives.
-    if (selfConfiguredDeviceRole() === 'personal') {
+    // A headed device (personal or desktop — the user's own interactive box or a
+    // headed always-on box) uses the per-version login for EVERY run, routines
+    // included — the setup-token is a worker-only credential (RUSH-2395, mirrors
+    // the claude adapter's headed-device branch). On a headed box, only strip an
+    // inherited copy of the account's OWN setup-token by value so a leaked ambient
+    // value can't override the login; a token the user set deliberately is a
+    // different string and survives.
+    if (isHeadedDeviceRole(selfConfiguredDeviceRole())) {
         if (setupToken && out.CLAUDE_CODE_OAUTH_TOKEN === setupToken)
             delete out.CLAUDE_CODE_OAUTH_TOKEN;
     }
@@ -1142,6 +1180,10 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayH
         // to the overlay so an ambient value cannot bypass the routine sandbox.
         out.XDG_CONFIG_HOME = path.join(overlayHome, '.config');
     }
+    if (overlayHome && agent === 'claude')
+        out.HOME = process.env.AGENTS_REAL_HOME || os.homedir();
+    if (overlayHome && agent === 'codex')
+        out.CODEX_HOME = path.join(overlayHome, '.codex');
     if (timezone)
         out.TZ = timezone;
     return out;
@@ -1303,7 +1345,7 @@ async function executeJobPlaced(config, deps, attempt) {
     // sentinel, version homes) from HOME, which the overlay would hide. Exec
     // still isolates the run in the host version home it swaps HOME into.
     const useSandbox = config.sandbox !== false && !config.resume && !(config.agent && isCustomHarnessName(config.agent));
-    const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
+    const overlayHome = useSandbox ? prepareJobHome(config, primaryVersion) : undefined;
     const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
@@ -1328,7 +1370,7 @@ async function executeJobPlaced(config, deps, attempt) {
     if (!dispatchesViaAgentsRun(config)) {
         const { findUnifiedAccount, resolveAccountSelection, resolveCredentialAccount } = await import('../account-registry.js');
         const meta = readMeta();
-        const selectedAccount = resolveAccountSelection(config.account, effectiveAgent, meta);
+        const selectedAccount = resolveAccountSelection(config.account, effectiveAgent, meta)?.id;
         if (selectedAccount) {
             // Only a provider account injects env; a native account (explicit or via a
             // device-scoped binding) is read from the harness home and forwards nothing.
@@ -1359,24 +1401,24 @@ async function executeJobPlaced(config, deps, attempt) {
     // Baseline the child's transcript dirs BEFORE spawning so archiveRoutineTranscripts
     // copies only THIS run's transcript out of a shared per-version home (RUSH-2271).
     snapshotRoutineTranscriptBase(meta, runDir, overlayHome);
-    // Auth preflight: if the last live probe rejected this (agent, version)'s
-    // token (verdict `revoked`), the run is guaranteed to fail auth — fail fast
-    // before spawning instead of producing a doomed run + poisoned report. Cache-
-    // only (the daemon refreshes it periodically); fail OPEN on any non-revoked or
-    // missing verdict so a stale/absent probe or a network blip never blocks a
-    // run, and agents with no live probe (codex/gemini/grok) are never blocked.
+    // Auth preflight: if the resolved account is provably signed out (revoked or
+    // unconfigured), record a terminal `blocked`/`agent_auth_failed` run with the
+    // re-login repair instead of spawning a doomed run that 401s and burns a
+    // session (PHNX-3415). `blocked` (readiness rejection, no body ran) is kept
+    // distinct from `failed` (a body ran and errored) per RT-7. Cache-only + fails
+    // OPEN — see fireTimeAuthReadiness.
     const preflightVersion = launch.chain[0]?.version;
-    if (preflightVersion) {
-        const health = readAuthHealth(machineId(), effectiveAgent, preflightVersion);
-        if (health && isDeadVerdict(health.verdict)) {
-            const reason = `auth_preflight: ${health.verdict}`;
-            process.stderr.write(`[agents] routine ${config.name}: ${effectiveAgent}@${preflightVersion} token ${health.verdict} — skipping run (re-login required)\n`);
-            finalizeRunMeta(meta, 'failed', 1, { errorMessage: reason });
-            writeRunMeta(meta);
-            timer.end({ status: 'failed', exitCode: 1, runId, error: reason });
-            archiveRoutineTranscripts(meta, runDir, overlayHome);
-            return { meta, reportPath: null };
-        }
+    // Dynamic import breaks the routine-readiness -> scheduling/routines -> runner cycle.
+    const { fireTimeAuthReadiness } = await import('../routine-readiness.js');
+    const authBlocker = preflightVersion ? fireTimeAuthReadiness(effectiveAgent, preflightVersion) : null;
+    if (authBlocker) {
+        process.stderr.write(`[agents] routine ${config.name}: ${effectiveAgent}@${preflightVersion} ${authBlocker.code} — skipping run (${authBlocker.repair})\n`);
+        meta.readiness = authBlocker;
+        finalizeRunMeta(meta, 'blocked', null, { errorMessage: `blocked: ${authBlocker.code} — ${authBlocker.message}` });
+        writeRunMeta(meta);
+        timer.end({ status: 'blocked', runId, error: authBlocker.code });
+        archiveRoutineTranscripts(meta, runDir, overlayHome);
+        return { meta, reportPath: null };
     }
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     // Loop path: delegate to runLoop (same driver as `agents run --loop` / workflow loop:).
@@ -1443,6 +1485,8 @@ async function executeJobPlaced(config, deps, attempt) {
         meta.version = attemptVersion;
         snapshotRoutineTranscriptBase(meta, runDir, overlayHome);
         const viaAgentsRun = dispatchesViaAgentsRun(config);
+        if (overlayHome)
+            linkVersionAuth(overlayHome, attemptAgent, attemptVersion);
         const cmd = viaAgentsRun
             ? baseCmd
             : pinJobBinary(baseCmd, attemptAgent, attemptVersion);
@@ -1836,7 +1880,7 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
     // sentinel, version homes) from HOME, which the overlay would hide. Exec
     // still isolates the run in the host version home it swaps HOME into.
     const useSandbox = config.sandbox !== false && !config.resume && !(config.agent && isCustomHarnessName(config.agent));
-    const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
+    const overlayHome = useSandbox ? prepareJobHome(config, version) : undefined;
     const runId = attempt.runId;
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
@@ -1849,7 +1893,7 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
         const { findAccount, resolveAccountSelection, resolveCredentialAccount } = await import('../account-registry.js');
         const selectedAccount = config.account && !findAccount(config.account)
             ? undefined
-            : resolveAccountSelection(config.account, config.agent, readMeta());
+            : resolveAccountSelection(config.account, config.agent, readMeta())?.id;
         if (selectedAccount)
             Object.assign(baseEnv, resolveCredentialAccount(selectedAccount, config.agent).env);
     }
@@ -1890,28 +1934,26 @@ async function executeJobDetachedClaimed(config, attempt, hooks) {
     // Baseline the child's transcript dirs BEFORE spawning so archiveRoutineTranscripts
     // copies only THIS run's transcript out of a shared per-version home (RUSH-2271).
     snapshotRoutineTranscriptBase(meta, runDir, overlayHome);
-    // Auth preflight (mirrors executeJob): with no injected token, a daemon-fired
-    // Claude routine authenticates via the pinned account's own CLAUDE_CONFIG_DIR
-    // login. If the last live probe rejected that (agent, version)'s token, the run
-    // is guaranteed to 401 — fail fast with a re-login hint instead of spawning a
-    // doomed run + poisoned report. Cache-only; fails OPEN on any non-dead/missing
-    // verdict, and agents with no live probe (codex/gemini/grok) are never blocked.
+    // Auth preflight (mirrors executeJob): a provably signed-out resolved account
+    // records a terminal `blocked`/`agent_auth_failed` run with the re-login repair
+    // instead of spawning a doomed run that 401s and burns a session (PHNX-3415).
+    // Cache-only + fails OPEN — see fireTimeAuthReadiness.
     const preflightVersion = launch.chain[0]?.version;
-    if (preflightVersion) {
-        const health = readAuthHealth(machineId(), effectiveAgent, preflightVersion);
-        if (health && isDeadVerdict(health.verdict)) {
-            const reason = `auth_preflight: ${health.verdict}`;
-            process.stderr.write(`[agents] routine ${config.name}: ${effectiveAgent}@${preflightVersion} token ${health.verdict} — skipping run (re-login required)\n`);
-            try {
-                fs.closeSync(stdoutFd);
-            }
-            catch { /* already closed */ }
-            finalizeRunMeta(meta, 'failed', 1, { errorMessage: reason });
-            writeRunMeta(meta);
-            archiveRoutineTranscripts(meta, runDir, overlayHome);
-            timer.end({ status: 'failed', exitCode: 1, runId, error: reason });
-            return meta;
+    // Dynamic import breaks the routine-readiness -> scheduling/routines -> runner cycle.
+    const { fireTimeAuthReadiness } = await import('../routine-readiness.js');
+    const authBlocker = preflightVersion ? fireTimeAuthReadiness(effectiveAgent, preflightVersion) : null;
+    if (authBlocker) {
+        process.stderr.write(`[agents] routine ${config.name}: ${effectiveAgent}@${preflightVersion} ${authBlocker.code} — skipping run (${authBlocker.repair})\n`);
+        try {
+            fs.closeSync(stdoutFd);
         }
+        catch { /* already closed */ }
+        meta.readiness = authBlocker;
+        finalizeRunMeta(meta, 'blocked', null, { errorMessage: `blocked: ${authBlocker.code} — ${authBlocker.message}` });
+        writeRunMeta(meta);
+        archiveRoutineTranscripts(meta, runDir, overlayHome);
+        timer.end({ status: 'blocked', runId, error: authBlocker.code });
+        return meta;
     }
     const child = spawn(cmd[0], cmd.slice(1), {
         stdio: ['ignore', stdoutFd, stdoutFd],

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

@@ -0,0 +1,21 @@
+/**
+ * Fleet usage-snapshot sync as a `PeriodicService` (PHNX-3392 usage-sync).
+ *
+ * On a headed box (personal/desktop) each tick pushes the local identity-keyed
+ * Claude usage rows to worker peers that cannot read usage themselves. On a
+ * worker whose cache is empty or stale, the same tick pulls those rows from the
+ * primary headed device. Both drivers gate on the self role, so this service is
+ * safe to register everywhere. Single-executor per destination: each daemon only
+ * writes the DESTINATION's own cache, and the merge is newest-wins + idempotent.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class UsageSyncService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    readonly startupDelayMs = 90000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Fleet usage-snapshot sync as a `PeriodicService` (PHNX-3392 usage-sync).
+ *
+ * On a headed box (personal/desktop) each tick pushes the local identity-keyed
+ * Claude usage rows to worker peers that cannot read usage themselves. On a
+ * worker whose cache is empty or stale, the same tick pulls those rows from the
+ * primary headed device. Both drivers gate on the self role, so this service is
+ * safe to register everywhere. Single-executor per destination: each daemon only
+ * writes the DESTINATION's own cache, and the merge is newest-wins + idempotent.
+ */
+import { BasePeriodicService } from './service.js';
+const USAGE_SYNC_TICK_MS = 15 * 60_000;
+const USAGE_SYNC_DEADLINE_MS = 2 * 60_000;
+const USAGE_SYNC_KICKOFF_MS = 90_000;
+export class UsageSyncService extends BasePeriodicService {
+    id = 'usage-sync';
+    intervalMs = USAGE_SYNC_TICK_MS;
+    deadlineMs = USAGE_SYNC_DEADLINE_MS;
+    startupDelayMs = USAGE_SYNC_KICKOFF_MS;
+    async onStart(_ctx) {
+        // No connections to open — each tick re-reads the local cache + registry.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup.
+    }
+    async onTick(ctx) {
+        const { pullUsageFromPrimary, syncFleetUsageSnapshots } = await import('../accounting/usage-sync.js');
+        const pushResult = syncFleetUsageSnapshots();
+        if (pushResult.pushed.length > 0) {
+            ctx.log('INFO', `usage-sync: pushed usage to ${pushResult.pushed.join(', ')}`);
+        }
+        for (const err of pushResult.errors) {
+            ctx.log('WARN', `usage-sync: ${err.device}: ${err.message}`);
+        }
+        const pullResult = pullUsageFromPrimary();
+        if (pullResult.pulledFrom) {
+            ctx.log('INFO', `usage-sync: pulled usage from ${pullResult.pulledFrom}; merged ${pullResult.merged} row(s)`);
+        }
+        if (pullResult.error)
+            ctx.log('WARN', `usage-sync: pull: ${pullResult.error}`);
+    }
+}

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' | 'auth-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
+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' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -97,6 +97,11 @@ export const DAEMON_SERVICES = [
         title: 'Auth bundle sync',
         description: 'Pushes the reserved file-backed auth bundle (setup-tokens) to pinned fleet devices that do not yet have it.',
     },
+    {
+        id: 'usage-sync',
+        title: 'Usage snapshot sync',
+        description: 'Bidirectional per-account usage sync: a headed personal/desktop box pushes its snapshot to worker peers, and a worker with a stale cache pulls from the primary — so workers that cannot read the endpoint themselves still route by real capacity.',
+    },
 ];
 /** Stable order of service IDs. */
 export const DAEMON_SERVICE_IDS = DAEMON_SERVICES.map((s) => s.id);

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

@@ -87,7 +87,7 @@ export interface ConfigTarget {
     fleet?: boolean;
 }
 /** Roles a device can be marked with — see the `role` key below. */
-declare const DEVICE_ROLES: readonly ["worker", "personal"];
+declare const DEVICE_ROLES: readonly ["worker", "personal", "desktop"];
 /** Which devices automatic placement may pick — see the `auto.pool` key below. */
 declare const AUTO_POOL_MODES: readonly ["workers", "all"];
 export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
@@ -150,13 +150,24 @@ export declare function configuredDeviceRole(name: string): ConfiguredDeviceRole
  * it was never marked. Keyed off {@link machineId} (overridable via
  * AGENTS_SYNC_MACHINE_ID), so it matches the device's own config-folder key.
  *
- * The auth strategy reads this: a `personal` device (the user's own interactive
- * box) holds a real per-version login and MUST authenticate from it for EVERY
- * run, interactive or headless; only a `worker` uses the file-based setup-token
- * (RUSH-2395). `undefined` is treated as non-personal (worker-equivalent) by
- * that gate — an unmarked box has no login to defer to.
+ * The auth strategy reads this: a headed device (`personal` or `desktop`, see
+ * {@link isHeadedDeviceRole}) holds a real per-version login and MUST
+ * authenticate from it for EVERY run, interactive or headless; only a `worker`
+ * uses the file-based setup-token (RUSH-2395). `undefined` is treated as
+ * non-headed (worker-equivalent) by that gate — an unmarked box has no login to
+ * defer to.
  */
 export declare function selfConfiguredDeviceRole(): ConfiguredDeviceRole | undefined;
+/**
+ * A "headed" device — one with an interactive desktop login, so it authenticates
+ * from its own per-version Claude login (which carries the `user:profile` scope
+ * the usage endpoint needs) rather than the headless file setup-token. Both
+ * `personal` (the box you sit at) and `desktop` (a headed always-on box like a
+ * Mac mini) qualify; a `worker` and an unmarked box do NOT. This is the single
+ * predicate the auth-bucket sites read, so `personal` and `desktop` never drift
+ * apart (claude adapter, routine spawn env, `agents view` usage login).
+ */
+export declare function isHeadedDeviceRole(role: ConfiguredDeviceRole | undefined): boolean;
 /** Mark a device's role fleet-wide; `undefined` clears the mark. */
 export declare function setConfiguredDeviceRole(name: string, role: ConfiguredDeviceRole | undefined): void;
 /**

package/dist/lib/device-config.js

@@ -41,7 +41,7 @@ import { migrateDeviceConfigStores } from './devices/config-migration.js';
 const DEVICE_PLATFORMS = ['windows', 'linux', 'macos', 'unknown'];
 const SSH_AUTH_METHODS = ['key', 'password'];
 /** Roles a device can be marked with — see the `role` key below. */
-const DEVICE_ROLES = ['worker', 'personal'];
+const DEVICE_ROLES = ['worker', 'personal', 'desktop'];
 /** Which devices automatic placement may pick — see the `auto.pool` key below. */
 const AUTO_POOL_MODES = ['workers', 'all'];
 export const CONFIG_KEYS = [
@@ -67,8 +67,8 @@ export const CONFIG_KEYS = [
         scope: 'user',
         type: 'string',
         description: "Which devices automatic placement (`--device auto`) may pick: 'workers' (default — only devices marked role=worker, " +
-            "once at least one is marked) or 'all' (every online device, ignoring worker marks). A device marked personal is " +
-            'never picked automatically under either mode.',
+            "once at least one is marked) or 'all' (every online device, ignoring worker marks). A device marked personal or " +
+            'desktop is never picked automatically under either mode.',
         defaultValue: 'workers',
         validate: (v) => AUTO_POOL_MODES.includes(v)
             ? null
@@ -279,9 +279,10 @@ export const CONFIG_KEYS = [
         scope: 'device',
         visibility: 'shared',
         type: 'string',
-        description: "What this device is for, fleet-wide: 'worker' (a box agents run on) or 'personal' (a machine you sit at — never " +
-            'picked automatically). Marking ANY device worker turns automatic placement into an allowlist: `--device auto` then ' +
-            'picks only from the marked workers.',
+        description: "What this device is for, fleet-wide: 'worker' (a box agents run on), 'personal' (a machine you sit at — your " +
+            "interactive seat), or 'desktop' (a headed always-on box like a Mac mini — the release/credential home). Personal " +
+            'and desktop are never picked automatically. Marking ANY device worker turns automatic placement into an allowlist: ' +
+            '`--device auto` then picks only from the marked workers.',
         validate: (v) => DEVICE_ROLES.includes(v)
             ? null
             : `role must be one of ${DEVICE_ROLES.join(' | ')}.`,
@@ -630,15 +631,28 @@ export function configuredDeviceRole(name) {
  * it was never marked. Keyed off {@link machineId} (overridable via
  * AGENTS_SYNC_MACHINE_ID), so it matches the device's own config-folder key.
  *
- * The auth strategy reads this: a `personal` device (the user's own interactive
- * box) holds a real per-version login and MUST authenticate from it for EVERY
- * run, interactive or headless; only a `worker` uses the file-based setup-token
- * (RUSH-2395). `undefined` is treated as non-personal (worker-equivalent) by
- * that gate — an unmarked box has no login to defer to.
+ * The auth strategy reads this: a headed device (`personal` or `desktop`, see
+ * {@link isHeadedDeviceRole}) holds a real per-version login and MUST
+ * authenticate from it for EVERY run, interactive or headless; only a `worker`
+ * uses the file-based setup-token (RUSH-2395). `undefined` is treated as
+ * non-headed (worker-equivalent) by that gate — an unmarked box has no login to
+ * defer to.
  */
 export function selfConfiguredDeviceRole() {
     return configuredDeviceRole(machineId());
 }
+/**
+ * A "headed" device — one with an interactive desktop login, so it authenticates
+ * from its own per-version Claude login (which carries the `user:profile` scope
+ * the usage endpoint needs) rather than the headless file setup-token. Both
+ * `personal` (the box you sit at) and `desktop` (a headed always-on box like a
+ * Mac mini) qualify; a `worker` and an unmarked box do NOT. This is the single
+ * predicate the auth-bucket sites read, so `personal` and `desktop` never drift
+ * apart (claude adapter, routine spawn env, `agents view` usage login).
+ */
+export function isHeadedDeviceRole(role) {
+    return role === 'personal' || role === 'desktop';
+}
 /** Mark a device's role fleet-wide; `undefined` clears the mark. */
 export function setConfiguredDeviceRole(name, role) {
     assertValidDeviceName(name);

package/dist/lib/devices/connect.d.ts

@@ -47,16 +47,25 @@ export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]):
  */
 export declare function isAgentsBrowserDrive(cmd: string[]): boolean;
 /**
- * Prefix a remote command so the far side sees `AGENTS_FLEET_REMOTE=1` — the
- * marker the browser consent gate reads. `wrapRemoteCommand` joins the argv
- * with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell.
+ * Prefix a remote command with the provenance the far-side browser needs: the
+ * `AGENTS_FLEET_REMOTE=1` consent marker AND the caller's resolved actor
+ * (`AGENTS_ACTOR*`/`GIT_*`). Without the actor, a task created over
+ * `agents ssh <host> 'agents browser …'` is stamped `UNRESOLVED@<host>` because
+ * the peer re-resolves identity from its own (empty) env — the same RUSH-2028
+ * gap the `--device` dispatch already closes via `withActorEnv`, applied here to
+ * the `agents ssh` browser-drive seam so ownership is honest across BOTH paths.
  *
- * Already-marked argv (the `--device` fan-out stamps this before
- * {@link buildSshInvocation}) is left unchanged so the prefix is not doubled.
+ * `wrapRemoteCommand` joins the argv with spaces (POSIX) or base64-encodes it for
+ * PowerShell, so a shell-appropriate prelude rides through both: `env VAR=v …` on
+ * POSIX, `$env:VAR='v'; …` on PowerShell. The marker stays the FIRST token so the
+ * consent gate and the idempotency guard below both still key on it.
+ *
+ * `provenanceEnv` is injectable so tests can pin a deterministic actor; it
+ * defaults to the live resolved actor. Already-marked argv (the `--device`
+ * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
+ * so nothing is doubled.
  */
-export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfile, 'shell'>): string[];
+export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
  * mirrored project directory, falling back to the remote home when that

package/dist/lib/devices/connect.js

@@ -16,6 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { resolveActor, actorEnv } from '../actor.js';
 import { getCliLaunch } from '../cli-entry.js';
 import { encodePwshBase64 } from '../pwsh.js';
 import { homeRemainder, remoteCdPrefix } from '../project-root.js';
@@ -104,24 +105,40 @@ export function isAgentsBrowserDrive(cmd) {
     return (bin === 'agents' || bin === 'ag') && tokens[1] === 'browser';
 }
 /**
- * Prefix a remote command so the far side sees `AGENTS_FLEET_REMOTE=1` — the
- * marker the browser consent gate reads. `wrapRemoteCommand` joins the argv
- * with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell.
+ * Prefix a remote command with the provenance the far-side browser needs: the
+ * `AGENTS_FLEET_REMOTE=1` consent marker AND the caller's resolved actor
+ * (`AGENTS_ACTOR*`/`GIT_*`). Without the actor, a task created over
+ * `agents ssh <host> 'agents browser …'` is stamped `UNRESOLVED@<host>` because
+ * the peer re-resolves identity from its own (empty) env — the same RUSH-2028
+ * gap the `--device` dispatch already closes via `withActorEnv`, applied here to
+ * the `agents ssh` browser-drive seam so ownership is honest across BOTH paths.
  *
- * Already-marked argv (the `--device` fan-out stamps this before
- * {@link buildSshInvocation}) is left unchanged so the prefix is not doubled.
+ * `wrapRemoteCommand` joins the argv with spaces (POSIX) or base64-encodes it for
+ * PowerShell, so a shell-appropriate prelude rides through both: `env VAR=v …` on
+ * POSIX, `$env:VAR='v'; …` on PowerShell. The marker stays the FIRST token so the
+ * consent gate and the idempotency guard below both still key on it.
+ *
+ * `provenanceEnv` is injectable so tests can pin a deterministic actor; it
+ * defaults to the live resolved actor. Already-marked argv (the `--device`
+ * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
+ * so nothing is doubled.
  */
-export function markFleetRemote(cmd, device) {
+export function markFleetRemote(cmd, device, provenanceEnv = actorEnv(resolveActor())) {
     if (device.shell === 'powershell') {
-        return cmd[0] === `$env:AGENTS_FLEET_REMOTE='1';`
-            ? cmd
-            : [`$env:AGENTS_FLEET_REMOTE='1';`, ...cmd];
+        // Exact-match guard, symmetric with the POSIX branch below: the marker token
+        // is always this literal, so `startsWith` would only loosen it for no gain.
+        if (cmd[0] === `$env:AGENTS_FLEET_REMOTE='1';`)
+            return cmd;
+        const prelude = [
+            `$env:AGENTS_FLEET_REMOTE='1';`,
+            ...Object.entries(provenanceEnv).map(([k, v]) => `$env:${k}='${v.replace(/'/g, "''")}';`),
+        ];
+        return [...prelude, ...cmd];
     }
-    return cmd[0] === 'env' && cmd[1] === 'AGENTS_FLEET_REMOTE=1'
-        ? cmd
-        : ['env', 'AGENTS_FLEET_REMOTE=1', ...cmd];
+    if (cmd[0] === 'env' && cmd[1] === 'AGENTS_FLEET_REMOTE=1')
+        return cmd;
+    const actorTokens = Object.entries(provenanceEnv).map(([k, v]) => shellQuote(`${k}=${v}`));
+    return ['env', 'AGENTS_FLEET_REMOTE=1', ...actorTokens, ...cmd];
 }
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a

package/dist/lib/devices/pool.d.ts

@@ -15,10 +15,11 @@
  * |---|---|
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
- * | marked `personal` | never, under either state |
+ * | marked `personal` / `desktop` | never, under either state |
  *
- * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
- * machine the user sits at is marked precisely so agents stay off it.
+ * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * excluded, because a box the user sits at (personal) or a headed always-on
+ * release/credential box (desktop) is marked precisely so agents stay off it.
  */
 import { type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
 export interface AutoPoolOptions {

package/dist/lib/devices/pool.js

@@ -15,15 +15,23 @@
  * |---|---|
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
- * | marked `personal` | never, under either state |
+ * | marked `personal` / `desktop` | never, under either state |
  *
- * `auto.pool all` turns the allowlist off; `personal` stays excluded, because a
- * machine the user sits at is marked precisely so agents stay off it.
+ * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * excluded, because a box the user sits at (personal) or a headed always-on
+ * release/credential box (desktop) is marked precisely so agents stay off it.
  */
 import { autoPoolMode, listConfiguredDeviceRoles } from '../device-config.js';
 import { normalizeHost } from '../machine-id.js';
-/** Roles that automatic placement never picks, whatever the pool mode. */
-const NEVER_AUTO = new Set(['personal']);
+/**
+ * Roles that automatic placement never picks, whatever the pool mode.
+ *
+ * `personal` (a box you sit at) and `desktop` (a headed always-on box — the
+ * release/credential home, e.g. a Mac mini) are both off-limits to `--device
+ * auto`: neither is headless fan-out capacity, and landing agent work on them
+ * is the outcome the mark exists to prevent. Only `worker` is auto-eligible.
+ */
+const NEVER_AUTO = new Set(['personal', 'desktop']);
 /**
  * Narrow a candidate host list to the devices automatic placement may pick.
  *