@phnx-labs/agents-cli 1.20.42 → 1.20.44

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

@@ -2,9 +2,13 @@
  * Shared host-task log viewer — the show-or-follow core behind both
  * `agents hosts logs <id>` and the top-level `agents logs <id>`.
  *
- * A running task with follow re-enters the offset-tail (`followHostTask`);
- * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
- * place so the two commands can never drift.
+ * A running task with follow re-enters the offset-tail (`followHostTask`).
+ * Otherwise the view is **concise by default**: a bounded tail of the captured
+ * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
+ * log. `full` opts into the entire raw log. (A host run's real transcript lives
+ * on the remote, not the local index — surfacing its rich summary needs remote
+ * runs to be discoverable there first; until then the bounded tail is the safe
+ * concise default.) Kept in one place so the two commands can never drift.
  */
 export interface HostLogResult {
     /** False when no host task with this id exists (caller may fall through to sessions). */
@@ -12,5 +16,10 @@ export interface HostLogResult {
     /** Process exit code to adopt when the task was shown/followed. */
     exitCode?: number;
 }
-/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
-export declare function showHostTaskLog(id: string, follow: boolean): Promise<HostLogResult>;
+/**
+ * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
+ * default; `full` dumps the entire raw combined-stdout log.
+ */
+export declare function showHostTaskLog(id: string, follow: boolean, full?: boolean): Promise<HostLogResult>;
+/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
+export declare function tailLines(text: string, n: number): string;

package/dist/lib/hosts/logs.js

@@ -2,9 +2,13 @@
  * Shared host-task log viewer — the show-or-follow core behind both
  * `agents hosts logs <id>` and the top-level `agents logs <id>`.
  *
- * A running task with follow re-enters the offset-tail (`followHostTask`);
- * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
- * place so the two commands can never drift.
+ * A running task with follow re-enters the offset-tail (`followHostTask`).
+ * Otherwise the view is **concise by default**: a bounded tail of the captured
+ * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
+ * log. `full` opts into the entire raw log. (A host run's real transcript lives
+ * on the remote, not the local index — surfacing its rich summary needs remote
+ * runs to be discoverable there first; until then the bounded tail is the safe
+ * concise default.) Kept in one place so the two commands can never drift.
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -12,8 +16,13 @@ import { loadTask, localLogPath, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { reconcileTask } from './reconcile.js';
 import { sshExecRaw } from '../ssh-exec.js';
-/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
-export async function showHostTaskLog(id, follow) {
+/** Lines of raw combined-stdout to show in the concise (non-`full`) view. */
+const HOST_LOG_TAIL_LINES = 40;
+/**
+ * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
+ * default; `full` dumps the entire raw combined-stdout log.
+ */
+export async function showHostTaskLog(id, follow, full = false) {
     const task = loadTask(id);
     if (!task)
         return { found: false };
@@ -36,21 +45,38 @@ export async function showHostTaskLog(id, follow) {
     // plain `logs <id>` also unsticks a task whose follower was killed. No-op (no
     // ssh) once the record is already terminal.
     reconcileTask(task);
+    // Raw combined-stdout: the whole log with `full`, else a bounded tail.
+    const raw = readTaskLog(task);
+    if (raw === null) {
+        process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
+        return { found: true, exitCode: 0 };
+    }
+    process.stdout.write(full ? raw : tailLines(raw, HOST_LOG_TAIL_LINES));
+    return { found: true, exitCode: 0 };
+}
+/** Read the task's combined-stdout — local mirror first, else fetch+cache remote. */
+function readTaskLog(task) {
     try {
-        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
+        return fs.readFileSync(localLogPath(task.id), 'utf-8');
     }
     catch {
         // No local log — task was dispatched with --no-follow. Fetch from the remote
         // on demand and cache locally so subsequent calls are instant.
         const remote = fetchAndCacheRemoteLog(task);
-        if (remote !== null) {
-            process.stdout.write(remote);
-        }
-        else {
-            process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
-        }
+        return remote !== null ? remote.toString('utf-8') : null;
     }
-    return { found: true, exitCode: 0 };
+}
+/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
+export function tailLines(text, n) {
+    const lines = text.split('\n');
+    // A trailing newline yields a final empty element — drop it from the count.
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    if (lines.length <= n)
+        return lines.join('\n') + '\n';
+    const hidden = lines.length - n;
+    const note = chalk.gray(`… ${hidden} earlier line${hidden === 1 ? '' : 's'} hidden — pass --full for the whole log\n`);
+    return note + lines.slice(-n).join('\n') + '\n';
 }
 /**
  * Fetch a task's remote log over SSH, write it to the local mirror path (for

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/redact.js

@@ -7,6 +7,7 @@ const SECRET_PATTERNS = [
     [/\bsk-[A-Za-z0-9]{20,}\b/g, '[REDACTED_API_KEY]'],
     [/\bnpm_[A-Za-z0-9]{36}\b/g, '[REDACTED_NPM_TOKEN]'],
     [/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED_JWT]'],
+    [/Bearer\s+\S+/gi, 'Bearer [REDACTED]'],
     [/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi, '$1=[REDACTED]'],
 ];
 export function redactSecrets(text) {

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. */
@@ -100,6 +102,12 @@ export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
 }
+/**
+ * Resolve an agent kind from a process's reported executable. `comm` may be an
+ * absolute path (shim-launched agents), and Windows image names carry an
+ * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
+ */
+export declare function agentKindFromComm(commRaw: string): string | undefined;
 /**
  * Pick a Claude transcript file within a project dir.
  *

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';
@@ -63,7 +64,16 @@ const AGENT_CLI_NAMES = {
  * absolute path (shim-launched agents), and Windows image names carry an
  * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
  */
-function agentKindFromComm(commRaw) {
+export function agentKindFromComm(commRaw) {
+    // A GUI desktop app can bundle a binary with the SAME name as an agent CLI: the
+    // Codex desktop app ships `/Applications/Codex.app/Contents/Resources/codex` (its
+    // `app-server`), whose basename `codex` would otherwise match the codex CLI and
+    // surface the app's background server as a phantom agent session — running at cwd
+    // '/', so it shows up unattributed in the feed. A real agent CLI is never inside a
+    // `.app` bundle, so exclude those. (The Claude desktop app is a separate case,
+    // already excluded by name below: its process is 'Claude', not the CLI's 'claude'.)
+    if (commRaw.includes('.app/Contents/'))
+        return undefined;
     const base = path.basename(commRaw);
     const stripped = base.replace(/\.exe$/i, '');
     // Windows image names compare case-insensitively; POSIX comms stay exact —
@@ -342,6 +352,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 +369,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 +383,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, `'\\''`)}'`;
 }