@phnx-labs/agents-cli 1.22.33 → 1.22.34

package/dist/lib/browser/sessions-list.d.ts

@@ -1,3 +1,4 @@
+import type { SessionMeta } from '../session/types.js';
 export type ArtifactKind = 'screenshot' | 'pdf' | 'recording' | 'download';
 export interface BrowserArtifact {
     kind: ArtifactKind;
@@ -19,6 +20,10 @@ export declare function listProfileArtifacts(profile: string): BrowserArtifact[]
  * when empty); otherwise every profile dir on disk that has at least one capture.
  */
 export declare function listBrowserSessions(only?: string): ProfileArtifacts[];
+export declare function formatBytes(n: number): string;
+/** Per-kind counts over a flat artifact list — shared by the printed table and
+ *  the interactive row labels. */
+export declare function countByKind(artifacts: BrowserArtifact[]): Record<ArtifactKind, number>;
 /** Human table for the CLI. Returns lines (no trailing newline). */
 export declare function renderBrowserSessions(groups: ProfileArtifacts[]): string;
 /**
@@ -28,6 +33,82 @@ export declare function renderBrowserSessions(groups: ProfileArtifacts[]): strin
 export declare function resolveArtifact(groups: ProfileArtifacts[], selector: string): string | null;
 /** Open a file in the OS default app. Returns true on success. */
 export declare function openArtifact(filePath: string): boolean;
