@phnx-labs/agents-cli 1.20.89 → 1.20.91

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-picker.js

@@ -18,6 +18,7 @@ import { extractTodoProgress, WORKTREE_RE } from '../lib/session/state.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
+import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
 /** A session whose transcript lives on another machine (folded in over the live
  * cross-machine fan-out): its `filePath` is on that peer's disk, so the preview
  * can't parse it locally — it shows metadata + a "resume there" note instead.
@@ -417,9 +418,15 @@ function formatCompactPreview(events, session) {
     }
     // Recent activity = directories touched (not raw tool calls). Prefer a
     // parser-supplied dirsTouched when present; else derive from event paths.
+    // Width-capped: a long Dirs line used to wrap and swamp the whole pane.
     const dirs = directoriesTouched(session, events, changes);
     if (dirs.length) {
-        lines.push(chalk.cyan('Dirs:    ') + chalk.white(dirs.join(chalk.gray(' · '))));
+        lines.push(chalk.cyan('Dirs:    ') + joinWidthCapped(dirs, termWidth - 12));
+    }
+    // Repos worked in (basename of each `.git` root under the touched paths).
+    const repos = extractRepos(events, session.cwd);
+    if (repos.length) {
+        lines.push(chalk.cyan('Repos:   ') + chalk.white(repos.slice(0, 4).join(chalk.gray(' · '))));
     }
     const teamLine = formatTeamLineage(session);
     if (teamLine) {
@@ -442,6 +449,41 @@ function formatCompactPreview(events, session) {
     if (activity.length) {
         lines.push(chalk.cyan('Changes:  ') + activity.join(chalk.gray(' · ')));
     }
+    // Documents the session produced (`.agents/artifacts|plans|reports`, other
+    // *.md/*.html creations) — the files a human browses later, named + clickable.
+    const artifacts = extractArtifacts(changes);
+    if (artifacts.length) {
+        const shown = artifacts.slice(0, 5).map(a => linkPath(a.path, a.basename));
+        const more = artifacts.length > 5 ? chalk.gray(` · +${artifacts.length - 5} more`) : '';
+        lines.push(chalk.cyan('Artifacts: ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Skills invoked (plugin skills included — they ride the same Skill tool).
+    const skills = extractSkills(events);
+    if (skills.length) {
+        const shown = skills.slice(0, 5).map(s => chalk.white(s.name) + (s.count > 1 ? chalk.gray(` ×${s.count}`) : ''));
+        const more = skills.length > 5 ? chalk.gray(` · +${skills.length - 5} more`) : '';
+        lines.push(chalk.cyan('Skills:  ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Hooks fired (Claude transcripts record firings; other harnesses don't).
+    const hooks = extractHooks(events);
+    if (hooks.length) {
+        const shown = hooks.slice(0, 4).map(h => chalk.white(h.name) + (h.count > 1 ? chalk.gray(` ×${h.count}`) : '') + (h.failed ? chalk.red(` (${h.failed} failed)`) : ''));
+        const more = hooks.length > 4 ? chalk.gray(` · +${hooks.length - 4} more`) : '';
+        lines.push(chalk.cyan('Hooks:   ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Links mentioned in the conversation — clickable (OSC 8), tracker-classified.
+    const links = extractLinks(events);
+    if (links.length) {
+        const shown = links.slice(0, 5).map(l => chalk.blue(linkUrl(l.url, l.label)));
+        const more = links.length > 5 ? chalk.gray(` · +${links.length - 5} more`) : '';
+        lines.push(chalk.cyan('Links:   ') + shown.join(chalk.gray(' · ')) + more);
+    }
+    // Error tally, mirroring the full summary's Errors section in one line.
+    const errorEvents = events.filter(e => e.type === 'error');
+    if (errorEvents.length) {
+        const first = errorEvents[0].tool || 'unknown';
+        lines.push(chalk.cyan('Errors:  ') + chalk.red(`${errorEvents.length} failure${errorEvents.length === 1 ? '' : 's'}`) + chalk.gray(` — first: ${first}`));
+    }
     const metadata = [
         ...toolTags,
         subAgentCount ? `${subAgentCount} sub-agent${subAgentCount === 1 ? '' : 's'}` : '',
@@ -559,12 +601,39 @@ function encodeClaudeSlug(absPath) {
 }
 /** The `.agents/worktrees/<name>` marker, Claude-slug-encoded (`/.` → `--`). */
 const SLUG_WORKTREE_RE = /--agents-worktrees-(.+)$/;
+/**
+ * Join display tokens with ` · `, stopping before the line exceeds `maxWidth`
+ * and appending `… +N more` for the rest. Keeps the Dirs line on one row.
+ */
+function joinWidthCapped(items, maxWidth) {
+    const sep = ' · ';
+    let out = '';
+    let shown = 0;
+    for (const item of items) {
+        const next = shown === 0 ? item : out + sep + item;
+        if (shown > 0 && next.length > maxWidth)
+            break;
+        out = next;
+        shown++;
+    }
+    const remaining = items.length - shown;
+    const suffix = remaining > 0 ? ` … +${remaining} more` : '';
+    return chalk.white(out) + (suffix ? chalk.gray(suffix) : '');
+}
 /** Relativize a file path to its parent dir, short enough for one preview line. */
 export function relativizeDir(filePath, cwd) {
     const norm = filePath.replace(/\\/g, '/');
     if (!norm || norm.includes('node_modules') || norm.includes('/.git/') || norm.includes('/plans/')) {
         return undefined;
     }
+    // agents-cli internals — version homes, session/run archives, the bare
+    // worktree container/root — are never meaningful "directories the user works
+    // in". Cwd is exempt: a session running inside such a dir keeps its own paths.
+    const normBase = cwd?.replace(/\\/g, '/').replace(/\/$/, '');
+    const underCwd = normBase && (norm === normBase || norm.startsWith(normBase + '/'));
+    if (!underCwd && (norm.includes('/.agents/.history/') || /\/\.agents\/worktrees(\/[^/]+)?\/?$/.test(norm))) {
+        return undefined;
+    }
     let dir = path.posix.dirname(norm);
     // Claude project-slug form: a leading `-`-segment (`-home-me-…`) that carries
     // the cwd, lossily encoded. Handle it in SLUG SPACE — never lossy-decode to a

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 {};