@phnx-labs/agents-cli 1.22.30 → 1.22.32

package/dist/commands/sessions.js

@@ -43,6 +43,7 @@ import { sessionOwnerDevice, RESUME_PINNED_ENV } from '../lib/session/resume-own
 import { renderMarkdown } from '../lib/markdown.js';
 import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
 import { getShimsDir } from '../lib/state.js';
+import { listJobs, listJobsWithRuns, listRuns } from '../lib/routines.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { itemPicker } from '../lib/picker.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
@@ -55,8 +56,8 @@ import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerSessionsForkCommand } from './fork.js';
-import { registerSessionsFavoriteCommand } from './sessions-favorite.js';
-import { isFavorite, listFavorites } from '../lib/session/favorites.js';
+import { registerSessionsBookmarkCommand } from './sessions-bookmark.js';
+import { isBookmarked, listBookmarks } from '../lib/session/bookmarks.js';
 import { registerGoCommand } from './go.js';
 import { registerFocusCommand } from './focus.js';
 import { registerReconnectCommand } from './reconnect.js';
@@ -1361,26 +1362,25 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     const self = machineId();
     const gathered = await gatherActiveSessions(opts);
     const { remoteDeviceCount } = gathered;
-    // --favorites narrows the live view too. Applied HERE, not only in the
+    // Backfill agent version, refs, created time, and routine provenance from the
+    // historical index. Routine filtering needs that provenance before it narrows
+    // the live pool; doing it here also enriches both JSON and human output.
+    backfillActiveRowsFromIndex(gathered.sessions);
+    // --bookmarks narrows the live view too. Applied HERE, not only in the
     // browser: the browser is skipped for --json, --waiting, a pipe, a multi-host
     // scope, and an SSH-fanout peer, and the flag silently did nothing on every
-    // one of those paths — including `--active --favorites --json`, which is
+    // one of those paths — including `--active --bookmarks --json`, which is
     // exactly what the browser's own `y` copy-cmd hands to an agent.
-    const merged = opts.favoritesOnly
-        ? gathered.sessions.filter((s) => !!s.sessionId && listFavorites().has(s.sessionId))
+    const merged = opts.bookmarksOnly
+        ? gathered.sessions.filter((s) => !!s.sessionId && listBookmarks().has(s.sessionId))
         : gathered.sessions;
+    const routineFiltered = filterActiveSessionsByRoutine(merged, opts.routine);
     // Status flags form a union. --waiting additionally retains its scriptable
     // gate: exit non-zero when the union contains a session awaiting the user.
     const statusFiltered = opts.statuses?.length
-        ? merged.filter((session) => opts.statuses.some((status) => matchesLiveStatus(session, status)))
-        : merged.filter(isRunningLiveSession);
+        ? routineFiltered.filter((session) => opts.statuses.some((status) => matchesLiveStatus(session, status)))
+        : routineFiltered.filter(isRunningLiveSession);
     const sessions = statusFiltered;
-    // Backfill agent version + ticket/PR/label/created onto the live rows from the
-    // historical index (RUSH-2205) — a running process reports none of these, and
-    // an orphan row usually lacks them. Done before both the JSON and human paths
-    // so every consumer (incl. the SSH fan-out's remote --json) sees enriched rows;
-    // transcripts sync across the fleet, so a remote row resolves from the local DB.
-    backfillActiveRowsFromIndex(sessions);
     if (asJson) {
         // Resolve who is watching each local tmux pane before serializing: `viewingIn`
         // is how a consumer distinguishes a session someone is looking at from one
@@ -1426,6 +1426,19 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     if (waitingOnly && sessions.some(isAwaitingUser))
         process.exitCode = 1;
 }
