@phnx-labs/agents-cli 1.20.89 → 1.20.90

package/dist/commands/secrets.js

@@ -460,7 +460,7 @@ function compactRemaining(expiresAt) {
     return `${Math.round(hours / 24)}d`;
 }
 /** The POLICY column for `secrets list`: the prompt policy, plus a concise
- * state hint. `daily` shows `held Nh` when the secrets-agent is currently
+ * state hint. `hold` shows `held Nh` when the secrets-agent is currently
  * caching the bundle; `always` and `never` show whether they prompt. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
 export function renderPolicyCol(b, held) {
@@ -472,6 +472,18 @@ export function renderPolicyCol(b, held) {
     const exp = held?.get(b.name);
     return exp ? chalk.green(`hold · held ${compactRemaining(exp)}`) : chalk.gray('hold');
 }
+/** The hold-window line at the top of `secrets status`. Names the `hold` policy
+ * the window belongs to — the rename in #1604 left this surface still saying
+ * "daily", the one name the CLI no longer accepts in its own help. Pure so the
+ * vocabulary is pinned by a test rather than re-drifting on the next rename. */
+export function renderHoldSummary(holdStr, configured) {
+    const source = configured ? ' (secrets.agent.holdMs)' : ' (default)';
+    return `hold: ${holdStr}${source} — a bundle on the hold policy prompts once, then stays silent for this long or until sleep/logout.`;
+}
+/** The empty-broker line under the hold summary. Named here, beside
+ * `renderHoldSummary`, for the same reason: it is the second line the rename
+ * left saying `daily`, and a test pins both. */
+export const NO_BUNDLES_HELD_LINE = 'No bundles held. The next read of each hold-policy bundle will prompt once, then hold.';
 /** Human-readable hold window for `secrets status`. Sub-hour values render in
  * minutes (so a near-floor `holdMs` never shows a confusing "0 hours"), whole
  * hours up to 2 days, whole days beyond. Pure — unit-tested. */
@@ -805,7 +817,7 @@ export function registerSecretsCommands(program) {
             return;
         }
         const bundles = listBundles();
-        // Cross-reference the secrets-agent so `daily` bundles that are currently
+        // Cross-reference the secrets-agent so `hold` bundles that are currently
         // held can show "· held Nh". Soft-fails to no hint if the broker is down.
         const held = new Map();
         if (process.platform === 'darwin') {
@@ -1174,7 +1186,7 @@ export function registerSecretsCommands(program) {
             const resolvedName = name ?? (await promptBundleName());
             validateBundleName(resolvedName);
             // Leave policy unset unless the user explicitly chose one, so the bundle
-            // inherits the configured default (`daily`) instead of being pinned.
+            // inherits the configured default (`hold`) instead of being pinned.
             const policyOpt = opts.policy ?? opts.tier;
             const policy = policyOpt ? parsePolicyOpt(policyOpt) : undefined;
             const backend = opts.synced ? 'vault' : resolveBackendOpt(opts.backend);
@@ -2266,7 +2278,7 @@ Examples:
             (brokerUp
                 ? chalk.green('running') + chalk.gray(isDaemonRunning() ? ' (hosted by the daemon)' : ' (standalone)')
                 : chalk.yellow('not running — starts on demand, or run `agents secrets start` to bring the daemon up now')));
-        // Diagnostic: version skew is the top reason a `daily` bundle keeps
+        // Diagnostic: version skew is the top reason a `hold` bundle keeps
         // re-prompting — a broker on an older build gets torn down when the CLI
         // version changes (e.g. `agents-cli-update`), wiping every held bundle.
         const onDisk = getCliVersionFresh();
@@ -2286,11 +2298,11 @@ Examples:
         catch {
             return false;
         } })();
