@phnx-labs/agents-cli 1.22.11 → 1.22.13

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/resources.d.ts

@@ -5,7 +5,7 @@
 import type { AgentId } from './types.js';
 import { type SkillParseError } from './skills.js';
 /** Resource kind — matches the subdirectory name under each repo root. */
-export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'cli' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'secrets';
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'clis' | 'permissions' | 'subagents' | 'workflows' | 'profiles' | 'secrets';
 /** A resource resolved with its origin. */
 export interface ResolvedResource {
     name: string;

package/dist/lib/runner.js

@@ -21,7 +21,7 @@ import { resolveJobPrompt, parseTimeout, writeRunMeta, listRuns, getJobRunsDir,
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
-import { createTimer, maybeRotate, redactPrompt } from './events.js';
+import { createTimer, redactPrompt } from './events.js';
 import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, detectAuthFailure, isAuthFailureFromLog, authFailureReason, } from './exec.js';
 import { resolveActor } from './actor.js';
 import { loadTask as loadHostTask } from './hosts/tasks.js';
@@ -691,7 +691,6 @@ export async function executeJob(config, deps) {
     if (config.command) {
         return executeCommandJobForeground(config);
     }
-    maybeRotate();
     const launch = await resolveRoutineLaunch(config);
     const primaryVersion = launch.chain[0]?.version ?? config.version;
     const timer = createTimer('agent.run', {

package/dist/lib/secrets/audit.js

@@ -4,7 +4,7 @@
  * This is the ONE write path for secret events. Every path that creates,
  * imports, exports, views, reads a VALUE from, or unlocks a bundle funnels its
  * audit through here, so the operational event stream — `agents events`, backed
- * by the append-only `~/.agents/.history/events/events.jsonl` audit log — carries a uniform,
+ * by the dated append-only `~/.agents/.history/events/` audit log — carries a uniform,
  * value-free provenance record: bundle, key NAMES, the resolving agent/harness
  * identity, operation, source, status. The ts / host / session / caller fields
  * are filled in by `emit()` itself. The secret VALUE is never part of the

package/dist/lib/startup/command-registry.js

@@ -124,7 +124,7 @@ export const COMMAND_LOADERS = {
     memory: [loadMemory],
     permissions: [loadPermissions],
     mcp: [loadMcp],
-    cli: [loadCli],
+    clis: [loadCli],
     subagents: [loadSubagents],
     plugins: [loadPlugins],
     workflows: [loadWorkflows],

package/dist/lib/state.d.ts

@@ -113,7 +113,7 @@ export declare function getUserSecretsDir(): string;
  * value-free usage telemetry (which bundle was created/imported/exported/viewed/
  * accessed/unlocked, when, by whom), never a secret value. It is a derived index
  * fed FROM the emitSecretAudit chokepoint alongside the append-only
- * ~/.agents/.history/events/events.jsonl audit log — the same way sessions.db indexes session
+ * ~/.agents/.history/events/YYYY-MM-DD audit log — the same way sessions.db indexes session
  * metadata off the real session flow — not a second write path.
  */
 export declare function getSecretsDbPath(): string;

package/dist/lib/state.js

@@ -372,7 +372,7 @@ export function getUserSecretsDir() { return USER_SECRETS_DIR; }
  * value-free usage telemetry (which bundle was created/imported/exported/viewed/
  * accessed/unlocked, when, by whom), never a secret value. It is a derived index
  * fed FROM the emitSecretAudit chokepoint alongside the append-only
- * ~/.agents/.history/events/events.jsonl audit log — the same way sessions.db indexes session
+ * ~/.agents/.history/events/YYYY-MM-DD audit log — the same way sessions.db indexes session
  * metadata off the real session flow — not a second write path.
  */
 export function getSecretsDbPath() {
@@ -794,6 +794,59 @@ function writeIfChanged(filePath, content) {
  * All callers funnel through writeMeta → here, so nothing else changes. Empty
  * `agents:` / `versions:` are not written (no empty committed files).
  */
+/**
+ * Every `Meta` key, classified as `central` (synced via agents.yaml) or `device`
+ * (routed to the per-machine device file by {@link writeMetaUnlocked}). The
+ * `Record<keyof Meta, …>` type makes this EXHAUSTIVE: adding a field to `Meta`
+ * without classifying it here is a compile error. That guarantee is what lets
+ * `serializeCentral` delete only keys THIS version models — a key a newer CLI
+ * version added (absent from this map) is preserved verbatim instead of being
+ * dropped and synced fleet-wide as data loss. This is the fix for the recurring
+ * agents.yaml key-loss (beta flags, `notify.owner`, and `feed:` all vanished
+ * this way when an older-versioned CLI on the fleet rewrote the file).
+ */
+const META_KEY_SCOPE = {
+    // Device-local — writeMetaUnlocked destructures these out; never in central.
+    agents: 'device',
+    isolatedAgents: 'device',
+    versions: 'device',
+    defaultBrowserProfile: 'device',
+    deviceConfig: 'device',
+    // Central — synced via agents.yaml.
+    run: 'central',
+    model: 'central',
+    watchdog: 'central',
+    lease: 'central',
+    secrets: 'central',
+    budget: 'central',
+    feed: 'central',
+    beta: 'central',
+    registries: 'central',
+    profiles: 'central',
+    source: 'central',
+    projectRoot: 'central',
+    extraRepos: 'central',
+    brands: 'central',
+    actors: 'central',
+    seededPresets: 'central',
+    hooks: 'central',
+    browser: 'central',
+    config: 'central',
+    hosts: 'central',
+    fleet: 'central',
+    share: 'central',
+    notify: 'central',
+    routines: 'central',
+};
+/**
+ * Every key this version models (central + device). serializeCentral deletes an
+ * on-disk key only when it is KNOWN and absent from the write's in-memory object:
+ * a central key the caller cleared, OR a device key that is legacy cruft in the
+ * synced file (device keys are routed to the per-machine file, so one lingering
+ * in central is stale and must be migrated out). A key NOT listed here — e.g. one
+ * a newer CLI version added — is preserved verbatim, never dropped + synced away.
+ */
+const KNOWN_META_KEYS = new Set(Object.keys(META_KEY_SCOPE));
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.
@@ -834,7 +887,12 @@ function serializeCentral(central) {
         }
     }
     for (const k of Object.keys(current)) {
-        if (!(k in central)) {
+        // Only delete a key THIS version knows about. A key not in KNOWN_META_KEYS
+        // (e.g. one a newer CLI version added) is preserved verbatim — deleting it
+        // here would drop it and sync the deletion fleet-wide (the agents.yaml
+        // config data-loss bug). A known device key lingering in the synced file is
+        // still removed — it belongs in the per-machine file, not here.
+        if (!(k in central) && KNOWN_META_KEYS.has(k)) {
             doc.delete(k);
             changed = true;
         }

package/dist/lib/watchdog/runner.d.ts

@@ -97,6 +97,11 @@ export interface WatchdogTickOptions {
         dryRun?: boolean;
         enter?: boolean;
     }) => Promise<InjectResult>;
+    /**
+     * Publish a declared block on the owner's feed. Default publishBlock() — tests
+     * inject a collector so no real feed dir is touched.
+     */
+    publishBlockFn?: (block: OpenBlock) => void;
     /** Override the canonical watchdog.log path (tests point at a tmp file). */
     logPath?: string;
     /**
@@ -195,6 +200,14 @@ export interface NudgeDecision {
     nudge: boolean;
     reason: string;
     text?: string;
+    /**
+     * Set to `true` when the brain (smart decider) explicitly concluded the session
+     * needs the human — as opposed to a cheap deterministic skip (session is done,
+     * not stalled, etc.). Only `true` when the brain escalation path ran and returned
+     * `nudge: false`. The watchdog uses this to gate the self-file reminder: a
+     * "session is done" skip does NOT trigger a reminder.
+     */
+    needsHuman?: boolean;
 }
 /**
  * The smart brain. Resolves a `watchdog` workflow for the session's cwd

package/dist/lib/watchdog/runner.js

@@ -44,7 +44,7 @@ import { withFileLock, atomicWriteFileSync, ensureLockTarget } from '../fs-atomi
 import { resolveAnswerRoute, isOpenQuestionBlock } from '../answer-router.js';
 import { enqueue, mailboxDir } from '../mailbox.js';
 import { mailboxIdForActiveSession } from '../mailbox-target.js';
-import { readBlock, blockIdForSession } from '../feed.js';
+import { readBlock, blockIdForSession, buildDeclaredBlock, publishBlock } from '../feed.js';
 import { summarizeWatchdogTail } from './watchdogTail.js';
 import { appendWatchdogEvents } from './log.js';
 import { buildRotateLaunchCommand, buildRotateReplayText, classifyTailForRotate, defaultRotateGate, defaultTuiLiveFor, exitSequenceFor, isInflightPhase, isWatchdogRotateEnabled, listInflightRotates, readRotateState, recordRotateSkip, shouldLogRotateSkip, writeRotateState, DEFAULT_ROTATE_READINESS_MS, DEFAULT_ROTATE_SKIP_COOLDOWN_MS, DEFAULT_ROTATE_FAILED_COOLDOWN_MS, } from './rotate.js';
@@ -353,6 +353,7 @@ export async function runWatchdogTick(opts = {}) {
     const smartDecider = opts.smartDecider ?? makeDefaultSmartDecider(opts.smartAgent ?? 'claude');
     const openBlockFor = opts.openBlockFor ?? defaultOpenBlockFor;
     const injectFn = opts.injectFn ?? injectIntoTerminal;
+    const publishBlockFn = opts.publishBlockFn ?? publishBlock;
     // Rotate seams (watchdog/rotate.ts). The config is read fresh per tick
     // (readMeta is mtime-cached), so a `watchdog.rotate` flip is honored on the
     // next pass. The default readiness probe (defaultTuiLiveFor) treats the
@@ -645,13 +646,21 @@ export async function runWatchdogTick(opts = {}) {
         // forces every stalled candidate through the brain.
         let decision;
         if (opts.smart) {
-            decision = await smartDecider(session, candidate);
+            const d = await smartDecider(session, candidate);
+            // Mark needsHuman when the brain explicitly concluded "leave for human".
+            decision = d.nudge ? d : { ...d, needsHuman: true };
         }
         else {
             const det = deterministicDecision(session, candidate);
-            decision = det.kind === 'escalate'
-                ? await smartDecider(session, candidate)
-                : { nudge: det.kind === 'nudge', reason: det.reason };
+            if (det.kind === 'escalate') {
+                const d = await smartDecider(session, candidate);
+                // Mark needsHuman when the brain escalation path concluded "leave for human".
+                decision = d.nudge ? d : { ...d, needsHuman: true };
+            }
+            else {
+                // Cheap deterministic path — completion or clear stall. Never "needs human".
+                decision = { nudge: det.kind === 'nudge', reason: det.reason };
+            }
         }
         const chosenText = decision.text ?? nudgeText;
         // Log the decision for the Factory watchdog card.
@@ -670,6 +679,53 @@ export async function runWatchdogTick(opts = {}) {
             lastAssistantMessage: summary.lastAssistantMessage,
         });
         if (!decision.nudge) {
+            // Brain explicitly concluded "leave for human" (needsHuman === true). Inject a
+            // self-file reminder into the agent's terminal so it knows to post a feed block.
+            // Cheap deterministic skips (session done, no stall) are NOT reminder-worthy —
+            // guard on needsHuman so a finished session is never poked.
+            // Gated by the same cooldown as a nudge to prevent re-firing every 2-minute tick.
+            if (decision.needsHuman) {
+                const lastNudgeMs = ledger[session.sessionId ?? ''] ?? 0;
+                const cooldownMs = thresholds.cooldownMs;
+                const withinCooldown = nowMs - lastNudgeMs < cooldownMs;
+                if (opts.nudge && session.sessionId && !withinCooldown) {
+                    const existingBlock = openBlockFor(session);
+                    if (existingBlock === null) {
+                        // Determine addressability without planning the full nudge (no text needed).
+                        const resolution = resolveInjectTargetForSession(session, { allowGhosttyFocus: opts.allowGhosttyFocus });
+                        if (resolution.addressable) {
+                            // Addressable → inject a reminder asking the agent to self-file a feed block.
+                            const reminderText = 'You appear stuck. If you genuinely need Muqsit, file it: ' +
+                                'agents feed post "<one-line ask>" --blocked --default "<safe default>". ' +
+                                'Otherwise keep going.';
+                            try {
+                                await injectFn(resolution.target, reminderText, { dryRun: opts.injectDryRun });
+                            }
+                            catch {
+                                // Swallow inject errors — reminder is best-effort; flag set below.
+                            }
+                            ledgerUpdates[session.sessionId] = nowMs;
+                        }
+                        else {
+                            // Un-addressable → we can't reach the terminal to remind it, so the ONLY
+                            // way to reach Muqsit is to file a declared block on the agent's behalf.
+                            // This is the most important case: the session genuinely needs the human
+                            // AND the watchdog can't even nudge it. Never let it silently vanish.
+                            const mailboxId = mailboxIdForActiveSession(session) ?? session.sessionId;
+                            const machineHost = session.provenance?.host ?? 'unknown';
+                            const runtime = session.kind;
+                            try {
+                                const declaredBlock = buildDeclaredBlock({ sessionId: session.sessionId, mailboxId, host: machineHost, runtime, cwd: session.cwd }, { text: `Session genuinely needs Muqsit and is un-addressable — ${decision.reason}. Needs attention.` });
+                                publishBlockFn(declaredBlock);
+                                ledgerUpdates[session.sessionId] = nowMs;
+                            }
+                            catch {
+                                // publishBlock failure is non-fatal — best-effort owner page.
+                            }
+                        }
+                    }
+                }
+            }
             outcomes.push({ ...base, decision: 'skip', reason: decision.reason });
             continue;
         }
@@ -682,6 +738,12 @@ export async function runWatchdogTick(opts = {}) {
         const addressable = plan.via === 'inject' ? true : undefined;
         if (plan.via === 'refuse') {
             // No addressable rail and not headless-resumable — flag, NEVER guess.
+            // This branch is reached ONLY for a nudge-worthy (decision.nudge === true)
+            // drive-forward poke, which is NEVER needsHuman (needsHuman is set only when
+            // decision.nudge === false). So we do NOT page the owner here — a short "just
+            // needs a poke" stall must not text Muqsit's phone. Owner-paging for an
+            // un-addressable session happens only on the confirmed needsHuman skip path
+            // above. Here we only flag it for the tray.
             flags[session.sessionId] = { reason: plan.reason, host: session.host, atMs: nowMs };
             outcomes.push({
                 ...base, decision: 'skip', addressable: false,
@@ -690,7 +752,14 @@ export async function runWatchdogTick(opts = {}) {
             });
             continue;
         }
-        // handsoff = detect + flag, but never deliver.
+        // handsoff = detect + flag, but never deliver via inject/mailbox.
+        // This branch is reached ONLY for a nudge-worthy (decision.nudge === true)
+        // drive-forward poke, which is NEVER needsHuman. A hands-off policy means "don't
+        // nudge it forward" — it must NOT translate into paging Muqsit for a poke. So we
+        // only flag it for the tray, no owner page. A genuinely needs-human session (even
+        // under hands-off) is paged by the confirmed-needsHuman skip path above, which
+        // does not consult policy — hands-off silences the forward nudge, not the
+        // "it's actually stuck" signal.
         if (policy === 'handsoff') {
             flags[session.sessionId] = {
                 reason: `handsoff: would nudge via ${viaLabel(plan)} but policy is hands-off`,

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.11",
+  "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",