+/** The identity fields this module cares about from a profile's `tasks.json`. */
+export interface TaskIdentity {
+    owner?: string;
+    launchId?: string;
+}
+/**
+ * Read a profile's `tasks.json` for the identity of its CURRENTLY LIVE tasks,
+ * keyed by task name. A task's entry is deleted on `agents browser stop` (see
+ * service.ts `saveTaskState`), so a task whose run has already ended is absent
+ * here even though its captures remain on disk — that is exactly the
+ * "unlinked legacy task" case {@link groupIntoRows} reports. Same read-straight-
+ * from-disk approach as the rest of this module: works whether or not the
+ * browser daemon is running.
+ */
+export declare function loadTaskIdentities(profile: string): Map<string, TaskIdentity>;
+/** launchId -> indexed session id, built once from every source that records
+ *  this join, so a task-heavy profile resolves without re-scanning per task. */
+export interface LaunchSessionIndex {
+    byLaunchId: Map<string, string>;
+}
+/**
+ * Build the launchId -> sessionId index from the same three sources
+ * `feed-post.ts` `resolvePostIdentity` already uses for this exact problem —
+ * a browser task's `launchId` IS the `AGENT_LAUNCH_ID` of the CLI run that
+ * called `agents browser start` (see service.ts `resolveTaskIdentity`), so
+ * resolving "which session ran this launch" is the same join, not a new one.
+ * Lowest-confidence source first so a later, more specific source overwrites
+ * it on a collision:
+ *  1. the activity log (durable, but least specific — read last)
+ *  2. the SessionStart hook's live-session index (kept for parity with
+ *     `hook-sessions.ts`; empty on this fleet today, harmless when so)
+ *  3. the per-pid launch registry (`ag run`, launch-scoped, most authoritative)
+ * Computed once per interactive session, not per row.
+ */
+export declare function buildLaunchSessionIndex(): LaunchSessionIndex;
+/** Resolve one launchId through the index to its canonical `SessionMeta`, or
+ *  `null` when the join has no hit or the resolved session isn't indexed here. */
+export declare function resolveLaunchSession(index: LaunchSessionIndex, launchId: string): SessionMeta | null;
+/** Why a row carries no session digest: `linked` resolved one, `unresolved`
+ *  has a launchId but no matching indexed session, `unlinked` has no launchId
+ *  at all (a legacy task, or one whose owning run already stopped). */
+export type BrowserSessionLinkStatus = 'linked' | 'unresolved' | 'unlinked';
+/** One task-first row: every capture for one browser task (or, for
+ *  `kind: 'downloads'`, one profile's downloads bucket), plus the agent
+ *  session it links to when resolvable. */
+export interface BrowserSessionRow {
+    kind: 'task' | 'downloads';
+    profile: string;
+    /** Task name; undefined for the downloads row. */
+    task?: string;
+    owner?: string;
+    launchId?: string;
+    linkStatus: BrowserSessionLinkStatus;
+    linkedSession?: SessionMeta;
+    /** Newest first. */
+    artifacts: BrowserArtifact[];
+    counts: Record<ArtifactKind, number>;
+    /** Most recent capture's mtime — the row's sort/age key. */
+    latestMtimeMs: number;
+}
+/**
+ * Group flat per-profile artifacts into task-first rows, newest first. Pure:
+ * identities and the launch resolver are passed in, so this has no filesystem
+ * or session-index dependency and is unit-testable with synthetic data (see
+ * {@link buildBrowserSessionRows} for the impure disk/index-reading caller).
+ */
+export declare function groupIntoRows(groups: ProfileArtifacts[], taskIdentities: Map<string, Map<string, TaskIdentity>>, resolveLaunch?: (launchId: string) => SessionMeta | null): BrowserSessionRow[];
+/** Build task-first rows for one profile (or every profile with captures),
+ *  reading `tasks.json` and resolving launchIds against the live indexes.
+ *  The interactive picker's data source. */
+export declare function buildBrowserSessionRows(profile?: string): BrowserSessionRow[];
+/**
+ * Search predicate for the interactive picker: task name, profile, the linked
+ * session's agent/topic/label, and any artifact filename in the row.
+ */
+export declare function matchesBrowserSessionRow(row: BrowserSessionRow, query: string): boolean;
 /**
  * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
  * `open` is the Commander value for `--open [selector]`: undefined when the flag

package/dist/lib/browser/sessions-list.js

@@ -4,12 +4,25 @@
  * Reads straight from `.cache/browser/<profile>/`, so it works whether or not the
  * browser daemon is running. Backs both `agents browser sessions` and the
  * `agents sessions --browser` alias.
+ *
+ * Also owns the task-first grouping (RUSH-2407): browser captures are per-task
+ * (`sessions/<task>/`), and a task persists `owner`/`launchId` in `tasks.json`
+ * while it is live (see service.ts `resolveTaskIdentity`). This module groups
+ * artifacts by task and, when a launchId is available, resolves it to the
+ * agent session that ran it — reusing the session index (`getSessionById`) and
+ * the same launchId join keys the rest of the CLI already uses for this exact
+ * problem (pid registry, the SessionStart hook index, the activity log; see
+ * `feed-post.ts` `resolvePostIdentity`), never a second parser.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
 import { formatRelativeTime } from '../session/relative-time.js';
+import { getSessionById } from '../session/db.js';
+import { listPidSessionEntries } from '../session/pid-registry.js';
+import { loadHookSessionIndex } from '../session/hook-sessions.js';
+import { readRecentActivity } from '../activity.js';
 const EXT_KIND = {
     '.png': 'screenshot',
     '.jpg': 'screenshot',
@@ -100,7 +113,7 @@ export function listBrowserSessions(only) {
         .map((p) => ({ profile: p, artifacts: listProfileArtifacts(p) }))
         .filter((r) => !!only || r.artifacts.length > 0);
 }
-function formatBytes(n) {
+export function formatBytes(n) {
     if (n < 1024)
         return `${n} B`;
     const units = ['KB', 'MB', 'GB'];
@@ -112,15 +125,21 @@ function formatBytes(n) {
     }
     return `${val < 10 ? val.toFixed(1) : Math.round(val)} ${units[i]}`;
 }
+/** Per-kind counts over a flat artifact list — shared by the printed table and
+ *  the interactive row labels. */
+export function countByKind(artifacts) {
+    const counts = { screenshot: 0, pdf: 0, recording: 0, download: 0 };
+    for (const a of artifacts)
+        counts[a.kind]++;
+    return counts;
+}
 /** Human table for the CLI. Returns lines (no trailing newline). */
 export function renderBrowserSessions(groups) {
     if (groups.length === 0)
         return 'No browser profiles found.';
     const lines = [];
     for (const g of groups) {
-        const counts = { screenshot: 0, pdf: 0, recording: 0, download: 0 };
-        for (const a of g.artifacts)
-            counts[a.kind]++;
+        const counts = countByKind(g.artifacts);
         lines.push(`${g.profile}  ` +
             `screenshots ${counts.screenshot}  pdfs ${counts.pdf}  recordings ${counts.recording}  downloads ${counts.download}`);
         if (g.artifacts.length === 0) {
@@ -161,6 +180,162 @@ export function openArtifact(filePath) {
     }
     return false;
 }
+/**
+ * Read a profile's `tasks.json` for the identity of its CURRENTLY LIVE tasks,
+ * keyed by task name. A task's entry is deleted on `agents browser stop` (see
+ * service.ts `saveTaskState`), so a task whose run has already ended is absent
+ * here even though its captures remain on disk — that is exactly the
+ * "unlinked legacy task" case {@link groupIntoRows} reports. Same read-straight-
+ * from-disk approach as the rest of this module: works whether or not the
+ * browser daemon is running.
+ */
+export function loadTaskIdentities(profile) {
+    const out = new Map();
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(getProfileRuntimeDir(profile), 'tasks.json'), 'utf8');
+    }
+    catch {
+        return out;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return out;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return out;
+    for (const [name, value] of Object.entries(parsed)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const t = value;
+        out.set(name, {
+            owner: typeof t.owner === 'string' ? t.owner : undefined,
+            launchId: typeof t.launchId === 'string' ? t.launchId : undefined,
+        });
+    }
+    return out;
+}
+/**
+ * Build the launchId -> sessionId index from the same three sources
+ * `feed-post.ts` `resolvePostIdentity` already uses for this exact problem —
+ * a browser task's `launchId` IS the `AGENT_LAUNCH_ID` of the CLI run that
+ * called `agents browser start` (see service.ts `resolveTaskIdentity`), so
+ * resolving "which session ran this launch" is the same join, not a new one.
+ * Lowest-confidence source first so a later, more specific source overwrites
+ * it on a collision:
+ *  1. the activity log (durable, but least specific — read last)
+ *  2. the SessionStart hook's live-session index (kept for parity with
+ *     `hook-sessions.ts`; empty on this fleet today, harmless when so)
+ *  3. the per-pid launch registry (`ag run`, launch-scoped, most authoritative)
+ * Computed once per interactive session, not per row.
+ */
+export function buildLaunchSessionIndex() {
+    const byLaunchId = new Map();
+    for (const ev of readRecentActivity({ maxBytesPerSession: 64 * 1024 })) {
+        if (ev.launchId && ev.sessionId)
+            byLaunchId.set(ev.launchId, ev.sessionId);
+    }
+    for (const [launchId, rec] of loadHookSessionIndex().byLaunchId) {
+        if (rec.session_id)
+            byLaunchId.set(launchId, rec.session_id);
+    }
+    for (const entry of listPidSessionEntries()) {
+        if (entry.launchId && entry.sessionId)
+            byLaunchId.set(entry.launchId, entry.sessionId);
+    }
+    return { byLaunchId };
+}
+/** Resolve one launchId through the index to its canonical `SessionMeta`, or
+ *  `null` when the join has no hit or the resolved session isn't indexed here. */
+export function resolveLaunchSession(index, launchId) {
+    const sessionId = index.byLaunchId.get(launchId);
+    return sessionId ? getSessionById(sessionId) : null;
+}
+/**
+ * Group flat per-profile artifacts into task-first rows, newest first. Pure:
+ * identities and the launch resolver are passed in, so this has no filesystem
+ * or session-index dependency and is unit-testable with synthetic data (see
+ * {@link buildBrowserSessionRows} for the impure disk/index-reading caller).
+ */
+export function groupIntoRows(groups, taskIdentities, resolveLaunch) {
+    const rows = [];
+    for (const g of groups) {
+        const identities = taskIdentities.get(g.profile) ?? new Map();
+        const byTask = new Map();
+        const downloads = [];
+        for (const a of g.artifacts) {
+            if (a.kind === 'download' || !a.task) {
+                downloads.push(a);
+                continue;
+            }
+            const list = byTask.get(a.task) ?? [];
+            list.push(a);
+            byTask.set(a.task, list);
+        }
+        for (const [task, artifacts] of byTask) {
+            artifacts.sort((a, b) => b.mtimeMs - a.mtimeMs);
+            const identity = identities.get(task);
+            const linkedSession = identity?.launchId ? resolveLaunch?.(identity.launchId) ?? null : null;
+            rows.push({
+                kind: 'task',
+                profile: g.profile,
+                task,
+                owner: identity?.owner,
+                launchId: identity?.launchId,
+                linkStatus: linkedSession ? 'linked' : identity?.launchId ? 'unresolved' : 'unlinked',
+                linkedSession: linkedSession ?? undefined,
+                artifacts,
+                counts: countByKind(artifacts),
+                latestMtimeMs: artifacts[0]?.mtimeMs ?? 0,
+            });
+        }
+        if (downloads.length > 0) {
+            downloads.sort((a, b) => b.mtimeMs - a.mtimeMs);
+            rows.push({
+                kind: 'downloads',
+                profile: g.profile,
+                linkStatus: 'unlinked',
+                artifacts: downloads,
+                counts: countByKind(downloads),
+                latestMtimeMs: downloads[0]?.mtimeMs ?? 0,
+            });
+        }
+    }
+    rows.sort((a, b) => b.latestMtimeMs - a.latestMtimeMs);
+    return rows;
+}
+/** Build task-first rows for one profile (or every profile with captures),
+ *  reading `tasks.json` and resolving launchIds against the live indexes.
+ *  The interactive picker's data source. */
+export function buildBrowserSessionRows(profile) {
+    const groups = listBrowserSessions(profile);
+    const taskIdentities = new Map(groups.map((g) => [g.profile, loadTaskIdentities(g.profile)]));
+    const index = buildLaunchSessionIndex();
+    return groupIntoRows(groups, taskIdentities, (launchId) => resolveLaunchSession(index, launchId));
+}
+/**
+ * Search predicate for the interactive picker: task name, profile, the linked
+ * session's agent/topic/label, and any artifact filename in the row.
+ */
+export function matchesBrowserSessionRow(row, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return true;
+    if (row.task?.toLowerCase().includes(q))
+        return true;
+    if (row.profile.toLowerCase().includes(q))
+        return true;
+    if (row.kind === 'downloads' && 'downloads'.includes(q))
+        return true;
+    const s = row.linkedSession;
+    if (s && (s.agent.toLowerCase().includes(q) || s.topic?.toLowerCase().includes(q) || s.label?.toLowerCase().includes(q))) {
+        return true;
+    }
+    return row.artifacts.some((a) => a.name.toLowerCase().includes(q));
+}
 /**
  * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
  * `open` is the Commander value for `--open [selector]`: undefined when the flag

package/dist/lib/daemon.js

@@ -1176,11 +1176,22 @@ export function startDaemon(agentsBin) {
         const pid = waitForPid(3000);
         return { pid, method: 'already-starting' };
     }
+    // Released by startDaemonLocked the moment the launch has been ISSUED, and
+    // again here as the backstop for every path that returned before reaching
+    // that point (a throw, or the platform default branch). Idempotent so the
+    // double call is a no-op rather than unlinking a lock a later claimer owns.
+    let released = false;
+    const releaseOnce = () => {
+        if (released)
+            return;
+        released = true;
+        releaseLock();
+    };
     try {
-        return startDaemonLocked(agentsBin ?? getAgentsBinPath());
+        return startDaemonLocked(agentsBin ?? getAgentsBinPath(), releaseOnce);
     }
     finally {
-        releaseLock();
+        releaseOnce();
     }
 }
 /**
@@ -1207,8 +1218,33 @@ export function ensureDaemonStarted() {
         return null;
     }
 }
-function startDaemonLocked(agentsBin) {
+/**
+ * Issue the launch, then wait for the child to record its pid.
+ *
+ * RUSH-2417: the wait phase MUST NOT hold the start lock. `acquireStartLock`
+ * and `claimDaemonInstance` resolve the same `<daemonDir>/daemon.lock`, so a
+ * parent that busy-waits on `waitForPid` while still holding it deterministically
+ * defeats the child it just launched: the child's `claimDaemonInstance` hits
+ * EEXIST, reads a holder pid that IS alive (this process), and exits with the
+ * false "another daemon is mid-takeover" warning — every launchd/systemd start
+ * on a fresh install. The lock's job is to keep two concurrent `startDaemon()`
+ * calls from both launching, and that is done once `launchctl load` /
+ * `systemctl start` / the detached spawn has been issued, so `releaseLock()` is
+ * called there rather than in the caller's `finally`.
+ *
+ * Releasing early cannot produce two daemons: launchd (one plist label) and
+ * systemd (one unit) are singletons that no-op a second start, and the detached
+ * path is covered by `claimDaemonInstance`'s last-wins takeover (SING-11) —
+ * a second claimer evicts the incumbent rather than running beside it.
+ */
+function startDaemonLocked(agentsBin, releaseLock) {
     const platform = os.platform();
+    // Same contract on the fallback path: the spawn IS the launch, so the lock is
+    // dropped before the child exists rather than in a `finally` the child races.
+    const detachedFallback = () => {
+        releaseLock();
+        return startDetached({ agentsBin });
+    };
     if (platform === 'darwin') {
         try {
             const plistPath = getLaunchdPlistPath();
@@ -1229,6 +1265,8 @@ function startDaemonLocked(agentsBin) {
             // of success. If no pid materializes within the window, give up on
             // launchd and fall through to a plain detached spawn.
             execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+            // Launch issued — the child needs this lock to claim (RUSH-2417).
+            releaseLock();
             const pid = waitForPid(3000) ?? readServiceManagerPid();
             if (pid)
                 return { pid, method: 'launchd' };
@@ -1237,7 +1275,7 @@ function startDaemonLocked(agentsBin) {
         catch {
             // load threw — fall through to detached spawn
         }
-        return startDetached({ agentsBin });
+        return detachedFallback();
     }
     if (platform === 'linux') {
         try {
@@ -1252,6 +1290,8 @@ function startDaemonLocked(agentsBin) {
             execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });
+            // Launch issued — the child needs this lock to claim (RUSH-2417).
+            releaseLock();
             const pid = waitForPid(3000) ?? readServiceManagerPid();
             if (pid)
                 return { pid, method: 'systemd' };
@@ -1261,7 +1301,7 @@ function startDaemonLocked(agentsBin) {
         catch {
             // start threw — fall through to detached spawn
         }
-        return startDetached({ agentsBin });
+        return detachedFallback();
     }
     return startDetached({ agentsBin });
 }

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

@@ -37,6 +37,30 @@ export declare function fleetDialTarget(device: DeviceProfile): string;
  * login).
  */
 export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
+/**
+ * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
+ * mirrored project directory, falling back to the remote home when that
+ * directory is absent. Returns undefined when there is nothing to mirror
+ * (`mirrorCwd` is undefined, or resolves to the home root itself) so the caller
+ * keeps the plain no-command interactive login.
+ *
+ * This is the interactive analogue of `agents run --host`'s cwd mirroring, and
+ * it reuses the SAME machinery so there is no second resolver: the portable
+ * `mirrorCwd` comes from `deriveMirroredCwd`, and — for POSIX — the best-effort
+ * `cd` comes from `remoteCdPrefix({ mirror: true })`, whose `|| cd "$HOME"`
+ * guarantees a missing checkout never fails the login (acceptance #2). It then
+ * replaces the wrapper with a login shell (`exec "$SHELL" -l`); running under
+ * the forced tty (`-tt`, see {@link buildSshInvocation}) makes that login shell
+ * interactive, so prompt, startup files, and login behavior match a plain
+ * `ssh <host>` (acceptance #1).
+ *
+ * PowerShell hosts get a profile-loading interactive shell (`-NoExit`, and
+ * deliberately NOT `-NoProfile` so the user's profile still runs) that
+ * `Set-Location`s into the mirrored dir when it exists. The path is carried
+ * through `-EncodedCommand` (base64 UTF-16LE), so it is literal and
+ * injection-safe regardless of spaces or shell metacharacters (acceptance #3).
+ */
+export declare function buildInteractiveShellCommand(device: DeviceProfile, mirrorCwd: string | undefined): string | undefined;
 /** Host-key posture for {@link buildSshInvocation}. */
 export interface SshHostKeyOptions {
     /**
@@ -65,9 +89,18 @@ export declare function deviceIdentityArgs(device: DeviceProfile): string[];
  * `opts.agentOnly` marks the connection as a read-only probe: for password auth
  * it sets {@link ASKPASS_AGENT_ONLY_ENV} in the overlay so the askpass resolve
  * stays broker-only and never pops a foreground biometric (RUSH-1970).
+ *
+ * `opts.interactiveCwd` is the portable (`~/…`) directory to mirror on an
+ * interactive login (no `cmd`) — from `deriveMirroredCwd(process.cwd())`. When
+ * it names a real home-relative sub-path, the login starts there via
+ * {@link buildInteractiveShellCommand} (best-effort — a missing dir falls back
+ * to the remote home), matching `agents run --host`. It is ignored when a `cmd`
+ * is given: an explicit command keeps its current cwd (the remote home) and its
+ * behavior unchanged (RUSH-2412).
  */
 export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions, opts?: {
     agentOnly?: boolean;
+    interactiveCwd?: string;
 }): {
     args: string[];
     env: Record<string, string>;

package/dist/lib/devices/connect.js

@@ -18,6 +18,7 @@ import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { getCliLaunch } from '../cli-entry.js';
 import { encodePwshBase64 } from '../pwsh.js';
+import { homeRemainder, remoteCdPrefix } from '../project-root.js';
 import { getCacheDir } from '../state.js';
 import { hostKeyCheckingOpts } from './known-hosts.js';
 import { hostNameFor } from './ssh-config.js';
@@ -82,6 +83,48 @@ export function wrapRemoteCommand(device, cmd) {
     }
     return joined;
 }
+/**
+ * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
+ * mirrored project directory, falling back to the remote home when that
+ * directory is absent. Returns undefined when there is nothing to mirror
+ * (`mirrorCwd` is undefined, or resolves to the home root itself) so the caller
+ * keeps the plain no-command interactive login.
+ *
+ * This is the interactive analogue of `agents run --host`'s cwd mirroring, and
+ * it reuses the SAME machinery so there is no second resolver: the portable
+ * `mirrorCwd` comes from `deriveMirroredCwd`, and — for POSIX — the best-effort
+ * `cd` comes from `remoteCdPrefix({ mirror: true })`, whose `|| cd "$HOME"`
+ * guarantees a missing checkout never fails the login (acceptance #2). It then
+ * replaces the wrapper with a login shell (`exec "$SHELL" -l`); running under
+ * the forced tty (`-tt`, see {@link buildSshInvocation}) makes that login shell
+ * interactive, so prompt, startup files, and login behavior match a plain
+ * `ssh <host>` (acceptance #1).
+ *
+ * PowerShell hosts get a profile-loading interactive shell (`-NoExit`, and
+ * deliberately NOT `-NoProfile` so the user's profile still runs) that
+ * `Set-Location`s into the mirrored dir when it exists. The path is carried
+ * through `-EncodedCommand` (base64 UTF-16LE), so it is literal and
+ * injection-safe regardless of spaces or shell metacharacters (acceptance #3).
+ */
+export function buildInteractiveShellCommand(device, mirrorCwd) {
+    if (!mirrorCwd)
+        return undefined;
+    const rest = homeRemainder(mirrorCwd);
+    // Only a real sub-path of the home dir is worth mirroring; the home root
+    // itself (rest === '') is where a plain login already lands, and a
+    // non-home-anchored path (rest === null) has no meaningful remote analogue.
+    if (rest === null || rest === '')
+        return undefined;
+    if (device.shell === 'powershell') {
+        // Single-quoted PowerShell literal: the only escape inside '…' is '' for a
+        // literal quote, so this is injection-safe for any path.
+        const literal = rest.replace(/'/g, "''");
+        const script = `$d = Join-Path -Path $HOME -ChildPath '${literal}'; ` +
+            `if (Test-Path -LiteralPath $d) { Set-Location -LiteralPath $d }`;
+        return `powershell -NoLogo -NoExit -EncodedCommand ${encodePwshBase64(script)}`;
+    }
+    return `${remoteCdPrefix(mirrorCwd, { mirror: true })}exec "$SHELL" -l`;
+}
 /** OpenSSH argv that makes an explicit device key authoritative. */
 export function deviceIdentityArgs(device) {
     return device.auth?.method === 'key' && device.auth.identityFile
@@ -101,10 +144,24 @@ export function deviceIdentityArgs(device) {
  * `opts.agentOnly` marks the connection as a read-only probe: for password auth
  * it sets {@link ASKPASS_AGENT_ONLY_ENV} in the overlay so the askpass resolve
  * stays broker-only and never pops a foreground biometric (RUSH-1970).
+ *
+ * `opts.interactiveCwd` is the portable (`~/…`) directory to mirror on an
+ * interactive login (no `cmd`) — from `deriveMirroredCwd(process.cwd())`. When
+ * it names a real home-relative sub-path, the login starts there via
+ * {@link buildInteractiveShellCommand} (best-effort — a missing dir falls back
+ * to the remote home), matching `agents run --host`. It is ignored when a `cmd`
+ * is given: an explicit command keeps its current cwd (the remote home) and its
+ * behavior unchanged (RUSH-2412).
  */
 export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}, opts = {}) {
     const target = sshTargetFor(device);
-    const remote = wrapRemoteCommand(device, cmd);
+    // No cmd ⇒ interactive login. It may still carry a derived cd+login-shell
+    // wrapper (interactiveCwd), which is an interactive login too and still needs
+    // a real tty below.
+    const interactive = cmd.length === 0;
+    const remote = interactive
+        ? buildInteractiveShellCommand(device, opts.interactiveCwd)
+        : wrapRemoteCommand(device, cmd);
     const env = {};
     const args = [
         ...hostKeyCheckingOpts(hostKey.pinned ?? false, hostKey.knownHostsFile),
@@ -126,8 +183,9 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}, o
         args.push('-o', 'BatchMode=yes');
         args.push(...deviceIdentityArgs(device));
     }
-    // An interactive login (no remote command) needs a real tty.
-    if (!remote)
+    // An interactive login needs a real tty — whether it starts a bare login
+    // shell (no remote command) or the derived cd+login-shell mirror.
+    if (interactive)
         args.push('-tt');
     args.push(target);
     if (remote)

package/dist/lib/devices/doctor-findings.d.ts

@@ -55,8 +55,10 @@ export interface DoctorFinding {
  * The exact remediation for a finding. Login fixes are harness-native
  * (`loginHint`); a per-version login is offered ONLY for agents that isolate the
  * credential per home (`agents run <agent>@<version>` then log in) — for
- * gemini/antigravity/droid/cursor the login is shared, so we say so instead of
- * faking a per-version fix. Every other kind maps to its canonical command.
+ * gemini/antigravity/droid the login is shared, so we say so instead of
+ * faking a per-version fix. (Cursor now isolates its token per version home via
+ * XDG_CONFIG_HOME — see buildExecEnv — so it gets the per-version run.) Every
+ * other kind maps to its canonical command.
  */
 export declare function remediationFor(finding: DoctorFinding): string;
 export interface LocalFindingInputs {

package/dist/lib/devices/doctor-findings.js

@@ -168,8 +168,10 @@ function sortedAgentIds(ids) {
  * The exact remediation for a finding. Login fixes are harness-native
  * (`loginHint`); a per-version login is offered ONLY for agents that isolate the
  * credential per home (`agents run <agent>@<version>` then log in) — for
- * gemini/antigravity/droid/cursor the login is shared, so we say so instead of
- * faking a per-version fix. Every other kind maps to its canonical command.
+ * gemini/antigravity/droid the login is shared, so we say so instead of
+ * faking a per-version fix. (Cursor now isolates its token per version home via
+ * XDG_CONFIG_HOME — see buildExecEnv — so it gets the per-version run.) Every
+ * other kind maps to its canonical command.
  */
 export function remediationFor(finding) {
     const { kind, agent, version } = finding;