@phnx-labs/agents-cli 1.22.8 → 1.22.10

package/dist/lib/share/config.js

@@ -9,7 +9,7 @@
 //   `cloudflare` bundle.
 import { randomBytes } from 'node:crypto';
 import { readMeta, updateMeta } from '../state.js';
-import { bundleExists, bundleItemStore, bundlePolicy, isHeadlessSecretsContext, keychainRef, readAndResolveBundleEnv, readBundle, writeBundle, } from '../secrets/bundles.js';
+import { bundleExists, bundleItemStore, bundlePolicy, keychainRef, readAndResolveBundleEnv, readBundle, writeBundle, } from '../secrets/bundles.js';
 import { secretsKeychainItem } from '../secrets/index.js';
 export const SHARE_BUNDLE = 'share';
 export const SHARE_TOKEN_KEY = 'WRITE_TOKEN';
@@ -76,10 +76,8 @@ export function storeWriteToken(token) {
 export function readWriteTokenFromBundle() {
     const { env } = readAndResolveBundleEnv(SHARE_BUNDLE, {
         caller: 'share',
-        // Explicit `agents share` command (a human published a file): a headless agent
-        // subprocess resolves broker-only, an interactive human may unlock. This is NOT
-        // an agent LAUNCH read (that is exec.ts's --secrets injection, always agentOnly).
-        agentOnly: isHeadlessSecretsContext(),
+        // Explicit share commands are reads, not authorization to authenticate.
+        agentOnly: true,
     });
     const token = env[SHARE_TOKEN_KEY];
     if (!token) {
@@ -136,8 +134,8 @@ export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
     }
     const { env } = readAndResolveBundleEnv(bundle, {
         caller: 'share',
-        // Explicit `agents share setup` provisioning read — not an agent launch.
-        agentOnly: isHeadlessSecretsContext(),
+        // Setup is still a read; only `agents secrets unlock` may authenticate.
+        agentOnly: true,
     });
     const find = (re) => {
         for (const [k, v] of Object.entries(env))

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

@@ -89,7 +89,16 @@ export const loadFunnel = async () => (await import('../../commands/funnel.js'))
  * inherit the root's custom help formatter rather than getting the per-command
  * recursive pass. Keeping that ordering preserves their `--help` output exactly.
  */
-export const LAZY_COMMAND_NAMES = new Set(['sessions', 'teams', 'cloud', 'message', 'serve']);
+// `roster` is an observe-umbrella alias of `sessions --active` — same module,
+// same SQLite stack, same post-help registration order as sessions.
+export const LAZY_COMMAND_NAMES = new Set([
+    'sessions',
+    'roster',
+    'teams',
+    'cloud',
+    'message',
+    'serve',
+]);
 /**
  * User-typed top-level command name -> ordered list of module loaders to run.
  *
@@ -194,12 +203,17 @@ export const COMMAND_LOADERS = {
     setup: [loadSetup],
     uninstall: [loadUninstall],
     sessions: [loadSessions],
+    // Observe-umbrella alias of sessions --active (same lazy module).
+    roster: [loadSessions],
     teams: [loadTeams],
     cloud: [loadCloud],
     message: [loadMessage],
     send: [loadSend],
     notify: [loadSend],
     feed: [loadFeed],
+    // Observe-umbrella aliases of feed / feed --filter updates.
+    inbox: [loadFeed],
+    timeline: [loadFeed],
     mailboxes: [loadMailboxes],
     mailbox: [loadMailboxes],
     serve: [loadServe],

package/dist/lib/types.d.ts

@@ -610,6 +610,12 @@ export interface DiscoveredPlugin {
     commands: string[];
     /** Subagent .md files in the plugin's agents/ directory (names without extension). */
     agentDefs: string[];
+    /**
+     * Workflow directory names under the plugin's `workflows/` (each must contain
+     * WORKFLOW.md). Phase 5 packaging: plugins may package workflows as entrypoints;
+     * `agents run <name>` resolves them via project > user > plugin > extra > system.
+     */
+    workflows: string[];
     /** Memory fact basenames from the plugin's memory/ directory (without .md). */
     memory: string[];
     /** Executable files in the plugin's bin/ directory. */

package/dist/lib/usage-refresh.d.ts

@@ -1,16 +1,23 @@
 import { type UsageHeadroom, type UsageSnapshot, type UsageInfo } from './usage.js';
 import type { AgentId } from './types.js';
-/** Floor on the adaptive interval: an account seconds from its cap still isn't
- * polled faster than this. */
+/**
+ * Default schedule between successful (or attempted) live usage fetches for one
+ * account. Floor and ceiling of the delay helper are pinned to this so the
+ * daemon does not poll faster than 5 minutes even under high burn, and does not
+ * let an idle account rot longer than 5 minutes between attempts.
+ */
+export declare const REFRESH_INTERVAL_MS: number;
+/** @deprecated alias — use {@link REFRESH_INTERVAL_MS}. Kept for test imports. */
 export declare const REFRESH_MIN_MS: number;
-/** Ceiling on the adaptive interval: an idle account is still re-checked at
- * least this often so a cache never silently rots. */
+/** @deprecated alias — use {@link REFRESH_INTERVAL_MS}. Kept for test imports. */
 export declare const REFRESH_MAX_MS: number;
-/** Schedule the next refresh at `minutesToLimit / K` — poll well before the cap,
- * not exactly at it. */
+/** Burn-rate divisor retained for the pure delay helper / tests; with min=max
+ * the divisor does not change the scheduled interval. */
 export declare const REFRESH_BURN_DIVISOR = 4;
-/** At most this many live fetches per account per rolling hour. */
-export declare const HOURLY_CALL_CAP = 6;
+/** At most this many live fetches per account per rolling hour (5m cadence ⇒ 12). */
+export declare const HOURLY_CALL_CAP = 12;
+/** How often the daemon wakes to *consider* a refresh pass (due accounts only). */
+export declare const USAGE_REFRESH_TICK_MS: number;
 /**
  * One account's refresh state + published headroom. `sessionUsedPercent` /
  * `capturedAt` are the prior sample the NEXT tick projects the burn rate from;
@@ -38,9 +45,10 @@ export declare function readHeadroomEntry(usageKey: string): HeadroomEntry | nul
 /** Merge entries into the cache (best-effort; preserves other accounts' rows). */
 export declare function writeHeadroomEntries(entries: Record<string, HeadroomEntry>): void;
 /**
- * The adaptive interval until the next refresh, clamped to [MIN, MAX]. A
- * shorter `minutesToLimit` (closer to the cap) polls sooner; `null` (unknown /
- * idle / not burning) waits the full ceiling.
+ * Interval until the next refresh attempt, clamped to [minMs, maxMs].
+ * Defaults pin both ends to {@link REFRESH_INTERVAL_MS} (5 minutes) so the
+ * live daemon path is a fixed schedule. Tests may pass a wider range to
+ * exercise burn-aware scheduling without changing production cadence.
  */
 export declare function computeNextRefreshDelayMs(minutesToLimit: number | null, opts?: {
     minMs?: number;

package/dist/lib/usage-refresh.js

@@ -1,49 +1,74 @@
 /**
- * Daemon-owned adaptive usage refresher.
+ * Daemon-owned usage refresher (per host).
  *
  * The routing hot path (`agents run` → collectRunCandidates) reads usage
  * CACHE-ONLY (`getUsageInfoForIdentity` `readOnly`, RUSH-2061) and never blocks
  * on a provider fetch. Something still has to keep that cache fresh — this
- * module is that something, running inside the daemon.
+ * module is that something, running inside the daemon on **each machine**.
  *
- * Design (per account, this host is the SOLE writer — the refresher only ever
- * touches accounts whose credentials live locally, so no cross-host
- * coordination and no shared-token contention):
+ * Design:
  *
- *  - **Adaptive cadence from burn rate.** Each refresh stores the session
- *    window's `usedPercent` + `capturedAt`. The next refresh is scheduled from
- *    `deriveUsageHeadroom`'s projected `minutesToLimit`: an account racing
- *    toward its cap is polled more often (down to 90s), an idle one rarely (up
- *    to 15min). `computeNextRefreshDelayMs` is the pure clamp.
- *  - **Hard hourly cap.** Regardless of cadence, at most `HOURLY_CALL_CAP` live
- *    fetches per account per rolling hour, so a fast burn can't turn the 90s
- *    floor into a hammering loop.
- *  - **Respects the existing 429 backoff.** A provider under
- *    `usageRateLimitedUntil` is skipped entirely — the whole point of the
- *    backoff is to stop poking an endpoint that just said no.
+ *  - **Per-host sole writer.** Only accounts whose credentials live on THIS
+ *    box are listed; no fleet-wide usage sync.
+ *  - **Fixed 5-minute cadence** (`REFRESH_INTERVAL_MS`). Enough to keep
+ *    balanced/`agents view` off multi-hour stale data without thrashing
+ *    provider APIs when the user runs agents frequently. The delay helpers
+ *    still accept a burn projection for tests/future tuning, but the default
+ *    floor and ceiling are both 5 minutes.
+ *  - **Hard hourly cap** (`HOURLY_CALL_CAP`) so a stuck "due" loop cannot
+ *    hammer an endpoint past ~12 calls/account/hour.
+ *  - **429 backoff.** A provider under `usageRateLimitedUntil` is skipped
+ *    entirely — no live fetch, no Touch ID, no re-armed penalty.
+ *  - **File-only credentials on the daemon path.** Refresh never opens the
+ *    ACL-bound macOS keychain item (Touch ID storm). It uses the no-ACL
+ *    access-token cache / setup-token / `.credentials.json` only
+ *    (`fileOnly: true` on `getUsageInfo`).
+ *  - **Concurrency-safe cache writes.** Usage + headroom files are updated
+ *    under `withFileLock` + atomic rename so a concurrent `agents view`
+ *    background refresh cannot tear or drop another account's row.
  *
- * It also publishes the projected headroom (`minutesToLimit` + status) to a
- * small cache keyed by usage key, so the routing hot path can deprioritize an
- * account projected to cap without recomputing a burn rate it has no prior
- * sample for. `fleet-cache.ts` is the sync reader.
+ * Scenarios (what this path must survive):
+ *
+ *  1. **Daemon tick overlaps a slow tick** — overlap guard in daemon.ts;
+ *     second tick is a no-op.
+ *  2. **`agents view` writes cache while daemon refreshes** — file lock
+ *     serializes read-modify-write; no lost updates.
+ *  3. **macOS keychain ACL / Touch ID** — fileOnly refresh never calls
+ *     `security find-generic-password` on Claude's ACL item.
+ *  4. **Provider 429** — whole provider skipped until Retry-After; cache
+ *     freezes (visible as aged `capturedAt`) rather than hammering.
+ *  5. **Expired access token (no refresh)** — usage path never rotates
+ *     single-use refresh tokens; counts as `failed`, reschedules 5m later.
+ *  6. **No file credential on this host** — account skipped / failed; no
+ *     keychain fallback from the daemon refresher.
+ *  7. **Grok/Codex (network:false)** — not listed by `buildLocalUsageAccounts`;
+ *     their "cache" is local logs, not this HTTP refresher.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { deriveUsageHeadroom, getUsageInfo, buildCanonicalUsageContext, agentUsesNetworkUsage, USAGE_SOURCE_AGENT_IDS, } from './usage.js';
 import { getAccountInfo } from './agents.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
-/** Floor on the adaptive interval: an account seconds from its cap still isn't
- * polled faster than this. */
-export const REFRESH_MIN_MS = 90 * 1000;
-/** Ceiling on the adaptive interval: an idle account is still re-checked at
- * least this often so a cache never silently rots. */
-export const REFRESH_MAX_MS = 15 * 60 * 1000;
-/** Schedule the next refresh at `minutesToLimit / K` — poll well before the cap,
- * not exactly at it. */
+/**
+ * Default schedule between successful (or attempted) live usage fetches for one
+ * account. Floor and ceiling of the delay helper are pinned to this so the
+ * daemon does not poll faster than 5 minutes even under high burn, and does not
+ * let an idle account rot longer than 5 minutes between attempts.
+ */
+export const REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+/** @deprecated alias — use {@link REFRESH_INTERVAL_MS}. Kept for test imports. */
+export const REFRESH_MIN_MS = REFRESH_INTERVAL_MS;
+/** @deprecated alias — use {@link REFRESH_INTERVAL_MS}. Kept for test imports. */
+export const REFRESH_MAX_MS = REFRESH_INTERVAL_MS;
+/** Burn-rate divisor retained for the pure delay helper / tests; with min=max
+ * the divisor does not change the scheduled interval. */
 export const REFRESH_BURN_DIVISOR = 4;
-/** At most this many live fetches per account per rolling hour. */
-export const HOURLY_CALL_CAP = 6;
+/** At most this many live fetches per account per rolling hour (5m cadence ⇒ 12). */
+export const HOURLY_CALL_CAP = 12;
+/** How often the daemon wakes to *consider* a refresh pass (due accounts only). */
+export const USAGE_REFRESH_TICK_MS = 60 * 1000;
 const HOUR_MS = 60 * 60 * 1000;
 /** Test seam for the headroom cache path (see usage.ts `setClaudeUsageCachePathForTest`). */
 let headroomCachePathOverride = null;
@@ -74,27 +99,30 @@ export function readHeadroomEntry(usageKey) {
 /** Merge entries into the cache (best-effort; preserves other accounts' rows). */
 export function writeHeadroomEntries(entries) {
     try {
-        const dir = getCacheDir();
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        const merged = {
-            version: 1,
-            entries: { ...readHeadroomCache(), ...entries },
-        };
-        fs.writeFileSync(headroomCachePath(), JSON.stringify(merged, null, 2));
+        const cachePath = headroomCachePath();
+        ensureLockTarget(cachePath, JSON.stringify({ version: 1, entries: {} }, null, 2));
+        withFileLock(cachePath, () => {
+            // Re-read under the lock so a concurrent tick/view cannot drop rows.
+            const merged = {
+                version: 1,
+                entries: { ...readHeadroomCache(), ...entries },
+            };
+            atomicWriteFileSync(cachePath, JSON.stringify(merged, null, 2));
+        });
     }
     catch {
         // best-effort; a failed write just means the router sees no projection
     }
 }
 /**
- * The adaptive interval until the next refresh, clamped to [MIN, MAX]. A
- * shorter `minutesToLimit` (closer to the cap) polls sooner; `null` (unknown /
- * idle / not burning) waits the full ceiling.
+ * Interval until the next refresh attempt, clamped to [minMs, maxMs].
+ * Defaults pin both ends to {@link REFRESH_INTERVAL_MS} (5 minutes) so the
+ * live daemon path is a fixed schedule. Tests may pass a wider range to
+ * exercise burn-aware scheduling without changing production cadence.
  */
 export function computeNextRefreshDelayMs(minutesToLimit, opts = {}) {
-    const minMs = opts.minMs ?? REFRESH_MIN_MS;
-    const maxMs = opts.maxMs ?? REFRESH_MAX_MS;
+    const minMs = opts.minMs ?? REFRESH_INTERVAL_MS;
+    const maxMs = opts.maxMs ?? REFRESH_INTERVAL_MS;
     const divisor = opts.divisor ?? REFRESH_BURN_DIVISOR;
     if (minutesToLimit === null || !Number.isFinite(minutesToLimit))
         return maxMs;
@@ -169,10 +197,14 @@ export async function buildLocalUsageAccounts() {
             accounts.push({
                 usageKey,
                 agentId,
+                // fileOnly: never open the ACL-bound keychain item from the daemon —
+                // that path is the Touch ID storm. Usage reads setup-token /
+                // no-ACL cache / .credentials.json only (see loadClaudeOauth).
                 fetch: () => getUsageInfo(agentId, {
                     home: fetchInput.home,
                     cliVersion: fetchInput.cliVersion,
                     organizationId: fetchInput.organizationId,
+                    fileOnly: true,
                 }),
             });
         }

package/dist/lib/usage.d.ts

@@ -86,6 +86,13 @@ interface UsageOptions {
     home?: string;
     cliVersion?: string | null;
     organizationId?: string | null;
+    /**
+     * When true, never open the ACL-bound OS keychain item (macOS Touch ID).
+     * Daemon usage refresh sets this so a background tick cannot pop biometrics.
+     * Credentials come from the no-ACL access-token cache, a file-based
+     * setup-token, or `<home>/.claude/.credentials.json` only.
+     */
+    fileOnly?: boolean;
 }
 /** Canonical input for a single usage fetch operation. */
 export interface UsageFetchInput {
@@ -462,9 +469,14 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  * `getClaudeAccessToken`) or export the full blob (`readClaudeCredentialsBlob`
  * for Rush Cloud dispatch) must NOT pass it. Only the read-only, high-frequency
  * access-token-only consumers (the usage fetch and the auth-health probe) opt in.
+ *
+ * `opts.fileOnly` (implies access-token-only consumers) skips the ACL keychain
+ * read entirely — setup-token, no-ACL cache, and `.credentials.json` only. Used
+ * by the daemon usage refresher so a background tick can never pop Touch ID.
  */
 export declare function loadClaudeOauth(home?: string, opts?: {
     accessTokenCache?: boolean;
+    fileOnly?: boolean;
 }): Promise<ClaudeOauthCredentials | null>;
 /**
  * Save Claude OAuth credentials to the system keychain/keyring.

package/dist/lib/usage.js

@@ -24,6 +24,7 @@ import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { formatBackoffRemaining, noteUsageRateLimited, usageRateLimitedUntil, } from './usage-backoff.js';
 import { getCacheDir } from './state.js';
 import { mapBounded } from './concurrency.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -654,7 +655,12 @@ async function getClaudeUsageInfo(options) {
     try {
         // Opt into the no-ACL access-token cache: this is the every-60s watchdog hot
         // path and usage needs only the access token, so it kills the Touch ID storm.
-        const oauth = await loadClaudeOauth(options?.home, { accessTokenCache: true });
+        // Daemon refresh also sets fileOnly so we never fall through to the ACL
+        // keychain item (that path is the Touch ID prompt).
+        const oauth = await loadClaudeOauth(options?.home, {
+            accessTokenCache: true,
+            fileOnly: options?.fileOnly === true,
+        });
         if (!oauth?.accessToken) {
             return { snapshot: null, error: usageNoCredentialError('Claude') };
         }
@@ -1333,6 +1339,10 @@ function deleteCachedClaudeOauth(service) {
  * `getClaudeAccessToken`) or export the full blob (`readClaudeCredentialsBlob`
  * for Rush Cloud dispatch) must NOT pass it. Only the read-only, high-frequency
  * access-token-only consumers (the usage fetch and the auth-health probe) opt in.
+ *
+ * `opts.fileOnly` (implies access-token-only consumers) skips the ACL keychain
+ * read entirely — setup-token, no-ACL cache, and `.credentials.json` only. Used
+ * by the daemon usage refresher so a background tick can never pop Touch ID.
  */
 export async function loadClaudeOauth(home, opts) {
     // Read-only usage/probe callers (accessTokenCache) authenticate with a
@@ -1359,7 +1369,11 @@ export async function loadClaudeOauth(home, opts) {
     // anywhere, so the platform check must yield to it exactly as the inner
     // claudeOauthCacheActive() gate does — otherwise this whole block is dead on
     // a Windows runner and the tests below it read an empty home.
-    if (process.platform === 'darwin' || process.platform === 'linux' || isKeychainBackendOverridden()) {
+    //
+    // fileOnly: daemon refresh must never open the ACL-bound item (Touch ID).
+    // It may still read the no-ACL cache item (set-no-acl — prompt-free).
+    if (!opts?.fileOnly
+        && (process.platform === 'darwin' || process.platform === 'linux' || isKeychainBackendOverridden())) {
         const service = getClaudeKeychainService(home);
         // Serve the no-ACL cache first (opt-in, macOS/test only) so the ACL-gated read
         // below — the one that pops Touch ID — happens at most once per token lifetime
@@ -1386,6 +1400,13 @@ export async function loadClaudeOauth(home, opts) {
                 deleteCachedClaudeOauth(service);
         }
     }
+    else if (opts?.fileOnly === true && opts?.accessTokenCache === true && claudeOauthCacheActive()) {
+        // fileOnly + accessTokenCache: still allow the no-ACL cache (never Touch ID).
+        const service = getClaudeKeychainService(home);
+        const cached = readCachedClaudeOauth(service);
+        if (cached)
+            return cached;
+    }
     const credsPath = path.join(home ?? os.homedir(), '.claude', '.credentials.json');
     try {
         if (fs.existsSync(credsPath)) {
@@ -1487,9 +1508,19 @@ export function readClaudeUsageCache(usageKey, cachePath = getClaudeUsageCachePa
 }
 /** Write a usage snapshot to the on-disk cache. */
 export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeUsageCachePath()) {
-    const cache = readClaudeUsageCacheFile(cachePath);
-    cache[usageKey] = serializeClaudeUsageSnapshot(snapshot);
-    writeClaudeUsageCacheFile(cache, cachePath);
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            // Re-read under the lock so a concurrent daemon tick / agents view
+            // refresh cannot drop another account's row (lost update).
+            const cache = readClaudeUsageCacheFile(cachePath);
+            cache[usageKey] = serializeClaudeUsageSnapshot(snapshot);
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
 }
 /** Read the entire usage cache file from disk. */
 function readClaudeUsageCacheFile(cachePath) {
@@ -1508,7 +1539,7 @@ function readClaudeUsageCacheFile(cachePath) {
 function writeClaudeUsageCacheFile(cache, cachePath) {
     try {
         fs.mkdirSync(path.dirname(cachePath), { recursive: true });
-        fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
     }
     catch {
         /* best-effort cache write */

package/dist/lib/workflows.d.ts

@@ -312,11 +312,25 @@ export declare const GROK_WORKFLOW_MARKER = "agents_workflow";
 export declare function transformWorkflowForGrok(workflowPath: string, name: string): string;
 /** Read the agents_workflow marker from a Grok `.rhai` file, if present. */
 export declare function grokWorkflowMarker(filePath: string): string | 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 declare function listPluginWorkflowDirs(cwd?: 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.
+ */
+export declare function isBareWorkflowName(ref: string): boolean;
 /**
  * Resolve an `agents run <workflow>` reference.
  *
  * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
- * Name lookup keeps the normal resource precedence: project > user > system > extras.
+ * Name lookup precedence (docs/07-entrypoints): project > user > plugin > extra > system.
+ * Bare name only; `name@plugin` disambiguation is a follow-up.
  */
 export declare function resolveWorkflowRef(ref: string, cwd?: string): string | null;
 /**
@@ -326,10 +340,11 @@ export declare function resolveWorkflowRef(ref: string, cwd?: string): string |
  */
 export declare function discoverWorkflowsFromRepo(repoPath: string): DiscoveredWorkflow[];
 /**
- * List all workflows in central storage.
- * User layer (~/.agents/workflows/) wins over system (~/.agents/.system/workflows/).
+ * List all workflows in central storage + plugin packages.
+ * Precedence: user > plugin > extra > system (first writer wins; project is
+ * cwd-scoped and handled by resolveWorkflowRef / the resource handler).
  */
-export declare function listInstalledWorkflows(): Map<string, InstalledWorkflow>;
+export declare function listInstalledWorkflows(cwd?: string): Map<string, InstalledWorkflow>;
 /** Copy a workflow directory into user central storage (~/.agents/workflows/<name>/). */
 export declare function installWorkflowCentrally(sourcePath: string, name: string): {
     success: boolean;

package/dist/lib/workflows.js

@@ -10,7 +10,7 @@ import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { capableAgents, supports } from './capabilities.js';
-import { getProjectAgentsDir, getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, } from './state.js';
+import { getProjectAgentsDir, getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, getPluginsDir, getSystemPluginsDir, getProjectPluginsDir, } from './state.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 /**
  * Hard upper bound on items a single `for_each` expands, absent an explicit
@@ -522,22 +522,94 @@ 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 = [];
+    const pluginsDirs = [];
+    const projectPlugins = getProjectPluginsDir(cwd);
+    if (projectPlugins)
+        pluginsDirs.push(projectPlugins);
+    pluginsDirs.push(getPluginsDir(), getSystemPluginsDir());
+    for (const extra of getEnabledExtraRepos()) {
+        pluginsDirs.push(path.join(extra.dir, 'plugins'));
+    }
+    for (const pluginsDir of pluginsDirs) {
+        if (!fs.existsSync(pluginsDir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                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)
+                continue;
+            const workflowsDir = path.join(pluginRoot, 'workflows');
+            if (fs.existsSync(workflowsDir))
+                pluginRoots.push(workflowsDir);
+        }
+    }
+    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.
+ */
+export function isBareWorkflowName(ref) {
+    if (!ref || ref === '.' || ref === '..')
+        return false;
+    if (ref.includes('/') || 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;
+}
 /**
  * Resolve an `agents run <workflow>` reference.
  *
  * Directories are accepted anywhere on disk when they contain WORKFLOW.md.
- * Name lookup keeps the normal resource precedence: project > user > system > extras.
+ * Name lookup precedence (docs/07-entrypoints): project > user > plugin > extra > system.
+ * Bare name only; `name@plugin` disambiguation is a follow-up.
  */
 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))
+        return null;
     const projectAgentsDir = getProjectAgentsDir(cwd);
     const searchDirs = [
         ...(projectAgentsDir ? [path.join(projectAgentsDir, 'workflows')] : []),
         getUserWorkflowsDir(),
-        getSystemWorkflowsDir(),
+        ...listPluginWorkflowDirs(cwd),
         ...getEnabledExtraRepos().map(r => path.join(r.dir, 'workflows')),
+        getSystemWorkflowsDir(),
     ];
     for (const dir of searchDirs) {
         const workflowPath = path.join(dir, ref);
@@ -592,16 +664,18 @@ export function discoverWorkflowsFromRepo(repoPath) {
     return results;
 }
 /**
- * List all workflows in central storage.
- * User layer (~/.agents/workflows/) wins over system (~/.agents/.system/workflows/).
+ * List all workflows in central storage + plugin packages.
+ * Precedence: user > plugin > extra > system (first writer wins; project is
+ * cwd-scoped and handled by resolveWorkflowRef / the resource handler).
  */
-export function listInstalledWorkflows() {
+export function listInstalledWorkflows(cwd = process.cwd()) {
     const result = new Map();
     const extraRepos = getEnabledExtraRepos();
     const searchDirs = [
         getUserWorkflowsDir(),
-        getSystemWorkflowsDir(),
+        ...listPluginWorkflowDirs(cwd),
         ...extraRepos.map(r => path.join(r.dir, 'workflows')),
+        getSystemWorkflowsDir(),
     ];
     for (const dir of searchDirs) {
         if (!fs.existsSync(dir))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.8",
+  "version": "1.22.10",
   "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",