@phnx-labs/agents-cli 1.22.12 → 1.22.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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/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

@@ -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/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/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.13",
   "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",