-        console.log(chalk.gray(`hold: ${holdStr}${configured ? ' (secrets.agent.holdMs)' : ' (default)'} — a daily bundle prompts once, then stays silent for this long or until sleep/logout.`));
+        console.log(chalk.gray(renderHoldSummary(holdStr, configured)));
         const entries = await agentStatus();
         const held = new Set(entries.map((e) => e.name));
         if (entries.length === 0) {
-            console.log(chalk.gray('No bundles held. The next read of each daily bundle will prompt once, then hold.'));
+            console.log(chalk.gray(NO_BUNDLES_HELD_LINE));
             console.log(chalk.gray('Pre-warm now with: agents secrets unlock <bundle>  (or --all)'));
         }
         else {

package/dist/commands/sessions-browser.d.ts

@@ -26,6 +26,8 @@ export interface BrowserFilter {
     device?: string;
     /** filter to one team's lineage, or all — the `T` key / `--in-team`. */
     team?: string;
+    /** favorited-only — the `f` key / `--favorites`. */
+    favorites: boolean;
     /** this-repo subtree vs every directory — the `P` key / `--all`. */
     projectScope: 'repo' | 'all';
     /** time window (undefined = all time) — the `W` key / `--since`. */
@@ -77,6 +79,7 @@ export declare function activeBrowserSeed(opts: {
     host?: string[];
     since?: string;
     all?: boolean;
+    favorites?: boolean;
 }): Partial<BrowserFilter>;
 /**
  * The initial filter for the bare interactive listing: current-repo subtree by
@@ -92,6 +95,7 @@ export declare function bareBrowserSeed(opts: {
     since?: string;
     host?: string[];
     inTeam?: string;
+    favorites?: boolean;
 }): Partial<BrowserFilter>;
 /**
  * A live session's stable row key: its session id when the agent reported one,

package/dist/commands/sessions-browser.js

@@ -17,9 +17,10 @@ import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
 import { enrichTeamOrigins, safeTeamText } from '../lib/session/team-filter.js';
+import { listFavorites, toggleFavorite } from '../lib/session/favorites.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
-import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, } from './sessions.js';
 /**
  * Complete a seed into the filter the picker actually runs on.
  *
@@ -37,6 +38,7 @@ export function buildInitialFilter(initial) {
     return {
         running: initial.running ?? false,
         teams: initial.teams ?? false,
+        favorites: initial.favorites ?? false,
         agent: initial.agent,
         device: initial.device,
         team: initial.team,
@@ -107,6 +109,8 @@ export function browserFilterToArgv(f, query = '') {
         a.push('--active');
     if (f.teams)
         a.push('--teams');
+    if (f.favorites)
+        a.push('--favorites');
     if (f.agent)
         a.push('-a', f.agent);
     if (f.device)
@@ -140,6 +144,7 @@ export function activeBrowserSeed(opts) {
     return {
         running: true,
         teams: !!opts.teams,
+        favorites: !!opts.favorites,
         agent: opts.agent,
         projectScope: 'all',
         device: normalizeDeviceSeed(opts.host?.[0]),
@@ -170,6 +175,7 @@ export function bareBrowserSeed(opts) {
     const wholeTeam = !!opts.inTeam;
     return {
         teams: !!opts.teams,
+        favorites: !!opts.favorites,
         agent: opts.agent,
         // The filter carries one device; seed it only when the scope names exactly
         // one, so a two-device scope isn't narrowed to the first of them.
@@ -359,9 +365,14 @@ export function shouldShowHostColumn(f, live, rows) {
         return false;
     return rows.some((r) => liveHostLabel(live.get(r.id)) !== '');
 }
-/** Apply the cheap in-memory filters (agent / device / project / running). */
-function applyFilters(rows, live, f, self) {
+/** Apply the cheap in-memory filters (agent / device / project / running / favorites). */
+function applyFilters(rows, live, f, self, favorites) {
     let out = rows;
+    // A projected live row is keyed by pid/task when it has no session id, and a
+    // favorite is always keyed by a real session id — so an id-less row can never
+    // be favorited and correctly drops out here.
+    if (f.favorites)
+        out = out.filter((r) => favorites.has(r.id));
     if (f.agent)
         out = out.filter((r) => r.agent === f.agent);
     if (f.device)
@@ -398,13 +409,15 @@ function headerFor(f) {
         bits.push('running');
     if (f.teams)
         bits.push('teams');
+    if (f.favorites)
+        bits.push('favorites');
     return bits.join(' · ');
 }
 function helpFor(_f, mode) {
     if (mode === 'search') {
         return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
     }
-    return 's search · r running · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
+    return 's search · r running · f favorites · * star · c teams · t team · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
 }
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.
@@ -432,6 +445,10 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
     // The live index is slow (a full ps/tmux scan) and only the running filter
     // needs it — fetch it once, lazily, the first time running is toggled on.
     let liveCache = null;
+    // Re-read every load (it's an mtime-memoized parse of one small file), so the
+    // `*` key's reload picks up the star it just wrote — and so does a favorite
+    // starred by another session on this machine.
+    let favorites = new Set();
     // Generation guard: two quick keypresses can start overlapping loads whose
     // SSH fan-outs settle out of order. dynamicPicker's own gen ref guards which
     // rows become `items`, but the shared closure state below (cols / cycle pools /
@@ -489,9 +506,14 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             ...rows.map((r) => safeTeamText(r.spawnedTeam)),
             ...rows.map((r) => safeTeamText(r.teamOrigin?.team)),
         ]);
-        const filtered = applyFilters(rows, live ?? new Map(), f, self);
+        favorites = listFavorites();
+        const filtered = applyFilters(rows, live ?? new Map(), f, self, favorites);
         cols = pickerColumnsFor(filtered);
         cols.showHost = shouldShowHostColumn(f, live, filtered);
+        // Status rides the same gate as the host column: both come from the live
+        // scan, so both belong to the running view and neither should widen a plain
+        // transcript listing that has no live rows to fill them.
+        cols.showStatus = !!f.running && !!live;
         return filtered;
     };
     const picked = await dynamicPicker({
@@ -499,9 +521,17 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         initialFilter,
         load,
         keyFor: (s) => s.id,
-        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id))),
+        labelFor: (s, q) => formatPickerLabel(s, q, cols, sshOriginTagFor(liveCache, s.id), liveHostLabel(liveCache?.get(s.id)), favorites.has(s.id), liveCache?.get(s.id)),
         matches: sessionMatchesQuery,