+/** Apply the routine selector to enriched live rows for every non-browser active view. */
+export function filterActiveSessionsByRoutine(sessions, routine) {
+    if (!routine)
+        return sessions;
+    const routineSessions = sessions.filter((session) => session.origin === 'routine' || !!session.routineName);
+    if (typeof routine !== 'string')
+        return routineSessions;
+    const names = [...new Set(routineSessions.map((session) => session.routineName).filter((name) => !!name))];
+    const selected = resolveRoutineName(routine, names);
+    return selected
+        ? routineSessions.filter((session) => session.routineName === selected)
+        : [];
+}
 /** Match the status words users see, preserving activity's richer working signal. */
 export function matchesLiveStatus(session, status) {
     if (status === 'working')
@@ -1492,7 +1505,9 @@ export function isBareBrowserListing(options, query) {
  */
 export function hasNoBrowserDisqualifyingFlags(options, query) {
     return (!query &&
-        !options.routine &&
+        // A named team view is a flat selectable pool; the bare --teams report
+        // stays grouped and printed because the browser cannot preserve its shape.
+        (!options.teams || !!options.inTeam) &&
         !options.flat &&
         !options.tree &&
         !options.markdown &&
@@ -1543,14 +1558,14 @@ export function buildRoutineRunGroups(sessions) {
     }))
         .sort((a, b) => (a.timestamp < b.timestamp ? 1 : a.timestamp > b.timestamp ? -1 : a.runId.localeCompare(b.runId)));
 }
-export function buildRoutineChoices(sessions) {
+export function buildRoutineChoices(sessions, runOnlyNames = []) {
     const byName = new Map();
     for (const session of sessions) {
         if (!session.routineName)
             continue;
         (byName.get(session.routineName) ?? byName.set(session.routineName, []).get(session.routineName)).push(session);
     }
-    return [...byName.entries()]
+    const choices = [...byName.entries()]
         .map(([name, rows]) => {
         const runs = buildRoutineRunGroups(rows);
         return {
@@ -1559,11 +1574,28 @@ export function buildRoutineChoices(sessions) {
             runCount: runs.length,
             latestRunSessionCount: runs[0].sessions.length,
         };
-    })
-        .sort((a, b) => (a.lastRunAt < b.lastRunAt ? 1 : a.lastRunAt > b.lastRunAt ? -1 : a.name.localeCompare(b.name)));
+    });
+    // Routines whose only attempts are pre-session (blocked/skipped/failed-before-
+    // spawn) have run records but no transcript. Surface them so the picker is
+    // built from definitions+runs, never only transcripts — otherwise a routine
+    // that has never produced a session reads as "No routines match" (the plan).
+    const seen = new Set(choices.map((c) => c.name));
+    for (const name of runOnlyNames) {
+        if (seen.has(name))
+            continue;
+        const runs = listRuns(name);
+        const latest = runs[runs.length - 1];
+        choices.push({
+            name,
+            lastRunAt: latest?.startedAt ?? '',
+            runCount: runs.length,
+            latestRunSessionCount: 0,
+        });
+    }
+    return choices.sort((a, b) => (a.lastRunAt < b.lastRunAt ? 1 : a.lastRunAt > b.lastRunAt ? -1 : a.name.localeCompare(b.name)));
 }
 async function selectRoutineName(sessions) {
-    const choices = buildRoutineChoices(sessions);
+    const choices = buildRoutineChoices(sessions, safeListJobsWithRuns());
     const picked = await itemPicker({
         message: 'Select a routine:',
         items: choices,
@@ -1576,7 +1608,8 @@ async function selectRoutineName(sessions) {
         labelFor: (choice) => {
             const runs = `${choice.runCount} run${choice.runCount === 1 ? '' : 's'}`;
             const sessions = `${choice.latestRunSessionCount} session${choice.latestRunSessionCount === 1 ? '' : 's'} in latest`;
-            return `${choice.name}  ${chalk.gray(`${runs} · ${sessions} · ${formatRelativeTime(choice.lastRunAt)}`)}`;
+            const age = choice.lastRunAt ? ` · ${formatRelativeTime(choice.lastRunAt)}` : '';
+            return `${choice.name}  ${chalk.gray(`${runs} · ${sessions}${age}`)}`;
         },
         shortIdFor: (choice) => choice.name,
         emptyMessage: 'No routines match.',
@@ -1584,8 +1617,22 @@ async function selectRoutineName(sessions) {
     });
     return picked?.item.name ?? null;
 }
+/** `listJobsWithRuns` but never throws into the sessions reader (best-effort). */
+function safeListJobsWithRuns() {
+    try {
+        return [...new Set([...listJobs().map((job) => job.name), ...listJobsWithRuns()])];
+    }
+    catch {
+        return [];
+    }
+}
 export async function filterSessionsByRoutine(sessions, routine, interactive) {
-    const routineNames = [...new Set(sessions.map((session) => session.routineName).filter((name) => !!name))].sort((a, b) => a.localeCompare(b));
+    // The name universe is transcripts UNION routines that have any run record —
+    // so a routine whose attempts never produced a session still resolves.
+    const routineNames = [...new Set([
+            ...sessions.map((session) => session.routineName).filter((name) => !!name),
+            ...safeListJobsWithRuns(),
+        ])].sort((a, b) => a.localeCompare(b));
     let selectedRoutine = null;
     if (typeof routine === 'string') {
         selectedRoutine = resolveRoutineName(routine, routineNames);
@@ -1602,9 +1649,10 @@ export async function filterSessionsByRoutine(sessions, routine, interactive) {
         if (!selectedRoutine)
             return null;
     }
-    return selectedRoutine
-        ? sessions.filter((session) => session.routineName === selectedRoutine)
-        : sessions;
+    if (!selectedRoutine)
+        return sessions;
+    const matched = sessions.filter((session) => session.routineName === selectedRoutine);
+    return matched;
 }
 /** The canonical `ag sessions …` command for a set of flags — the twin of the
  * browser's `y` hotkey (see --print-cmd). Normalizes to the stable flag form. */
@@ -1657,8 +1705,8 @@ function canonicalSessionsCommand(query, options) {
         a.push('--local');
     if (options.waiting)
         a.push('--waiting');
-    if (options.favorites)
-        a.push('--favorites');
+    if (options.bookmarks)
+        a.push('--bookmarks');
     const q = (query ?? '').trim();
     if (q)
         a.push(JSON.stringify(q));
@@ -1768,7 +1816,7 @@ export async function renderSessionPreview(query, scope) {
         }));
         return;
     }
-    const headline = formatLiveStatusHeadline(live, isFavorite(session.id));
+    const headline = formatLiveStatusHeadline(live, isBookmarked(session.id));
     if (headline)
         console.log(headline);
     console.log(buildPreview(session));
@@ -1783,12 +1831,12 @@ export async function renderSessionPreview(query, scope) {
  * reads "orphan" and knows it means "still running in tmux with no window
  * attached", so those two spell it out.
  */
-export function formatLiveStatusHeadline(live, favorite = false) {
-    const star = favorite ? chalk.yellow('★ ') : '';
+export function formatLiveStatusHeadline(live, bookmarked = false) {
+    const star = bookmarked ? chalk.yellow('★ ') : '';
     // With no live row there is no status to lead with, so the star has to say
     // what it means on its own — a bare `★` above a preview reads as noise.
     if (!live)
-        return favorite ? chalk.yellow('★ favorited') : '';
+        return bookmarked ? chalk.yellow('★ bookmarked') : '';
     const { glyph } = liveGlyphAndPreview(live);
     const word = liveStatusWord(live) || live.status;
     // One definition, shared with `--waiting`. A second local copy drifted: the
@@ -2140,7 +2188,8 @@ limitSource) {
                 host: options.host,
                 since: options.since,
                 all: options.all,
-                favorites: options.favorites,
+                bookmarks: options.bookmarks,
+                routine: options.routine,
             }), { local: options.local === true, hosts: options.host });
             return;
         }
@@ -2150,8 +2199,9 @@ limitSource) {
         await renderActiveSessions(options.json === true, options.waiting === true, {
             local: forceLocal,
             hosts: options.host,
-            favoritesOnly: options.favorites === true,
+            bookmarksOnly: options.bookmarks === true,
             statuses: liveStatuses,
+            routine: options.routine,
         });
         return;
     }
