@phnx-labs/agents-cli 1.22.57 → 1.22.59

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,8 +37,6 @@ 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 { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../device-config.js';
 import { isSelfUpdatingAgent, ROUTINE_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../agents.js';
 import { isCustomHarnessName, readProfile } from '../profiles.js';
@@ -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`);
@@ -1143,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;
@@ -1304,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 });
@@ -1329,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.
@@ -1360,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:).
@@ -1444,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);
@@ -1837,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 });
@@ -1850,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);
     }
@@ -1891,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/session-index-service.js

@@ -11,7 +11,7 @@
  * and deadline instead.
  */
 import { BasePeriodicService } from './service.js';
-import { runSessionIndexWarmTick } from '../daemon-ticks.js';
+import { runDeferredToolIndex, runSessionIndexWarmTick } from '../daemon-ticks.js';
 /** Matches the historical inline interval (daemon.ts SESSION_INDEX_WARM_TICK_MS). */
 const SESSION_INDEX_WARM_TICK_MS = 20_000;
 /** Hard cap per tick — well above a healthy incremental scan, short enough that a hang never freezes the service for long. */
@@ -36,5 +36,13 @@ export class SessionIndexService extends BasePeriodicService {
             ctx.log('INFO', 'session-index warm: skipped, another process holds the scan claim');
         else if (indexed > 0)
             ctx.log('INFO', `session-index warm: indexed ${indexed} transcript(s)`);
+        // Deferred tool-index pass (PHNX-3411): fill tool_scan_ledger rows for
+        // harnesses whose scanner produces no events. Runs only when the warm tick
+        // claimed the scan lock (i.e. we are the active indexer this tick).
+        if (claimed) {
+            const { indexed: toolIndexed } = await runDeferredToolIndex();
+            if (toolIndexed > 0)
+                ctx.log('INFO', `session-index deferred: tool-indexed ${toolIndexed} transcript(s)`);
+        }
     }
 }

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

@@ -2,9 +2,9 @@
  * 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. A no-op on
- * a worker/unmarked box or when the local cache is empty — the driver
- * ({@link syncFleetUsageSnapshots}) gates on the self role, so this service is
+ * 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.
  */

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

@@ -2,9 +2,9 @@
  * 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. A no-op on
- * a worker/unmarked box or when the local cache is empty — the driver
- * ({@link syncFleetUsageSnapshots}) gates on the self role, so this service is
+ * 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.
  */
@@ -24,13 +24,19 @@ export class UsageSyncService extends BasePeriodicService {
         // Nothing to release — the supervisor's timer teardown is the only cleanup.
     }
     async onTick(ctx) {
-        const { syncFleetUsageSnapshots } = await import('../accounting/usage-sync.js');
-        const result = syncFleetUsageSnapshots();
-        if (result.pushed.length > 0) {
-            ctx.log('INFO', `usage-sync: pushed usage to ${result.pushed.join(', ')}`);
+        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 result.errors) {
+        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.js

@@ -100,7 +100,7 @@ export const DAEMON_SERVICES = [
     {
         id: 'usage-sync',
         title: 'Usage snapshot sync',
-        description: 'From a personal/desktop box, pushes the per-account usage snapshot to worker peers that cannot read it themselves.',
+        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. */

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

@@ -121,3 +121,18 @@ export declare function runSessionIndexWarmTick(): Promise<{
     indexed: number;
     claimed: boolean;
 }>;
+/**
+ * Deferred tool-index pass for large-transcript harnesses (PHNX-3411).
+ *
+ * Kimi (wire.jsonl) and Grok (chat_history.jsonl) scanners produce only
+ * metadata — no events. Calling parseSession for those on the warm tick wedges
+ * the Node event loop when the transcript is large and active (observed: several
+ * seconds per tick on zion, causing browser IPC ECONNREFUSED). This pass fills
+ * the gap: it queries recently-active kimi/grok sessions and calls
+ * ensureToolIndex, which uses tool_scan_ledger stamps to skip already-current
+ * sessions and applies byte/file budget caps so no large transcript monopolises
+ * the tick.
+ */
+export declare function runDeferredToolIndex(): Promise<{
+    indexed: number;
+}>;

package/dist/lib/daemon-ticks.js

@@ -185,3 +185,29 @@ export async function runSessionIndexWarmTick() {
         return { indexed: 0, claimed: false };
     return { indexed: scanned, claimed: true };
 }
+/**
+ * Deferred tool-index pass for large-transcript harnesses (PHNX-3411).
+ *
+ * Kimi (wire.jsonl) and Grok (chat_history.jsonl) scanners produce only
+ * metadata — no events. Calling parseSession for those on the warm tick wedges
+ * the Node event loop when the transcript is large and active (observed: several
+ * seconds per tick on zion, causing browser IPC ECONNREFUSED). This pass fills
+ * the gap: it queries recently-active kimi/grok sessions and calls
+ * ensureToolIndex, which uses tool_scan_ledger stamps to skip already-current
+ * sessions and applies byte/file budget caps so no large transcript monopolises
+ * the tick.
+ */
+export async function runDeferredToolIndex() {
+    const { querySessionsForDeferredToolIndex } = await import('./session/db.js');
+    const { ensureToolIndex } = await import('./session/tool-index.js');
+    // Feed the 200 most-recently-active kimi/grok sessions; ensureToolIndex skips
+    // any whose tool_scan_ledger stamp is current.
+    const sessions = querySessionsForDeferredToolIndex(200);
+    if (sessions.length === 0)
+        return { indexed: 0 };
+    const coverage = await ensureToolIndex(sessions, {
+        maxFiles: 20,
+        maxBytes: 20 * 1024 * 1024, // 20 MB — bounds one tick even on large transcripts
+    });
+    return { indexed: coverage.indexedFiles };
+}

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

@@ -194,7 +194,11 @@ export declare function devicesPinningBrowserProfile(profile: string): Array<{
 export declare function listConfiguredDeviceRoles(roster?: string[]): Record<string, ConfiguredDeviceRole>;
 /** The configured automatic-placement pool mode. Unset means `workers`. */
 export declare function autoPoolMode(): AutoPoolMode;
-/** A device's auto-launch flags, as read by Factory's launch ranking. */
+/**
+ * A device's auto-launch flags, read by the automatic-placement pool
+ * (`filterAutoPool` drops `enabled: false`; `pickBestDevice` boosts
+ * `preferred: true` — see `lib/devices/pool.ts`) and by the menu-bar snapshot.
+ */
 export interface AutoLaunchPreference {
     enabled?: boolean;
     preferred?: boolean;

package/dist/lib/device-config.js

@@ -294,7 +294,7 @@ export const CONFIG_KEYS = [
         visibility: 'shared',
         type: 'bool',
         defaultValue: true,
-        description: 'Whether AGI EXT auto-launch may pick this device (default on).',
+        description: 'Whether `--device auto` (run, teams, AGI EXT) may pick this device (default on). Off drops it from every automatic-placement path.',
     },
     {
         name: 'auto-launch.preferred',
@@ -303,7 +303,7 @@ export const CONFIG_KEYS = [
         visibility: 'shared',
         type: 'bool',
         defaultValue: false,
-        description: 'Boost this device in AGI EXT auto-launch ranking (default off).',
+        description: 'Boost this device in `--device auto` ranking (default off) — picked ahead of load-equal peers when eligible.',
     },
 ];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */

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/health.js

@@ -145,8 +145,12 @@ export function parseProbeOutput(host, stdout, fetchedAt) {
  * numbers, mirroring how garbage POSIX output degrades. */
 export function parseWinProbeOutput(host, stdout, fetchedAt) {
     const m = stdout.match(/AGWINSTAT load=([0-9.]*) freeKb=([0-9]+) totalKb=([0-9]+) ncpu=([0-9]+)(?: diskFreeKb=([0-9.]+) diskTotalKb=([0-9.]+))?/);
+    // Unparseable output still means the probe RAN — the box answered, we just
+    // could not read it. Stamp specsFetchedAt anyway so a hardware-fact carry
+    // forward (retainHardwareFacts, RUSH-3096) has a real observation moment
+    // instead of undefined.
     if (!m)
-        return { host, reachable: true, fetchedAt };
+        return { host, reachable: true, fetchedAt, specsFetchedAt: fetchedAt };
     const loadPercent = m[1] === '' ? undefined : parseFloat(m[1]);
     const freeKb = parseInt(m[2], 10);
     const totalKb = parseInt(m[3], 10);

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

@@ -16,12 +16,20 @@
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
  * | marked `personal` / `desktop` | never, under either state |
+ * | `auto-launch.enabled` off | never, whatever its role or the mode |
  *
- * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * `auto.pool all` turns the WORKER 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.
+ *
+ * A device the operator turned off with `agents devices disable <name>`
+ * (`auto-launch.enabled` = false) is dropped here too — one operator switch,
+ * one place, so `disable` removes a box from EVERY automatic-placement path
+ * (run/teams/ssh auto), not just one surface. Its sibling
+ * `auto-launch.preferred` does not narrow the pool; it BOOSTS a member in the
+ * ranker ({@link autoLaunchPreferredSet}, applied by `pickBestDevice`).
  */
-import { type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
+import { type AutoLaunchPreference, type AutoPoolMode, type ConfiguredDeviceRole } from '../device-config.js';
 export interface AutoPoolOptions {
     /** Pool mode; defaults to the configured `auto.pool`. */
     mode?: AutoPoolMode;
@@ -34,6 +42,14 @@ export interface AutoPoolOptions {
      * {@link listConfiguredDeviceRoles}.
      */
     roster?: string[];
+    /**
+     * Auto-launch flags by device name; defaults to the fleet-shared block for
+     * the roster (or the pool). A device whose `enabled` is `false` is dropped
+     * from the pool. Inject `{}` in a pure unit test to keep the rule off disk,
+     * exactly as `roles: {}` does for the role rule. See
+     * {@link loadAutoLaunchPreferences}.
+     */
+    autoLaunch?: Record<string, AutoLaunchPreference>;
 }
 /**
  * Narrow a candidate host list to the devices automatic placement may pick.
@@ -44,6 +60,13 @@ export interface AutoPoolOptions {
  * quietly widening back to the full fleet.
  */
 export declare function filterAutoPool(pool: string[], opts?: AutoPoolOptions): string[];
+/**
+ * Normalized hosts the operator boosted with `auto-launch.preferred` = true —
+ * the set `pickBestDevice` ranks ahead of its peers. Unlike the disable drop,
+ * a preference never removes a device: an eligible non-preferred box is still
+ * picked when no preferred one is available.
+ */
+export declare function autoLaunchPreferredSet(pool: string[], opts?: AutoPoolOptions): Set<string>;
 /** True when this host is one automatic placement may pick. */
 export declare function isAutoPoolMember(host: string, opts?: AutoPoolOptions): boolean;
 /** Device names explicitly marked `worker`, in registry order. */

package/dist/lib/devices/pool.js

@@ -16,12 +16,20 @@
  * | no device marked | every online device (unchanged behavior) |
  * | some marked `worker` | ONLY those workers |
  * | marked `personal` / `desktop` | never, under either state |
+ * | `auto-launch.enabled` off | never, whatever its role or the mode |
  *
- * `auto.pool all` turns the allowlist off; `personal` and `desktop` stay
+ * `auto.pool all` turns the WORKER 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.
+ *
+ * A device the operator turned off with `agents devices disable <name>`
+ * (`auto-launch.enabled` = false) is dropped here too — one operator switch,
+ * one place, so `disable` removes a box from EVERY automatic-placement path
+ * (run/teams/ssh auto), not just one surface. Its sibling
+ * `auto-launch.preferred` does not narrow the pool; it BOOSTS a member in the
+ * ranker ({@link autoLaunchPreferredSet}, applied by `pickBestDevice`).
  */
-import { autoPoolMode, listConfiguredDeviceRoles } from '../device-config.js';
+import { autoPoolMode, listConfiguredDeviceRoles, loadAutoLaunchPreferences, } from '../device-config.js';
 import { normalizeHost } from '../machine-id.js';
 /**
  * Roles that automatic placement never picks, whatever the pool mode.
@@ -44,7 +52,10 @@ export function filterAutoPool(pool, opts = {}) {
     const roles = opts.roles ?? listConfiguredDeviceRoles(opts.roster ?? pool);
     const byHost = new Map(Object.entries(roles).map(([name, role]) => [normalizeHost(name), role]));
     const roleOf = (host) => byHost.get(normalizeHost(host));
+    const disabled = disabledAutoLaunchSet(pool, opts);
     const eligible = pool.filter((host) => {
+        if (disabled.has(normalizeHost(host)))
+            return false;
         const role = roleOf(host);
         return role === undefined || !NEVER_AUTO.has(role);
     });
@@ -56,6 +67,25 @@ export function filterAutoPool(pool, opts = {}) {
         return eligible;
     return eligible.filter((host) => roleOf(host) === 'worker');
 }
+/** Normalized hosts the operator turned off with `auto-launch.enabled` = false. */
+function disabledAutoLaunchSet(pool, opts) {
+    const prefs = opts.autoLaunch ?? loadAutoLaunchPreferences(opts.roster ?? pool);
+    return new Set(Object.entries(prefs)
+        .filter(([, pref]) => pref.enabled === false)
+        .map(([name]) => normalizeHost(name)));
+}
+/**
+ * Normalized hosts the operator boosted with `auto-launch.preferred` = true —
+ * the set `pickBestDevice` ranks ahead of its peers. Unlike the disable drop,
+ * a preference never removes a device: an eligible non-preferred box is still
+ * picked when no preferred one is available.
+ */
+export function autoLaunchPreferredSet(pool, opts = {}) {
+    const prefs = opts.autoLaunch ?? loadAutoLaunchPreferences(opts.roster ?? pool);
+    return new Set(Object.entries(prefs)
+        .filter(([, pref]) => pref.preferred === true)
+        .map(([name]) => normalizeHost(name)));
+}
 /** True when this host is one automatic placement may pick. */
 export function isAutoPoolMember(host, opts = {}) {
     return filterAutoPool([host], opts).length > 0;