@phnx-labs/agents-cli 1.20.87 → 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/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

@@ -124,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;
@@ -425,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'],
         },
@@ -669,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
@@ -1269,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,
@@ -1549,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,
@@ -1573,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/project-resources.js

@@ -2,7 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
 import { supports } from './capabilities.js';
-import { buildCommandSkillContent, commandSkillName, readSkillSourceCommandMarker, shouldInstallCommandAsSkill } from './command-skills.js';
+import { buildCommandSkillContent, commandSkillName, readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill } from './command-skills.js';
 import { commandAppliesTo, parseCommandMetadata } from './commands.js';
 import { markdownToToml } from './convert.js';
 import { safeJoin } from './paths.js';
@@ -134,6 +134,7 @@ function skip(dest, projectRoot, result) {
 function syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {
     const cfg = AGENTS[agent];
     const commandsAsSkills = shouldInstallCommandAsSkill(agent, version);
+    const commandsAlsoAsSkills = shouldAlsoInstallCommandAsSkill(agent, version);
     const supportsCommands = supports(agent, 'commands', version).ok;
     if (!commandsAsSkills && !supportsCommands)
         return;
@@ -146,37 +147,50 @@ function syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result
         const metadata = parseCommandMetadata(srcFile);
         if (!commandAppliesTo(agent, version, metadata).ok)
             continue;
-        if (commandsAsSkills) {
+        const written = [];
+        if (commandsAsSkills || commandsAlsoAsSkills) {
             const sourceMarker = readSkillSourceCommandMarker(name, [path.join(projectAgentsDir, 'skills')]);
-            if (pathExists(path.join(projectAgentsDir, 'skills', name)) && sourceMarker !== name)
-                continue;
-            const skillName = commandSkillName(name);
-            const rel = path.join('skills', skillName);
-            const destDir = path.join(agentRoot, rel);
-            if (pathExists(destDir)) {
-                skip(destDir, projectRoot, result);
+            if (pathExists(path.join(projectAgentsDir, 'skills', name)) && sourceMarker !== name) {
+                if (commandsAsSkills)
+                    continue;
+            }
+            else {
+                const skillName = commandSkillName(name);
+                const rel = path.join('skills', skillName);
+                const destDir = path.join(agentRoot, rel);
+                if (pathExists(destDir)) {
+                    skip(destDir, projectRoot, result);
+                }
+                else {
+                    fs.mkdirSync(destDir, { recursive: true });
+                    fs.writeFileSync(path.join(destDir, 'SKILL.md'), buildCommandSkillContent(name, srcFile), 'utf-8');
+                    written.push(rel);
+                }
+            }
+            if (commandsAsSkills) {
+                if (written.length > 0)
+                    record('commands', name, written, result, manifestPaths);
                 continue;
             }
-            fs.mkdirSync(destDir, { recursive: true });
-            fs.writeFileSync(path.join(destDir, 'SKILL.md'), buildCommandSkillContent(name, srcFile), 'utf-8');
-            record('commands', name, [rel], result, manifestPaths);
-            continue;
         }
         const ext = cfg.format === 'toml' ? '.toml' : '.md';
         const rel = path.join(cfg.commandsSubdir, `${name}${ext}`);
         const destFile = path.join(agentRoot, rel);
         if (pathExists(destFile)) {
             skip(destFile, projectRoot, result);
-            continue;
-        }
-        fs.mkdirSync(path.dirname(destFile), { recursive: true });
-        if (cfg.format === 'toml') {
-            fs.writeFileSync(destFile, markdownToToml(name, fs.readFileSync(srcFile, 'utf-8')), 'utf-8');
         }
         else {
-            fs.copyFileSync(srcFile, destFile);
+            fs.mkdirSync(path.dirname(destFile), { recursive: true });
+            if (cfg.format === 'toml') {
+                fs.writeFileSync(destFile, markdownToToml(name, fs.readFileSync(srcFile, 'utf-8')), 'utf-8');
+            }
+            else {
+                fs.copyFileSync(srcFile, destFile);
+            }
+            written.push(rel);
         }
-        record('commands', name, [rel], result, manifestPaths);
+        if (written.length > 0)
+            record('commands', name, written, result, manifestPaths);
     }
 }
 function syncProjectSkills(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {

package/dist/lib/runner.d.ts

@@ -23,6 +23,9 @@ export interface RunResult {
     meta: RunMeta;
     reportPath: string | null;
 }
+/** Agents the daemon can actually run, derived from the command table above
+ * so the `--agent` help and any validation can never drift from it. */
+export declare const ROUTINE_AGENT_IDS: readonly string[];
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
 export declare function archiveRoutineTranscripts(meta: Pick<RunMeta, 'jobName' | 'runId' | 'agent'>, runDir: string, overlayHome?: string): void;
@@ -63,7 +66,7 @@ export declare function dispatchesViaAgentsRun(config: Pick<JobConfig, 'workflow
  * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
  * with `agents run`.
  */
-export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, agent: AgentId, version: string | undefined, timezone?: string): Record<string, string>;
+export declare function buildRoutineSpawnEnv(baseEnv: Record<string, string>, agent: AgentId, version: string | undefined, timezone?: string, overlayHome?: string): Record<string, string>;
 export declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
 /**
  * Optional lifecycle callbacks for a detached routine run. The daemon passes an
@@ -80,5 +83,15 @@ export interface RoutineHooks {
 export declare function executeJobDetached(config: JobConfig, hooks?: RoutineHooks): Promise<RunMeta>;
 /** Extract the final assistant message from a stream-JSON log file as a markdown report. */
 export declare function extractReport(stdoutPath: string, agentType: AgentId): string | null;
+/** Derive the final status of a detached run by reading the agent's stream-json
+ *  tail. Detached children fire-and-forget, so we never see their exit code
+ *  directly — but Claude's stream-json terminates with a `type: result` line
+ *  that carries `is_error`. If we find it, the run completed cleanly (modulo
+ *  agent-reported error). If not, the process likely died mid-stream and the
+ *  caller should treat the run as failed. */
+export declare function inferFinalStatusFromLog(stdoutPath: string, agent: AgentId): {
+    status: 'completed' | 'failed';
+    exitCode: number;
+} | null;
 /** Scan all runs marked "running" and finalize any whose process has exited. */
 export declare function monitorRunningJobs(): void;

package/dist/lib/runner.js

@@ -32,17 +32,23 @@ import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
 import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
+import { isSelfUpdatingAgent } from './agents.js';
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
     codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
+    cursor: ['cursor-agent', '-p', '{prompt}', '--output-format', 'stream-json'],
     kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
     droid: ['droid', 'exec', '{prompt}', '-o', 'stream-json'],
 };
+/** Agents the daemon can actually run, derived from the command table above
+ * so the `--agent` help and any validation can never drift from it. */
+export const ROUTINE_AGENT_IDS = Object.freeze(Object.keys(AGENT_COMMANDS));
 const ROUTINE_TRANSCRIPT_SPECS = {
     claude: [{ root: ['.claude', 'projects'], ext: '.jsonl' }],
     codex: [{ root: ['.codex', 'sessions'], ext: '.jsonl' }],
+    cursor: [{ root: ['.cursor', 'projects'], ext: '.jsonl' }],
 };
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
@@ -133,6 +139,20 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         appendModelAndReasoning(cmd, config);
     }
+    if (config.agent === 'cursor') {
+        // cursor-agent supports --plan, but the capability registry has not been
+        // upgraded yet. RUSH-2101 tracks adding that read-only mode after PR #1721.
+        const cursorMode = resolveHeadlessMode('cursor', mode, false, `routine ${config.name}`);
+        if (cursorMode === 'skip') {
+            cmd.push('-f');
+        }
+        else {
+            // The configured cwd is the user's workspace trust decision. --trust is
+            // narrower than --yolo/-f because it does not bypass tool permissions.
+            cmd.push('--trust');
+        }
+        appendModelAndReasoning(cmd, config);
+    }
     if (config.agent === 'kimi') {
         // kimi daemon jobs always run headless via `--prompt`, which cannot be
         // combined with any startup-mode flag (--plan/--auto/--yolo all abort with
@@ -385,7 +405,7 @@ export function dispatchesViaAgentsRun(config) {
  * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
  * with `agents run`.
  */
-export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
+export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone, overlayHome) {
     const execEnv = buildExecEnv({
         agent,
         version,
@@ -415,6 +435,11 @@ export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
     // provisioned box does. Drop it here so a routine always uses the login of the
     // machine it runs on.
     delete out.CLAUDE_CODE_OAUTH_TOKEN;
+    if (agent === 'cursor' && overlayHome) {
+        // prepareJobHome links this host's Cursor auth file here. Pin XDG_CONFIG_HOME
+        // to the overlay so an ambient value cannot bypass the routine sandbox.
+        out.XDG_CONFIG_HOME = path.join(overlayHome, '.config');
+    }
     if (timezone)
         out.TZ = timezone;
     return out;
@@ -621,16 +646,20 @@ export async function executeJob(config, deps) {
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     // Loop path: delegate to runLoop (same driver as `agents run --loop` / workflow loop:).
     if (config.loop) {
-        const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone);
+        const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone, overlayHome);
         const execOptions = {
             agent: effectiveAgent,
-            version: primaryVersion,
+            // Routine-supported self-updating CLIs (Cursor/Droid) use one global
+            // binary; a versioned shim would point at a nonexistent isolated install.
+            version: isSelfUpdatingAgent(effectiveAgent) ? undefined : primaryVersion,
             prompt: resolvedPrompt,
             mode: normalizeMode(config.mode),
             effort: config.effort,
             env: spawnEnv,
             json: true,
             headless: true,
+            modeWarningContext: `routine ${config.name}`,
+            modeWarningState: {},
             ...(config.config?.model ? { model: config.config.model } : {}),
             ...(config.allow?.dirs ? {
                 addDirs: config.allow.dirs
@@ -681,7 +710,7 @@ export async function executeJob(config, deps) {
                     e.TZ = config.timezone;
                 return e;
             })()
-            : buildRoutineSpawnEnv(baseEnv, attemptAgent, attemptVersion, config.timezone);
+            : buildRoutineSpawnEnv(baseEnv, attemptAgent, attemptVersion, config.timezone, overlayHome);
         // Remaining timeout budget shared across failover attempts.
         const elapsed = Date.now() - Date.parse(meta.startedAt);
         const remaining = Math.max(1_000, timeoutMs - (Number.isFinite(elapsed) ? elapsed : 0));
@@ -1067,7 +1096,7 @@ export async function executeJobDetached(config, hooks) {
             return e;
         })()
         // Non-command path only: config.agent is always set here (command/workflow branch earlier).
-        : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone);
+        : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone, overlayHome);
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
@@ -1262,7 +1291,7 @@ export function extractReport(stdoutPath, agentType) {
         for (const line of lines) {
             try {
                 const parsed = JSON.parse(line);
-                if (agentType === 'claude') {
+                if (agentType === 'claude' || agentType === 'cursor') {
                     if (parsed.type === 'assistant' && parsed.message?.content) {
                         for (const block of parsed.message.content) {
                             if (block.type === 'text' && block.text) {
@@ -1298,7 +1327,7 @@ export function extractReport(stdoutPath, agentType) {
  *  that carries `is_error`. If we find it, the run completed cleanly (modulo
  *  agent-reported error). If not, the process likely died mid-stream and the
  *  caller should treat the run as failed. */
-function inferFinalStatusFromLog(stdoutPath, agent) {
+export function inferFinalStatusFromLog(stdoutPath, agent) {
     if (!fs.existsSync(stdoutPath))
         return null;
     try {
@@ -1309,7 +1338,7 @@ function inferFinalStatusFromLog(stdoutPath, agent) {
         for (let i = lines.length - 1, scanned = 0; i >= 0 && scanned < 20; i--, scanned++) {
             try {
                 const parsed = JSON.parse(lines[i]);
-                if (agent === 'claude' && parsed.type === 'result') {
+                if ((agent === 'claude' || agent === 'cursor') && parsed.type === 'result') {
                     return parsed.is_error
                         ? { status: 'failed', exitCode: 1 }
                         : { status: 'completed', exitCode: 0 };

package/dist/lib/sandbox.d.ts

@@ -21,6 +21,8 @@ export declare function buildSpawnEnv(overlayHome: string, extraEnv?: Record<str
 export declare function getJobHomePath(name: string): string;
 /** Create a fresh overlay HOME for a job, including agent config and allowed-dir symlinks. */
 export declare function prepareJobHome(config: JobConfig): string;
+/** Link this host's Cursor login and CLI config into the disposable overlay. */
+export declare function generateCursorConfig(overlayHome: string): void;
 /** Remove a job's overlay HOME directory entirely. */
 export declare function cleanJobHome(name: string): void;
 /** Symlink allowed directories into the overlay HOME, skipping paths outside the real HOME. */