@phnx-labs/agents-cli 1.22.12 → 1.22.14

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.22.14
+
+- **`agents secrets view <bundle> --reveal` now resolves a locked keychain bundle
+  interactively at a real terminal.** The command hardcoded `agentOnly: true` on
+  both reveal call sites (`commands/secrets.ts`), so an explicit human `--reveal`
+  on a locked bundle went through the broker-only path and errored with an unlock
+  hint instead of raising the one Touch ID sheet the human just asked for. The
+  `agentOnly` flag is now `isHeadlessSecretsContext() || !isInteractiveTerminal()`
+  — under an agent (`AGENTS_RUNTIME`) or with no TTY it stays broker-only and
+  never prompts, but a deliberate `--reveal` typed at an interactive terminal
+  resolves the value with a single biometric sheet. This mirrors the existing
+  `reveal && !isInteractiveTerminal()` guard a few lines up. `export --plaintext`
+  and `exec` are untouched — they stay intentionally silent for release/CI
+  scripts. Source: `apps/cli/src/commands/secrets.ts`.
+
+- **`agents sessions optimize` — compact the FTS5 session search index.** The scanner delete+inserts a session's docs into the `tool_call_text` / `session_text` full-text indexes on every rescan, and FTS5 never merges the resulting segments on its own — so over thousands of sessions the `%_data` shadow tables bloat with hundreds of thousands of unmerged segments (observed on a real fleet box: 701 MB of index for ~69 MB of content, 196K segments) and `agents sessions` slows to a crawl / hangs. The new command runs FTS5 `'optimize'` (merge all segments, purge tombstones), non-destructively — no searchable content is lost. Reclaimed space frees as reusable pages inside the DB file (VACUUM with the daemon stopped returns it to disk); wireable to a weekly routine so the index never re-bloats. Source: `apps/cli/src/lib/session/db.ts` (`optimizeSessionSearchIndex`), `apps/cli/src/commands/sessions-optimize.ts`.
+
+## 1.22.13
+
+- **`agents sessions` accepts direct live-state flags and remains fleet-wide by default.** `--working`, `--idle`, `--waiting`, `--orphan`/`--orphaned`, `--crashed`, `--closed`, `--abandoned`, `--queued`, and `--unknown` each imply the live scan; multiple flags form a union. `--working` is narrower than `--active`: it excludes idle, waiting, and lifecycle-failure rows. Cross-device collection was already the default and stays that way; `--local` opts out, while `--all` continues to widen historical directory and time scope. Source: `apps/cli/src/commands/sessions.ts`, `apps/cli/src/commands/sessions.test.ts`.
+
+- **Workflows: `name@source` disambiguation (Phase 5 packaging).** When two plugins (or a plugin and an extra repo) ship the same workflow name, pin the source: `agents run deploy@ship-tools` or `agents run workflow:deploy@social`. Bare names keep layered precedence (project > user > plugin > extra > system); a missing source returns no match instead of silently falling back. Source: `apps/cli/src/lib/workflows.ts`, `apps/cli/src/lib/resources/workflows.ts`.
+
 ## 1.22.12
 
 - Store operational events in daily history directories, retain 7 days and at most 50 MiB automatically, and make `agents logs audit` use the `agents events --audit` reader.

package/README.md

@@ -292,6 +292,10 @@ Search is the past tense. `--active` is the present -- it infers what each runni
 
 ```bash
 agents sessions --active            # every live run across the fleet, with state
+agents sessions --working           # actively producing work (fleet-wide)
+agents sessions --idle              # stopped between turns (fleet-wide)
+agents sessions --orphan            # agent outlived its terminal client
+agents sessions --crashed           # terminal and agent disappeared uncleanly
 agents sessions focus a1b2c3d4      # jump back into one — attach in place, or resume
 ```
 
@@ -322,7 +326,7 @@ Filters **stack** (they AND together), the active set shows in the header, and t
 | --- | --- |
 | ![sessions browser, preview hidden](assets/demos/sessions-preview-before.png) | ![sessions browser, preview open with a links line](assets/demos/sessions-preview-after.png) |
 
-Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), or `idle`, alongside badges for the PR it opened, the worktree it sits in, and the ticket it's working. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
+Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), `idle`, or a lifecycle state such as `orphaned`, `crashed`, `closed`, `abandoned`, `queued`, or `unknown`. Pass the matching flag (`--working`, `--idle`, `--waiting`, `--orphan`, `--crashed`, `--closed`, `--abandoned`, `--queued`, `--unknown`) directly; each implies `--active`, and several flags form a union. The fleet fan-out is already the default; `--local` opts out. `--all` instead widens historical directory and time scope. Rows also carry badges for the PR, worktree, and ticket. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
 
 Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work (including parsed Bash commands -- `git`, `npm`, `ffmpeg`, `ssh`, and so on), and the last test verdict -- the signals to reload a task in seconds.
 

package/dist/commands/secrets.js

@@ -18,7 +18,7 @@ import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, verifyRemoteKeychainPush, keychainWriteFailureMessage, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, SECRET_TYPES, } from '../lib/secrets/bundles.js';
+import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, isHeadlessSecretsContext, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, SECRET_TYPES, } from '../lib/secrets/bundles.js';
 import { parseListFilters, bundleMatchesFilter, bundleExpiry, filterIsActive, describeFilter, parseSortField, sortBundles, SORT_FIELDS, REF_KINDS, DEFAULT_EXPIRING_DAYS, } from '../lib/secrets/list-filter.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, maybeAutoRekey, } from '../lib/secrets/index.js';
