@phnx-labs/agents-cli 1.22.32 → 1.22.34

package/dist/lib/exec.js

@@ -292,10 +292,37 @@ export function buildExecEnv(options) {
             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;
+                // The `auth` bundle's setup-token exists so a run with NO human present
+                // authenticates without the Touch-ID-gated login item — usage probes,
+                // routines, dispatched runs (claude-account-token.ts). An interactive run
+                // has a human at the TTY, and their own per-version login is the credential
+                // they established and expect; overriding it made `/status` report
+                // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
+                // hand-driven session off that login. macOS cannot cheaply confirm a home's
+                // login first (probing the Keychain raises an authorization sheet per
+                // installed version on the `agents run` hot path — agents.ts
+                // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
+                // Code, which prompts a present human to log in if the login is missing.
+                if (resolveInteractive(options)) {
+                    // Drop an INHERITED copy of the same token too: an interactive launch from
+                    // inside a headless agent's shell inherits that agent's injected value via
+                    // sanitizeProcessEnv(process.env) and would keep authenticating as it.
+                    // Matched by VALUE, so a token the user exported deliberately is a
+                    // different string and is left alone. This is NARROWER than the routines
+                    // path, which overwrites-or-deletes unconditionally and never inspects the
+                    // inherited value (`runner.ts:1020-1021`) — the gap between the two is
+                    // what RUSH-2360 tracks, including a DIFFERENT account's inherited token,
+                    // which this equality check lets through.
+                    if (result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
+                        delete result.CLAUDE_CODE_OAUTH_TOKEN;
+                    }
+                }
+                else {
+                    // 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
@@ -381,6 +408,29 @@ export function buildExecEnv(options) {
         delete result.COPILOT_HOME;
         delete result.KIMI_CODE_HOME;
     }
+    else if (options.agent === 'cursor') {
+        // Cursor has no config-dir env var (only CURSOR_API_KEY / CURSOR_API_ENDPOINT).
+        // Its OAuth token — the login gate — lives at $XDG_CONFIG_HOME/cursor/auth.json
+        // (verified empirically: relocating XDG_CONFIG_HOME relocates the login;
+        // ~/.cursor/cli-config.json holds only account metadata, not the token). Pin
+        // XDG_CONFIG_HOME into the version home so each installed Cursor account
+        // authenticates from its own token, isolated per run — no global ~/.cursor
+        // symlink swap, so concurrent runs on different accounts never clobber one
+        // another. cli-config.json (HOME-relative) has no override and stays on the
+        // shared home; only the token is per-account, which is what gates the login.
+        const cwd = options.cwd || process.cwd();
+        const resolvedVersion = options.version ?? resolveVersion('cursor', cwd);
+        const version = options.version
+            ? resolvedVersion
+            : (resolvedVersion && isVersionInstalled('cursor', resolvedVersion) ? resolvedVersion : null);
+        if (version) {
+            result.XDG_CONFIG_HOME = path.join(getVersionHomePath('cursor', version), '.config');
+        }
+        delete result.CLAUDE_CONFIG_DIR;
+        delete result.CODEX_HOME;
+        delete result.COPILOT_HOME;
+        delete result.KIMI_CODE_HOME;
+    }
     else {
         delete result.CLAUDE_CONFIG_DIR;
         delete result.CODEX_HOME;
@@ -1139,8 +1189,15 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     // a shell, while the hook runs under the agent descendant. This is the primary
     // attribution path on Windows (no lsof), so the launchId join matters most here.
     const launchId = randomUUID();
-    // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
-    // derives the per-version config-dir env); pass the agent's default to satisfy the type.
+    // mode/effort are required by ExecOptions but do not affect the env buildExecEnv
+    // derives; pass the agent's default to satisfy the type. Passing no prompt makes
+    // this resolve INTERACTIVE, so the launch authenticates from the per-version
+    // login rather than the headless `auth` setup-token (EXEC-2a) — right for the
+    // common case, someone invoking the harness binary directly. Known limit: we do
+    // not parse `rawArgs`, so a `-p "task"` passthrough is headless in fact and
+    // interactive by this classification, and loses the token. Windows-only in
+    // practice (POSIX uses the bash shim, which execs the binary and never reaches
+    // buildExecEnv — `shims.ts:749`, `shims.ts:761-764`).
     const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {

package/dist/lib/help.d.ts

@@ -19,7 +19,7 @@ export interface CommandGroup {
  */
 export declare function registerCommandGroups(parent: Command, groups: readonly CommandGroup[]): void;
 /** Examples + Notes blocks attached to a command via setHelpSections. */
-interface HelpSections {
+export interface HelpSections {
     examples?: string;
     notes?: string;
 }
@@ -32,6 +32,7 @@ interface HelpSections {
  * literals without babysitting whitespace.
  */
 export declare function setHelpSections(cmd: Command, sections: HelpSections): void;
+/** Read the workflow-first sections attached to a command for generated references. */
+export declare function getHelpSections(cmd: Command): Readonly<HelpSections>;
 /** Apply standardized help formatting to the root command and all subcommands. */
 export declare function applyGlobalHelpConventions(root: Command): void;
-export {};

package/dist/lib/help.js

@@ -19,6 +19,10 @@ const helpSectionRegistry = new WeakMap();
 export function setHelpSections(cmd, sections) {
     helpSectionRegistry.set(cmd, sections);
 }
+/** Read the workflow-first sections attached to a command for generated references. */
+export function getHelpSections(cmd) {
+    return helpSectionRegistry.get(cmd) ?? {};
+}
 /** Strip a uniform leading indent from a block and trim surrounding blank lines. */
 function dedent(body) {
     const lines = body.replace(/^\n+/, '').replace(/\s+$/, '').split('\n');

package/dist/lib/hosts/dispatch.d.ts

@@ -11,38 +11,8 @@
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
 import { type HostCredentials } from './credentials.js';
-/**
- * Derive the remote directory to mirror from the local cwd, for a host run the
- * caller gave no `--cwd`/`--remote-cwd`.
- *
- * Without this a `--host` run lands in the remote `$HOME`, so an agent launched
- * from a repo starts with no project context and the user has to `cd` by hand.
- * Only a cwd under the LOCAL home is mirrored — that is the part with a
- * meaningful remote analogue (`~/src/x` re-roots onto the remote home). A path
- * outside home returns undefined: `/opt/thing` on this box says nothing about
- * the target's filesystem, so the run keeps the remote home.
- */
-export declare function deriveMirroredCwd(localCwd: string): string | undefined;
-/**
- * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
- *
- * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
- * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
- * for that segment — the remote login shell expands it — and shell-quote the
- * remainder. Any other path (absolute or relative) is quoted verbatim.
- *
- * `mirror` marks a directory the caller DERIVED from the local cwd rather than
- * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
- * the same home-relative path on both boxes is the common fleet layout, so
- * mirroring lands the remote agent in the project instead of `$HOME`. It is a
- * best-effort mirror by definition — the host may simply not have that checkout
- * — so a missing directory falls back to the remote home instead of failing the
- * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
- * directory, so a missing one must surface as a `cd` error.
- */
-export declare function remoteCdPrefix(remoteCwd?: string, opts?: {
-    mirror?: boolean;
-}): string;
+import { deriveMirroredCwd, homeRemainder, remoteCdPrefix } from '../project-root.js';
+export { deriveMirroredCwd, homeRemainder, remoteCdPrefix };
 /**
  * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
  * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH

package/dist/lib/hosts/dispatch.js

@@ -19,72 +19,17 @@ import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { wrapHostCommandWithCredentials } from './credentials.js';
 import { hostKeyCheckingOpts } from '../devices/known-hosts.js';
-import { toRemotePortable } from '../project-root.js';
+import { deriveMirroredCwd, homeRemainder, remoteCdPrefix } from '../project-root.js';
 import { RUN_AUTO_KEYWORD, RUN_AUTO_HOST_RESOLVED_ENV } from '../types.js';
+// The home-relative portability helpers live in project-root.js (the canonical
+// home-relative conversion home), reused by the interactive `agents ssh` login
+// shell builder (devices/connect.ts) as well as this dispatch layer. Re-exported
+// here so existing `hosts/dispatch.js` importers and tests keep resolving them.
+export { deriveMirroredCwd, homeRemainder, remoteCdPrefix };
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
 const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
-/**
- * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
- * remainder (no leading slash), else null. Callers that want a local-home
- * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
- * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
- * `--remote-cwd` is left literal and so is never re-rooted here.
- */
-function homeRemainder(p) {
-    if (p === '~' || p === '$HOME')
-        return '';
-    if (p.startsWith('~/'))
-        return p.slice(2);
-    if (p.startsWith('$HOME/'))
-        return p.slice(6);
-    return null;
-}
-/**
- * Derive the remote directory to mirror from the local cwd, for a host run the
- * caller gave no `--cwd`/`--remote-cwd`.
- *
- * Without this a `--host` run lands in the remote `$HOME`, so an agent launched
- * from a repo starts with no project context and the user has to `cd` by hand.
- * Only a cwd under the LOCAL home is mirrored — that is the part with a
- * meaningful remote analogue (`~/src/x` re-roots onto the remote home). A path
- * outside home returns undefined: `/opt/thing` on this box says nothing about
- * the target's filesystem, so the run keeps the remote home.
- */
-export function deriveMirroredCwd(localCwd) {
-    const portable = toRemotePortable(localCwd);
-    return homeRemainder(portable) === null ? undefined : portable;
-}
-/**
- * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
- *
- * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
- * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
- * for that segment — the remote login shell expands it — and shell-quote the
- * remainder. Any other path (absolute or relative) is quoted verbatim.
- *
- * `mirror` marks a directory the caller DERIVED from the local cwd rather than
- * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
- * the same home-relative path on both boxes is the common fleet layout, so
- * mirroring lands the remote agent in the project instead of `$HOME`. It is a
- * best-effort mirror by definition — the host may simply not have that checkout
- * — so a missing directory falls back to the remote home instead of failing the
- * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
- * directory, so a missing one must surface as a `cd` error.
- */
-export function remoteCdPrefix(remoteCwd, opts = {}) {
-    if (!remoteCwd)
-        return '';
-    const rest = homeRemainder(remoteCwd);
-    if (rest === '')
-        return 'cd "$HOME" && ';
-    if (rest !== null) {
-        const dir = `"$HOME"/${shellQuote(rest)}`;
-        return opts.mirror ? `{ cd ${dir} || cd "$HOME"; } && ` : `cd ${dir} && `;
-    }
-    return `cd ${shellQuote(remoteCwd)} && `;
-}
 /**
  * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
  * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH

package/dist/lib/hosts/tasks.d.ts

@@ -74,3 +74,10 @@ export declare function findTaskBySessionId(sessionId: string): HostTask | null;
  * reused across dispatches.
  */
 export declare function findTaskByName(name: string): HostTask | null;
+/**
+ * Resolve a host-task reference the way `agents hosts ps/logs/stop` do: a raw
+ * dispatch id first, then a `--name` handle, then the remote agent/session id.
+ * Shared so any other caller resolving "does this ref name a detached --device
+ * dispatch?" (e.g. `agents message`) uses the identical three-way lookup.
+ */
+export declare function resolveTaskRef(ref: string): HostTask | null;

package/dist/lib/hosts/tasks.js

@@ -101,3 +101,12 @@ export function findTaskByName(name) {
     }
     return null;
 }
+/**
+ * Resolve a host-task reference the way `agents hosts ps/logs/stop` do: a raw
+ * dispatch id first, then a `--name` handle, then the remote agent/session id.
+ * Shared so any other caller resolving "does this ref name a detached --device
+ * dispatch?" (e.g. `agents message`) uses the identical three-way lookup.
+ */
+export function resolveTaskRef(ref) {
+    return loadTask(ref) ?? findTaskByName(ref) ?? findTaskBySessionId(ref);
+}

package/dist/lib/mailbox-target.d.ts

@@ -5,6 +5,7 @@
  * NEVER guessed; the caller reports it. Pure (no I/O) so it is unit-testable.
  */
 import type { ActiveSession } from './session/active.js';
+import type { HostTask } from './hosts/tasks.js';
 export type MessageResolution = {
     kind: 'cloud';
     id: string;
@@ -34,3 +35,29 @@ export declare function mailboxIdForActiveSession(s: ActiveSession): string | un
  * cloud provider.
  */
 export declare function resolveMessageTarget(target: string, sessions: ActiveSession[], isCloudTask: (id: string) => boolean): MessageResolution;
+export type HostTaskRoute = {
+    kind: 'reroute';
+    remoteRef: string;
+    host: string;
+} | {
+    kind: 'finished';
+    host: string;
+    status: string;
+    exitCode?: number;
+} | {
+    kind: 'not-found';
+};
+/**
+ * Decide how `agents message <target>` should handle a target that matched no
+ * local/cloud session (RUSH-2366 follow-up): `getActiveSessions()` has no
+ * visibility into a detached `agents run --device <host> --no-follow`
+ * dispatch, whose only local record is the `~/.agents/.cache/hosts/<id>.json`
+ * sidecar `agents hosts ps` reads. Pure — the caller does the actual lookup
+ * (`resolveTaskRef`) and I/O (the ssh reroute).
+ *
+ * `remoteRef` prefers the remote agent's OWN identity (its captured session id
+ * or `--name` handle) over the LOCAL dispatch-record id the user typed here —
+ * the live process on the host registers itself under the former, never the
+ * latter.
+ */
+export declare function decideHostTaskRoute(task: HostTask | null, target: string): HostTaskRoute;

package/dist/lib/mailbox-target.js

@@ -43,3 +43,24 @@ export function resolveMessageTarget(target, sessions, isCloudTask) {
         candidates: [...byId.entries()].map(([id, s]) => ({ id, label: labelFor(s) })),
     };
 }
+/**
+ * Decide how `agents message <target>` should handle a target that matched no
+ * local/cloud session (RUSH-2366 follow-up): `getActiveSessions()` has no
+ * visibility into a detached `agents run --device <host> --no-follow`
+ * dispatch, whose only local record is the `~/.agents/.cache/hosts/<id>.json`
+ * sidecar `agents hosts ps` reads. Pure — the caller does the actual lookup
+ * (`resolveTaskRef`) and I/O (the ssh reroute).
+ *
+ * `remoteRef` prefers the remote agent's OWN identity (its captured session id
+ * or `--name` handle) over the LOCAL dispatch-record id the user typed here —
+ * the live process on the host registers itself under the former, never the
+ * latter.
+ */
+export function decideHostTaskRoute(task, target) {
+    if (!task)
+        return { kind: 'not-found' };
+    if (task.status === 'running') {
+        return { kind: 'reroute', remoteRef: task.sessionId ?? task.name ?? target, host: task.host };
+    }
+    return { kind: 'finished', host: task.host, status: task.status, exitCode: task.exitCode };
+}

package/dist/lib/mcp.d.ts

@@ -73,6 +73,16 @@ export declare function untrustProjectMcp(cwd?: string): boolean;
 export declare function listMcpServerConfigs(cwd?: string, options?: {
     enforceProjectTrust?: boolean;
 }): InstalledMcpServer[];
+/**
+ * Parse one config during a directory SCAN. `validateMcpYamlConfig` returns null
+ * for some malformed shapes but *throws* for others (`args` not a string array,
+ * `command`/`env` of the wrong type), and a scan must not be all-or-nothing: a
+ * single bad file under `<repo>/mcp/` took down the whole of
+ * `agents inspect <repo>` with an unhandled stack trace. Skip the file and name
+ * it, exactly as a null return is already skipped. Explicit single-file
+ * operations call `parseMcpServerConfig` directly and still throw loudly.
+ */
+export declare function parseMcpConfigForScan(filePath: string): McpYamlConfig | null;
 /**
  * Scan a repository for MCP server YAML configs.
  * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.

package/dist/lib/mcp.js

@@ -219,7 +219,7 @@ export function listMcpServerConfigs(cwd = process.cwd(), options = {}) {
             if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
                 continue;
             const filePath = path.join(dir, entry.name);
-            const config = parseMcpServerConfig(filePath);
+            const config = parseMcpConfigForScan(filePath);
             if (config && !results.has(config.name)) {
                 results.set(config.name, {
                     name: config.name,
@@ -232,6 +232,25 @@ export function listMcpServerConfigs(cwd = process.cwd(), options = {}) {
     }
     return Array.from(results.values());
 }
+/**
+ * Parse one config during a directory SCAN. `validateMcpYamlConfig` returns null
+ * for some malformed shapes but *throws* for others (`args` not a string array,
+ * `command`/`env` of the wrong type), and a scan must not be all-or-nothing: a
+ * single bad file under `<repo>/mcp/` took down the whole of
+ * `agents inspect <repo>` with an unhandled stack trace. Skip the file and name
+ * it, exactly as a null return is already skipped. Explicit single-file
+ * operations call `parseMcpServerConfig` directly and still throw loudly.
+ */
+export function parseMcpConfigForScan(filePath) {
+    try {
+        return parseMcpServerConfig(filePath);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.error(`agents-cli: skipping ${filePath} — ${reason}`);
+        return null;
+    }
+}
 /**
  * Scan a repository for MCP server YAML configs.
  * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.
@@ -247,7 +266,7 @@ export function discoverMcpConfigsFromRepo(repoPath) {
         if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.yml'))
             continue;
         const filePath = path.join(dir, entry.name);
-        const config = parseMcpServerConfig(filePath);
+        const config = parseMcpConfigForScan(filePath);
         if (config) {
             results.push({ name: config.name, path: filePath, config, scope: 'user' });
         }

package/dist/lib/migrate.d.ts

@@ -168,5 +168,16 @@ export declare function migrateWatchdogSentinelToRoutine(sentinelPath?: string,
  * manually before proceeding. Exported for unit-testing with temp dirs.
  */
 export declare function migrateCliDirToClis(agentsDirs: string[]): void;
+/**
+ * Cursor's OAuth token historically lived only in the global
+ * ~/.config/cursor/auth.json, shared across every version home. Cursor runs now
+ * pin XDG_CONFIG_HOME per version home (real per-account isolation — see
+ * buildExecEnv), so the current login must be copied into the active account's
+ * version home or it would read as logged out after upgrade. The active account
+ * is the home the ~/.cursor symlink currently targets. Idempotent: skips when
+ * the home already has its own token, and a no-op for unmanaged Cursor installs
+ * (where ~/.cursor is a real dir, not a symlink into a version home).
+ */
+export declare function seedActiveCursorLoginPerVersion(): void;
 /** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;

package/dist/lib/migrate.js

@@ -2250,6 +2250,43 @@ function migrateHumans() {
         catch { /* best-effort — leave the old key if we can't rewrite */ }
     }
 }
+/**
+ * Cursor's OAuth token historically lived only in the global
+ * ~/.config/cursor/auth.json, shared across every version home. Cursor runs now
+ * pin XDG_CONFIG_HOME per version home (real per-account isolation — see
+ * buildExecEnv), so the current login must be copied into the active account's
+ * version home or it would read as logged out after upgrade. The active account
+ * is the home the ~/.cursor symlink currently targets. Idempotent: skips when
+ * the home already has its own token, and a no-op for unmanaged Cursor installs
+ * (where ~/.cursor is a real dir, not a symlink into a version home).
+ */
+export function seedActiveCursorLoginPerVersion() {
+    const realHome = process.env.AGENTS_REAL_HOME || os.homedir();
+    const globalAuth = path.join(realHome, '.config', 'cursor', 'auth.json');
+    let versionHome;
+    try {
+        if (!fs.existsSync(globalAuth))
+            return;
+        // ~/.cursor -> .../versions/cursor/<version>/home/.cursor ; the version home
+        // is that link's parent directory.
+        const link = fs.readlinkSync(path.join(realHome, '.cursor'));
+        const resolved = path.isAbsolute(link) ? link : path.resolve(realHome, link);
+        versionHome = path.dirname(resolved);
+    }
+    catch {
+        return; // not a symlink (unmanaged install) or unreadable — nothing to seed
+    }
+    if (!versionHome.includes(path.join('versions', 'cursor')))
+        return;
+    const dest = path.join(versionHome, '.config', 'cursor', 'auth.json');
+    try {
+        if (fs.existsSync(dest))
+            return;
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(globalAuth, dest);
+    }
+    catch { /* best-effort — a failed seed just means one re-login */ }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
@@ -2266,6 +2303,9 @@ export async function runMigration() {
     migratePromptcutsIntoHooks();
     migrateSystemVersionsToUser();
     mergeOverlappingVersionHomes();
+    // Cursor runs now isolate the login per version home; preserve the current
+    // login by seeding the active home's token from the legacy global copy.
+    seedActiveCursorLoginPerVersion();
     migrateRunsIntoRoutines();
     migrateTrashToHidden();
     migrateBackupsToHidden();

package/dist/lib/project-root.d.ts

@@ -24,6 +24,53 @@ export declare function expandLocalHome(p: string): string;
  * it is a literal remote path by contract.
  */
 export declare function toRemotePortable(p: string): string;
+/**
+ * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
+ * remainder (no leading slash), else null. Callers that want a local-home
+ * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
+ * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
+ * `--remote-cwd` is left literal and so is never re-rooted here.
+ *
+ * The canonical home-anchor stripper — shared by `remoteCdPrefix`,
+ * `deriveMirroredCwd`, and the interactive-login shell builder
+ * (`devices/connect.ts`), so there is exactly one notion of "the part below the
+ * home dir".
+ */
+export declare function homeRemainder(p: string): string | null;
+/**
+ * Derive the remote directory to mirror from the local cwd, for a host run the
+ * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
+ * login with no command).
+ *
+ * Without this a `--host` run — or an `agents ssh <device>` login — lands in the
+ * remote `$HOME`, so an agent launched from a repo starts with no project
+ * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
+ * mirrored — that is the part with a meaningful remote analogue (`~/src/x`
+ * re-roots onto the remote home). A path outside home returns undefined:
+ * `/opt/thing` on this box says nothing about the target's filesystem, so the
+ * run keeps the remote home.
+ */
+export declare function deriveMirroredCwd(localCwd: string): string | undefined;
+/**
+ * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
+ *
+ * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
+ * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
+ * for that segment — the remote login shell expands it — and shell-quote the
+ * remainder. Any other path (absolute or relative) is quoted verbatim.
+ *
+ * `mirror` marks a directory the caller DERIVED from the local cwd rather than
+ * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
+ * the same home-relative path on both boxes is the common fleet layout, so
+ * mirroring lands the remote agent in the project instead of `$HOME`. It is a
+ * best-effort mirror by definition — the host may simply not have that checkout
+ * — so a missing directory falls back to the remote home instead of failing the
+ * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
+ * directory, so a missing one must surface as a `cd` error.
+ */
+export declare function remoteCdPrefix(remoteCwd?: string, opts?: {
+    mirror?: boolean;
+}): string;
 /** The configured projects root (home-relative or absolute), or undefined when unset. */
 export declare function getProjectRoot(): string | undefined;
 /** Set (override) the cached projects root. Stored home-relative when under `$HOME`. */

package/dist/lib/project-root.js

@@ -18,6 +18,7 @@ import { readMeta, updateMeta } from './state.js';
 import { getMainRepoRoot } from './git.js';
 import { toPosix } from './platform/index.js';
 import { loadProjectDef, resolveDefinedProjectPath } from './projects.js';
+import { shellQuote } from './ssh-exec.js';
 const HOME = process.env.HOME ?? os.homedir();
 /** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
 export function toHomeRelative(abs) {
@@ -53,6 +54,73 @@ export function toRemotePortable(p) {
         return toHomeRelative(p);
     return p;
 }
+/**
+ * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
+ * remainder (no leading slash), else null. Callers that want a local-home
+ * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
+ * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
+ * `--remote-cwd` is left literal and so is never re-rooted here.
+ *
+ * The canonical home-anchor stripper — shared by `remoteCdPrefix`,
+ * `deriveMirroredCwd`, and the interactive-login shell builder
+ * (`devices/connect.ts`), so there is exactly one notion of "the part below the
+ * home dir".
+ */
+export function homeRemainder(p) {
+    if (p === '~' || p === '$HOME')
+        return '';
+    if (p.startsWith('~/'))
+        return p.slice(2);
+    if (p.startsWith('$HOME/'))
+        return p.slice(6);
+    return null;
+}
+/**
+ * Derive the remote directory to mirror from the local cwd, for a host run the
+ * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
+ * login with no command).
+ *
+ * Without this a `--host` run — or an `agents ssh <device>` login — lands in the
+ * remote `$HOME`, so an agent launched from a repo starts with no project
+ * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
+ * mirrored — that is the part with a meaningful remote analogue (`~/src/x`
+ * re-roots onto the remote home). A path outside home returns undefined:
+ * `/opt/thing` on this box says nothing about the target's filesystem, so the
+ * run keeps the remote home.
+ */
+export function deriveMirroredCwd(localCwd) {
+    const portable = toRemotePortable(localCwd);
+    return homeRemainder(portable) === null ? undefined : portable;
+}
+/**
+ * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
+ *
+ * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
+ * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
+ * for that segment — the remote login shell expands it — and shell-quote the
+ * remainder. Any other path (absolute or relative) is quoted verbatim.
+ *
+ * `mirror` marks a directory the caller DERIVED from the local cwd rather than
+ * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
+ * the same home-relative path on both boxes is the common fleet layout, so
+ * mirroring lands the remote agent in the project instead of `$HOME`. It is a
+ * best-effort mirror by definition — the host may simply not have that checkout
+ * — so a missing directory falls back to the remote home instead of failing the
+ * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
+ * directory, so a missing one must surface as a `cd` error.
+ */
+export function remoteCdPrefix(remoteCwd, opts = {}) {
+    if (!remoteCwd)
+        return '';
+    const rest = homeRemainder(remoteCwd);
+    if (rest === '')
+        return 'cd "$HOME" && ';
+    if (rest !== null) {
+        const dir = `"$HOME"/${shellQuote(rest)}`;
+        return opts.mirror ? `{ cd ${dir} || cd "$HOME"; } && ` : `cd ${dir} && `;
+    }
+    return `cd ${shellQuote(remoteCwd)} && `;
+}
 /** The configured projects root (home-relative or absolute), or undefined when unset. */
 export function getProjectRoot() {
     return readMeta().projectRoot;

package/dist/lib/secrets/agent.d.ts

@@ -263,7 +263,7 @@ export declare function brokerPidAlive(): boolean;
 export declare function runSecretsAgent(opts?: {
     service?: boolean;
 }): Promise<{
-    close(): void;
+    close(): void | Promise<void>;
 } | null>;
 /**
  * Host the secrets broker inside the always-on daemon (#416).
@@ -284,8 +284,15 @@ export declare function runSecretsAgent(opts?: {
  * or null off-darwin (nothing to broker without biometry).
  */
 export declare function startHostedBroker(): Promise<{
-    close(): void;
+    close(): void | Promise<void>;
 } | null>;
+/**
+ * Call Node's net.Server.close() and wait for the 'close' event (or a bounded
+ * timeout). Without this, close() returned while the listen socket could still
+ * be held — a successor bind could race EADDRINUSE against a half-closed server
+ * (RUSH-2421). Pure side-effect helper; never throws.
+ */
+export declare function closeServerBounded(server: net.Server, timeoutMs?: number): Promise<void>;
 /** True if a broker socket exists at all. Cheap; gates the sync read so the
  * never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;