@phnx-labs/agents-cli 1.20.86 → 1.20.88

package/dist/lib/devices/fleet-divergence.d.ts

@@ -40,6 +40,23 @@ export interface RepoState {
     /** True when the working tree has uncommitted changes. */
     dirty: boolean;
 }
+/**
+ * Per-version sign-in state a device self-reports, so the fleet doctor can show
+ * every installed version's account (and a provable logged-out) without a second
+ * SSH round-trip. `provable` is true only when the credential is absent from BOTH
+ * the version home and the active/global HOME (see `credentialPresence`); an
+ * unprovable absence (opaque/keychain agent) is a warning, not a critical.
+ */
+export interface FleetVersionSignIn {
+    version: string;
+    /** A usable local credential was found for this version (or shared globally). */
+    signedIn: boolean;
+    /** Human account label (email, org badge, or opaque id), when derivable. */
+    account: string | null;
+    /** True only when a logged-out state is PROVABLE (credential absent per-version
+     *  AND globally) — the caller gates a critical on this. */
+    provable: boolean;
+}
 /**
  * The self-reported harness inventory a single device emits in `doctor --json`.
  * Comparable device-to-device with no further probing.
@@ -55,6 +72,11 @@ export interface FleetInventory {
         agents: RepoState | null;
         system: RepoState | null;
     };
+    /** Per-version sign-in state per agent id, for the fleet doctor's accounts
+     *  line and cross-fleet logged-out criticals. Optional — an older CLI that
+     *  predates this field omits it, and the caller degrades to a warning
+     *  ("older agents-cli — can't report per-version sign-in"). */
+    signIn?: Record<string, FleetVersionSignIn[]>;
 }
 /** A device's inventory paired with its name (and reachability). A device that
  *  was unreachable / failed to report carries `inventory: null` and is skipped

package/dist/lib/devices/fleet-divergence.js

@@ -45,20 +45,25 @@ function repoLabel(repo) {
 }
 /** Describe how a remote repo state diverges from the local baseline, or null
  *  when they match. Compares HEAD first (the load-bearing difference), then
- *  branch, then a dirty tree on either side (naming which side is dirty). */
+ *  branch, then a dirty tree on either side.
+ *
+ *  HEAD and branch differences are symmetric — by convention the remote is the
+ *  one "diverged from the baseline" — but a dirty tree belongs to exactly one
+ *  box, and blaming the wrong one sends the user to a clean machine. */
 function describeRepoDrift(local, remote) {
     if (local.head && remote.head && local.head !== remote.head) {
-        return `HEAD ${remote.head} != local ${local.head}`;
+        return { detail: `repo diverged: HEAD ${remote.head} != local ${local.head}`, blame: 'remote' };
     }
     if (local.branch !== remote.branch) {
-        return `branch ${remote.branch ?? 'detached'} != local ${local.branch ?? 'detached'}`;
+        return {
+            detail: `repo diverged: branch ${remote.branch ?? 'detached'} != local ${local.branch ?? 'detached'}`,
+            blame: 'remote',
+        };
     }
-    // Flag a dirty tree on EITHER side (symmetric with HEAD/branch above), and name
-    // the side that has the uncommitted changes — the remote, or the local baseline.
     if (remote.dirty !== local.dirty) {
         return remote.dirty
-            ? 'remote tree has uncommitted changes'
-            : 'local tree has uncommitted changes';
+            ? { detail: 'tree has uncommitted changes', blame: 'remote' }
+            : { detail: 'tree has uncommitted changes', blame: 'local' };
     }
     return null;
 }