@@ -2165,12 +2215,10 @@ limitSource) {
     // printed/render paths (agents and scripts unaffected). An explicit --since seeds
     // the browser's window so the flag is honored, not swallowed.
     //
-    // `--teams` diverts to the printed team-grouped report (printTeamsView, below):
-    // grouping teammates under their team is a shape the flat fuzzy picker cannot
-    // represent, so like --tree it is a printed listing, not an interactive pick.
-    // --teams --flat/--tree keep their inline table rendering; a search query keeps
-    // the picker so `<term> --teams` still searches.
-    if (isBareBrowserListing(options, query) && !options.teams) {
+    // Bare `--teams` still diverts to the printed team-grouped report because the
+    // flat picker cannot preserve that shape. `--in-team <name> --teams` is one
+    // flat lineage, so it qualifies through hasNoBrowserDisqualifyingFlags.
+    if (isBareBrowserListing(options, query)) {
         const { runSessionBrowser, bareBrowserSeed } = await import('./sessions-browser.js');
         await runSessionBrowser(bareBrowserSeed({
             teams: options.teams,
@@ -2179,7 +2227,8 @@ limitSource) {
             since: options.since,
             host: options.host,
             inTeam: options.inTeam,
-            favorites: options.favorites,
+            bookmarks: options.bookmarks,
+            routine: options.routine,
         }), { local: options.local === true, hosts: options.host });
         return;
     }
@@ -2349,11 +2398,11 @@ limitSource) {
         // read. Match either, after that pass has populated `teamOrigin`.
         if (options.inTeam)
             sessions = sessions.filter((s) => matchesTeam(s, options.inTeam));
-        // --favorites narrows to the starred set. Applied here, before the JSON
-        // emit, so `--favorites --json` is the machine-readable twin of the `f` key.
-        if (options.favorites) {
-            const starred = listFavorites();
-            sessions = sessions.filter((s) => starred.has(s.id));
+        // --bookmarks narrows to the bookmarked set. Applied here, before the JSON
+        // emit, so `--bookmarks --json` is the machine-readable twin of the `b` key.
+        if (options.bookmarks) {
+            const bookmarks = listBookmarks();
+            sessions = sessions.filter((s) => bookmarks.has(s.id));
         }
         if (toolEvidenceMode) {
             const self = toolSelf;
@@ -2659,7 +2708,7 @@ function timeCell(age, topicSlack) {
  * (tracker/PR ref, pulled out of the badge blob so refs align) is only rendered
  * when `showTicket` — otherwise a listing with no refs would waste a column of
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
-export function flatSessionRow(session, live, showTicket = false, cols = {}, favorite = false) {
+export function flatSessionRow(session, live, showTicket = false, cols = {}, bookmarked = false) {
     const agentColor = colorAgent(session.agent);
     const age = sessionAgeParts(session.timestamp, session.lastActivity);
     const project = session.project || '-';
@@ -2696,18 +2745,18 @@ export function flatSessionRow(session, live, showTicket = false, cols = {}, fav
     const width = terminalWidth();
     const requestedModelW = cols.showModel ? (cols.modelWidth ?? PICKER_MODEL_MAX) : 0;
     // Same conditional 2 cells as the picker's marker, for the same reason.
-    const favW = cols.showFavorite ? 2 : 0;
-    const favCell = cols.showFavorite ? (favorite ? chalk.yellow('★ ') : '  ') : '';
+    const bookmarkW = cols.showBookmark ? 2 : 0;
+    const bookmarkCell = cols.showBookmark ? (bookmarked ? chalk.yellow('★ ') : '  ') : '';
     // Sized against the last-activity label alone, so the creation field is an
     // additive decision the row makes only once it knows what space is left.
-    const fixedW = favW + (10 + 9 + 8 + 16) + glyphW + statusW + machineW + ticketW + wtW + team.width + stringWidth(age.last) + 1;
+    const fixedW = bookmarkW + (10 + 9 + 8 + 16) + glyphW + statusW + machineW + ticketW + wtW + team.width + stringWidth(age.last) + 1;
     const modelSlack = width - fixedW - MIN_TOPIC_W;
     const modelW = requestedModelW <= modelSlack
         ? requestedModelW
         : modelSlack >= PICKER_MODEL_MIN ? modelSlack : 0;
     const when = timeCell(age, width - fixedW - modelW);
     const topicW = Math.max(MIN_TOPIC_W, width - fixedW - modelW - when.extraW);
-    return (favCell +
+    return (bookmarkCell +
         chalk.white(padToWidth(truncateToWidth(session.shortId, 9), 10)) +
         agentColor(padToWidth(truncateToWidth(session.agent, 8), 9)) +
         chalk.yellow(padToWidth(truncateToWidth(session.version || '-', 7), 8)) +
@@ -2907,9 +2956,9 @@ function printSessionTable(sessions, hiddenCount = 0, tree = false, liveIndex) {
     // column (and its compact labels) is computed the same way the picker does it.
     const showTicket = sessions.some((s) => ticketLabel(s) !== '');
     const cols = pickerColumnsFor(sessions);
-    const favorites = listFavorites();
+    const bookmarks = listBookmarks();
     for (const session of sessions) {
-        console.log(flatSessionRow(session, liveIndex?.get(session.id), showTicket, cols, favorites.has(session.id)));
+        console.log(flatSessionRow(session, liveIndex?.get(session.id), showTicket, cols, bookmarks.has(session.id)));
     }
     const countLine = `${sessions.length} session${sessions.length === 1 ? '' : 's'}.`;
     console.log(chalk.gray(`\n${countLine}`));
@@ -3252,10 +3301,10 @@ export function pickerColumnsFor(sessions) {
         showModel: sessions.some((s) => !!s.model),
         modelWidth: modelColumnWidth(sessions),
         showTicket: sessions.some((s) => ticketLabel(s) !== ''),
-        showFavorite: (() => {
+        showBookmark: (() => {
             // One read of the store per pool, not one per row.
-            const starred = listFavorites();
-            return starred.size > 0 && sessions.some((s) => starred.has(s.id));
+            const bookmarks = listBookmarks();
+            return bookmarks.size > 0 && sessions.some((s) => bookmarks.has(s.id));
         })(),
     };
 }
@@ -3275,7 +3324,7 @@ export function liveHostLabel(a) {
     const viewer = a.viewingIn?.app;
     return viewer && viewer !== a.host ? `${a.host}→${viewer}` : a.host;
 }
-export function formatPickerLabel(s, query, cols = {}, ssh, host = '', favorite = false, live) {
+export function formatPickerLabel(s, query, cols = {}, ssh, host = '', bookmarked = false, live) {
     const agentColor = colorAgent(s.agent);
     const age = sessionAgeParts(s.timestamp, s.lastActivity);
     const project = s.project || '-';
@@ -3317,11 +3366,11 @@ export function formatPickerLabel(s, query, cols = {}, ssh, host = '', favorite
     const ticketW = cols.showTicket ? TICKET_W + 1 : 0;
     const hostW = cols.showHost ? PICKER_HOST_W : 0;
     const wtW = wt ? stringWidth(wt) + 1 : 0;
-    // Within a pool that HAS starred rows the marker holds its 2 cells whether this
-    // row is starred or not, so the columns after it never jog; a pool with none
-    // drops the column entirely (`showFavorite`) and costs nothing.
-    const favW = cols.showFavorite ? 2 : 0;
-    const favCell = cols.showFavorite ? (favorite ? chalk.yellow('★ ') : '  ') : '';
+    // Within a pool that HAS bookmarked rows the marker holds its 2 cells whether
+    // this row is bookmarked or not, so the columns after it never jog; a pool
+    // with none drops the column entirely (`showBookmark`) and costs nothing.
+    const bookmarkW = cols.showBookmark ? 2 : 0;
+    const bookmarkCell = cols.showBookmark ? (bookmarked ? chalk.yellow('★ ') : '  ') : '';
     // The same status word the flat listing shows, so a session that is `orphan`
     // or `crashed` reads that way in the browser too — not only in its preview.
     // Constant width whenever the column is on. `liveStatusCell` already pads its
@@ -3333,10 +3382,10 @@ export function formatPickerLabel(s, query, cols = {}, ssh, host = '', favorite
     const statusCell = cols.showStatus ? (status.cell || ' '.repeat(LIVE_STATUS_W)) : '';
     // Sized against the last-activity label alone; the creation field is then an
     // additive decision made against whatever width is left (see the flat listing).
-    const baseTopicW = terminalWidth() - gutter - favW - statusW - (10 + 9 + 8 + 16) - machineColW - hostW - ticketW - wtW - sshW - team.width - stringWidth(age.last) - 1;
+    const baseTopicW = terminalWidth() - gutter - bookmarkW - statusW - (10 + 9 + 8 + 16) - machineColW - hostW - ticketW - wtW - sshW - team.width - stringWidth(age.last) - 1;
     const when = timeCell(age, baseTopicW);
     const topicW = Math.max(MIN_TOPIC_W, baseTopicW - when.extraW);
-    return (favCell +
+    return (bookmarkCell +
         // Truncated, not just padded: an indexed shortId is always 8 chars, but a
         // live row with no session id is named by its pid or cloud task, which can
         // run past the column and shunt every later column out of alignment.
@@ -4459,6 +4508,7 @@ export function registerSessionsCommands(program) {
         .option('--grok', 'Shorthand for --agent grok')
         .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Widen every non-status filter to "all": every directory (not just this project) and all time (no window cap). Status filters like --active still compose; -a/--device/--since still narrow their axis.')
+        .option('--bookmarks', 'Show only bookmarked sessions — bookmark them with `*` in the browser or `agents sessions bookmark <id>`')
         .option('--unmanaged', "Also show sessions from your own ~/.<agent> installs (hidden once agents-cli manages that agent)")
         .option('--team, --teams', 'Show team-spawned sessions (hidden by default), grouped by team — each team names its spawner and spawn time, teammates show their mode + handle, and team-flagged spawns with no teammate record sink into a (no team) bucket. --flat/--tree keep the plain inline table')
         .option('--in-team <name>', "Only this team: the session that spawned it plus (with --teams) its teammates. Spans every directory and all time, since a team's worktrees and history sit outside the default window.")
@@ -4492,7 +4542,6 @@ export function registerSessionsCommands(program) {
         .option('--abandoned', 'Show sessions with no transcript progress for the abandonment window (implies --active)')
         .option('--queued', 'Show queued sessions that have not started running (implies --active)')
         .option('--unknown', 'Show sessions whose live state cannot be determined (implies --active)')
-        .option('--favorites', 'Show only favorited sessions — favorite them with `*` in the browser or `agents sessions favorite <id>`')
         .option('--tree', 'Group the listing by directory; drops the id/version columns for readability')
         .option('--flat', 'Plain flat table (one row per session) instead of the grouped project overview')
         .option('--no-live', 'Do not enrich the listing with live status/preview for running sessions')
@@ -4662,7 +4711,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
     registerSessionsForkCommand(sessionsCmd);
-    registerSessionsFavoriteCommand(sessionsCmd);
+    registerSessionsBookmarkCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);
     registerFocusCommand(sessionsCmd);
     registerReconnectCommand(sessionsCmd);

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerUpdateCommand(program: Command): void;

package/dist/commands/update.js

@@ -0,0 +1,148 @@
+import chalk from 'chalk';
+import { formatAgentError, resolveAgentName } from '../lib/agents.js';
+import { setHelpSections } from '../lib/help.js';
+import { describeInstallation, listInstallations, resolveInstallation, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
+/**
+ * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
+ * label, or the release it currently carries — never a release to install; that
+ * is `--to`. Keeping them separate is what lets `agents update claude@2.0.65
+ * --to 2.0.71` read unambiguously.
+ */
+function parseTarget(raw) {
+    const at = raw.indexOf('@');
+    const name = at === -1 ? raw : raw.slice(0, at);
+    const selector = at === -1 ? undefined : raw.slice(at + 1).trim();
+    if (at !== -1 && !selector) {
+        throw new Error(`Missing installation in '${raw}'. Use <agent>@<installed-version>, or just <agent>.`);
+    }
+    const agent = resolveAgentName(name);
+    if (!agent)
+        throw new Error(formatAgentError(name));
+    return { agent, selector };
+}
+function serialize(installation) {
+    return {
+        id: installation.id,
+        agent: installation.agent,
+        label: installation.label,
+        releaseVersion: installation.releaseVersion,
+        createdAt: installation.createdAt,
+        updatedAt: installation.updatedAt,
+    };
+}
+function printOutcome(outcome, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            installation: serialize(outcome.installation),
+            strategy: outcome.strategy,
+            fromRelease: outcome.fromRelease,
+            toRelease: outcome.toRelease,
+            unchanged: outcome.unchanged,
+            alsoUpdated: outcome.alsoUpdated.map(serialize),
+        }, null, 2));
+        return;
+    }
+    const name = `${outcome.installation.agent}@${outcome.installation.label}`;
+    if (outcome.unchanged) {
+        console.log(chalk.gray(`${name} is already on release ${outcome.toRelease}.`));
+        return;
+    }
+    console.log(chalk.green(`Updated ${name}: release ${outcome.fromRelease} -> ${outcome.toRelease}`));
+    console.log(chalk.gray(`Its name is unchanged, so every default, project pin, and routine that names ${name} still resolves to it.`));
+    for (const other of outcome.alsoUpdated) {
+        console.log(chalk.gray(`  ${other.agent}@${other.label} shares the same binary and now also reports release ${other.releaseVersion}.`));
+    }
+}
+function printInstallations(agent, json) {
+    const installations = listInstallations(agent);
+    if (json) {
+        console.log(JSON.stringify(installations.map(serialize), null, 2));
+        return;
+    }
+    if (!installations.length) {
+        console.log(chalk.gray(`No managed ${agent} installations. Install one with: agents add ${agent}@latest`));
+        return;
+    }
+    console.log(chalk.bold(`${agent} installations\n`));
+    for (const installation of installations) {
+        console.log(`  ${chalk.cyan(installation.label)}  release ${installation.releaseVersion}  ${chalk.gray(installation.id)}`);
+    }
+}
+/**
+ * Surface a failure as one red line, not a stack trace. Everything this command
+ * can fail on — an unknown agent, an ambiguous selector, an unpinnable harness,
+ * a release that would not launch — is a message the user acts on, and a
+ * commander async action rejection otherwise reaches the user as a raw Node dump.
+ */
+function fail(err) {
+    console.error(chalk.red(err.message));
+    process.exitCode = 1;
+}
+export function registerUpdateCommand(program) {
+    const update = program
+        .command('update [target]')
+        .description('Move a frozen agent installation to a new release, keeping its name and every reference to it')
+        .option('--to <release>', 'Release to move to: latest (default), oldest, or an exact version')
+        .option('--account <label>', 'Disambiguate by signed-in account when several installations match')
+        .option('--json', 'Machine-readable result')
+        .action(async (target, options) => {
+        try {
+            if (!target) {
+                throw new Error('Which agent? Use: agents update <agent>[@<installed-version>]');
+            }
+            const { agent, selector } = parseTarget(target);
+            if (options.to && options.to !== 'latest' && !supportsPinnedUpdate(agent)) {
+                // Fail loud at the boundary rather than installing the current release
+                // and reporting it as the pin that was asked for.
+                throw new Error(`${agent} is a single self-updating binary with no pinnable releases — drop --to, or pass --to latest.`);
+            }
+            const installation = await resolveInstallation(agent, selector, { account: options.account });
+            const strategy = selectUpdateStrategy(agent);
+            if (!options.json && !strategy.transactional) {
+                console.log(chalk.yellow(`${agent} installs one vendor-managed binary, so this update cannot be staged or rolled back; `
+                    + `a failure leaves whatever its installer wrote.`));
+            }
+            if (!options.json) {
+                console.log(chalk.gray(`Updating ${agent}@${describeInstallation(installation)} via the ${strategy.id} strategy...`));
+            }
+            const outcome = await updateInstallation(installation, {
+                to: options.to,
+                onProgress: options.json ? undefined : (message) => console.log(chalk.gray(`  ${message}`)),
+            });
+            printOutcome(outcome, !!options.json);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    update
+        .command('list <agent>')
+        .description('Show every frozen installation of an agent and the release each carries')
+        .option('--json', 'Machine-readable listing')
+        // `--json` is declared on both `update` and `update list`, and commander
+        // binds a flag the parent also declares to the PARENT's option store — so
+        // reading this subcommand's own opts alone silently drops it. Merge them.
+        .action((rawAgent, _options, command) => {
+        try {
+            const agent = resolveAgentName(rawAgent);
+            if (!agent)
+                throw new Error(formatAgentError(rawAgent));
+            printInstallations(agent, !!command.optsWithGlobals().json);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    setHelpSections(update, {
+        examples: `agents update list claude
+agents update claude@2.0.65
+agents update claude@2.0.65 --to 2.1.220
+agents update claude --account work
+agents update claude@2.0.65 --json`,
+        notes: 'An installation keeps its name for life; only the release inside it moves. That is why a default, a project pin, '
+            + 'a routine version, or a profile that names claude@2.0.65 keeps working after you update it. '
+            + 'The selector matches either the installation name or the release it currently carries — when two installations '
+            + 'share a release, name one or pass --account <label> (see: agents accounts). '
+            + 'The new release is fetched and launched before it replaces the working one, so a bad release leaves your agent running.',
+    });
+}

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadDaemon, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadAccounts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadUpdate, loadImport, loadExport, loadPackages, loadRoutines, loadDaemon, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadAccounts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadBench, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -292,6 +292,7 @@ Quick start:
 Agent versions:
   add <agent>[@version]           Install an agent CLI (e.g. agents add grok or agents add codex)
   import <agent>                  Adopt an existing global install (npm/homebrew) into agents-cli
+  update <agent>[@version]        Move an installed agent to a new release, keeping its name (agents-cli itself is 'agents upgrade')
   prune <agent>[@version]         Uninstall a version
   remove <agent>[@version]        Alias for prune
   use <agent>@<version>           Set the default version
@@ -942,6 +943,7 @@ async function registerAllEagerCommands() {
     await reg(loadWorkflows);
     await reg(loadWorktree);
     await reg(loadVersions);
+    await reg(loadUpdate);
     await reg(loadImport);
     await reg(loadExport);
     await reg(loadPackages);
@@ -1247,7 +1249,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v17';
+        const sentinelValue = 'v18';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/catchup.js

@@ -139,7 +139,10 @@ export async function runCatchup(opts = {}) {
             continue;
         }
         try {
-            const meta = await executeJobDetached(config);
+            // No `scheduledFor` here on purpose: the missed slot is already claimed by
+            // `claimMissedFire` above (its atomic mkdir IS the catch-up single-fire), so
+            // the late run gets a fresh id rather than colliding with the missed record.
+            const meta = await executeJobDetached(config, undefined, { kind: 'catchup' });
             outcomes.push({
                 name: entry.name,
                 expectedAt: entry.expectedAt,

package/dist/lib/daemon.d.ts

@@ -273,6 +273,23 @@ export interface DaemonStopResult {
     surviving: string[];
     detachedChildren: number[];
 }
+/**
+ * Live `__daemon-run` processes still registered in THIS state dir's instance
+ * registry, excluding `exclude`. State-dir-scoped by construction: the registry
+ * lives inside this daemon dir, so a daemon serving a DIFFERENT state dir (a test
+ * fixture with its own HOME, a separate install/home) registers elsewhere and is
+ * invisible here — it is never a stop/takeover target. POSIX-only (the registry
+ * and its `ps` liveness probe are); `[]` on Windows.
+ *
+ * Exported for `agents daemon status`/`doctor`/`services` (RUSH-2368): those
+ * commands previously flagged every `__daemon-run` on the box (a raw `ps` scan)
+ * as a "duplicate" of this daemon, which misreported test fixtures under their
+ * own HOME — and therefore their own state dir and registry — as strays to
+ * kill. This registry read is the same scope the reaper (`reapStrayDaemons`)
+ * and the stop postcondition (`stopDaemon`) already use, so the display and the
+ * reaper agree on what a duplicate is.
+ */
+export declare function findSurvivingStateDirDaemons(exclude: Set<number>): number[];
 /**
  * Stop the daemon and ASSERT its postcondition (SING-12, RUSH-2355), unloading it
  * from launchd/systemd if applicable.