-        buildPreview,
+        // Lead the preview with the live status banner — the one place a `crashed` /
+        // `orphaned` session gets a sentence instead of a glyph. `buildPreview` is
+        // memoized per session, so the volatile live half is prepended here rather
+        // than baked into the cached body.
+        buildPreview: (s) => {
+            const headline = formatLiveStatusHeadline(liveCache?.get(s.id), favorites.has(s.id));
+            const body = buildPreview(s);
+            return headline ? `${headline}\n${body}` : body;
+        },
         headerFor: (f) => unreachable.length > 0
             ? `${headerFor(f)} · ${chalk.yellow(`${unreachable.join(', ')}: unreachable`)}`
             : headerFor(f),
@@ -511,6 +541,7 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
         loadingMessage: local ? 'Loading…' : 'Loading (reaching other machines)…',
         keyBindings: {
             r: (f) => ({ ...f, running: !f.running }),
+            f: (f) => ({ ...f, favorites: !f.favorites }),
             c: (f) => ({ ...f, teams: !f.teams }),
             a: (f) => ({ ...f, agent: cycle(f.agent, agentsInPool) }),
             d: (f) => ({ ...f, device: cycle(f.device, devicesInPool) }),
@@ -521,8 +552,19 @@ export async function runSessionBrowser(initial = {}, opts = {}) {
             p: (f) => (hosts ? f : { ...f, projectScope: f.projectScope === 'repo' ? 'all' : 'repo' }),
             w: (f) => ({ ...f, window: cycleWindow(f.window) }),
         },
-        onKey: (name, f, _active, query) => {
-            if (name === 'y') {
+        onKey: (name, f, active, query) => {
+            if (name === '*') {
+                // Only a row with a real session id can be starred: a projected live row
+                // with no id is keyed by pid, which is gone the moment the process is.
+                if (!active || active.id.startsWith(LIVE_ROW_PREFIX))
+                    return 'nothing to star on this row';
+                const on = toggleFavorite(active.id);
+                // reload so the row's star is repainted — labels are memoized per row.
+                return { flash: on ? `★ favorited ${active.shortId}` : `☆ unfavorited ${active.shortId}`, reload: true };
+            }
+            // Both cases: `hotkeyToken` hands `onKey` the literal character, and this
+            // key worked with caps lock on before it existed.
+            if (name === 'y' || name === 'Y') {
                 // Thread the live search query so the copied command reproduces the
                 // exact view — the human→agent bridge must include the search term.
                 const cmd = 'ag ' + browserFilterToArgv(f, query).join(' ');

package/dist/commands/sessions-favorite.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `agents sessions favorite` — the non-TTY half of the star.
+ *
+ * The `*` hotkey in the interactive browser is how a human stars a session; this
+ * is how a script, an agent, or a machine without a TTY does the same thing, and
+ * it is what makes the feature testable end to end without driving a terminal UI.
+ * Both write the one store in `lib/session/favorites.ts`.
+ */
+import type { Command } from 'commander';
+/**
+ * Resolve one user-typed id (usually the 8-char short id the listing prints) to
+ * a full session id. Ambiguity is an ERROR, not a silent first-match: starring
+ * the wrong session is invisible until the user wonders where their star went.
+ */
+export declare function resolveFavoriteTarget(idQuery: string): {
+    id: string;
+} | {
+    error: string;
+};
+export declare function registerSessionsFavoriteCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-favorite.js

@@ -0,0 +1,120 @@
+/**
+ * `agents sessions favorite` — the non-TTY half of the star.
+ *
+ * The `*` hotkey in the interactive browser is how a human stars a session; this
+ * is how a script, an agent, or a machine without a TTY does the same thing, and
+ * it is what makes the feature testable end to end without driving a terminal UI.
+ * Both write the one store in `lib/session/favorites.ts`.
+ */
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { findSessionsById } from '../lib/session/db.js';
+import { isCompleteSessionId } from '../lib/session/discover.js';
+import { isFavorite, listFavorites, setFavorite } from '../lib/session/favorites.js';
+/**
+ * Resolve one user-typed id (usually the 8-char short id the listing prints) to
+ * a full session id. Ambiguity is an ERROR, not a silent first-match: starring
+ * the wrong session is invisible until the user wonders where their star went.
+ */
+export function resolveFavoriteTarget(idQuery) {
+    const matches = findSessionsById(idQuery);
+    // A COMPLETE id needs no index entry: the id is the key the store is built on,
+    // and requiring a transcript row would refuse exactly the newest sessions — a
+    // live one that has not been indexed yet. The browser's `*` stars those from
+    // the live row, so demanding a DB hit here would make the two disagree.
+    if (matches.length === 0) {
+        return isCompleteSessionId(idQuery.trim())
+            ? { id: idQuery.trim() }
+            : { error: `No session matches "${idQuery}".` };
+    }
+    if (matches.length > 1) {
+        const ids = matches.slice(0, 5).map((m) => m.shortId).join(', ');
+        return { error: `"${idQuery}" matches ${matches.length} sessions (${ids}…) — use a longer id.` };
+    }
+    return { id: matches[0].id };
+}
+export function registerSessionsFavoriteCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('favorite')
+        .argument('[ids...]', 'Session ids to star (full or short id prefix)')
+        .description('Star sessions so they are easy to find again — list them with --favorites, or `f` in the browser.')
+        .option('--remove', 'Unstar the given sessions instead of starring them')
+        .option('--list', 'List the starred sessions (the default when no ids are given)')
+        .option('--json', 'Output JSON');
+    setHelpSections(cmd, {
+        examples: `
+      # Star a session by its short id (the 8 chars the listing prints)
+      agents sessions favorite 26c27162
+
+      # See what is starred
+      agents sessions favorite --list
+
+      # Browse only the starred ones
+      agents sessions --favorites
+
+      # Unstar it again
+      agents sessions favorite 26c27162 --remove
+    `,
+        notes: `
+      In the interactive browser (\`agents sessions\`), \`*\` stars the highlighted
+      session and \`f\` filters the list down to the starred ones.
+
+      Stars live in ~/.agents/.history/favorites.json, keyed by session id, so
+      they survive a reindex of the session cache. They are per-machine: session
+      sync carries transcripts, not this file.
+    `,
+    });
+    cmd.action((ids, options, self) => {
+        // `--json` has to come from the merged view, not `options`. The parent
+        // `sessions` command declares `--json` AND takes a positional `[query]`, so
+        // commander keeps parsing parent-known options past the subcommand name and
+        // binds `--json` to the PARENT — `options.json` is silently undefined here
+        // while `--remove`/`--list` (unknown to the parent) arrive fine.
+        // `optsWithGlobals` is commander's own answer for reading an option a parent
+        // owns; it is still declared on this command so `--help` documents it.
+        const json = self.optsWithGlobals().json === true;
+        if (options.list || ids.length === 0) {
+            const starred = [...listFavorites()].sort();
+            if (json) {
+                process.stdout.write(JSON.stringify({ favorites: starred }, null, 2) + '\n');
+                return;
+            }
+            if (starred.length === 0) {
+                console.log(chalk.gray('No favorited sessions. Star one with `agents sessions favorite <id>`.'));
+                return;
+            }
+            for (const id of starred)
+                console.log(`${chalk.yellow('★')} ${id}`);
+            console.log(chalk.gray(`\n${starred.length} favorite${starred.length === 1 ? '' : 's'}.`));
+            return;
+        }
+        const on = !options.remove;
+        const results = [];
+        for (const idQuery of ids) {
+            const resolved = resolveFavoriteTarget(idQuery);
+            if ('error' in resolved) {
+                results.push({ query: idQuery, error: resolved.error });
+                continue;
+            }
+            // Unstarring something that was never starred, or starring it twice, is a
+            // no-op the store already short-circuits — report the resulting state.
+            setFavorite(resolved.id, on);
+            results.push({ query: idQuery, id: resolved.id, favorite: isFavorite(resolved.id) });
+        }
+        if (json) {
+            process.stdout.write(JSON.stringify({ results }, null, 2) + '\n');
+        }
+        else {
+            for (const r of results) {
+                if (r.error)
+                    console.error(chalk.red(r.error));
+                else
+                    console.log(`${r.favorite ? chalk.yellow('★ favorited') : chalk.gray('☆ unfavorited')} ${r.id}`);
+            }
+        }
+        // A failed lookup is a failed command — a script must not read "starred" from
+        // a zero exit when nothing was starred.
+        if (results.some((r) => r.error))
+            process.exitCode = 1;
+    });
+}

package/dist/commands/sessions.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
@@ -17,6 +17,10 @@ interface SessionsOptions extends SessionFilterOptions {
     /** Also list sessions from the user's own unmanaged ~/.<agent> installs. */
     unmanaged?: boolean;
     query?: string;
+    /** Resolve one historical selector to metadata only (requires --json). */
+    resolve?: string;
+    /** Versioned internal peer protocol; old/unsafe peers must reject it. */
+    resolveSafeV1?: string;
     limit?: string;
     sort?: string;
     json?: boolean;
@@ -40,6 +44,8 @@ interface SessionsOptions extends SessionFilterOptions {
     flat?: boolean;
     /** With --active: show only sessions waiting on user input; exit 1 if any. */
     waiting?: boolean;
+    /** Show only favorited (starred) sessions — the `f` key's flag twin. */
+    favorites?: boolean;
     /** Enrich the listing with live glyphs/preview for running rows. Default on;
      * `--no-live` sets this false. Commander's `--no-` convention. */
     live?: boolean;
@@ -120,6 +126,29 @@ export declare function liveGlyphAndPreview(a: ActiveSession | undefined): {
  * exported for the row tests.
  */
 export declare function liveStatusWord(a: ActiveSession | undefined): string;
+/**
+ * True when a session is blocked on a human — the `--waiting` contract.
+ *
+ * NOT `status === 'input_required'`. `foldHostLink` rewrites that status to
+ * `orphaned` when nothing is attached, and a session waiting on a question with
+ * NOBODY watching is the most acute case `--waiting` exists to surface, not one
+ * it should drop. The underlying `activity` is never rewritten, so it is the
+ * honest signal here.
+ *
+ * But `activity` is never rewritten for a DEAD session either: one that died
+ * mid-question keeps `waiting_input` forever, and answering it is not a thing a
+ * human can do — it needs a relaunch. `--waiting` is a scriptable gate ("does
+ * anything need me?"), so a corpse must not trip it.
+ *
+ * `closed` and `crashed` are unconditionally dead, so they are excluded outright.
+ * `abandoned` is NOT: it fires on transcript staleness before the liveness check,
+ * so it also covers the live-but-forgotten case — an interactive session that
+ * asked a question and sat untouched over a long weekend is still answerable, and
+ * is exactly what this gate exists for. It is excluded only when we positively
+ * know its process is gone; unknown liveness (an older peer, a row with no pid)
+ * stays excluded rather than inventing a human who can answer.
+ */
+export declare function isAwaitingUser(s: ActiveSession): boolean;
 /**
  * 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
@@ -230,6 +259,10 @@ export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: s
  * `--json --host` remote fan-out so both emit byte-identical row shapes.
  */
 export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
+/** The intentionally small metadata contract emitted by `sessions --resolve`.
+ * Transcript locations, extracted plans, account data, costs, and other indexed
+ * payload stay local to the machine that owns them. */
+export declare function serializeResolvedSessionsJson(sessions: SessionMeta[]): string;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
  * included by default; an explicit `--host`/`--device` list scopes the view to
@@ -281,6 +314,17 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/**
+ * The one-line live status banner shown above a session preview: the glyph, the
+ * status word, and — when the session needs a human or has LOST one — a plain
+ * sentence saying so. Shared by `--preview` and the interactive browser's preview
+ * pane so both explain a state the same way.
+ *
+ * `crashed` and `orphaned` are the states a glyph alone cannot carry: nobody
+ * reads "orphan" and knows it means "still running in tmux with no window
+ * attached", so those two spell it out.
+ */
+export declare function formatLiveStatusHeadline(live: ActiveSession | undefined, favorite?: boolean): string;
 /**
  * Whether a session belongs to `team`, from either end: it spawned the team, or
  * it is one of the team's teammates. Case-insensitive, matching the SQL
@@ -305,7 +349,7 @@ export declare function teamBadge(session: SessionMeta): {
  * (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;
+export declare function flatSessionRow(session: SessionMeta, live?: ActiveSession, showTicket?: boolean, cols?: PickerColumns, favorite?: boolean): 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
@@ -370,6 +414,19 @@ export interface PickerColumns {
      * off for a plain transcript listing, where no row has a host.
      */
     showHost?: boolean;
+    /**
+     * Render the favorite marker column. Like every other conditional column here,
+     * it earns its 2 cells only when some row in the pool is actually starred — a
+     * user who has never favorited anything pays nothing for the feature.
+     */
+    showFavorite?: boolean;
+    /**
+     * Render the live status column (`working` / `waiting` / `orphan` / `crashed`).
+     * Live-only, gated the same way as {@link showHost}: it comes from the
+     * active-session scan, so the running-filtered browser sets it and a plain
+     * transcript listing — where no row has a status — leaves it off.
+     */
+    showStatus?: boolean;
     /**
      * Cells the picker prepends before each row: 2 for the single-select cursor
      * ('> '), 6 for the multi-select cursor + checkbox ('> [x] '). Reserved from
@@ -399,7 +456,7 @@ export declare function pickerColumnsFor(sessions: SessionMeta[]): PickerColumns
  * resolvable host (cloud rows, an unreadable process env).
  */
 export declare function liveHostLabel(a: ActiveSession | undefined): string;
-export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag, host?: string): string;
+export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns, ssh?: SshOriginTag, host?: string, favorite?: boolean, live?: ActiveSession): string;
 /**
  * Pick a hint to show above the picker. Deterministic (keys off the pool size)
  * so it stays fixed across the picker's re-renders within a single run.
@@ -466,7 +523,9 @@ export interface SessionQueryResolution {
  * search (a bare id must not surface every transcript that merely mentions it).
  * A genuine search phrase keeps the ranked metadata+content search.
  */
-export declare function resolveSessionQuery(pool: SessionMeta[], query: string): SessionQueryResolution;
+export declare function resolveSessionQuery(pool: SessionMeta[], query: string, options?: {
+    indexFallback?: boolean;
+}): SessionQueryResolution;
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
 /**
@@ -489,36 +548,60 @@ export interface FleetResolveDeps {
     gatherRemoteList: typeof gatherRemoteList;
     runOnPeer: typeof runOnPeer;
 }
-/** One distinct machine that reported the id, plus its winning row. */
+/** One distinct machine that reported a logical session, plus its winning row. */
 interface FleetHit {
     machine: string;
     session: SessionMeta;
 }
-/** Group a fleet sweep's rows to the DISTINCT machines that hold the id. Each
- * peer answered `sessions <id> --json --local`, which (post-fix) id-resolves and
- * so returns the matching row(s); a peer with a synced MIRROR of the same id can
- * emit more than one row, so we keep the first per machine. Rows the peer somehow
- * returned that do NOT match the id (defensive against version skew) are dropped
- * so a stray content hit can never masquerade as an exact resolution. */
-export declare function fleetHitsById(rows: SessionMeta[], id: string): FleetHit[];
-/**
- * Locate a full session id across the online fleet and render it from the machine
+/** One logical session returned by the fleet, including every machine holding a copy. */
+export interface FleetSessionCandidate {
+    id: string;
+    hits: FleetHit[];
+}
+export type MetadataResolveOutcome = {
+    kind: 'resolved';
+    session: SessionMeta;
+} | {
+    kind: 'not-found';
+} | {
+    kind: 'ambiguous';
+    candidates: FleetSessionCandidate[];
+} | {
+    kind: 'partial';
+    failedPeers: string[];
+};
+/** Resolve a fleet sweep through the same canonical full-id / prefix resolver as
+ * local lookups, then group copies by logical session id. Synced mirrors of one
+ * session therefore stay one candidate even when several machines report them;
+ * distinct ids sharing a prefix remain distinct ambiguity candidates. */
+export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: string): FleetSessionCandidate[];
+/** Fixed peer argv for the metadata resolver. Scope flags compose identically on
+ * every host; `--all` removes the SSH login cwd/time window, not agent/project filters. */
+export declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
+/** Resolution must fail closed when any selected peer did not answer. Choosing
+ * from a partial fleet can turn an unseen candidate into a false unique match. */
+export declare function metadataResolveOutcome(localMatches: SessionMeta[], remote: {
+    sessions: SessionMeta[];
+    unreachable: string[];
+}, selector: string): MetadataResolveOutcome;
+/**
+ * Locate a full session id or short id prefix across the online fleet and render it from the machine
  * that holds it. The local disk already missed; this fans `sessions <id> --json
  * --all` out to every registered online peer (or the explicit `hosts` set),
  * groups the rows to distinct machines, then:
  *
- *   - exactly one machine  → delegate rendering to that peer via `runOnPeer`
+ *   - exactly one logical session → delegate rendering to one peer via `runOnPeer`
  *     (its transcript and agent binary live there — a local `--host` hop would
  *     re-discover locally and dead-end), returning `'rendered'`.
- *   - more than one machine → print the conflict with machine labels so the user
- *     can disambiguate with `--device <host>`, returning `'conflict'`.
+ *   - more than one logical session → print every full-id candidate with its
+ *     machine labels, returning `'conflict'`.
  *   - none                 → `'not-found'`, letting the caller print the local
  *     "no session on this machine" message.
  *
- * No fuzzy/content fallback: the sweep forwards a UUID, each peer id-resolves it,
- * and `fleetHitsById` drops anything that isn't an exact id match.
+ * No fuzzy/content fallback: the sweep forwards the id selector and every result
+ * is resolved through `resolveSessionQuery`, the same id-only resolver used locally.
  */
-export declare function resolveSessionAcrossFleet(id: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<'rendered' | 'conflict' | 'not-found'>;
+export declare function resolveSessionAcrossFleet(query: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<'rendered' | 'conflict' | 'not-found'>;
 /** Register the `agents sessions` command with all its options and help text. */
 export declare function registerSessionsCommands(program: Command): void;
 export {};