@phnx-labs/agents-cli 1.22.11 → 1.22.13

package/dist/commands/sessions.js

@@ -1091,9 +1091,12 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     const merged = opts.favoritesOnly
         ? gathered.sessions.filter((s) => !!s.sessionId && listFavorites().has(s.sessionId))
         : gathered.sessions;
-    // --waiting: only sessions blocked on the user. Exits non-zero when any are
-    // present so a supervising agent or hook can poll it as a gate.
-    const sessions = waitingOnly ? merged.filter(isAwaitingUser) : merged;
+    // Status flags form a union. --waiting additionally retains its scriptable
+    // gate: exit non-zero when the union contains a session awaiting the user.
+    const statusFiltered = opts.statuses?.length
+        ? merged.filter((session) => opts.statuses.some((status) => matchesLiveStatus(session, status)))
+        : merged;
+    const sessions = statusFiltered;
     if (asJson) {
         // Resolve who is watching each local tmux pane before serializing: `viewingIn`
         // is how a consumer distinguishes a session someone is looking at from one
@@ -1101,7 +1104,7 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
         // scriptable path stays cheap — see enrichTmuxLocators.
         await enrichTmuxLocators(sessions.filter(s => !s.machine || s.machine === self));
         process.stdout.write(JSON.stringify(serializeActiveSessionsForJson(sessions), null, 2) + '\n');
-        if (waitingOnly && sessions.length > 0)
+        if (waitingOnly && sessions.some(isAwaitingUser))
             process.exitCode = 1;
         return;
     }
@@ -1136,9 +1139,40 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     if (!opts.local && !opts.hosts?.length && remoteDeviceCount === 0)
         printCrossMachineTip();
     // Scriptable gate: a non-zero exit when anything is waiting on the user.
-    if (waitingOnly && sessions.length > 0)
+    if (waitingOnly && sessions.some(isAwaitingUser))
         process.exitCode = 1;
 }
