@phnx-labs/agents-cli 1.20.78 → 1.20.82

package/dist/commands/sessions.d.ts

@@ -40,12 +40,23 @@ export declare function liveGlyphAndPreview(a: ActiveSession | undefined): {
     glyph: string;
     preview: string;
 };
+/**
+ * The one-word live status for a listing row — `working` / `waiting` / `idle`,
+ * the same three states the `--active` column shows, so the default list is no
+ * longer just a glyph. `waiting` is the actionable "needs you" case (a question /
+ * permission / plan-review), kept distinct from `idle` (stopped) and `working`.
+ * Empty for a not-live row, and for the rare no-signal `unknown`. Pure +
+ * exported for the row tests.
+ */
+export declare function liveStatusWord(a: ActiveSession | undefined): string;
 /**
  * The tracker/PR ref for a session's dedicated column: the ticket id when known,
  * else `PR#<n>`, else empty. Pulled out of the trailing badge blob so refs align
  * into a scannable column instead of jamming against a truncated topic.
  */
 export declare function ticketLabel(s: Pick<SessionMeta, 'ticketId' | 'prNumber'>): string;
+export declare function linkTicketCell(s: Pick<SessionMeta, 'ticketId' | 'prNumber' | 'prUrl'>, label: string): string;
+export declare function linkCwdCell(s: Pick<SessionMeta, 'cwd' | '_remote'>, label: string): string;
 /**
  * The row shape `agents sessions --active --json` emits. RUSH-1981: a watcher
  * joins active sessions on ticketId + project, but the raw ActiveSession nests
@@ -58,7 +69,16 @@ export declare function ticketLabel(s: Pick<SessionMeta, 'ticketId' | 'prNumber'
 export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<ActiveSession & {
     ticketId: string | null;
     project: string | null;
+    prLink: string | null;
 }>;
+/**
+ * Compact owner display for the `--active` owner column: the local-part of a
+ * resolved actor email/login (`muqsit@getrush.ai` -> `muqsit`), the id as-is
+ * when it has no `@`, and `-` when the actor is unresolved (`UNRESOLVED@<host>`)
+ * or absent (a launch predating actor stamping). Honest by design — an
+ * unresolved local run shows no owner rather than inventing one.
+ */
+export declare function ownerLabel(s: ActiveSession): string;
 /** Grouped + sorted view of active sessions for the --active renderer. */
 export interface ActiveSessionsLayout {
     workspaces: Array<{
@@ -170,6 +190,13 @@ export declare function gatherActiveSessions(opts?: {
     sessions: ActiveSession[];
     remoteDeviceCount: number;
 }>;
+/** One flat table row:
+ *   shortId · agent · version · model · project · [glyph] label·doing · [ticket] · [wt] · time
+ * `doing` is the live preview when running, else the topic. The `ticket` column
+ * (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 declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns): string;
 /**
  * Group key for the overview: prefer the indexed project name; else fold the cwd
  * to its repo — a worktree (`.../<repo>/.agents/worktrees/<slug>`) folds to the
@@ -221,6 +248,10 @@ export interface PickerColumns {
     /** Total width of the machine column, sized to the widest compacted hostname
      * in the pool (capped). Falls back to PICKER_MACHINE_W when absent. */
     machineWidth?: number;
+    /** Render the model column only when at least one row carries a model. */
+    showModel?: boolean;
+    /** Pool-sized model column width, including one trailing separator cell. */
+    modelWidth?: number;
     /** Render the ticket/PR column (only when at least one row carries a ref). */
     showTicket?: boolean;
     /**

package/dist/commands/sessions.js

@@ -32,7 +32,7 @@ import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
 import { formatRelativeTime } from '../lib/session/relative-time.js';
-import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList, linkUrl } from '../lib/session/render.js';
+import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList, linkPath, linkUrl, shortenModel } from '../lib/session/render.js';
 import { linearIssueUrl } from '../lib/session/linear.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
@@ -182,6 +182,11 @@ function statusColor(status) {
         case 'idle': return chalk.gray;
         case 'queued': return chalk.blue;
         case 'input_required': return chalk.yellow;
+        // Dead process: dimmed so it recedes from the live rows without being mistaken
+        // for the gray `idle` (which reads as "done, waiting for you" — a live state).
+        case 'closed': return chalk.dim;
+        // Days-stale / dangling: red so a session nobody is driving stands out.
+        case 'abandoned': return chalk.red;
         // Alive but un-introspectable (a harness whose transcript we can't parse).
         // Magenta so it never reads as the gray "idle" it used to be faked as.
         case 'unknown': return chalk.magenta;
@@ -303,6 +308,10 @@ export function formatActiveRowDescription(s) {
 }
 /** Short human word for a session's activity (falls back to the coarse status). */
 function activityLabel(s) {
+    // Lifecycle status wins over any residual parsed activity — a dead/dangling
+    // session must read `closed`/`abandoned`, not the `idle` its stale tail infers.
+    if (s.status === 'closed' || s.status === 'abandoned')
+        return s.status;
     if (s.activity === 'waiting_input')
         return 'waiting';
     if (s.activity === 'working')
@@ -335,14 +344,54 @@ export function indexActiveBySessionId(active) {
 export function liveGlyphAndPreview(a) {
     if (!a)
         return { glyph: '', preview: '' };
+    // `◌` (dotted) = alive but un-introspectable — visually distinct from `○` idle
+    // so an opaque harness is never mistaken for a finished one. `⊘` = abandoned /
+    // dangling; `×` = closed (dead pid) — both distinct from the `○` idle a live,
+    // stopped session shows, so a gone session never masquerades as a resting one.
+    if (a.status === 'abandoned')
+        return { glyph: statusColor(a.status)('⊘'), preview: buildSessionDescription(a) };
+    if (a.status === 'closed')
+        return { glyph: statusColor(a.status)('×'), preview: buildSessionDescription(a) };
     const waiting = a.status === 'input_required' || a.activity === 'waiting_input';
     const running = a.status === 'running' || a.activity === 'working';
-    // `◌` (dotted) = alive but un-introspectable — visually distinct from `○` idle
-    // so an opaque harness is never mistaken for a finished one.
     const unknown = a.status === 'unknown';
-    const shape = waiting ? '◐' : running ? '●' : unknown ? '◌' : '○';
+    const shape = waiting ? '◐'
+        : running ? '●'
+            : unknown ? '◌'
+                : '○';
     return { glyph: statusColor(a.status)(shape), preview: buildSessionDescription(a) };
 }
+/**
+ * The one-word live status for a listing row — `working` / `waiting` / `idle`,
+ * the same three states the `--active` column shows, so the default list is no
+ * longer just a glyph. `waiting` is the actionable "needs you" case (a question /
+ * permission / plan-review), kept distinct from `idle` (stopped) and `working`.
+ * Empty for a not-live row, and for the rare no-signal `unknown`. Pure +
+ * exported for the row tests.
+ */
+export function liveStatusWord(a) {
+    if (!a)
+        return '';
+    // Lifecycle status is definitive — surface it ahead of any parsed activity.
+    if (a.status === 'closed' || a.status === 'abandoned')
+        return a.status;
+    if (a.status === 'input_required' || a.activity === 'waiting_input')
+        return 'waiting';
+    if (a.status === 'running' || a.activity === 'working')
+        return 'working';
+    if (a.status === 'idle' || a.activity === 'idle')
+        return 'idle';
+    if (a.status === 'queued')
+        return 'queued';
+    return '';
+}
+/** The colored, space-padded status cell for a listing row (empty when not live). */
+function liveStatusCell(live) {
+    const word = liveStatusWord(live);
+    if (!word || !live)
+        return { cell: '', width: 0 };
+    return { cell: statusColor(live.status)(padToWidth(word, 8)), width: 8 };
+}
 /**
  * The tracker/PR ref for a session's dedicated column: the ticket id when known,
  * else `PR#<n>`, else empty. Pulled out of the trailing badge blob so refs align
@@ -351,6 +400,21 @@ export function liveGlyphAndPreview(a) {
 export function ticketLabel(s) {
     return s.ticketId ?? (s.prNumber ? `PR#${s.prNumber}` : '');
 }
+function ticketUrl(s) {
+    if (s.ticketId)
+        return linearIssueUrl(s.ticketId);
+    return s.prNumber ? s.prUrl : undefined;
+}
+export function linkTicketCell(s, label) {
+    const url = ticketUrl(s);
+    return url && label.trim() !== '-' ? linkUrl(url, label) : label;
+}
+export function linkCwdCell(s, label) {
+    return s.cwd && !s._remote ? linkPath(s.cwd, label) : label;
+}
+function modelLabel(model) {
+    return model ? shortenModel(model) : '-';
+}
 /**
  * The row shape `agents sessions --active --json` emits. RUSH-1981: a watcher
  * joins active sessions on ticketId + project, but the raw ActiveSession nests
@@ -365,6 +429,7 @@ export function serializeActiveSessionsForJson(sessions) {
         ...s,
         ticketId: s.ticket?.id ?? null,
         project: s.cwd ? path.basename(s.cwd) : null,
+        prLink: s.pr?.url ?? null,
     }));
 }
 /**
@@ -435,11 +500,12 @@ function locatorBadge(s) {
  * terminal width so the row never wraps.
  */
 function printActiveRow(s, indent) {
-    // shortId (8-char) · agent · host · status · badges · identity+todos+snippet
+    // shortId (8-char) · agent · host · status · owner · badges · identity+todos+snippet
     const idCol = chalk.dim(padToWidth((s.sessionId?.slice(0, 8)) ?? '-', 9));
     const kindCol = colorAgent(s.kind)(padToWidth(truncateToWidth(s.kind, 8), 9));
     const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
     const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
+    const ownerCol = chalk.cyan(padToWidth(truncateToWidth(ownerLabel(s), 8), 9));
     const fork = s.pidCount && s.pidCount > 1 ? chalk.dim(`×${s.pidCount} `) : '';
     const badges = (fork ? fork : '') + [signalBadges(s), locatorBadge(s)].filter(Boolean).join(' ');
     // Identity (label/project/ticket clickable) + checklist + live snippet.
@@ -447,10 +513,24 @@ function printActiveRow(s, indent) {
     // via the SSH fan-out already populated (including todos when the peer has them).
     const desc = formatActiveRowDescription(s) || '-';
     // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
-    const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);
+    const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);
     const room = Math.max(12, terminalWidth() - fixed - 1);
     const descCol = chalk.white(truncateToWidth(desc, room));
-    console.log(indent + idCol + kindCol + hostCol + statusCol + (badges ? badges + ' ' : '') + descCol);
+    console.log(indent + idCol + kindCol + hostCol + statusCol + ownerCol + (badges ? badges + ' ' : '') + descCol);
+}
+/**
+ * Compact owner display for the `--active` owner column: the local-part of a
+ * resolved actor email/login (`muqsit@getrush.ai` -> `muqsit`), the id as-is
+ * when it has no `@`, and `-` when the actor is unresolved (`UNRESOLVED@<host>`)
+ * or absent (a launch predating actor stamping). Honest by design — an
+ * unresolved local run shows no owner rather than inventing one.
+ */
+export function ownerLabel(s) {
+    const owner = s.owner;
+    if (!owner || owner.startsWith('UNRESOLVED@'))
+        return '-';
+    const at = owner.indexOf('@');
+    return at > 0 ? owner.slice(0, at) : owner;
 }
 /**
  * Short label for an IDE window. The slice key in live-terminals.json is
@@ -666,8 +746,8 @@ async function runRemoteSessionsJson(hosts) {
     process.stdout.write(serializeSessionsJson(sessions));
 }
 /**
- * `running N · idle N · waiting N · queued N · unknown N` for a bucket of
- * sessions (zero buckets omitted). Same bucketing as the grand-total summary so
+ * `running N · idle N · waiting N · queued N · closed N · abandoned N · unknown N`
+ * for a bucket of sessions (zero buckets omitted). Same bucketing as the summary so
  * per-group counts reconcile with the `(total)` beside the header — the `unknown`
  * bucket is what keeps an alive-but-opaque row from silently vanishing from the
  * tally. Empty when nothing.
@@ -677,6 +757,8 @@ function groupTally(sessions) {
     const idle = sessions.filter(s => s.status === 'idle').length;
     const waiting = sessions.filter(s => s.status === 'input_required').length;
     const queued = sessions.filter(s => s.status === 'queued').length;
+    const closed = sessions.filter(s => s.status === 'closed').length;
+    const abandoned = sessions.filter(s => s.status === 'abandoned').length;
     const unknown = sessions.filter(s => s.status === 'unknown').length;
     const parts = [];
     if (running)
@@ -687,6 +769,10 @@ function groupTally(sessions) {
         parts.push(`${waiting} waiting`);
     if (queued)
         parts.push(`${queued} queued`);
+    if (closed)
+        parts.push(`${closed} closed`);
+    if (abandoned)
+        parts.push(`${abandoned} abandoned`);
     if (unknown)
         parts.push(`${unknown} unknown`);
     return parts.join(' · ');
@@ -958,6 +1044,21 @@ async function renderSessionPreview(query, scope) {
             console.log(chalk.gray(`No session matches "${query}".`));
         return;
     }
+    // Lead with the live status when the session is still running, so the preview
+    // says working / waiting / idle up front — not just the historical transcript.
+    let live;
+    try {
+        live = indexActiveBySessionId(await getActiveSessions()).get(session.id);
+    }
+    catch { /* plain preview on any probe failure */ }
+    if (live) {
+        const { glyph } = liveGlyphAndPreview(live);
+        const word = liveStatusWord(live) || live.status;
+        const needsYou = live.status === 'input_required' || live.activity === 'waiting_input';
+        const reason = live.awaitingReason ? ` (${live.awaitingReason.replace('_', ' ')})` : '';
+        const suffix = needsYou ? chalk.yellow(`  ← needs you${reason}`) : '';
+        console.log(`${glyph} ${statusColor(live.status)(word)}${suffix}`);
+    }
     console.log(buildPreview(session));
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
@@ -1322,12 +1423,12 @@ function metaSignals(s) {
     };
 }
 /** One flat table row:
- *   shortId · agent · version · project · [glyph] label·doing · [ticket] · [wt] · time
+ *   shortId · agent · version · model · project · [glyph] label·doing · [ticket] · [wt] · time
  * `doing` is the live preview when running, else the topic. The `ticket` column
  * (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. */
-function flatSessionRow(session, live, showTicket = false, cols = {}) {
+export function flatSessionRow(session, live, showTicket = false, cols = {}) {
     const agentColor = colorAgent(session.agent);
     const when = formatRelativeTime(session.lastActivity ?? session.timestamp);
     const project = session.project || '-';
@@ -1350,19 +1451,31 @@ function flatSessionRow(session, live, showTicket = false, cols = {}) {
         : '';
     const TICKET_W = 10;
     const ticketCell = showTicket
-        ? chalk.blue(padToWidth(truncateToWidth(ticketLabel(session) || '-', TICKET_W), TICKET_W + 1))
+        ? chalk.blue(linkTicketCell(session, padToWidth(truncateToWidth(ticketLabel(session) || '-', TICKET_W), TICKET_W + 1)))
         : '';
+    // Live status word (working / waiting / idle) next to the glyph — the default
+    // list is no longer a bare glyph. Empty (zero width) for resting rows.
+    const { cell: statusCell, width: statusW } = liveStatusCell(live);
     const glyphW = glyph ? 2 : 0;
     const machineW = cols.showMachine ? machineColW : 0;
     const ticketW = showTicket ? TICKET_W + 1 : 0;
     const wtW = wt ? stringWidth(wt) + 1 : 0;
-    const topicW = Math.max(16, terminalWidth() - (10 + 9 + 8 + 16) - glyphW - machineW - ticketW - wtW - stringWidth(when) - 1);
+    const width = terminalWidth();
+    const requestedModelW = cols.showModel ? (cols.modelWidth ?? PICKER_MODEL_MAX) : 0;
+    const fixedW = (10 + 9 + 8 + 16) + glyphW + statusW + machineW + ticketW + wtW + stringWidth(when) + 1;
+    const modelSlack = width - fixedW - 16;
+    const modelW = requestedModelW <= modelSlack
+        ? requestedModelW
+        : modelSlack >= PICKER_MODEL_MIN ? modelSlack : 0;
+    const topicW = Math.max(16, width - fixedW - modelW);
     return (chalk.white(padToWidth(truncateToWidth(session.shortId, 9), 10)) +
         agentColor(padToWidth(truncateToWidth(session.agent, 8), 9)) +
         chalk.yellow(padToWidth(truncateToWidth(session.version || '-', 7), 8)) +
+        (modelW ? chalk.yellow(padToWidth(truncateToWidth(modelLabel(session.model), modelW - 1), modelW)) : '') +
         machineCell +
-        chalk.cyan(padToWidth(truncateToWidth(project, 14), 16)) +
+        chalk.cyan(linkCwdCell(session, padToWidth(truncateToWidth(project, 14), 16))) +
         (glyph ? glyph + ' ' : '') +
+        statusCell +
         renderTopicCell(label, doing, '', topicW, topicW) +
         ticketCell +
         (wt ? wt + ' ' : '') +
@@ -1383,13 +1496,15 @@ function treeSessionRow(session, live) {
     const badges = signalBadges(metaSignals(session));
     const badgeW = badges ? stringWidth(badges) + 1 : 0;
     const head = label ? `${label} · ${topic}` : topic;
+    const { cell: statusCell, width: statusW } = liveStatusCell(live);
     const glyphW = glyph ? 2 : 0;
-    const topicW = Math.max(12, terminalWidth() - (2 + 9 + 8) - glyphW - badgeW - stringWidth(when) - 1);
+    const topicW = Math.max(12, terminalWidth() - (2 + 9 + 8) - glyphW - statusW - badgeW - stringWidth(when) - 1);
     return ('  ' +
         chalk.dim(padToWidth(session.shortId, 9)) +
         agentColor(padToWidth(truncateToWidth(session.agent, 7), 8)) +
         (badges ? badges + ' ' : '') +
         (glyph ? glyph + ' ' : '') +
+        statusCell +
         padToWidth(chalk.white(truncateToWidth(head, topicW)), topicW) +
         ' ' + chalk.gray(when));
 }
@@ -1506,7 +1621,9 @@ function printSessionTable(sessions, hiddenCount = 0, tree = false, liveIndex) {
                 console.log();
             first = false;
             const group = byDir.get(key);
-            console.log(`${chalk.cyan.bold(shortCwd(key))} ${chalk.gray(`(${group.length})`)}`);
+            const cwd = group.find((s) => s.cwd && !s._remote)?.cwd;
+            const header = cwd ? linkPath(cwd, shortCwd(key)) : shortCwd(key);
+            console.log(`${chalk.cyan.bold(header)} ${chalk.gray(`(${group.length})`)}`);
             for (const s of group)
                 console.log(treeSessionRow(s, liveIndex?.get(s.id)));
         }
@@ -1702,12 +1819,18 @@ function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
 const PICKER_MACHINE_W = 11;
 const PICKER_MACHINE_MIN = 8;
 const PICKER_MACHINE_MAX = 18;
+const PICKER_MODEL_MIN = 6;
+const PICKER_MODEL_MAX = 13;
 /** Column width that shows every compacted hostname in `machines` whole (one
  * trailing space for separation), bounded by MIN/MAX. */
 function machineColumnWidth(machines, label) {
     const widest = machines.reduce((w, m) => Math.max(w, stringWidth(label(m))), 0);
     return Math.min(PICKER_MACHINE_MAX, Math.max(PICKER_MACHINE_MIN, widest + 1));
 }
+function modelColumnWidth(sessions) {
+    const widest = sessions.reduce((width, session) => (Math.max(width, session.model ? stringWidth(modelLabel(session.model)) : 0)), 0);
+    return Math.min(PICKER_MODEL_MAX, Math.max(PICKER_MODEL_MIN, widest + 1));
+}
 /**
  * Compact display form for machine ids: strip the longest shared dash-delimited
  * prefix so "yosemite-s0"/"yosemite-s1" read as "s0"/"s1" while unrelated ids
@@ -1743,6 +1866,8 @@ export function pickerColumnsFor(sessions) {
         showMachine: distinct.length > 1,
         machineLabel,
         machineWidth: machineColumnWidth(distinct, machineLabel),
+        showModel: sessions.some((s) => !!s.model),
+        modelWidth: modelColumnWidth(sessions),
         showTicket: sessions.some((s) => ticketLabel(s) !== ''),
     };
 }

package/dist/commands/set.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agents set` — ergonomic top-level setter for per-agent/version run defaults.
+ *
+ * `agents set claude@2.1.220 --model opus-5` pins the default model (and/or
+ * mode) that `agents run` uses for that agent version. It reads and writes the
+ * same store as `agents defaults run set` (agents.yaml -> run.defaults), so the
+ * two stay consistent — `set` is just the short front door.
+ *
+ *   agents set                          # list every configured default
+ *   agents set claude@2.1.220           # show the default for one version
+ *   agents set claude@2.1.220 --model opus-5
+ *   agents set 'claude:*' --mode auto --model opus
+ */
+import type { Command } from 'commander';
+export declare function registerSetCommand(program: Command): void;

package/dist/commands/set.js

@@ -0,0 +1,79 @@
+/**
+ * `agents set` — ergonomic top-level setter for per-agent/version run defaults.
+ *
+ * `agents set claude@2.1.220 --model opus-5` pins the default model (and/or
+ * mode) that `agents run` uses for that agent version. It reads and writes the
+ * same store as `agents defaults run set` (agents.yaml -> run.defaults), so the
+ * two stay consistent — `set` is just the short front door.
+ *
+ *   agents set                          # list every configured default
+ *   agents set claude@2.1.220           # show the default for one version
+ *   agents set claude@2.1.220 --model opus-5
+ *   agents set 'claude:*' --mode auto --model opus
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { formatRunDefaultEntry, listRunDefaults, parseRunDefaultSelector, setRunDefault, } from '../lib/run-defaults.js';
+export function registerSetCommand(program) {
+    const set = program
+        .command('set [selector]')
+        .description('Set the default model/mode an agent version uses for `agents run`')
+        .option('--model <model>', 'Default model or model alias, forwarded via --model')
+        .option('--mode <mode>', "Default mode: plan, edit, auto, skip. 'full' accepted as alias for skip.")
+        .action((selector, options) => {
+        try {
+            const hasFlags = options.model !== undefined || options.mode !== undefined;
+            if (!selector) {
+                if (hasFlags) {
+                    throw new Error('Selector is required when passing --model/--mode. Example: agents set claude@2.1.220 --model opus-5');
+                }
+                const entries = listRunDefaults();
+                if (entries.length === 0) {
+                    console.log(chalk.gray('No agent defaults configured.'));
+                    console.log(chalk.gray('Set one with: agents set claude@2.1.220 --model opus-5'));
+                    return;
+                }
+                console.log(chalk.bold('Agent Defaults\n'));
+                for (const entry of entries) {
+                    console.log(`  ${formatRunDefaultEntry(entry)}`);
+                }
+                return;
+            }
+            if (!hasFlags) {
+                const parsed = parseRunDefaultSelector(selector);
+                const entry = listRunDefaults().find((e) => e.selector === parsed.selector);
+                if (!entry || (!entry.defaults.mode && !entry.defaults.model)) {
+                    console.log(chalk.gray(`No default set for ${parsed.selector}.`));
+                    console.log(chalk.gray(`Set one with: agents set ${selector} --model <model>`));
+                    return;
+                }
+                console.log(`  ${formatRunDefaultEntry(entry)}`);
+                return;
+            }
+            const entry = setRunDefault(selector, {
+                ...(options.mode !== undefined ? { mode: options.mode } : {}),
+                ...(options.model !== undefined ? { model: options.model } : {}),
+            });
+            console.log(chalk.green('Set default:'));
+            console.log(`  ${formatRunDefaultEntry(entry)}`);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    setHelpSections(set, {
+        examples: `
+      agents set claude@2.1.220 --model opus-5
+      agents set 'claude:*' --mode auto --model opus
+      agents set claude@2.1.220
+      agents set
+    `,
+        notes: `
+      Selectors use <agent>@<version> or <agent>:<version>; * matches all versions.
+      Exact selectors override wildcard selectors field by field.
+      Writes the same store as 'agents defaults run set'. Explicit flags on
+      'agents run' always win over configured defaults.
+    `,
+    });
+}

package/dist/commands/setup-fleet.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `agents setup fleet` — guided Tailscale device onboarding.
+ *
+ * This wizard is a front door over the existing fleet/device commands: sync
+ * Tailscale into the registry, choose auth, render SSH config, test devices, and
+ * optionally run the fleet updater without reimplementing those subcommands.
+ */
+import type { Command } from 'commander';
+interface SetupFleetOptions {
+    auth?: string;
+    bundle?: string;
+    bundleKey?: string;
+    yes?: boolean;
+    writeSshConfig?: boolean;
+    testConnectivity?: boolean;
+    fleetUpdate?: boolean;
+}
+export declare function runFleetSetupWizard(opts?: SetupFleetOptions): Promise<boolean>;
+/** Register `agents setup fleet` under the parent `setup` command. */
+export declare function registerSetupFleetCommand(setupCmd: Command): void;
+export {};