@@ -1254,7 +1254,10 @@ export function registerSecretsCommands(program) {
                     const { env } = readAndResolveBundleEnv(bundle.name, {
                         caller: 'view --reveal --json',
                         keyMode: 'storage',
-                        agentOnly: true,
+                        // An explicit human `--reveal` at a terminal is a deliberate value
+                        // access → resolve interactively (one Touch ID). Under an agent
+                        // (AGENTS_RUNTIME) or headless (no TTY) it stays broker-only.
+                        agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
                     });
                     for (const entry of entries) {
                         if (entry.kind === 'keychain' && env[entry.key] !== undefined) {
@@ -1369,15 +1372,16 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
                 process.exit(1);
             }
-            // Resolve through the broker / durable-session path. A locked keychain
-            // bundle errors with the explicit unlock hint; viewing never raises a
-            // Touch ID sheet itself.
+            // An explicit human `view --reveal` at a terminal is a deliberate value
+            // access: resolve interactively (one Touch ID) so a locked bundle shows
+            // its values. Under an agent (AGENTS_RUNTIME) or headless (no TTY) it
+            // stays broker-only and errors with the unlock hint — never a sheet.
             const revealedValues = new Map();
             if (reveal) {
                 const { env } = readAndResolveBundleEnv(bundle.name, {
                     caller: 'view --reveal',
                     keyMode: 'storage',
-                    agentOnly: true,
+                    agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
                 });
                 for (const entry of entries) {
                     if (entry.kind === 'keychain' && env[entry.key] !== undefined) {

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

@@ -0,0 +1,14 @@
+/**
+ * `agents sessions optimize` — compact the FTS5 session/tool-call search index.
+ *
+ * The scanner delete+inserts a session's docs into the `tool_call_text` /
+ * `session_text` FTS5 indexes on every rescan (and on every extractor-version
+ * bump), and FTS5 never merges the resulting segments on its own. Over thousands
+ * of sessions and re-index passes the `%_data` shadow tables bloat with hundreds
+ * of thousands of unmerged segments — gigabytes of index for tens of MB of
+ * actual content — and `agents sessions` queries slow to a crawl. This runs the
+ * FTS5 `'optimize'` command to merge every segment into one and purge tombstones.
+ * Non-destructive: no searchable content is lost.
+ */
+import type { Command } from 'commander';
+export declare function registerSessionsOptimizeCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-optimize.js

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+import { optimizeSessionSearchIndex } from '../lib/session/db.js';
+import { setHelpSections } from '../lib/help.js';
+export function registerSessionsOptimizeCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('optimize')
+        .description('Compact the session search index (FTS5), reclaiming bloat from repeated re-indexing')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((_opts, c) => {
+        const opts = c.optsWithGlobals();
+        const results = optimizeSessionSearchIndex();
+        if (opts.json) {
+            console.log(JSON.stringify(results, null, 2));
+            return;
+        }
+        for (const r of results) {
+            const merged = Math.max(0, r.segmentsBefore - r.segmentsAfter);
+            console.log(`  ${chalk.cyan(r.table)}: ${r.segmentsBefore} -> ${r.segmentsAfter} segments ` +
+                `(${chalk.green(merged)} merged)`);
+        }
+        console.log(chalk.gray('  Reclaimed space stays as reusable pages inside the file; VACUUM (daemon stopped) returns it to disk.'));
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Compact the session/tool search index once it has grown fragmented
+      agents sessions optimize
+
+      # Machine-readable segment counts
+      agents sessions optimize --json
+
+      # Wire it to a weekly routine so the index never re-bloats
+      agents routines add sessions-optimize --schedule "0 4 * * 0" --agent claude \\
+        --prompt "Run: agents sessions optimize"
+    `,
+        notes: `
+      - FTS5 appends a segment on every insert and tombstones every delete; the scanner delete+inserts a session's docs on each rescan and never self-merges, so \`tool_call_text_data\` / \`session_text_data\` bloat with unmerged segments — GBs of index for tens of MB of content, and queries slow down.
+      - This runs FTS5 \`'optimize'\`: it merges every segment into one and purges tombstones. Non-destructive — no searchable content is lost.
+      - Reclaimed space becomes reusable free pages inside the DB file. To return it to the OS, stop the daemon (\`agents routines stop\`) and run \`VACUUM\` against \`~/.agents/.history/sessions/sessions.db\`.
+    `,
+    });
+}

package/dist/commands/sessions.d.ts

@@ -46,6 +46,16 @@ interface SessionsOptions extends SessionFilterOptions {
     flat?: boolean;
     /** With --active: show only sessions waiting on user input; exit 1 if any. */
     waiting?: boolean;
+    /** Live-state shorthand filters. Any one implies --active; several compose as OR. */
+    working?: boolean;
+    idle?: boolean;
+    orphan?: boolean;
+    orphaned?: boolean;
+    crashed?: boolean;
+    closed?: boolean;
+    abandoned?: boolean;
+    queued?: boolean;
+    unknown?: 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;
@@ -311,6 +321,11 @@ export declare function gatherActiveSessions(opts?: {
     sessions: ActiveSession[];
     remoteDeviceCount: number;
 }>;
+export type LiveStatusFilter = 'working' | 'idle' | 'waiting' | 'orphaned' | 'crashed' | 'closed' | 'abandoned' | 'queued' | 'unknown';
+/** Match the status words users see, preserving activity's richer working signal. */
+export declare function matchesLiveStatus(session: ActiveSession, status: LiveStatusFilter): boolean;
+/** Resolve convenience flags once. Multiple flags intentionally form a union. */
+export declare function requestedLiveStatuses(options: SessionsOptions): LiveStatusFilter[];
 /**
  * A bare interactive fleet listing — no query, no render/filter flag — that the
  * `runSessionBrowser` picker can represent. The single predicate shared by the

package/dist/commands/sessions.js

@@ -61,6 +61,7 @@ import { registerSessionsImportCommand } from './sessions-import.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
 import { registerSessionsStatsCommand } from './sessions-stats.js';
+import { registerSessionsOptimizeCommand } from './sessions-optimize.js';
 import { runBrowserSessions } from '../lib/browser/sessions-list.js';
 import { countToolProgramOccurrences, parseToolProgramCountClause, readToolIndexCoverage, searchToolCalls, TOOL_QUERY_MAX_CLAUSE_BYTES, TOOL_QUERY_MAX_CLAUSES, TOOL_QUERY_MAX_RESULT_SESSIONS, serializeToolSearchEnvelope, toolSearchRemoteReceiveBudget, } from '../lib/session/tool-index.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
@@ -1091,9 +1092,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 +1105,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 +1140,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 +1239,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 +1472,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 +1604,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 +1644,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 +1659,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 +1683,7 @@ limitSource) {
             local: forceLocal,
             hosts: options.host,
             favoritesOnly: options.favorites === true,
+            statuses: liveStatuses,
         });
         return;
     }
@@ -3617,7 +3671,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 +3708,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 +3772,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.
@@ -3742,6 +3812,7 @@ export function registerSessionsCommands(program) {
     registerSessionsMigrationsCommand(sessionsCmd);
     registerSessionsBackfillCommand(sessionsCmd);
     registerSessionsStatsCommand(sessionsCmd);
+    registerSessionsOptimizeCommand(sessionsCmd);
     // Observe-umbrella alias (Phase 3): roster → sessions --active.
     registerSessionsObserveAliases(program);
 }

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/resources/workflows.js

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getProjectAgentsDir, getUserWorkflowsDir, getSystemWorkflowsDir, getEnabledExtraRepos, } from '../state.js';
-import { parseWorkflowFrontmatter, countWorkflowSubagents, listPluginWorkflowDirs, isBareWorkflowName, } from '../workflows.js';
+import { parseWorkflowFrontmatter, countWorkflowSubagents, listPluginWorkflowDirs, resolveWorkflowRef, parseWorkflowRef, } from '../workflows.js';
 function getLayerDirs(cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
@@ -47,6 +47,27 @@ function orderedWorkflowSearchDirs(cwd) {
     out.push({ dir: dirs.system, layer: 'system' });
     return out;
 }
+/** Map a resolved absolute workflow dir to its origin layer (best-effort). */
+function layerForWorkflowPath(workflowPath, cwd) {
+    const abs = path.resolve(workflowPath);
+    const under = (root) => {
+        const r = path.resolve(root);
+        return abs === r || abs.startsWith(r + path.sep);
+    };
+    const projectDir = getProjectAgentsDir(cwd);
+    if (projectDir && under(path.join(projectDir, 'workflows')))
+        return 'project';
+    if (under(getUserWorkflowsDir()))
+        return 'user';
+    if (under(getSystemWorkflowsDir()))
+        return 'system';
+    for (const extra of getEnabledExtraRepos()) {
+        if (under(path.join(extra.dir, 'workflows')))
+            return 'system';
+    }
+    // Plugin marketplaces (and anything else plugin-shaped).
+    return 'plugin';
+}
 class WorkflowsHandlerImpl {
     kind = 'workflow';
     listAll(_agent, cwd) {
@@ -76,27 +97,26 @@ class WorkflowsHandlerImpl {
         return results.sort((a, b) => a.name.localeCompare(b.name));
     }
     resolve(_agent, name, cwd) {
-        // Same bare-name gate as resolveWorkflowRef — never path-join traversal refs.
-        if (!isBareWorkflowName(name))
+        // Delegate to resolveWorkflowRef so bare, workflow:, and name@source share one path.
+        const workflowPath = resolveWorkflowRef(name, cwd ?? process.cwd());
+        if (!workflowPath)
             return null;
-        for (const { dir, layer } of orderedWorkflowSearchDirs(cwd)) {
-            const workflowPath = path.join(dir, name);
-            const fm = parseWorkflowFrontmatter(workflowPath);
-            if (fm) {
-                return {
-                    name,
-                    item: {
-                        name: fm.name || name,
-                        description: fm.description,
-                        model: fm.model,
-                        subagentCount: countWorkflowSubagents(workflowPath),
-                    },
-                    layer,
-                    path: workflowPath,
-                };
-            }
-        }
-        return null;
+        const fm = parseWorkflowFrontmatter(workflowPath);
+        if (!fm)
+            return null;
+        const parsed = parseWorkflowRef(name);
+        const displayName = parsed?.name ?? path.basename(workflowPath);
+        return {
+            name: displayName,
+            item: {
+                name: fm.name || displayName,
+                description: fm.description,
+                model: fm.model,
+                subagentCount: countWorkflowSubagents(workflowPath),
+            },
+            layer: layerForWorkflowPath(workflowPath, cwd),
+            path: workflowPath,
+        };
     }
     sync(_agent, _versionHome, _cwd) {
         // Version-home copies are written by syncResourcesToVersion in versions.ts.

package/dist/lib/session/db.d.ts

@@ -120,6 +120,25 @@ export interface QueryOptions {
 export declare function getDB(): Database.Database;
 /** Close the cached database connection. */
 export declare function closeDB(): void;
+export interface FtsOptimizeResult {
+    table: string;
+    segmentsBefore: number;
+    segmentsAfter: number;
+}
+/**
+ * Compact the session + tool-call full-text-search indexes.
+ *
+ * FTS5 appends a new segment on every insert and leaves a tombstone on every
+ * delete. The scanner delete+inserts a session's docs on each rescan (and on
+ * every extractor-version bump), and FTS5 never merges those segments on its
+ * own — so `tool_call_text_data` / `session_text_data` accumulate hundreds of
+ * thousands of unmerged segments, gigabytes of index for tens of MB of content,
+ * and `agents sessions` queries slow to a crawl. The FTS5 `'optimize'` command
+ * merges every segment into one and purges tombstones. Non-destructive: no
+ * searchable content is lost. Reclaimed space becomes reusable free pages inside
+ * the DB file; run VACUUM (with the daemon stopped) to return it to the OS.
+ */
+export declare function optimizeSessionSearchIndex(): FtsOptimizeResult[];
 /**
  * Try to claim the right to run the incremental scan. Returns true if this
  * process should proceed with scanning, false if another live process is

package/dist/lib/session/db.js

@@ -820,6 +820,30 @@ export function closeDB() {
         cachedStmts = {};
     }
 }
+/**
+ * Compact the session + tool-call full-text-search indexes.
+ *
+ * FTS5 appends a new segment on every insert and leaves a tombstone on every
+ * delete. The scanner delete+inserts a session's docs on each rescan (and on
+ * every extractor-version bump), and FTS5 never merges those segments on its
+ * own — so `tool_call_text_data` / `session_text_data` accumulate hundreds of
+ * thousands of unmerged segments, gigabytes of index for tens of MB of content,
+ * and `agents sessions` queries slow to a crawl. The FTS5 `'optimize'` command
+ * merges every segment into one and purges tombstones. Non-destructive: no
+ * searchable content is lost. Reclaimed space becomes reusable free pages inside
+ * the DB file; run VACUUM (with the daemon stopped) to return it to the OS.
+ */
+export function optimizeSessionSearchIndex() {
+    const db = getDB();
+    // Hardcoded literals — never interpolate caller input into an identifier.
+    const tables = ['tool_call_text', 'session_text'];
+    const segments = (table) => db.prepare(`SELECT count(*) AS n FROM ${table}_data`).get().n;
+    return tables.map((table) => {
+        const segmentsBefore = segments(table);
+        db.prepare(`INSERT INTO ${table}(${table}) VALUES('optimize')`).run();
+        return { table, segmentsBefore, segmentsAfter: segments(table) };
+    });
+}
 // ---------------------------------------------------------------------------
 // Scan coordinator — prevents concurrent full scans across processes
 // ---------------------------------------------------------------------------

package/dist/lib/workflows.d.ts

@@ -318,19 +318,37 @@ export declare function grokWorkflowMarker(filePath: string): string | null;
  * runnable via `agents run <name>` without a separate install into
  * ~/.agents/workflows/ (Phase 5 packaging). Within the plugin band, project
  * plugins beat user/system plugins (same first-hit-wins as other layers).
+ *
+ * Pass `pluginName` to restrict to one plugin (for `name@plugin` resolution).
  */
-export declare function listPluginWorkflowDirs(cwd?: string): string[];
+export declare function listPluginWorkflowDirs(cwd?: string, pluginName?: string): string[];
 /**
- * True when `ref` is a single bare workflow name (no path separators, no `..`).
- * Name lookup must not path-join multi-segment or traversal refs into search roots.
+ * True when `ref` is a single bare workflow / source identifier (no path
+ * separators, no `..`, no `@`). Name lookup must not path-join multi-segment
+ * or traversal refs into search roots. `name@source` is parsed separately.
  */
 export declare function isBareWorkflowName(ref: string): boolean;
+/** Parsed `agents run` workflow reference (docs/07-entrypoints). */
+export interface ParsedWorkflowRef {
+    /** Workflow directory name (WORKFLOW.md parent). */
+    name: string;
+    /**
+     * When set (`name@source`), pin resolution to that source only:
+     * a plugin name, or an enabled extra-repo alias.
+     */
+    source?: string;
+}
+/**
+ * Parse a workflow run target: optional `workflow:` type prefix and optional
+ * `@source` pin. Returns null when the form is not a valid name lookup.
+ */
+export declare function parseWorkflowRef(ref: string): ParsedWorkflowRef | null;
 /**
  * Resolve an `agents run <workflow>` reference.
  *
  * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
  * Name lookup precedence (docs/07-entrypoints): project > user > plugin > extra > system.
- * Bare name only; `name@plugin` disambiguation is a follow-up.
+ * Pin a source with `name@plugin` or `name@extra-alias` (optional `workflow:` prefix).
  */
 export declare function resolveWorkflowRef(ref: string, cwd?: string): string | null;
 /**

package/dist/lib/workflows.js

@@ -522,15 +522,8 @@ function resolveWorkflowPath(ref, cwd) {
     const candidate = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
     return isWorkflowDir(candidate) ? candidate : null;
 }
-/**
- * Plugin `workflows/` directories in discovery order (project → user → system →
- * extra). Used by name resolution and listing so a plugin-packaged workflow is
- * runnable via `agents run <name>` without a separate install into
- * ~/.agents/workflows/ (Phase 5 packaging). Within the plugin band, project
- * plugins beat user/system plugins (same first-hit-wins as other layers).
- */
-export function listPluginWorkflowDirs(cwd = process.cwd()) {
-    const pluginRoots = [];
+/** Plugin-root marketplace dirs in project → user → system → extra order. */
+function pluginMarketplaceDirs(cwd) {
     const pluginsDirs = [];
     const projectPlugins = getProjectPluginsDir(cwd);
     if (projectPlugins)
@@ -539,7 +532,34 @@ export function listPluginWorkflowDirs(cwd = process.cwd()) {
     for (const extra of getEnabledExtraRepos()) {
         pluginsDirs.push(path.join(extra.dir, 'plugins'));
     }
-    for (const pluginsDir of pluginsDirs) {
+    return pluginsDirs;
+}
+function isPluginDirectory(pluginRoot, entry) {
+    if (entry.name.startsWith('.'))
+        return false;
+    let isDir = entry.isDirectory();
+    if (!isDir && entry.isSymbolicLink()) {
+        try {
+            isDir = fs.statSync(pluginRoot).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+    }
+    return isDir;
+}
+/**
+ * Plugin `workflows/` directories in discovery order (project → user → system →
+ * extra). Used by name resolution and listing so a plugin-packaged workflow is
+ * runnable via `agents run <name>` without a separate install into
+ * ~/.agents/workflows/ (Phase 5 packaging). Within the plugin band, project
+ * plugins beat user/system plugins (same first-hit-wins as other layers).
+ *
+ * Pass `pluginName` to restrict to one plugin (for `name@plugin` resolution).
+ */
+export function listPluginWorkflowDirs(cwd = process.cwd(), pluginName) {
+    const pluginRoots = [];
+    for (const pluginsDir of pluginMarketplaceDirs(cwd)) {
         if (!fs.existsSync(pluginsDir))
             continue;
         let entries;
@@ -550,20 +570,10 @@ export function listPluginWorkflowDirs(cwd = process.cwd()) {
             continue;
         }
         for (const entry of entries) {
-            if (entry.name.startsWith('.'))
+            if (pluginName !== undefined && entry.name !== pluginName)
                 continue;
-            // Directories and symlinks-to-directories (plugin marketplaces often symlink).
             const pluginRoot = path.join(pluginsDir, entry.name);
-            let isDir = entry.isDirectory();
-            if (!isDir && entry.isSymbolicLink()) {
-                try {
-                    isDir = fs.statSync(pluginRoot).isDirectory();
-                }
-                catch {
-                    isDir = false;
-                }
-            }
-            if (!isDir)
+            if (!isPluginDirectory(pluginRoot, entry))
                 continue;
             const workflowsDir = path.join(pluginRoot, 'workflows');
             if (fs.existsSync(workflowsDir))
@@ -573,8 +583,9 @@ export function listPluginWorkflowDirs(cwd = process.cwd()) {
     return pluginRoots;
 }
 /**
- * True when `ref` is a single bare workflow name (no path separators, no `..`).
- * Name lookup must not path-join multi-segment or traversal refs into search roots.
+ * True when `ref` is a single bare workflow / source identifier (no path
+ * separators, no `..`, no `@`). Name lookup must not path-join multi-segment
+ * or traversal refs into search roots. `name@source` is parsed separately.
  */
 export function isBareWorkflowName(ref) {
     if (!ref || ref === '.' || ref === '..')
@@ -583,26 +594,65 @@ export function isBareWorkflowName(ref) {
         return false;
     if (ref.includes('..'))
         return false;
+    if (ref.includes('@'))
+        return false;
     // Reject absolute paths (posix or Windows).
     if (path.isAbsolute(ref))
         return false;
     return path.basename(ref) === ref;
 }
+/**
+ * Parse a workflow run target: optional `workflow:` type prefix and optional
+ * `@source` pin. Returns null when the form is not a valid name lookup.
+ */
+export function parseWorkflowRef(ref) {
+    let r = ref.trim();
+    if (r.startsWith('workflow:'))
+        r = r.slice('workflow:'.length);
+    if (!r)
+        return null;
+    const at = r.lastIndexOf('@');
+    if (at > 0) {
+        const name = r.slice(0, at);
+        const source = r.slice(at + 1);
+        if (!isBareWorkflowName(name) || !isBareWorkflowName(source))
+            return null;
+        return { name, source };
+    }
+    if (!isBareWorkflowName(r))
+        return null;
+    return { name: r };
+}
 /**
  * Resolve an `agents run <workflow>` reference.
  *
  * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
  * Name lookup precedence (docs/07-entrypoints): project > user > plugin > extra > system.
- * Bare name only; `name@plugin` disambiguation is a follow-up.
+ * Pin a source with `name@plugin` or `name@extra-alias` (optional `workflow:` prefix).
  */
 export function resolveWorkflowRef(ref, cwd = process.cwd()) {
     const direct = resolveWorkflowPath(ref, cwd);
     if (direct)
         return direct;
-    // Name lookup only — reject traversal / multi-segment so path.join(dir, ref)
-    // cannot escape a workflows root (absolute paths already handled above).
-    if (!isBareWorkflowName(ref))
+    const parsed = parseWorkflowRef(ref);
+    if (!parsed)
         return null;
+    // Source-qualified: only that plugin or extra-repo workflows/ (no layered fallback).
+    if (parsed.source) {
+        for (const dir of listPluginWorkflowDirs(cwd, parsed.source)) {
+            const workflowPath = path.join(dir, parsed.name);
+            if (isWorkflowDir(workflowPath))
+                return workflowPath;
+        }
+        for (const extra of getEnabledExtraRepos()) {
+            if (extra.alias !== parsed.source)
+                continue;
+            const workflowPath = path.join(extra.dir, 'workflows', parsed.name);
+            if (isWorkflowDir(workflowPath))
+                return workflowPath;
+        }
+        return null;
+    }
     const projectAgentsDir = getProjectAgentsDir(cwd);
     const searchDirs = [
         ...(projectAgentsDir ? [path.join(projectAgentsDir, 'workflows')] : []),
@@ -612,7 +662,7 @@ export function resolveWorkflowRef(ref, cwd = process.cwd()) {
         getSystemWorkflowsDir(),
     ];
     for (const dir of searchDirs) {
-        const workflowPath = path.join(dir, ref);
+        const workflowPath = path.join(dir, parsed.name);
         if (isWorkflowDir(workflowPath))
             return workflowPath;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.12",
+  "version": "1.22.14",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",