+/** Match the status words users see, preserving activity's richer working signal. */
+export function matchesLiveStatus(session, status) {
+    if (status === 'working')
+        return session.activity === 'working' || (!session.activity && session.status === 'running');
+    if (status === 'waiting')
+        return isAwaitingUser(session);
+    return session.status === status;
+}
+/** Resolve convenience flags once. Multiple flags intentionally form a union. */
+export function requestedLiveStatuses(options) {
+    const statuses = [];
+    if (options.working)
+        statuses.push('working');
+    if (options.idle)
+        statuses.push('idle');
+    if (options.waiting)
+        statuses.push('waiting');
+    if (options.orphan || options.orphaned)
+        statuses.push('orphaned');
+    if (options.crashed)
+        statuses.push('crashed');
+    if (options.closed)
+        statuses.push('closed');
+    if (options.abandoned)
+        statuses.push('abandoned');
+    if (options.queued)
+        statuses.push('queued');
+    if (options.unknown)
+        statuses.push('unknown');
+    return [...new Set(statuses)];
+}
 /** Nudge shown when `--active` has no other machines to fold in. */
 function printCrossMachineTip() {
     console.log(chalk.gray("\nTip: include sessions from your other machines — register them with 'ag devices sync', then rerun. Use --local to skip."));
@@ -1204,6 +1238,22 @@ function canonicalSessionsCommand(query, options) {
     const a = ['sessions'];
     if (options.active)
         a.push('--active');
+    if (options.working)
+        a.push('--working');
+    if (options.idle)
+        a.push('--idle');
+    if (options.orphan || options.orphaned)
+        a.push('--orphan');
+    if (options.crashed)
+        a.push('--crashed');
+    if (options.closed)
+        a.push('--closed');
+    if (options.abandoned)
+        a.push('--abandoned');
+    if (options.queued)
+        a.push('--queued');
+    if (options.unknown)
+        a.push('--unknown');
     if (options.teams)
         a.push('--teams');
     if (options.inTeam)
@@ -1421,6 +1471,8 @@ async function sessionsAction(query, options,
  */
 limitSource) {
     const queryClauses = options.query ?? [];
+    const liveStatuses = requestedLiveStatuses(options);
+    const liveOnly = options.active === true || liveStatuses.length > 0;
     const toolOnly = options.include?.split(',').map((role) => role.trim()).filter(Boolean).join(',') === 'tools';
     const toolEvidenceMode = toolOnly;
     if (options.count && !toolOnly) {
@@ -1551,7 +1603,7 @@ limitSource) {
     // keeps the legacy per-host stream (each remote's raw stdout under a
     // `── host ──` banner). With --active, the hosts are folded into the merged
     // machine-grouped view instead (handled below).
-    if (options.host && options.host.length > 0 && !options.active && !toolEvidenceMode) {
+    if (options.host && options.host.length > 0 && !liveOnly && !toolEvidenceMode) {
         // --local means "skip the SSH fan-out"; --host means "look only over there".
         // Together they ask for a peer's sessions without dialing the peer, which can
         // only ever be empty — so say that instead of rendering a blank list.
@@ -1591,7 +1643,7 @@ limitSource) {
         await renderSessionPreview(query, { agent: options.agent, project: options.project, local: options.local });
         return;
     }
-    if (options.active) {
+    if (liveOnly) {
         // The running view is built from the live scan, which carries no team lineage
         // (that comes off the transcript index and the teams meta dir), so --in-team
         // has nothing to match on here. Say so rather than ignoring the flag.
@@ -1606,7 +1658,7 @@ limitSource) {
         // --since seeds the window; --until / --project (no browser field) or a
         // multi-host scope fall through to the static dump that already honors them.
         if (useInteractiveBrowser(options) &&
-            !options.waiting &&
+            liveStatuses.length === 0 &&
             !options.until &&
             !options.project &&
             !options.sort &&
@@ -1630,6 +1682,7 @@ limitSource) {
             local: forceLocal,
             hosts: options.host,
             favoritesOnly: options.favorites === true,
+            statuses: liveStatuses,
         });
         return;
     }
@@ -3617,7 +3670,16 @@ export function registerSessionsCommands(program) {
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
         .option('--roots', 'With --json: emit the on-disk directories scanned for session transcripts, per agent (for external watchers)')
         .option('--local', 'Only this machine — skip the cross-machine SSH fan-out (default listing and --active)')
-        .option('--waiting', 'With --active: show only sessions waiting on your input (exits non-zero if any)')
+        .option('--working', 'Show live sessions currently doing work (implies --active)')
+        .option('--idle', 'Show live sessions that have stopped between turns (implies --active)')
+        .option('--waiting', 'Show live sessions waiting on your input; exits non-zero if any (implies --active)')
+        .option('--orphan', 'Show live sessions whose process outlived its terminal client (implies --active)')
+        .option('--orphaned', 'Alias for --orphan')
+        .option('--crashed', 'Show sessions whose terminal disappeared with the process (implies --active)')
+        .option('--closed', 'Show recently observed sessions whose process exited normally (implies --active)')
+        .option('--abandoned', 'Show sessions with no transcript progress for the abandonment window (implies --active)')
+        .option('--queued', 'Show queued sessions that have not started running (implies --active)')
+        .option('--unknown', 'Show sessions whose live state cannot be determined (implies --active)')
         .option('--favorites', 'Show only favorited (starred) sessions — star them with `*` in the browser or `agents sessions favorite <id>`')
         .option('--tree', 'Group the listing by directory; drops the id/version columns for readability')
         .option('--flat', 'Plain flat table (one row per session) instead of the grouped project overview')
@@ -3645,6 +3707,12 @@ export function registerSessionsCommands(program) {
       # Show only what's running right now (terminals, teams, cloud, headless)
       agents sessions --active
 
+      # Filter the live fleet by the status word shown in the roster
+      agents sessions --working
+      agents sessions --idle
+      agents sessions --orphan
+      agents sessions --crashed
+
       # --- Session lifecycle (one verb per intent) ---
       # Jump to a live session (attach its terminal, or open a tab + resume)
       agents sessions focus a1b2c3d4
@@ -3703,7 +3771,8 @@ export function registerSessionsCommands(program) {
         detach <id>             interactive → headless continuation
         attach <id>             headless → interactive in this terminal
         resume [query]          multi-select history → open tabs (or run --resume <id>)
-      - The interactive listing folds in your other online machines automatically (live over SSH, no sync) — each row is labelled by host, this machine first. Use --local to skip the fan-out; --json and single-id lookups stay local.
+      - The interactive listing and every live-status flag fold in your other online machines automatically (live over SSH, no sync) — each row is labelled by host, this machine first. Use --local to skip the fan-out; single-id lookups stay local.
+      - --all is not a device flag: it widens historical directory and time filters. Fleet collection is already the default. A status flag (--working/--idle/--waiting/--orphan/--crashed/--closed/--abandoned/--queued/--unknown) implies --active; combine status flags for a union.
       - --host runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
       - --in-team matches both ends of the lineage: the session that ran 'agents teams create/add', and (with --teams) that team's teammates. In the interactive list, 't' cycles the same filter over the teams in view.
       - --include and --exclude are mutually exclusive.

package/dist/commands/view.d.ts

@@ -32,7 +32,7 @@ export interface ViewSectionFilter {
     rules?: boolean;
     hooks?: boolean;
     promptcuts?: boolean;
-    cli?: boolean;
+    clis?: boolean;
 }
 /** Trim a description to a column-friendly snippet. Strips newlines, collapses whitespace. */
 export declare function summarizeDescription(desc: string | undefined, maxLen?: number): string;

package/dist/commands/view.js

@@ -154,7 +154,7 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
-const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts', 'cli'];
+const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts', 'clis'];
 /**
  * Decide whether a section should render given the filter. If no flags are set,
  * everything renders (current behavior). If any flag is set, only those sections
@@ -231,7 +231,7 @@ function hostCliSourceTag(source) {
 }
 /**
  * Render the host-CLI section. Host CLIs are host-global: declared in any
- * DotAgents repo's `cli/` (project > user > system > extras), installed to PATH
+ * DotAgents repo's `clis/` (project > user > system > extras), installed to PATH
  * rather than copied into a version home. They render identically in the overview
  * and in a per-agent detail view because every agent on the host shares them.
  * The source tag shows which repo layer declared each — so user-level and
@@ -241,7 +241,7 @@ function renderHostClisSection(cwd) {
     const { statuses, errors } = listCliStatus(cwd);
     console.log(chalk.bold('\nHost CLIs\n'));
     if (statuses.length === 0) {
-        console.log(`  ${chalk.gray('none declared')} ${chalk.gray('— add one with `agents cli add <name>`')}`);
+        console.log(`  ${chalk.gray('none declared')} ${chalk.gray('— add one with `agents clis add <name>`')}`);
     }
     else {
         const nameWidth = Math.max(...statuses.map((s) => s.manifest.name.length));
@@ -258,7 +258,7 @@ function renderHostClisSection(cwd) {
             console.log(prefix + desc);
         }
         if (anyMissing) {
-            console.log(chalk.gray('  Install missing with `agents cli install`'));
+            console.log(chalk.gray('  Install missing with `agents clis install`'));
         }
     }
     for (const err of errors) {
@@ -1100,7 +1100,7 @@ async function showAgentResources(agentId, requestedVersion, filter) {
     if (shouldRenderSection('promptcuts', filter)) {
         renderPromptcuts();
     }
-    if (shouldRenderSection('cli', filter)) {
+    if (shouldRenderSection('clis', filter)) {
         renderHostClisSection(cwd);
     }
     // Show legend at the end if git repo exists and we showed all sections.
@@ -1565,7 +1565,7 @@ export async function viewAction(agentArg, options) {
         rules: options?.rules,
         hooks: options?.hooks,
         promptcuts: options?.promptcuts,
-        cli: options?.cli,
+        clis: options?.clis,
     };
     const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
     // RUSH-1320: fold any stale literal `latest` version-home into its concrete
@@ -1684,7 +1684,7 @@ export function registerViewCommand(program) {
         .option('--rules', 'Show only rules in the detail view.')
         .option('--hooks', 'Show only hooks in the detail view.')
         .option('--promptcuts', 'Show only promptcuts in the detail view.')
-        .option('--cli', 'Show only host CLIs (declared in cli/, installed to PATH).')
+        .option('--clis', 'Show only host CLIs (declared in clis/, installed to PATH).')
         .option('--merged', 'Show the merged, first-wins resource surface across all layers (project, user, extras, system) in one table with the winning layer per row.')
         .addHelpText('after', `
 Examples:

package/dist/commands/workflows.js

@@ -30,6 +30,7 @@ Structure:
     plugins/           optional: plugin bundles scoped to this workflow
 
 Resolution: project > user > plugin (plugins/*/workflows/) > extra > system.
+Pin a source with name@plugin or name@extra-alias (optional workflow: prefix).
 
 Note: agents run defaults to --mode plan (read-only). For workflows that
 write files, post comments, or otherwise mutate state, pass --mode edit or

package/dist/lib/cli-resources.js

@@ -217,7 +217,7 @@ export function parseCliManifest(contents, opts) {
  * manifests and any parse errors separately so the CLI can show both.
  */
 export function listCliManifests(cwd) {
-    const resolved = listResources('cli', cwd);
+    const resolved = listResources('clis', cwd);
     const manifests = [];
     const errors = [];
     for (const entry of resolved) {
@@ -240,7 +240,7 @@ export function listCliManifests(cwd) {
 }
 /** Resolve a single CLI manifest by name. Returns null when not declared. */
 export function resolveCliManifest(name, cwd) {
-    const resolved = resolveResource('cli', name, cwd);
+    const resolved = resolveResource('clis', name, cwd);
     if (!resolved)
         return null;
     if (!resolved.path.endsWith('.yaml') && !resolved.path.endsWith('.yml'))

package/dist/lib/event-stream.d.ts

@@ -1,6 +1,6 @@
 /**
  * The unified event reader -- one stream over BOTH operational events
- * (`~/.agents/.history/events/events.jsonl` via events.ts: secrets, commands, teams, ...) and
+ * (`~/.agents/.history/events/YYYY-MM-DD/` via events.ts: secrets, commands, teams, ...) and
  * agent-semantic events (the per-session activity logs via activity.ts: plans,
  * PRs, worktrees, sub-agents, artifacts). They share one {@link EventType}
  * vocabulary and one {@link EventRecord} shape, so `agents events` and any

package/dist/lib/event-stream.js

@@ -1,6 +1,6 @@
 /**
  * The unified event reader -- one stream over BOTH operational events
- * (`~/.agents/.history/events/events.jsonl` via events.ts: secrets, commands, teams, ...) and
+ * (`~/.agents/.history/events/YYYY-MM-DD/` via events.ts: secrets, commands, teams, ...) and
  * agent-semantic events (the per-session activity logs via activity.ts: plans,
  * PRs, worktrees, sub-agents, artifacts). They share one {@link EventType}
  * vocabulary and one {@link EventRecord} shape, so `agents events` and any

package/dist/lib/events.d.ts

@@ -1,8 +1,8 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL audit log at ~/.agents/.history/events/events.jsonl with lossless numbered
- * gzip rotation at 10 MB and rich metadata for debugging/auditing.
+ * Structured JSONL audit logs at ~/.agents/.history/events/YYYY-MM-DD/events.jsonl with
+ * lossless numbered gzip rotation at 10 MiB and bounded retention.
  *
  * Features:
  * - Rich metadata: hostname, platform, arch, pid, timezone
@@ -75,6 +75,17 @@ export interface EventPayload {
     [key: string]: unknown;
 }
 export type EventRecord = EventMeta & EventPayload;
+/**
+ * Move root-level and interim flat-history event families into dated directories.
+ *
+ * The common case is a whole-family rename into an empty destination. A
+ * Each segment is assigned to the local calendar day of its filesystem mtime;
+ * new writes are split by day at source. A partially completed migration keeps
+ * the destination active file authoritative and assigns a fresh archive number,
+ * so no record is overwritten or silently discarded. The legacy active-file
+ * lock serializes this with older installed processes that still append there.
+ */
+export declare function migrateLegacyEventLogs(userDir?: string): number;
 /**
  * Replace a prompt string with length + short SHA so we can correlate runs
  * without persisting the raw text. Returns the fields to spread into a payload.
@@ -187,15 +198,13 @@ export declare function emitError(err: Error | string, payload?: EventPayload):
  * the same failure across sessions (e.g. 'remote-cwd-on-add', 'not-installed').
  */
 export declare function emitFriction(surface: string, failureId: string, payload?: EventPayload): void;
-/**
- * Remove log files older than the retention period.
- * Removes numbered gzip archives whose filesystem mtime exceeds retention.
- *
- * @param retentionDays - Number of days to keep (default 7, from DEFAULT_RETENTION_DAYS)
- * @returns Number of files removed
- */
-export declare function rotate(retentionDays?: number): number;
-export declare function maybeRotate(): void;
+export interface RotationResult {
+    removedByAge: number;
+    removedBySize: number;
+    bytesReclaimed: number;
+}
+/** Apply age retention and the total-size ceiling immediately. */
+export declare function rotate(retentionDays?: number, maxStorageBytes?: number): RotationResult;
 /**
  * Read events from log files within a date range.
  *
@@ -245,4 +254,4 @@ export declare function stats(options?: {
     days?: number;
 }): EventStats;
 export declare function getLogsPath(): string;
-export declare function _resetForTest(overrideEventsPath?: string): void;
+export declare function _resetForTest(overrideEventsPath?: string, overrideUserAgentsDir?: string): void;