@phnx-labs/agents-cli 1.20.42 → 1.20.43

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 1.20.43
+
+- **NEW: `agents run --name <slug>` — a durable, human/agent-friendly handle for any run.** An agent that dispatches another agent had no cheap status handle: the host-task id was never even printed (the `--no-follow` tip showed a literal `<id>` placeholder), and only Claude's session id is known up front (pre-minted `--session-id`) — every other agent's id is discovered later by scanning transcripts, so callers fell back to `agents logs`, which dumps the raw, token-heavy transcript. `--name` is chosen at launch, agent-agnostic, and stored on the structures that already back these views: a first-class `name` column on `sessions.db` (schema v9, additive, no rescan) parallel to `label` — `agents sessions <ref>` resolves against **both** name and label; the HostTask sidecar (forwarded to the remote run, so `agents hosts ps` gains a NAME column and `agents hosts logs <name>` resolves by name); and a run-name sidecar (`~/.agents/.cache/run-names/`) that joins a local run's name onto the index by id every scan via `syncNames` — the same idempotent pattern as `/rename` label sync. The `name` column is deliberately left out of the upsert `ON CONFLICT … SET` clause, so a discovery rescan can never null an existing name (regression-tested in `db.names.test.ts`). Omitting `--name` is a strict no-op: `name` stays unset and every id-based path is unchanged. The `--no-follow` dispatch tip now prints the real handle and steers to the compact `agents sessions` digest over the raw log. Source: `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/session/{db,run-names,discover}.ts`, `apps/cli/src/lib/hosts/{dispatch,tasks}.ts`.
+- **New terminals (and teammates) no longer launch into a rate-limited account; `balanced` is now the default run strategy.** Two coupled fixes. (1) A bare `agents run <agent>` — every new agent terminal the extension spawns, and every non-version-pinned `agents teams add`/`start` teammate, since both route through bare `agents run` — used to default to the `available` strategy, which *prefers the pinned default version when it looks healthy*. But "healthy" was judged by the router's `getRoutingUsedPercent`, which **excluded the 5-hour session window** and looked at weekly usage only. So a session-maxed account with weekly headroom (e.g. session 100% / week 60%) was deemed eligible and kept getting launched — while `agents view` showed it "rate-limited" (its badge, `deriveUsageStatusFromSnapshot`, *counts* the session window). The router and the badge disagreed. Now `hasUsageAvailable` shares the badge's exact signal: an account maxed on **any** blocking window (session or weekly) is ineligible and skipped by both `available` and `balanced` — you never spin up an agent on an account that can't serve the next request. Capacity *weighting* still ranks eligible accounts by weekly headroom, so a brief session spike doesn't distort long-run routing. (2) The default strategy is now `balanced` (was `available`): a bare run spreads load across all healthy accounts by remaining headroom instead of sticking to the pinned default. Override per-workspace with `run.<agent>.strategy` in `agents.yaml`, or per-invocation with `--strategy` / `-b`. Source: `apps/cli/src/lib/rotate.ts`, `apps/cli/src/lib/usage.ts`, `apps/cli/src/commands/exec.ts`.
+- **[browser] Logins survive browser restarts: sandboxed profiles keep memory-only session cookies, without restoring tabs.** Sites that issue login cookies with `expires=-1` (idealista, many banking/classifieds sites) logged the profile out on every browser restart, because Chromium purges memory-only session cookies at startup unless the session-restore preference is set — a constraint that had already leaked into agent designs as "sessions can't survive restarts". Every launch now pins `session.restore_on_startup: 1` ("continue where you left off") in the profile's `Default/Preferences`, which is the switch Chromium's cookie purge actually keys off — and pairs it with `--no-startup-window` so the *visible* side of restore never happens: no window exists at startup for restore to fill, no ghost tabs from the last task reopen, and the task flow creates its own tab over CDP exactly as before. Verified live on Windows/Comet: a memory-only cookie planted pre-restart was still present after a full stop/start, with OS-level window enumeration confirming a single window and zero restored tabs. The Preferences patch runs pre-spawn (browser down, so Chromium can't overwrite it on exit), stamps the profile name only on first launch, skips malformed files untouched, and is a no-op when already set. Electron profiles keep the old name-only seeding — they manage their own storage and need their startup window (the CDP driver binds to it). Bare `agents browser start` (no `--url`) recreates the old startup-window affordance by opening a blank page target when none exists, unregistered on the task like the startup window always was. Server-side session TTLs still apply — this removes the restart logout, not the site's own expiry. Source: `apps/cli/src/lib/browser/chrome.ts` (`ensureProfilePreferences`, launch args), `apps/cli/src/lib/browser/service.ts`.
+- **Security fix: `agents sessions --host <target>` no longer accepts a leading-dash target (SSH argv-flag smuggling).** `session/remote.ts` carried its own copy of `assertValidSshTarget` that omitted the `host.startsWith('-')` guard every other SSH path enforces, so a bare flag like `-l` or `-F/path` — which passes the character allowlist — was handed straight to `ssh` as an argument (`-oProxyCommand=…`-class injection) before any connection. The duplicate validator (and its `SSH_TARGET_RE`) is deleted; `runRemoteSessions` now routes through the canonical `assertValidSshTarget` in `ssh-exec.ts`, whose dash guard is already regression-tested (`ssh-exec.test.ts`). Source: `apps/cli/src/lib/session/remote.ts`.
+
 ## 1.20.42
 
 - **Fix: exiting a split pane inside an interactive `ag run` session kicked you out of tmux entirely.** When you split the window of an interactive agent session (`ag run claude`) with Ctrl-b `"`/`%` and then `exit`ed *your* split, the whole tmux client detached and dumped you back to the parent shell — even though the agent was still running in the other pane. Cause: `runInTmux` installed a session-wide `pane-died` hook (`detach-client`) meant to fire only when the AGENT pane exits (so the attach returns and the exit status is read), but with no `#{hook_pane}` guard it fired for *any* pane's death. The hook is now scoped to the agent pane; a user split that exits is closed in place (`kill-pane`, no lingering dead husk) and the agent keeps running full-window. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/tmux/session.test.ts`.

package/dist/commands/exec.js

@@ -218,12 +218,13 @@ export function registerRunCommand(program) {
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
         .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
+        .option('--name <slug>', 'Give the run a durable name — a stable handle you can check on later with `agents sessions <name>` (and `agents hosts logs <name>` for --host runs), instead of an opaque id. Optional; omitting it keeps today\'s id-only behavior.')
         .option('--verbose', 'Show detailed execution logs')
         .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
-        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then pinned. (Legacy `rotate` accepted as alias for `balanced`.)')
+        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then balanced (spreads load across healthy accounts and skips any that are rate-limited). (Legacy `rotate` accepted as alias for `balanced`.)')
         .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for gemini, claude (via @zed-industries/claude-code-acp adapter). Unified event stream; emits ndjson when --json.')
         .option('-y, --yes', 'Skip the interactive budget-confirm prompt (require_confirm_over). Never skips a hard budget block.', false)
         .option('--loop', 'Re-inject the prompt/entrypoint each iteration until a stop condition (issue #332). Guards (--max-iterations, --budget, --until) are enforced outside the agent. Writes a checkpoint after every iteration for --resume-checkpoint.')
@@ -275,9 +276,10 @@ export function registerRunCommand(program) {
         Legacy 'full' is silently rewritten to 'skip'.
 
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
-        pinned     use the workspace/global pinned version (default)
-        available  use pinned if usage available; otherwise switch to another signed-in version
-        balanced   distribute load across healthy accounts by remaining capacity
+        pinned     use the workspace/global pinned version
+        available  use pinned if it can run right now; otherwise switch to another signed-in version
+        balanced   distribute load across healthy accounts by remaining capacity (default)
+        A version/account is skipped when it is rate-limited right now — any usage window (incl. the 5-hour session window) at 100%, matching the 'agents view' badge.
         --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
 
       Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
@@ -404,15 +406,22 @@ export function registerRunCommand(program) {
                     model: options.model,
                     remoteCwd: options.remoteCwd,
                     sessionId: hostSessionId,
+                    name: options.name,
                     resume: resumeId,
                     follow: options.follow !== false,
                 });
                 // Register the dispatched run in the LOCAL session index so it shows
-                // up in `agents sessions` and resolves by id, even though its
+                // up in `agents sessions` and resolves by id/name, even though its
                 // transcript lives on the host. No-op when no session id was captured.
                 registerHostSession(task, { cwd: process.cwd(), prompt });
                 if (options.follow === false) {
-                    console.log(chalk.green(`Dispatched to ${host.name}.`) + chalk.gray(' Track: agents hosts ps · Follow: agents hosts logs <id> -f'));
+                    // The handle the caller uses to check on the run: the name if given,
+                    // else the real host-task id (never the old literal `<id>`). Steer
+                    // to the compact `agents sessions` digest over the raw log first.
+                    const handle = task.name ?? task.id;
+                    console.log(chalk.green(`Dispatched to ${host.name}${task.name ? ` as "${task.name}"` : ''}.`) + '\n' +
+                        chalk.gray(`  Status:  agents sessions ${handle}`) + chalk.gray('   (compact digest — use this)') + '\n' +
+                        chalk.gray(`  Raw log: agents hosts logs ${handle} -f`) + chalk.gray('   (heavy, only if needed)'));
                     process.exit(0);
                 }
                 // -1 = the follow window closed but the run continues on the host (the
@@ -1062,6 +1071,7 @@ export function registerRunCommand(program) {
             json: options.json,
             headless: options.headless,
             sessionId: resumeSessionId ?? options.sessionId,
+            name: options.name,
             resume: resumeNative,
             verbose: options.verbose,
             raw: options.raw,

package/dist/commands/hosts.js

@@ -15,7 +15,7 @@ import { sshTargetFor } from '../lib/hosts/types.js';
 import { listSshConfigHosts, listKnownHosts, isSshConfigHost } from '../lib/hosts/ssh-config.js';
 import { probeHost, remoteAgentsVersion, bootstrapAgentsCli, localCliVersion, } from '../lib/hosts/ready.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { listTasks } from '../lib/hosts/tasks.js';
+import { listTasks, loadTask, findTaskByName, findTaskBySessionId } from '../lib/hosts/tasks.js';
 import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
 import { showHostTaskLog } from '../lib/hosts/logs.js';
 /** Parse `user@host` or `host` into its pieces. */
@@ -179,18 +179,22 @@ async function doPs(json) {
         return;
     }
     const cols = terminalWidth();
-    console.log(chalk.bold('ID').padEnd(11) + chalk.bold('HOST').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
+    console.log(chalk.bold('ID').padEnd(11) + chalk.bold('NAME').padEnd(16) + chalk.bold('HOST').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
     for (const t of tasks) {
         const status = t.status === 'completed' ? chalk.green(t.status) : t.status === 'failed' ? chalk.red(t.status) : chalk.yellow(t.status);
+        const nameCol = truncateToWidth(t.name ?? chalk.gray('-'), 15).padEnd(16);
         // Prompt fills the remaining width instead of a fixed 50-char byte slice (98-char rows).
-        const promptCol = truncateToWidth(t.prompt, Math.max(12, cols - (11 + 16 + 10 + 11)));
-        console.log(t.id.padEnd(11) + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
+        const promptCol = truncateToWidth(t.prompt, Math.max(12, cols - (11 + 16 + 16 + 10 + 11)));
+        console.log(t.id.padEnd(11) + nameCol + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
     }
 }
-async function doLogs(id, follow) {
+async function doLogs(ref, follow) {
+    // Resolve the ref as a task id first, then fall back to a `--name` handle so
+    // `agents hosts logs <name>` works, not just the opaque id.
+    const id = loadTask(ref) ? ref : (findTaskByName(ref)?.id ?? findTaskBySessionId(ref)?.id ?? ref);
     const res = await showHostTaskLog(id, follow);
     if (!res.found) {
-        console.log(chalk.red(`Unknown task "${id}".`));
+        console.log(chalk.red(`Unknown task "${ref}".`));
         process.exitCode = 1;
         return;
     }

package/dist/lib/browser/chrome.d.ts

@@ -36,6 +36,28 @@ export declare function getRunningChromeInfo(profileName: string): {
     pid: number;
     port: number;
 } | null;
+/**
+ * Prepare `<userDataDir>/Default/Preferences` before launch.
+ *
+ * Two concerns, one write:
+ *  - First launch (file absent): stamp the agents-cli profile name so
+ *    Chromium's UI shows "<profile>" instead of its default "Person 1".
+ *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
+ *  - Every launch (when `persistSessionCookies`): pin
+ *    `session.restore_on_startup: 1` ("continue where you left off").
+ *    Chromium purges memory-only session cookies at startup UNLESS this
+ *    preference says the session will be restored — it keys the purge off
+ *    the pref, not off tabs actually reopening. Sites like idealista issue
+ *    login cookies with `expires=-1`, so without this every browser restart
+ *    silently logs the profile out. The visible tab-restore side effect is
+ *    suppressed separately via `--no-startup-window` (see launchBrowser).
+ *
+ * Runs only while the browser is down (called before spawn), so Chromium
+ * can't overwrite the patch on exit. Best-effort: a malformed existing file
+ * is left untouched (Chromium recovers its own state better than we can),
+ * and any I/O hiccup is silently ignored.
+ */
+export declare function ensureProfilePreferences(userDataDir: string, profileName: string, persistSessionCookies: boolean): void;
 /**
  * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
  * (lsof doesn't exist there). Returns false on any tooling error so port

package/dist/lib/browser/chrome.js

@@ -212,11 +212,11 @@ isElectron = false) {
     const runtimeDir = getProfileRuntimeDir(profileName);
     const userDataDir = path.join(runtimeDir, 'chrome-data');
     fs.mkdirSync(userDataDir, { recursive: true });
-    // First-launch seed: stamp the user-data-dir's Default/Preferences with
-    // the agents-cli profile name so Chromium's UI shows "<profile>" instead
-    // of its default "Person 1". Done only when the file doesn't exist —
-    // subsequent launches inherit whatever Chrome wrote in the meantime.
-    seedDefaultProfileName(userDataDir, profileName);
+    // Pre-launch Preferences pass: first-launch profile-name stamp, plus (for
+    // real browsers, not Electron apps) the session-cookie persistence pin.
+    // Electron apps manage their own storage and don't read Chromium's
+    // `session.*` prefs, so they get the name stamp only.
+    ensureProfilePreferences(userDataDir, profileName, !isElectron);
     // Chromium on macOS coordinates instances via the SingletonLock file
     // *inside* each user-data-dir. Direct binary spawn with a fresh
     // --user-data-dir creates a fully independent process — the user's
@@ -242,6 +242,14 @@ isElectron = false) {
         // remote-debugging transport is active. That property is the loudest
         // signal Cloudflare Turnstile, hCaptcha, and similar checks read.
         '--disable-blink-features=AutomationControlled',
+        // Companion to `session.restore_on_startup: 1` (see
+        // ensureProfilePreferences): the pref keeps session cookies alive across
+        // restarts, but on its own it would also reopen last session's tabs at
+        // startup. Suppressing the startup window leaves restore nothing to fill —
+        // cookies survive, no ghost tabs — and the task flow creates its own tab
+        // over CDP anyway. Electron apps need their window to appear (the CDP
+        // driver binds to it), so they skip the flag.
+        ...(isElectron ? [] : ['--no-startup-window']),
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -325,20 +333,52 @@ export function getRunningChromeInfo(profileName) {
     return { pid: rt.pid, port: rt.port };
 }
 /**
- * Stamp `<userDataDir>/Default/Preferences` with our profile name so
- * Chrome's UI labels the window with the agents-cli name rather than the
- * default "Person 1". Only writes when the file is absent (first launch).
- * Best-effort: any I/O hiccup is silently ignored; missing the rename is
- * cosmetic, not functional.
+ * Prepare `<userDataDir>/Default/Preferences` before launch.
+ *
+ * Two concerns, one write:
+ *  - First launch (file absent): stamp the agents-cli profile name so
+ *    Chromium's UI shows "<profile>" instead of its default "Person 1".
+ *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
+ *  - Every launch (when `persistSessionCookies`): pin
+ *    `session.restore_on_startup: 1` ("continue where you left off").
+ *    Chromium purges memory-only session cookies at startup UNLESS this
+ *    preference says the session will be restored — it keys the purge off
+ *    the pref, not off tabs actually reopening. Sites like idealista issue
+ *    login cookies with `expires=-1`, so without this every browser restart
+ *    silently logs the profile out. The visible tab-restore side effect is
+ *    suppressed separately via `--no-startup-window` (see launchBrowser).
+ *
+ * Runs only while the browser is down (called before spawn), so Chromium
+ * can't overwrite the patch on exit. Best-effort: a malformed existing file
+ * is left untouched (Chromium recovers its own state better than we can),
+ * and any I/O hiccup is silently ignored.
  */
-function seedDefaultProfileName(userDataDir, profileName) {
+export function ensureProfilePreferences(userDataDir, profileName, persistSessionCookies) {
     const defaultDir = path.join(userDataDir, 'Default');
     const prefsPath = path.join(defaultDir, 'Preferences');
-    if (fs.existsSync(prefsPath))
+    let prefs;
+    try {
+        prefs = JSON.parse(fs.readFileSync(prefsPath, 'utf8'));
+        if (typeof prefs !== 'object' || prefs === null)
+            return; // not ours to fix
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            return; // unreadable/malformed: leave alone
+    }
+    const firstLaunch = prefs === undefined;
+    if (firstLaunch)
+        prefs = { profile: { name: profileName } };
+    let dirty = firstLaunch;
+    if (persistSessionCookies && prefs.session?.restore_on_startup !== 1) {
+        prefs.session = { ...prefs.session, restore_on_startup: 1 };
+        dirty = true;
+    }
+    if (!dirty)
         return;
     try {
         fs.mkdirSync(defaultDir, { recursive: true });
-        fs.writeFileSync(prefsPath, JSON.stringify({ profile: { name: profileName } }));
+        fs.writeFileSync(prefsPath, JSON.stringify(prefs));
     }
     catch { /* not critical */ }
 }

package/dist/lib/browser/service.js

@@ -310,6 +310,19 @@ export class BrowserService {
             conn = await this.connectProfile(effectiveProfile, resolved.target);
             this.connections.set(composite, conn);
         }
+        // Browsers launch with --no-startup-window (session-cookie persistence,
+        // see launchBrowser), so a bare `start` with no --url would otherwise
+        // leave the user staring at a process with zero windows. Recreate the
+        // old startup-window affordance: if no page target exists, open a blank
+        // one. Deliberately NOT registered on the task — the startup window
+        // never was either, and tasks track only tabs they created.
+        if (!opts.url && !conn.electron) {
+            const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+            if (!targetInfos.some((t) => t.type === 'page')) {
+                await conn.cdp.send('Target.createTarget', { url: 'about:blank' });
+                this.invalidateTargetCache(conn);
+            }
+        }
         const task = {
             id: taskId,
             name: taskName,

package/dist/lib/exec.d.ts

@@ -80,6 +80,13 @@ export interface ExecOptions {
     addDirs?: string[];
     timeout?: string;
     sessionId?: string;
+    /**
+     * Durable `agents run --name <slug>` handle. Exported to the agent's env as
+     * `AGENT_SESSION_NAME` (companion to `AGENT_SESSION_ID`) and, when a session
+     * id is known at launch, recorded in the run-name index so `agents sessions
+     * <name>` resolves the run. Absent for unnamed runs — no behavior change.
+     */
+    name?: string;
     /**
      * Resume the conversation named by `sessionId` using the agent's NATIVE resume
      * form (claude `--resume`, codex `resume`) instead of the default `--session-id`

package/dist/lib/exec.js

@@ -17,6 +17,7 @@ import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js'
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
@@ -257,6 +258,12 @@ export function buildExecEnv(options) {
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
     }
+    // Export the run's durable name (companion to AGENT_SESSION_ID) so a
+    // SessionStart hook / the agent can associate its transcript with the handle
+    // the user gave the run. Only set when --name was passed.
+    if (options.name) {
+        result.AGENT_SESSION_NAME = options.name;
+    }
     return {
         ...result,
         ...options.env,
@@ -900,6 +907,12 @@ async function spawnAgent(options) {
     if (options.agent === 'claude' && !options.resume && !options.sessionId) {
         options = { ...options, sessionId: randomUUID() };
     }
+    // Record the run's --name against its session id (when both are known at
+    // launch) so `agents sessions <name>` resolves it. Best-effort; unnamed runs
+    // and agents whose id isn't known up front simply skip this.
+    if (options.name && options.sessionId) {
+        recordRunName({ sessionId: options.sessionId, name: options.name, agent: options.agent, cwd: options.cwd });
+    }
     const cmd = buildExecCommand(options);
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;

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

@@ -27,6 +27,11 @@ export interface DispatchOptions {
      * resumable by id. Mutually exclusive with `resume`.
      */
     sessionId?: string;
+    /**
+     * Durable `--name <slug>` handle, forwarded to the remote `agents run` and
+     * recorded on the local task so `agents hosts logs/ps <name>` resolve it.
+     */
+    name?: string;
     /** Resume an existing session on the host by id (via `agents run --resume`). */
     resume?: string;
     /** Stream progress and block until completion (default true). */

package/dist/lib/hosts/dispatch.js

@@ -62,6 +62,7 @@ async function launchDetached(host, target, opts) {
         prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
         sessionId: opts.sessionId,
+        name: opts.name,
         remoteLog,
         remoteExit,
         status: 'running',
@@ -96,6 +97,8 @@ export function buildRunForwardedArgs(opts) {
         args.push('--mode', opts.mode);
     if (opts.model)
         args.push('--model', opts.model);
+    if (opts.name)
+        args.push('--name', opts.name);
     if (opts.resume)
         args.push('--resume', opts.resume);
     else if (opts.sessionId)
@@ -115,6 +118,7 @@ export async function dispatchToHost(host, opts) {
         timeoutMs: opts.timeoutMs,
         agentLabel: opts.agent,
         promptLabel: opts.prompt,
+        name: opts.name,
         // On resume the remote session keeps its existing id; record that id so the
         // task stays mapped to the same session.
         sessionId: opts.resume ?? opts.sessionId,

package/dist/lib/hosts/session-index.js

@@ -36,6 +36,7 @@ export function hostSessionMeta(task, ctx) {
         filePath: '',
         topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
         label: `[host/${task.host}]`,
+        name: task.name,
     };
 }
 /**

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

@@ -15,6 +15,14 @@ export interface HostTask {
     agent: string;
     prompt: string;
     pid?: number;
+    /**
+     * The durable `agents run --name <slug>` handle for this dispatch, if given.
+     * Chosen at launch and agent-agnostic (unlike sessionId), so `agents hosts
+     * ps/logs <name>` and the dispatch tip can reference the run by a stable name
+     * even for agents that never expose a session id up front. Absent when the
+     * run was launched without `--name`.
+     */
+    name?: string;
     /**
      * The agent session id the remote run was launched with (Claude only — the
      * only agent that accepts `--session-id` to force a NEW session's id). Lets
@@ -52,3 +60,10 @@ export declare function listTasks(): HostTask[];
  * with the same forced id resolves to the most recent dispatch.
  */
 export declare function findTaskBySessionId(sessionId: string): HostTask | null;
+/**
+ * Find the newest host task launched with `--name <name>`, so `agents hosts
+ * logs/ps <name>` and resolve-by-handle can address a run by its durable name.
+ * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
+ * reused across dispatches.
+ */
+export declare function findTaskByName(name: string): HostTask | null;

package/dist/lib/hosts/tasks.js

@@ -85,3 +85,19 @@ export function findTaskBySessionId(sessionId) {
     }
     return null;
 }
+/**
+ * Find the newest host task launched with `--name <name>`, so `agents hosts
+ * logs/ps <name>` and resolve-by-handle can address a run by its durable name.
+ * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
+ * reused across dispatches.
+ */
+export function findTaskByName(name) {
+    if (!name)
+        return null;
+    const wanted = name.toLowerCase();
+    for (const task of listTasks()) {
+        if (task.name && task.name.toLowerCase() === wanted)
+            return task;
+    }
+    return null;
+}

package/dist/lib/rotate.d.ts

@@ -47,9 +47,11 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
  * Resolve the configured strategy. Lookup order:
  *   1. project-local agents.yaml (nearest to `startPath`)
  *   2. ~/.agents/.system/agents.yaml
- *   3. default: `available` (use the pinned default version when healthy,
- *      otherwise fall through to a healthy account so a single rate-limited
- *      account doesn't block the run).
+ *   3. default: `balanced` (weighted-random across all healthy accounts by
+ *      remaining headroom, skipping any that are currently rate-limited). A
+ *      bare `agents run <agent>` — e.g. every new terminal the extension spawns
+ *      — should spread load and never launch into a throttled account, rather
+ *      than stick to the pinned default even when it's maxed.
  */
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
@@ -65,9 +67,12 @@ export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrate
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and usage available
- * (any non-session window strictly under 100%, or local flag not exhausted
- * when no live snapshot exists).
+ * Eligibility: signed in (email present), auth valid, and not currently
+ * rate-limited — no blocking window (session OR weekly) at 100%, matching the
+ * `agents view` badge; or the local cached status is usable when no live
+ * snapshot exists. Note the split: eligibility considers the session window
+ * (a session-maxed account can't run now), but the capacity *weight* above is
+ * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
  * Dedupe: when multiple versions share an email, collapse to one candidate
  * per email (the least-recently-active version). Prevents two parallel pods

package/dist/lib/rotate.js

@@ -10,7 +10,7 @@ import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
-import { getUsageInfoByIdentity, getUsageLookupKey, } from './usage.js';
+import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -44,14 +44,16 @@ export function getProjectRunStrategy(agent, startPath) {
  * Resolve the configured strategy. Lookup order:
  *   1. project-local agents.yaml (nearest to `startPath`)
  *   2. ~/.agents/.system/agents.yaml
- *   3. default: `available` (use the pinned default version when healthy,
- *      otherwise fall through to a healthy account so a single rate-limited
- *      account doesn't block the run).
+ *   3. default: `balanced` (weighted-random across all healthy accounts by
+ *      remaining headroom, skipping any that are currently rate-limited). A
+ *      bare `agents run <agent>` — e.g. every new terminal the extension spawns
+ *      — should spread load and never launch into a throttled account, rather
+ *      than stick to the pinned default even when it's maxed.
  */
 export function getConfiguredRunStrategy(agent, startPath = process.cwd()) {
     return getProjectRunStrategy(agent, startPath)
         ?? normalizeRunStrategy(readMeta().run?.[agent]?.strategy)
-        ?? 'available';
+        ?? 'balanced';
 }
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export function setGlobalRunStrategy(agent, strategy) {
@@ -72,10 +74,19 @@ function isAvailableEligible(candidate) {
         && hasUsageAvailable(candidate);
 }
 function hasUsageAvailable(candidate) {
-    const usedPercent = getRoutingUsedPercent(candidate.usageSnapshot);
-    if (usedPercent !== null) {
-        return usedPercent < 100;
+    const snapshot = candidate.usageSnapshot;
+    if (snapshot && snapshot.windows.length > 0) {
+        // Eligibility mirrors the `agents view` throttle badge exactly
+        // (deriveUsageStatusFromSnapshot): an account maxed on ANY blocking window —
+        // including the 5-hour session window — cannot serve the next request, so it
+        // must not be picked. Previously this checked only non-session windows
+        // (getRoutingUsedPercent), so a session-maxed account with weekly headroom
+        // stayed "eligible" and the router kept launching into it while `ag view`
+        // showed it rate-limited. Capacity *weighting* still ranks eligible accounts
+        // by weekly headroom; this gate only decides can-it-run-right-now.
+        return deriveUsageStatusFromSnapshot(snapshot) !== 'rate_limited';
     }
+    // No live snapshot: fall back to the coarse cached status.
     if (candidate.usageStatus === 'out_of_credits' || candidate.usageStatus === 'rate_limited') {
         return false;
     }
@@ -140,9 +151,12 @@ function dedupeAndSortCandidates(candidates) {
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and usage available
- * (any non-session window strictly under 100%, or local flag not exhausted
- * when no live snapshot exists).
+ * Eligibility: signed in (email present), auth valid, and not currently
+ * rate-limited — no blocking window (session OR weekly) at 100%, matching the
+ * `agents view` badge; or the local cached status is usable when no live
+ * snapshot exists. Note the split: eligibility considers the session window
+ * (a session-maxed account can't run now), but the capacity *weight* above is
+ * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
  * Dedupe: when multiple versions share an email, collapse to one candidate
  * per email (the least-recently-active version). Prevents two parallel pods

package/dist/lib/session/active.d.ts

@@ -20,6 +20,8 @@ export interface ActiveSession {
     cwd?: string;
     /** User-given name from /rename command. */
     label?: string;
+    /** Durable `agents run --name` launch handle, when the run was named. */
+    name?: string;
     /** First meaningful line of the initial prompt (extracted topic). */
     topic?: string;
     /** Live preview: the latest turn (agent message or tool action), from the state engine. */

package/dist/lib/session/active.js

@@ -26,6 +26,7 @@ import { AgentManager } from '../teams/agents.js';
 import { getTerminalsDir } from '../state.js';
 import { readPidSessionEntry, prunePidSessionRegistry } from './pid-registry.js';
 import { buildClaudeLabelMap } from './discover.js';
+import { buildRunNameMap } from './run-names.js';
 import { latestSessionFileForCwd } from './db.js';
 import { extractSessionTopic } from './prompt.js';
 import { readSessionTail } from './tail.js';
@@ -342,6 +343,9 @@ export async function listTerminalsActive() {
         procByPid.set(r.pid, r);
     // Build label map from Claude's sessions/*.json for /rename support
     const labelMap = buildClaudeLabelMap();
+    // Run-name handles (`agents run --name`) keyed by session id, for the same
+    // sessionId → handle resolution as labels.
+    const runNameMap = buildRunNameMap();
     return entries.map((t) => {
         // The id cached in live-terminals.json goes stale when Claude rotates its
         // transcript uuid on resume/compact, so it often no longer matches any
@@ -356,6 +360,8 @@ export async function listTerminalsActive() {
         const sessionFile = findSessionFileForKind(t.kind, t.cwd ?? undefined, resolvedId);
         // Prefer label from live terminal, fall back to Claude's session label
         const label = t.label ?? (t.sessionId ? labelMap.get(t.sessionId) : undefined) ?? undefined;
+        // Durable run name from `agents run --name`, resolved by the run's session id.
+        const name = resolvedId ? runNameMap.get(resolvedId) ?? undefined : undefined;
         // Extract topic from session file (first meaningful user message)
         const topic = sessionFile ? quickExtractTopic(sessionFile) : undefined;
         const state = computeLiveState(t.kind, sessionFile, t.cwd ?? undefined, isPidAlive(t.pid));
@@ -368,6 +374,7 @@ export async function listTerminalsActive() {
             sessionId: t.sessionId ?? sessionIdFromFile(sessionFile),
             cwd: t.cwd ?? undefined,
             label,
+            name,
             topic,
             sessionFile,
             startedAtMs: t.startedAtMs,

package/dist/lib/session/db.d.ts

@@ -22,6 +22,7 @@ export interface SessionRow {
     git_branch: string | null;
     topic: string | null;
     label: string | null;
+    name: string | null;
     message_count: number | null;
     token_count: number | null;
     cost_usd: number | null;
@@ -128,6 +129,16 @@ export declare function upsertSessionsBatch(entries: Array<{
  * Leaves FTS5 content/topic/project untouched — cheap to call every run.
  */
 export declare function syncLabels(labelMap: Map<string, string | null>): number;
+/**
+ * Sync `agents run --name` handles for a set of sessions, keyed by session id.
+ * The name's source of truth lives outside the transcript (host task sidecars,
+ * run-name sidecars written at launch), so — like {@link syncLabels} — it is
+ * re-applied by id every scan rather than parsed per-file. Updates only
+ * `sessions.name` (names resolve via a direct column tier in ftsSearch, not
+ * FTS, so there's no session_text column to touch). Only writes when the value
+ * differs; cheap to call every run. Returns the number of rows updated.
+ */
+export declare function syncNames(nameMap: Map<string, string | null>): number;
 /**
  * Sync topics (session titles) for a set of sessions, keyed by id. For agents
  * whose human-readable title lives in a side index that updates independently

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 8;
+const SCHEMA_VERSION = 9;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -52,6 +52,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   git_branch TEXT,
   topic TEXT,
   label TEXT,
+  name TEXT,
   message_count INTEGER,
   token_count INTEGER,
   cost_usd REAL,
@@ -188,6 +189,15 @@ function migrateSchema(db, fromVersion) {
         db.exec(`UPDATE sessions SET last_activity = timestamp WHERE last_activity IS NULL`);
         db.exec(`DELETE FROM scan_ledger;`);
     }
+    if (fromVersion < 9) {
+        // v8 → v9: `agents run --name <slug>` gives a run a durable launch handle,
+        // resolvable via `agents sessions <name>`. Additive column; NO rescan — the
+        // name is set at run time (host sidecar / run-name sidecar), not parsed from
+        // transcripts, so existing rows stay valid with a NULL name.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'name'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN name TEXT`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -401,13 +411,13 @@ export function recordScans(entries) {
 const upsertSessionStmt = (db) => db.prepare(`
   INSERT INTO sessions (
     id, short_id, agent, version, account, timestamp, last_activity,
-    project, cwd, git_branch, topic, label, message_count, token_count,
+    project, cwd, git_branch, topic, label, name, message_count, token_count,
     cost_usd, duration_ms,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
     pr_url, pr_number, worktree_slug, ticket_id
   ) VALUES (
     @id, @short_id, @agent, @version, @account, @timestamp, @last_activity,
-    @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
+    @project, @cwd, @git_branch, @topic, @label, @name, @message_count, @token_count,
     @cost_usd, @duration_ms,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
     @pr_url, @pr_number, @worktree_slug, @ticket_id
@@ -471,6 +481,7 @@ export function upsertSession(meta, content, scan) {
         git_branch: meta.gitBranch ?? null,
         topic: meta.topic ?? null,
         label: meta.label ?? null,
+        name: meta.name ?? null,
         message_count: meta.messageCount ?? null,
         token_count: meta.tokenCount ?? null,
         cost_usd: meta.costUsd ?? null,
@@ -559,6 +570,7 @@ export function upsertSessionsBatch(entries) {
                     git_branch: meta.gitBranch ?? null,
                     topic: meta.topic ?? null,
                     label: meta.label ?? null,
+                    name: meta.name ?? null,
                     message_count: meta.messageCount ?? null,
                     token_count: meta.tokenCount ?? null,
                     cost_usd: meta.costUsd ?? null,
@@ -626,6 +638,45 @@ export function syncLabels(labelMap) {
     txn(updates);
     return updates.length;
 }
+/**
+ * Sync `agents run --name` handles for a set of sessions, keyed by session id.
+ * The name's source of truth lives outside the transcript (host task sidecars,
+ * run-name sidecars written at launch), so — like {@link syncLabels} — it is
+ * re-applied by id every scan rather than parsed per-file. Updates only
+ * `sessions.name` (names resolve via a direct column tier in ftsSearch, not
+ * FTS, so there's no session_text column to touch). Only writes when the value
+ * differs; cheap to call every run. Returns the number of rows updated.
+ */
+export function syncNames(nameMap) {
+    if (nameMap.size === 0)
+        return 0;
+    const db = getDB();
+    const ids = [...nameMap.keys()];
+    const CHUNK = 500;
+    const updates = [];
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db
+            .prepare(`SELECT id, name FROM sessions WHERE id IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            const live = nameMap.get(row.id) ?? null;
+            if ((live ?? '') !== (row.name ?? '')) {
+                updates.push({ id: row.id, name: live });
+            }
+        }
+    }
+    if (updates.length === 0)
+        return 0;
+    const upd = db.prepare(`UPDATE sessions SET name = ? WHERE id = ?`);
+    const txn = db.transaction((items) => {
+        for (const { id, name } of items)
+            upd.run(name, id);
+    });
+    txn(updates);
+    return updates.length;
+}
 /**
  * Sync topics (session titles) for a set of sessions, keyed by id. For agents
  * whose human-readable title lives in a side index that updates independently
@@ -688,6 +739,7 @@ function rowToMeta(row) {
         account: row.account ?? undefined,
         topic: row.topic ?? undefined,
         label: row.label ?? undefined,
+        name: row.name ?? undefined,
         isTeamOrigin: row.is_team_origin === 1,
         prUrl: row.pr_url ?? undefined,
         prNumber: row.pr_number ?? undefined,
@@ -956,26 +1008,39 @@ export function ftsSearch(input, limit = 200) {
     const lower = trimmed.toLowerCase();
     const seen = new Set();
     const hits = [];
-    // Tier 1-3: label-based matches, ordered by exactness.
+    // Tier 1-3: handle-based matches, ordered by exactness. A session's handle is
+    // its /rename `label` OR its `agents run --name` handle — both are user-chosen
+    // aliases and rank identically, so typing either the renamed title or the run
+    // name resolves the session ahead of any FTS content hit.
     const labelRows = db.prepare(`
-    SELECT id, label FROM sessions
-    WHERE label IS NOT NULL AND LOWER(label) LIKE ?
-  `).all(`%${lower}%`);
+    SELECT id, label, name FROM sessions
+    WHERE (label IS NOT NULL AND LOWER(label) LIKE ?)
+       OR (name  IS NOT NULL AND LOWER(name)  LIKE ?)
+  `).all(`%${lower}%`, `%${lower}%`);
     let hasExactLabelMatch = false;
     for (const row of labelRows) {
-        const labelLower = row.label.toLowerCase();
-        let score;
-        if (labelLower === lower) {
-            score = 1_000_000;
-            hasExactLabelMatch = true;
-        }
-        else if (labelLower.startsWith(lower)) {
-            score = 900_000;
-        }
-        else {
-            score = 800_000;
+        // Score against whichever handle matches best (exact > prefix > contains).
+        let score = 0;
+        for (const handle of [row.label, row.name]) {
+            if (!handle)
+                continue;
+            const h = handle.toLowerCase();
+            if (!h.includes(lower))
+                continue;
+            if (h === lower) {
+                score = Math.max(score, 1_000_000);
+                hasExactLabelMatch = true;
+            }
+            else if (h.startsWith(lower)) {
+                score = Math.max(score, 900_000);
+            }
+            else {
+                score = Math.max(score, 800_000);
+            }
         }
-        // matchedTerms is empty for label hits — the picker can render the label
+        if (score === 0)
+            continue;
+        // matchedTerms is empty for handle hits — the picker can render the handle
         // itself as the highlight, no badge needed.
         hits.push({ sessionId: row.id, score, matchedTerms: [] });
         seen.add(row.id);

package/dist/lib/session/discover.js

@@ -25,7 +25,8 @@ import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand } from '.
 import { costOfUsage } from '../pricing/index.js';
 import { machineId } from './sync/config.js';
 import { mapBounded } from '../concurrency.js';
-import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
+import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, syncNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
+import { buildRunNameMap } from './run-names.js';
 const HOME = os.homedir();
 // Versions can live under either repo: the user repo (current canonical
 // location, ~/.agents/.history/versions/) or the system repo (legacy / npm-shipped,
@@ -63,6 +64,9 @@ export async function discoverSessions(options) {
             // reads to behavioral EDR (CrowdStrike Falcon) as a ransomware-style bulk
             // file-enumeration sweep. Same dirs, same results — just not all at once.
             await scanAgentsBounded(agents, agent => dispatchAgentScan(agent, onProgress));
+            // Apply `agents run --name` handles onto the freshly-scanned rows by id —
+            // the same idempotent, re-applied-every-scan pattern as /rename labels.
+            syncNames(buildRunNameMap());
         }
         finally {
             releaseScan(process.pid);

package/dist/lib/session/remote.d.ts

@@ -1,11 +1,9 @@
 /**
- * SSH target: a bare ssh-config host alias (e.g. `yosemite-s1`) or `user@host`.
- * The strict allowlist blocks shell metacharacters and a leading `-`, so a target
- * can never be smuggled in as an ssh argv flag.
+ * POSIX single-quote a string for safe interpolation into a remote shell command.
+ * Always wraps (unlike the bare-passthrough variant in `ssh-exec.ts`) — the
+ * forwarded `agents` argv is embedded verbatim inside `bash -lc '<cmd>'`, so
+ * every token is quoted to keep the command boundary unambiguous.
  */
-export declare const SSH_TARGET_RE: RegExp;
-export declare function assertValidSshTarget(host: string): void;
-/** POSIX single-quote a string for safe interpolation into a remote shell command. */
 export declare function shellQuote(s: string): string;
 /**
  * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,

package/dist/lib/session/remote.js

@@ -27,24 +27,17 @@ import { join } from 'path';
 import { createHash } from 'crypto';
 import chalk from 'chalk';
 import { getCacheDir } from '../state.js';
-import { SSH_OPTS, controlOpts } from '../ssh-exec.js';
+import { SSH_OPTS, controlOpts, assertValidSshTarget } from '../ssh-exec.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
 import { formatRelativeTime } from './relative-time.js';
 import { terminalWidth } from './width.js';
 /**
- * SSH target: a bare ssh-config host alias (e.g. `yosemite-s1`) or `user@host`.
- * The strict allowlist blocks shell metacharacters and a leading `-`, so a target
- * can never be smuggled in as an ssh argv flag.
+ * POSIX single-quote a string for safe interpolation into a remote shell command.
+ * Always wraps (unlike the bare-passthrough variant in `ssh-exec.ts`) — the
+ * forwarded `agents` argv is embedded verbatim inside `bash -lc '<cmd>'`, so
+ * every token is quoted to keep the command boundary unambiguous.
  */
-export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
-export function assertValidSshTarget(host) {
-    if (!SSH_TARGET_RE.test(host)) {
-        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host ` +
-            `(letters, digits, '.', '_', '-').`);
-    }
-}
-/** POSIX single-quote a string for safe interpolation into a remote shell command. */
 export function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }

package/dist/lib/session/run-names.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Run-name index: the join between a `agents run --name <slug>` handle and the
+ * session id of the run it named.
+ *
+ * `agents run` records `<sessionId>.json` here at launch whenever both a name
+ * and a session id are known up front (Claude pre-mints its id — see
+ * spawnAgent). The session-discovery pass reads these sidecars and applies the
+ * names onto the SQLite index by id (via syncNames), the same idempotent,
+ * re-applied-every-scan pattern as Claude `/rename` labels. Names therefore
+ * survive transcript rescans without being parsed out of the transcript itself.
+ *
+ * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
+ * one small JSON per run under `~/.agents/.cache/run-names/`.
+ */
+export interface RunNameRecord {
+    sessionId: string;
+    name: string;
+    agent: string;
+    cwd?: string;
+    ts: number;
+}
+export declare function runNamesDir(): string;
+/**
+ * Record a run's `--name` handle keyed by its session id. Best-effort: a failed
+ * write must never break the run itself. No-op without both a name and id.
+ */
+export declare function recordRunName(rec: Omit<RunNameRecord, 'ts'>): void;
+/**
+ * Build the sessionId → name map from every run-name sidecar, for syncNames to
+ * apply onto the index. Returns an empty map when the dir doesn't exist yet.
+ */
+export declare function buildRunNameMap(): Map<string, string | null>;

package/dist/lib/session/run-names.js

@@ -0,0 +1,63 @@
+/**
+ * Run-name index: the join between a `agents run --name <slug>` handle and the
+ * session id of the run it named.
+ *
+ * `agents run` records `<sessionId>.json` here at launch whenever both a name
+ * and a session id are known up front (Claude pre-mints its id — see
+ * spawnAgent). The session-discovery pass reads these sidecars and applies the
+ * names onto the SQLite index by id (via syncNames), the same idempotent,
+ * re-applied-every-scan pattern as Claude `/rename` labels. Names therefore
+ * survive transcript rescans without being parsed out of the transcript itself.
+ *
+ * Mirrors the host-task sidecar convention (`~/.agents/.cache/hosts/<id>.json`),
+ * one small JSON per run under `~/.agents/.cache/run-names/`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+export function runNamesDir() {
+    return path.join(getCacheDir(), 'run-names');
+}
+function recordFile(sessionId) {
+    return path.join(runNamesDir(), `${sessionId}.json`);
+}
+/**
+ * Record a run's `--name` handle keyed by its session id. Best-effort: a failed
+ * write must never break the run itself. No-op without both a name and id.
+ */
+export function recordRunName(rec) {
+    if (!rec.sessionId || !rec.name)
+        return;
+    try {
+        fs.mkdirSync(runNamesDir(), { recursive: true });
+        fs.writeFileSync(recordFile(rec.sessionId), JSON.stringify({ ...rec, ts: Date.now() }, null, 2));
+    }
+    catch {
+        /* the run is already launching; the name is a convenience, not load-bearing */
+    }
+}
+/**
+ * Build the sessionId → name map from every run-name sidecar, for syncNames to
+ * apply onto the index. Returns an empty map when the dir doesn't exist yet.
+ */
+export function buildRunNameMap() {
+    const map = new Map();
+    let files;
+    try {
+        files = fs.readdirSync(runNamesDir()).filter((f) => f.endsWith('.json'));
+    }
+    catch {
+        return map;
+    }
+    for (const f of files) {
+        try {
+            const rec = JSON.parse(fs.readFileSync(path.join(runNamesDir(), f), 'utf-8'));
+            if (rec.sessionId && rec.name)
+                map.set(rec.sessionId, rec.name);
+        }
+        catch {
+            /* skip a corrupt sidecar */
+        }
+    }
+    return map;
+}

package/dist/lib/session/types.d.ts

@@ -67,6 +67,14 @@ export interface SessionMeta {
     topic?: string;
     /** Custom name the user gave the session (e.g. Claude Code /rename). */
     label?: string;
+    /**
+     * Durable launch handle from `agents run --name <slug>` — an alias chosen at
+     * launch (not derived from the session id), used to resolve the run in
+     * `agents sessions <name>`. Distinct from `label` (post-hoc /rename): a run's
+     * name is immutable; both are searchable. Absent for runs launched without
+     * `--name`.
+     */
+    name?: string;
     /** Set when this session was spawned by `agents teams`. */
     teamOrigin?: TeamOrigin;
     /** Durable state signals extracted at scan time by the session-state engine. */

package/dist/lib/usage.d.ts

@@ -88,9 +88,11 @@ export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Prom
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
 /**
  * Derive an account's real throttle state from its live usage windows — the
- * same signal `agents usage` shows and balanced rotation trusts
- * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
- * the account is throttled until that window resets.
+ * single signal both the `agents view` badge and run-rotation eligibility share
+ * (`hasUsageAvailable` in rotate.ts treats a `rate_limited` verdict here as
+ * ineligible). A window at 100% utilization means the account is throttled until
+ * that window resets. Rotation *weighting* still ranks eligible accounts by
+ * weekly headroom (`getRoutingUsedPercent`); this function is the yes/no gate.
  *
  * Returns `null` when there is no snapshot, so callers render no badge rather
  * than a misleading one. This deliberately never consults

package/dist/lib/usage.js

@@ -212,9 +212,11 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3) {
 }
 /**
  * Derive an account's real throttle state from its live usage windows — the
- * same signal `agents usage` shows and balanced rotation trusts
- * (`getRoutingUsedPercent` in rotate.ts). A window at 100% utilization means
- * the account is throttled until that window resets.
+ * single signal both the `agents view` badge and run-rotation eligibility share
+ * (`hasUsageAvailable` in rotate.ts treats a `rate_limited` verdict here as
+ * ineligible). A window at 100% utilization means the account is throttled until
+ * that window resets. Rotation *weighting* still ranks eligible accounts by
+ * weekly headroom (`getRoutingUsedPercent`); this function is the yes/no gate.
  *
  * Returns `null` when there is no snapshot, so callers render no badge rather
  * than a misleading one. This deliberately never consults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.42",
+  "version": "1.20.43",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",