@@ -78,6 +83,9 @@ export function compareFleetInventories(devices, baselineName) {
     const comparedDevices = [];
     const skippedDevices = [];
     const divergences = [];
+    /** Repos already reported as the BASELINE's problem — one dirty local tree is
+     *  one finding, not one per remote compared against. */
+    const localBlamed = new Set();
     if (!baseline) {
         // No local baseline to compare against — record every remote as skipped so
         // the caller can say so, but emit no divergences (we can't know the truth).
@@ -163,15 +171,31 @@ export function compareFleetInventories(devices, baselineName) {
             if (!localRepo || !remoteRepo)
                 continue; // one side isn't a readable repo
             const drift = describeRepoDrift(localRepo, remoteRepo);
-            if (drift) {
+            if (!drift)
+                continue;
+            if (drift.blame === 'local') {
+                // The BASELINE owns this one. File it against the baseline, and only
+                // once: the local tree being dirty is a single fact about this machine,
+                // not one problem per remote we happened to compare against.
+                if (localBlamed.has(repo))
+                    continue;
+                localBlamed.add(repo);
                 divergences.push({
                     kind: 'repo-drift',
-                    device: remote.name,
+                    device: baselineName,
                     category: repo,
                     name: repoLabel(repo),
-                    message: `${remote.name} ${repoLabel(repo)} repo diverged: ${drift}`,
+                    message: `${baselineName} ${repoLabel(repo)} ${drift.detail}`,
                 });
+                continue;
             }
+            divergences.push({
+                kind: 'repo-drift',
+                device: remote.name,
+                category: repo,
+                name: repoLabel(repo),
+                message: `${remote.name} ${repoLabel(repo)} ${drift.detail}`,
+            });
         }
     }
     divergences.sort((a, b) => a.device.localeCompare(b.device) ||

package/dist/lib/devices/fleet-inventory.d.ts

@@ -8,12 +8,23 @@
  * FleetInventory} that both the local baseline and every remote box serialize
  * into their doctor payload; the comparator then diffs those payloads.
  */
-import { type FleetInventory } from './fleet-divergence.js';
+import { type FleetInventory, type FleetVersionSignIn } from './fleet-divergence.js';
+/**
+ * Probe every installed version's sign-in state, per agent. For each version we
+ * read its own home's account (via the shim-set config dir) and, when logged
+ * out, decide whether that is PROVABLE: an agent that can't be inspected
+ * (`!supportsAccountInspection`) never claims logged out, and a version that
+ * merely lacks its own credential but shares the global login (`active`) is
+ * signed in, not out. Pure reads (file-presence + cheap account parse), no
+ * network, no keychain prompt. Only agents with at least one installed version
+ * appear, so the map lines up with {@link FleetInventory.agentVersions}.
+ */
+export declare function collectLocalFleetSignIn(): Promise<Record<string, FleetVersionSignIn[]>>;
 /**
  * Collect this machine's harness inventory: installed resources per kind,
- * installed version ids per agent, and `.agents`/`.system` repo state. Pure
- * reads — never mutates the install. `promptcuts` (a single present/absent bit
- * in {@link getAvailableResources}) is surfaced as a one-element list so it
- * compares like any other named resource.
+ * installed version ids per agent, `.agents`/`.system` repo state, and
+ * per-version sign-in. Pure reads — never mutates the install. `promptcuts` (a
+ * single present/absent bit in {@link getAvailableResources}) is surfaced as a
+ * one-element list so it compares like any other named resource.
  */
-export declare function collectLocalFleetInventory(cwd?: string): FleetInventory;
+export declare function collectLocalFleetInventory(cwd?: string): Promise<FleetInventory>;

package/dist/lib/devices/fleet-inventory.js

@@ -8,24 +8,71 @@
  * FleetInventory} that both the local baseline and every remote box serialize
  * into their doctor payload; the comparator then diffs those payloads.
  */
-import { getAvailableResources, listInstalledVersions } from '../versions.js';
+import { getAvailableResources, getVersionHomePath, listInstalledVersions } from '../versions.js';
 import { getUserAgentsDir, getSystemAgentsDir } from '../state.js';
 import { readRepoState } from '../git.js';
-import { ALL_AGENT_IDS } from '../agents.js';
-import { FLEET_RESOURCE_KINDS } from './fleet-divergence.js';
+import { ALL_AGENT_IDS, accountDisplayLabel, credentialPresence, getAccountInfo, supportsAccountInspection, } from '../agents.js';
+import { FLEET_RESOURCE_KINDS, } from './fleet-divergence.js';
 function toRepoState(snap) {
     if (!snap)
         return null;
     return { branch: snap.branch, head: snap.head, dirty: snap.dirty };
 }
+/**
+ * Probe every installed version's sign-in state, per agent. For each version we
+ * read its own home's account (via the shim-set config dir) and, when logged
+ * out, decide whether that is PROVABLE: an agent that can't be inspected
+ * (`!supportsAccountInspection`) never claims logged out, and a version that
+ * merely lacks its own credential but shares the global login (`active`) is
+ * signed in, not out. Pure reads (file-presence + cheap account parse), no
+ * network, no keychain prompt. Only agents with at least one installed version
+ * appear, so the map lines up with {@link FleetInventory.agentVersions}.
+ */
+export async function collectLocalFleetSignIn() {
+    const out = {};
+    await Promise.all(ALL_AGENT_IDS.map(async (agent) => {
+        const versions = listInstalledVersions(agent);
+        if (versions.length === 0)
+            return;
+        const rows = await Promise.all(versions.map(async (version) => {
+            const home = getVersionHomePath(agent, version);
+            let signedIn = false;
+            let account = null;
+            try {
+                const info = await getAccountInfo(agent, home);
+                signedIn = info.signedIn;
+                account = accountDisplayLabel(info) || null;
+            }
+            catch {
+                /* advisory only — treat as logged out, provability decided below */
+            }
+            // Provable logout: the agent is inspectable AND the credential is absent
+            // from BOTH the version home and the active/global HOME. An opaque or
+            // keychain-only agent, or one sharing the global login, is never a
+            // provable logout.
+            let provable = false;
+            if (!signedIn && supportsAccountInspection(agent)) {
+                const presence = credentialPresence(agent, home);
+                // `knownLocation` is load-bearing: an agent can sit in the inspection
+                // set with no credential path (cursor does), and then both probes are
+                // false only because there is nothing to look for. Treating that as a
+                // provable logout prints a CRITICAL for a version that is signed in.
+                provable = presence.knownLocation && !presence.perVersion && !presence.active;
+            }
+            return { version, signedIn, account, provable };
+        }));
+        out[agent] = rows;
+    }));
+    return out;
+}
 /**
  * Collect this machine's harness inventory: installed resources per kind,
- * installed version ids per agent, and `.agents`/`.system` repo state. Pure
- * reads — never mutates the install. `promptcuts` (a single present/absent bit
- * in {@link getAvailableResources}) is surfaced as a one-element list so it
- * compares like any other named resource.
+ * installed version ids per agent, `.agents`/`.system` repo state, and
+ * per-version sign-in. Pure reads — never mutates the install. `promptcuts` (a
+ * single present/absent bit in {@link getAvailableResources}) is surfaced as a
+ * one-element list so it compares like any other named resource.
  */
-export function collectLocalFleetInventory(cwd = process.cwd()) {
+export async function collectLocalFleetInventory(cwd = process.cwd()) {
     const available = getAvailableResources(cwd);
     const resources = {};
     for (const kind of FLEET_RESOURCE_KINDS) {
@@ -53,5 +100,6 @@ export function collectLocalFleetInventory(cwd = process.cwd()) {
             agents: toRepoState(readRepoState(getUserAgentsDir())),
             system: toRepoState(readRepoState(getSystemAgentsDir())),
         },
+        signIn: await collectLocalFleetSignIn(),
     };
 }

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

@@ -142,3 +142,28 @@ export declare function addIgnored(name: string): Promise<Set<string>>;
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was
  * not ignored. */
 export declare function removeIgnored(name: string): Promise<boolean>;
+/**
+ * Auto-launch preferences: which registered devices are eligible for Factory's
+ * auto-host selection, and which are preferred. Stored as a sibling to the
+ * registry and ignore-list under ~/.agents/.history/devices/.
+ */
+export interface AutoLaunchPreference {
+    enabled?: boolean;
+    preferred?: boolean;
+}
+export interface AutoLaunchPreferences {
+    devices: Record<string, AutoLaunchPreference>;
+    updatedAt: string;
+}
+/** Load auto-launch preferences. Missing or malformed file => empty map. */
+export declare function loadAutoLaunchPreferences(): Promise<Record<string, AutoLaunchPreference>>;
+/** True if the device is enabled for auto-launch. Missing entry defaults to true. */
+export declare function isAutoLaunchEnabled(name: string): Promise<boolean>;
+/** Set whether a device is enabled for auto-launch. Setting to the default
+ * (enabled) removes the entry to keep the file minimal. */
+export declare function setAutoLaunchEnabled(name: string, enabled: boolean): Promise<void>;
+/** True if the device is preferred for auto-launch ranking. */
+export declare function isAutoLaunchPreferred(name: string): Promise<boolean>;
+/** Set whether a device is preferred for auto-launch. Setting to the default
+ * (not preferred) removes the flag to keep the file minimal. */
+export declare function setAutoLaunchPreferred(name: string, preferred: boolean): Promise<void>;

package/dist/lib/devices/registry.js

@@ -18,7 +18,7 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
-import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+import { getDevicesRegistryPath, getDevicesIgnoredPath, getDevicesAutoLaunchPath } from '../state.js';
 /** A device's effective role, defaulting to `worker` when unset. */
 export function deviceRole(d) {
     return d.role ?? 'worker';
@@ -288,3 +288,84 @@ export async function removeIgnored(name) {
         return true;
     });
 }
+function autoLaunchPath() {
+    return getDevicesAutoLaunchPath();
+}
+/** Load auto-launch preferences. Missing or malformed file => empty map. */
+export async function loadAutoLaunchPreferences() {
+    const p = autoLaunchPath();
+    let raw;
+    try {
+        raw = await fs.readFile(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return {};
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed.devices && typeof parsed.devices === 'object' ? parsed.devices : {};
+    }
+    catch (err) {
+        throw new Error(`Device auto-launch preferences corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
+    }
+}
+/** True if the device is enabled for auto-launch. Missing entry defaults to true. */
+export async function isAutoLaunchEnabled(name) {
+    assertValidDeviceName(name);
+    const prefs = await loadAutoLaunchPreferences();
+    return prefs[name]?.enabled !== false;
+}
+/** Set whether a device is enabled for auto-launch. Setting to the default
+ * (enabled) removes the entry to keep the file minimal. */
+export async function setAutoLaunchEnabled(name, enabled) {
+    assertValidDeviceName(name);
+    const p = autoLaunchPath();
+    await withRegistryLock(p, async () => {
+        const prefs = await loadAutoLaunchPreferences();
+        if (enabled) {
+            if (prefs[name]) {
+                const { enabled: _, ...rest } = prefs[name];
+                if (Object.keys(rest).length === 0) {
+                    delete prefs[name];
+                }
+                else {
+                    prefs[name] = rest;
+                }
+            }
+        }
+        else {
+            prefs[name] = { ...prefs[name], enabled: false };
+        }
+        await atomicWriteJson(p, { devices: prefs, updatedAt: new Date().toISOString() });
+    });
+}
+/** True if the device is preferred for auto-launch ranking. */
+export async function isAutoLaunchPreferred(name) {
+    assertValidDeviceName(name);
+    const prefs = await loadAutoLaunchPreferences();
+    return prefs[name]?.preferred === true;
+}
+/** Set whether a device is preferred for auto-launch. Setting to the default
+ * (not preferred) removes the flag to keep the file minimal. */
+export async function setAutoLaunchPreferred(name, preferred) {
+    assertValidDeviceName(name);
+    const p = autoLaunchPath();
+    await withRegistryLock(p, async () => {
+        const prefs = await loadAutoLaunchPreferences();
+        if (preferred) {
+            prefs[name] = { ...prefs[name], preferred: true };
+        }
+        else if (prefs[name]) {
+            const { preferred: _, ...rest } = prefs[name];
+            if (Object.keys(rest).length === 0) {
+                delete prefs[name];
+            }
+            else {
+                prefs[name] = rest;
+            }
+        }
+        await atomicWriteJson(p, { devices: prefs, updatedAt: new Date().toISOString() });
+    });
+}

package/dist/lib/events.d.ts

@@ -13,7 +13,7 @@
  */
 import { type ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;
@@ -156,6 +156,13 @@ export declare function emitCommand(command: string, args?: string[], payload?:
  * Emit an error event with full details.
  */
 export declare function emitError(err: Error | string, payload?: EventPayload): void;
+/**
+ * Emit a friction event — a structured, point-of-use record of a failure or
+ * block the CLI just hit. `surface` is the subsystem (teams, browser, secrets,
+ * guard, …); `failureId` is a stable slug that lets the nightly routine group
+ * the same failure across sessions (e.g. 'remote-cwd-on-add', 'not-installed').
+ */
+export declare function emitFriction(surface: string, failureId: string, payload?: EventPayload): void;
 /**
  * Remove log files older than the retention period.
  * Removes numbered gzip archives whose filesystem mtime exceeds retention.

package/dist/lib/events.js

@@ -523,6 +523,19 @@ export function emitError(err, payload = {}) {
         errorStack: truncate(error.stack, 1000),
     });
 }
+/**
+ * Emit a friction event — a structured, point-of-use record of a failure or
+ * block the CLI just hit. `surface` is the subsystem (teams, browser, secrets,
+ * guard, …); `failureId` is a stable slug that lets the nightly routine group
+ * the same failure across sessions (e.g. 'remote-cwd-on-add', 'not-installed').
+ */
+export function emitFriction(surface, failureId, payload = {}) {
+    emit('friction', {
+        ...payload,
+        surface,
+        failureId,
+    });
+}
 // ─── Gzip rotation ──────────────────────────────────────────────────────────
 /** Rotate the active file while its append lock is held. */
 function maybeGzipRotateLocked(logPath) {

package/dist/lib/exec.d.ts

@@ -66,7 +66,14 @@ export declare function resolveMode(agent: AgentId, requested: Mode): Mode;
  * downgraded. This is the single source of truth shared by buildExecCommand
  * (agents run / teams) and the routine runner.
  */
-export declare function resolveHeadlessMode(agent: AgentId, requested: Mode, interactive: boolean): Mode;
+export declare function resolveHeadlessMode(agent: AgentId, requested: Mode, interactive: boolean, warningContext?: string, warningState?: ModeWarningState): Mode;
+export interface ModeWarningState {
+    /** Agents already warned about, so one run warns once per agent. A fallback
+     *  chain degrades each agent independently and the agent that actually ran is
+     *  usually not the first, so this cannot be a single boolean. */
+    emitted?: Set<AgentId>;
+    quiet?: boolean;
+}
 /**
  * The mode an agent should run in when the caller has no preference.
  *
@@ -94,6 +101,10 @@ export interface ExecOptions {
     cwd?: string;
     /** Force headless mode even when no prompt is provided (e.g. piping via stdin). */
     headless?: boolean;
+    /** Prefix for mode-degradation warnings emitted by shared headless paths. */
+    modeWarningContext?: string;
+    /** Shared across command previews/spawns/loop iterations so degradation warns once. */
+    modeWarningState?: ModeWarningState;
     json?: boolean;
     model?: string;
     addDirs?: string[];
@@ -400,8 +411,8 @@ export declare function detectAuthFailure(text: string): boolean;
  * reason logic can never catch it — the `error:"authentication_failed"` marker
  * and the `result`+`is_error` text are the reliable signals.
  *
- * Gated on the Claude stream-json shape; other agents don't emit these fields,
- * so callers pass their agent and this returns false for non-claude.
+ * Gated on the Claude-compatible stream-json shape emitted by Claude and Cursor;
+ * callers pass their agent so unrelated stream formats cannot match by accident.
  */
 export declare function detectAuthFailureEvent(logText: string, agent: AgentId): boolean;
 /**

package/dist/lib/exec.js

@@ -28,6 +28,7 @@ import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
 import { shellQuote } from './ssh-exec.js';
+import { resolveClaudeSetupToken } from './claude-account-token.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -123,10 +124,35 @@ export function resolveMode(agent, requested) {
  * downgraded. This is the single source of truth shared by buildExecCommand
  * (agents run / teams) and the routine runner.
  */
-export function resolveHeadlessMode(agent, requested, interactive) {
+export function resolveHeadlessMode(agent, requested, interactive, warningContext, warningState) {
     const mode = resolveMode(agent, requested);
+    const warn = (message) => {
+        if (warningState?.quiet)
+            return;
+        if (warningState) {
+            warningState.emitted ??= new Set();
+            if (warningState.emitted.has(agent))
+                return;
+            warningState.emitted.add(agent);
+        }
+        process.stderr.write(message);
+    };
+    if (mode !== requested) {
+        const subject = warningContext ? `${warningContext}: ` : '';
+        if (requested === 'plan') {
+            const limitation = agent === 'cursor'
+                ? "cursor's read-only plan mode is not enabled in this build"
+                : `${agent} has no read-only 'plan' mode`;
+            warn(`[agents] ${subject}${limitation}; ` +
+                `running '${mode}' (writable) instead${agent === 'cursor' ? ' (RUSH-2101)' : ''}. ` +
+                `Pass --mode ${mode} to silence this.\n`);
+        }
+        else {
+            warn(`[agents] ${subject}${agent} has no '${requested}' mode; using '${mode}'.\n`);
+        }
+    }
     if (!interactive && mode === 'plan' && AGENTS[agent].capabilities.headlessPlan === false) {
-        process.stderr.write(`warning: ${agent} has no headless plan mode; running --mode auto instead\n`);
+        warn(`warning: ${agent} has no headless plan mode; running --mode auto instead\n`);
         return resolveMode(agent, 'auto');
     }
     return mode;
@@ -259,7 +285,15 @@ export function buildExecEnv(options) {
             ? resolvedVersion
             : (resolvedVersion && isVersionInstalled('claude', resolvedVersion) ? resolvedVersion : null);
         if (version) {
-            result.CLAUDE_CONFIG_DIR = path.join(getVersionHomePath('claude', version), '.claude');
+            const versionHome = getVersionHomePath('claude', version);
+            result.CLAUDE_CONFIG_DIR = path.join(versionHome, '.claude');
+            const setupToken = resolveClaudeSetupToken(versionHome);
+            if (setupToken) {
+                // A token keyed to this version home's own account replaces any ambient
+                // shared value inherited from the launcher. options.env still wins below
+                // for explicit caller overrides.
+                result.CLAUDE_CODE_OAUTH_TOKEN = setupToken;
+            }
             // A managed pin lives in a per-version dir; Claude Code's own background
             // auto-updater would rewrite that pinned binary in place (and has left it
             // half-swapped and broken). Disable it so a pin stays a pin. Honor an
@@ -416,7 +450,6 @@ export const AGENT_COMMANDS = {
         base: ['cursor-agent'],
         promptFlag: '-p',
         modeFlags: {
-            // cursor-agent has no read-only flag; we only expose edit + skip.
             edit: [],
             skip: ['-f'],
         },
@@ -660,13 +693,18 @@ export function buildExecCommand(options) {
     //   degrades to `auto` with a stderr warning (see resolveHeadlessMode)
     // - `skip` on an unsupported agent → throws a clear error
     // After resolution, the chosen mode is guaranteed to be in template.modeFlags.
-    const resolvedMode = resolveHeadlessMode(options.agent, normalizeMode(options.mode), interactive);
+    const resolvedMode = resolveHeadlessMode(options.agent, normalizeMode(options.mode), interactive, options.modeWarningContext, options.modeWarningState);
     const modeFlags = template.modeFlags[resolvedMode];
     if (!modeFlags) {
         // Defense in depth: would only fire if AGENTS.capabilities.modes and
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
+    if (options.agent === 'cursor' && resolvedMode === 'edit' && !interactive) {
+        // A configured headless run is the workspace trust decision. Keep this
+        // narrower than --yolo/-f, which also bypasses permission checks.
+        cmd.push('--trust');
+    }
     // Codex's workspace-write sandbox blocks $HOME (verified against the live CLI
     // and OpenAI's sandbox docs: writable roots extend scope "without removing the
     // sandbox entirely"). But the model routinely shells out to `agents ...`, whose
@@ -1260,7 +1298,10 @@ async function spawnAgent(options) {
         agent: options.agent,
         version: options.version,
         cwd: options.cwd || process.cwd(),
-        mode: options.mode,
+        // The mode that ran, not the one requested — `agents run` passes the
+        // requested mode so the resolver can warn, but telemetry must agree with
+        // the audit log. See RUSH-2106 for removing that ambiguity at the source.
+        mode: resolveMode(options.agent, normalizeMode(options.mode)),
         model: options.model,
         interactive,
         sessionId: options.sessionId,
@@ -1540,6 +1581,7 @@ export function detectRateLimit(text) {
 export const AUTH_FAILURE_PATTERNS = [
     /OAuth (?:access token has been revoked|session expired)/i,
     /(?:Please run|run) \/login/i,
+    /Please run 'agent login' first/i,
     /\bNot logged in\b/i,
     /Invalid authentication credentials/i,
     /Failed to authenticate/i,
@@ -1564,11 +1606,11 @@ export function detectAuthFailure(text) {
  * reason logic can never catch it — the `error:"authentication_failed"` marker
  * and the `result`+`is_error` text are the reliable signals.
  *
- * Gated on the Claude stream-json shape; other agents don't emit these fields,
- * so callers pass their agent and this returns false for non-claude.
+ * Gated on the Claude-compatible stream-json shape emitted by Claude and Cursor;
+ * callers pass their agent so unrelated stream formats cannot match by accident.
  */
 export function detectAuthFailureEvent(logText, agent) {
-    if (agent !== 'claude')
+    if (agent !== 'claude' && agent !== 'cursor')
         return false;
     const lines = logText.split('\n');
     for (const line of lines) {

package/dist/lib/format.d.ts

@@ -27,6 +27,13 @@ export declare function formatDie(msg: string, opts?: DieOptions): {
  * keep the original red-stderr behavior.
  */
 export declare function die(msg: string, code?: number, opts?: DieOptions): never;
+/**
+ * `die()` with a structured friction event attached. Use this at CLI error
+ * chokepoints so the nightly routine can classify and rank recurring failures
+ * without re-parsing transcripts. `surface` is the subsystem (teams, browser,
+ * secrets, guard, …); `failureId` is a stable slug (e.g. 'remote-cwd-on-add').
+ */
+export declare function dieFriction(surface: string, failureId: string, msg: string, code?: number, opts?: DieOptions): never;
 /**
  * Truncate `s` to at most `max` characters, appending a single-char ellipsis
  * (`…`) when shortened. Character-count based (not ANSI/width aware — use

package/dist/lib/format.js

@@ -9,6 +9,7 @@
  */
 import chalk from 'chalk';
 import { readSync } from 'node:fs';
+import { emitFriction } from './events.js';
 /**
  * Render a fatal error to the right stream. Pure — no I/O, no `process.exit` — so
  * the human-vs-agent split is unit-testable. A `--json` caller gets
@@ -43,6 +44,16 @@ export function die(msg, code = 1, opts = {}) {
         console.error(text);
     process.exit(code);
 }
+/**
+ * `die()` with a structured friction event attached. Use this at CLI error
+ * chokepoints so the nightly routine can classify and rank recurring failures
+ * without re-parsing transcripts. `surface` is the subsystem (teams, browser,
+ * secrets, guard, …); `failureId` is a stable slug (e.g. 'remote-cwd-on-add').
+ */
+export function dieFriction(surface, failureId, msg, code = 1, opts = {}) {
+    emitFriction(surface, failureId, { error: msg });
+    die(msg, code, opts);
+}
 /**
  * Truncate `s` to at most `max` characters, appending a single-char ellipsis
  * (`…`) when shortened. Character-count based (not ANSI/width aware — use