@phnx-labs/agents-cli 1.20.88 → 1.20.90

package/dist/commands/secrets-rotate-passphrase.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `agents secrets rotate-passphrase` — rotate the encrypted file store's
+ * machine-local master passphrase (RUSH-1975).
+ *
+ * Re-encrypts every `<item>.enc` under a freshly generated key and rewrites the
+ * 0600 key file in place, atomically: the new store is staged, verified
+ * (round-trip + count), fsync'd, then swapped by directory rename, so a crash
+ * leaves the old store intact and readable. Headless-safe and Linux-first — the
+ * remediation path for a compromised passphrase (RUSH-1968), where the two
+ * supported alternatives are unacceptable (a hand-rolled non-atomic script, or
+ * export-to-plaintext which is the exposure being fixed).
+ *
+ * Dry-run by default, matching `import-keyring`; `--commit` performs the swap.
+ */
+import type { Command } from 'commander';
+/** Register `agents secrets rotate-passphrase` on the parent secrets Command. */
+export declare function registerSecretsRotatePassphraseCommand(secrets: Command): void;

package/dist/commands/secrets-rotate-passphrase.js

@@ -0,0 +1,96 @@
+/**
+ * `agents secrets rotate-passphrase` — rotate the encrypted file store's
+ * machine-local master passphrase (RUSH-1975).
+ *
+ * Re-encrypts every `<item>.enc` under a freshly generated key and rewrites the
+ * 0600 key file in place, atomically: the new store is staged, verified
+ * (round-trip + count), fsync'd, then swapped by directory rename, so a crash
+ * leaves the old store intact and readable. Headless-safe and Linux-first — the
+ * remediation path for a compromised passphrase (RUSH-1968), where the two
+ * supported alternatives are unacceptable (a hand-rolled non-atomic script, or
+ * export-to-plaintext which is the exposure being fixed).
+ *
+ * Dry-run by default, matching `import-keyring`; `--commit` performs the swap.
+ */
+import chalk from 'chalk';
+import { machinePassphraseExists, rotatePassphrase } from '../lib/secrets/filestore.js';
+import { agentStatus } from '../lib/secrets/agent.js';
+/** Register `agents secrets rotate-passphrase` on the parent secrets Command. */
+export function registerSecretsRotatePassphraseCommand(secrets) {
+    secrets
+        .command('rotate-passphrase')
+        .description('Re-key the encrypted file store under a new machine-local passphrase (atomic, headless-safe). Dry-run by default.')
+        .option('--commit', 'Perform the rotation (default is dry-run reporting only)')
+        .option('--dry-run', 'Report bundle count and round-trip result without re-keying (the default). Still heals an interrupted rotation — that is the one thing it writes.')
+        .option('--force', 'Override the safety refusals (held broker unlocks, or a passphrase exported in the environment)')
+        .addHelpText('after', `
+Rotates the auto-provisioned file-store key at ~/.agents/.secrets-key/passphrase:
+decrypts every item under the current key, re-encrypts under a new one, verifies
+every item round-trips, then swaps the store and key file atomically. A crash
+before the swap leaves the old store readable with the old key; a crash inside the
+swap self-heals on the next rotate-passphrase run (not on an ordinary get). No
+plaintext secret value or passphrase is ever written to disk, argv, or a log.
+
+Examples:
+  # Report what would rotate (no writes)
+  agents secrets rotate-passphrase
+
+  # Perform the rotation
+  agents secrets rotate-passphrase --commit`)
+        .action(async (opts) => {
+        try {
+            if (opts.commit && opts.dryRun) {
+                throw new Error('--commit and --dry-run are mutually exclusive.');
+            }
+            const dryRun = !opts.commit;
+            if (!machinePassphraseExists()) {
+                throw new Error('No machine-local passphrase is provisioned on this box, so there is nothing to rotate. ' +
+                    'This command re-keys the file store\'s auto-provisioned key at ~/.agents/.secrets-key/passphrase.');
+            }
+            // Guard 1: refuse while the secrets-agent holds live unlocks (macOS), so a
+            // concurrent read cannot land against a half-swapped store. --force overrides.
+            if (!dryRun && !opts.force) {
+                const held = await agentStatus();
+                if (held.length > 0) {
+                    throw new Error(`The secrets-agent is holding ${held.length} unlocked bundle(s) (${held.map((e) => e.name).join(', ')}). ` +
+                        'Lock them first (`agents secrets lock --all`) so no concurrent read races the rotation, or pass --force.');
+                }
+            }
+            // Guard 2: a passphrase exported in the environment shadows the on-disk key
+            // file with a now-stale value after the rotation, breaking every read. This
+            // is the exact RUSH-1968 footgun — refuse the commit and point at the fix.
+            if (!dryRun && !opts.force && (process.env.AGENTS_SECRETS_PASSPHRASE ?? '').length > 0) {
+                throw new Error('AGENTS_SECRETS_PASSPHRASE is set in this environment; it would shadow the rotated key file ' +
+                    'with a stale value and break every read. Unset it (this is the RUSH-1968 fix) before rotating, or pass --force.');
+            }
+            const report = rotatePassphrase({ dryRun });
+            console.log(`${chalk.bold(String(report.bundleCount))} item(s) decrypt under the current key and ` +
+                `${report.roundTripOk ? chalk.green('round-trip cleanly') : chalk.red('failed to round-trip')} under a new key.`);
+            if (report.skipped.length > 0) {
+                console.log(chalk.gray(`skipped ${report.skipped.length} orphan file(s) (not re-keyed):`));
+                for (const s of report.skipped)
+                    console.log(chalk.gray(`  - ${s}`));
+            }
+            if (report.dryRun) {
+                if (report.recoveredInterruptedRotation) {
+                    // Be precise: this run DID write. Recovery is deliberately not gated on
+                    // --commit, because healing is how a crashed store becomes readable
+                    // again without re-keying it.
+                    console.log(chalk.yellow('Recovered an interrupted rotation: the store was healed back to a single ' +
+                        'readable state. That is the only thing this dry run wrote — no re-keying happened.'));
+                }
+                else {
+                    console.log(chalk.gray('Dry-run: nothing written.'));
+                }
+                console.log(chalk.gray(`Pass --commit to re-encrypt the store and swap the key file (${report.keyFilePath}).`));
+                return;
+            }
+            console.log(chalk.green(`Rotated: re-encrypted ${report.bundleCount} item(s) and rewrote ${report.keyFilePath} (mode 0600).`));
+            console.log(chalk.gray('The previous key and ciphertext were removed. Any process still holding the old passphrase in its environment must be restarted.'));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/secrets.d.ts

@@ -80,10 +80,19 @@ export declare function exportBundleToFile(env: Record<string, string>, filePath
  */
 export declare function importBundleFromFile(filePath: string, passphrase: string): Record<string, string>;
 /** 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 declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
+/** 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 declare function renderHoldSummary(holdStr: string, configured: boolean): string;
+/** 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 declare 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. */

package/dist/commands/secrets.js

@@ -38,6 +38,7 @@ import { getVaultSession, vaultExists } from '../lib/secrets/vault.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
 import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
 import { registerSecretsImportKeyringCommand } from './secrets-import.js';
+import { registerSecretsRotatePassphraseCommand } from './secrets-rotate-passphrase.js';
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
@@ -459,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) {
@@ -471,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. */
@@ -804,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') {
@@ -1173,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);
@@ -2265,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();
@@ -2285,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 {
@@ -2419,6 +2432,7 @@ Examples:
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
     registerSecretsImportKeyringCommand(cmd);
+    registerSecretsRotatePassphraseCommand(cmd);
 }
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the
  * caller's try/catch renders it and exits). Accepts the legacy `biometry` /

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;
+    });
+}