@phnx-labs/agents-cli 1.22.9 → 1.22.10

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.22.10
+
+- **Plugins package workflows (Phase 5 packaging slice).** A plugin’s `workflows/<name>/WORKFLOW.md` is discovered and resolved by `agents run <name>` with precedence project > user > plugin > extra > system — no separate install into `~/.agents/workflows/` required. Plugin inventory / resource groups list `workflows`. Source: `apps/cli/src/lib/workflows.ts`, `apps/cli/src/lib/plugins.ts`, `apps/cli/src/lib/resources/workflows.ts`.
+
+- **`scripts/release.sh` routes the home-base publish hop via `agents ssh`.** Plain `ssh mac-mini` fails host-key checks on headless Linux workers; `agents ssh` uses the devices registry and brokered credentials. Falls back to plain ssh only when `agents` is not on PATH. Source: `apps/cli/scripts/release.sh`.
+
+- **Touch ID is now raised in exactly one place — `agents secrets unlock`.** `agents secrets list`, `agents run <agent>`, `secrets get`/`export`/`view`, and every background read resolve from the secrets broker / durable session / no-ACL layer and never raise a biometric sheet; a locked keychain bundle fails with an actionable "run `agents secrets unlock <bundle>`" hint instead of prompting. The `AGENTS_SECRETS_NO_PROMPT` environment override and the "a human at a TTY, so prompting is fine" heuristic are deleted — the prompt decision is structural, not an ambient env var. The macOS keychain `list`/`list-synced` enumeration queries now pass `kSecUseAuthenticationUISkip` (enumeration itself was evaluating the biometry ACL, so `agents secrets list` prompted and silently dropped keychain bundles when the sheet was cancelled), and the one-time hash-rekey + metadata-ACL heal run only inside the single `unlock` sheet so nothing on the run/list path can storm. Source: `apps/cli/src/lib/secrets/keychain-helper.swift`, `apps/cli/src/lib/secrets/index.ts`, `apps/cli/src/lib/secrets/bundles.ts`, `apps/cli/src/lib/secrets/headless.ts`, `apps/cli/src/commands/secrets.ts`.
+- **The Factory VS Code extension (`swarm-ext`) no longer decrypts secrets or shells raw `ssh`.** Device health, reachability, and sync route every remote command through `agents ssh <host>` (broker-owned credentials, no prompt); the extension's own secret-resolution path (`resolveSecret`/`discoverSecretsReadCmd`/`extractCredentials`) is removed, so rendering the devices list never raises Touch ID. Source: `apps/factory/src/vscode/deviceHealth.vscode.ts`, `apps/factory/src/vscode/settings.vscode.ts`, `apps/factory/src/vscode/extension.ts`.
+
 ## 1.22.9
 
 - **`agents ssh auto` and `agents teams add --device auto` no longer reject with "Unknown device 'auto'" (RUSH-2185).** The `auto` affinity sentinel was a `run`-only preprocessing step (`applyDeviceAutoToOptions` in `smart-launch.ts`, wired only from `agents run`'s exec path) — every other `--host`/`--device` caller went straight to the shared resolver, which had no idea what `auto` meant and reported it as an unregistered device. `matchHost` (the one core every `--host`/`--device` caller shares) now resolves `auto` directly via the same `resolveDeviceAffinity` engine `run` uses, so `agents ssh`, `agents teams add`, and anything else routed through `matchHost`/`resolveHost` (including the generic `--host`/`--device` passthrough) pick a device the same way. `agents teams add --device auto` landing on the local machine now just runs the teammate locally, matching `run`'s "null pick = local" outcome; `agents ssh auto` refuses a local pick with a clear message instead of self-SSHing, since `agents ssh` exists to dial OUT to a remote box. Source: `apps/cli/src/lib/hosts/registry.ts`, `apps/cli/src/lib/devices/resolve-target.ts`, `apps/cli/src/commands/ssh.ts`, `apps/cli/src/commands/teams.ts`, `apps/cli/docs/00-concepts.md`, `apps/cli/docs/hosts.md`, `apps/cli/docs/teams.md`.
@@ -2908,10 +2917,8 @@
   `agentOnly` guard; and `isHeadlessSecretsContext` recognized the `headless` and
   `teams` runtimes but not `terminal`, which is what an interactive run sets. Agent
   launches now resolve broker-only and a locked bundle fails fast naming
-  `agents secrets unlock <bundle>`; `AGENTS_SECRETS_NO_PROMPT=1` is no longer needed
-  as a workaround. `agents secrets get/export/exec` typed in a **plain shell** still
-  prompts — it carries no `AGENTS_RUNTIME`, so the guard does not apply. Run beneath
-  an agent it refuses, because there the agent is the caller. This narrows the
+  `agents secrets unlock <bundle>`. Direct read commands use the same broker-only
+  path even from a plain shell; only an explicit unlock may authenticate. This narrows the
   agent-triggered approval added in RUSH-2032, which is unreleased.
 
 - **`release.sh` now borrows the npm token from a primary device when the local box

package/dist/commands/browser.js

@@ -5,7 +5,7 @@ import { updateMeta } from '../lib/state.js';
 import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
 import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
@@ -1481,7 +1481,7 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
             try {
-                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(parsed.bundle, { caller: 'browser type', keys: [parsed.key], keyMode: 'storage', agentOnly: true });
                 if (!(parsed.key in env)) {
                     console.error(`Key "${parsed.key}" not in bundle "${parsed.bundle}".`);
                     process.exit(1);

package/dist/commands/secrets.js

@@ -18,10 +18,10 @@ 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, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, 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, 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, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
+import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, maybeAutoRekey, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { GLOBAL_HARNESS } from '../lib/secrets/scope.js';
 import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
@@ -1251,15 +1251,15 @@ export function registerSecretsCommands(program) {
                 }
                 const revealed = new Map();
                 if (reveal) {
-                    const items = entries
-                        .filter((e) => e.kind === 'keychain')
-                        .map((e) => secretsKeychainItem(bundle.name, e.detail));
-                    try {
-                        for (const [item, value] of getKeychainTokens(items))
-                            revealed.set(item, value);
-                    }
-                    catch {
-                        /* cancelled / batch failure — fall through to masked (null) values */
+                    const { env } = readAndResolveBundleEnv(bundle.name, {
+                        caller: 'view --reveal --json',
+                        keyMode: 'storage',
+                        agentOnly: true,
+                    });
+                    for (const entry of entries) {
+                        if (entry.kind === 'keychain' && env[entry.key] !== undefined) {
+                            revealed.set(secretsKeychainItem(bundle.name, entry.detail), env[entry.key]);
+                        }
                     }
                     const exposed = revealed.size + entries.filter((e) => e.kind === 'literal').length;
                     if (exposed > 0) {
@@ -1369,23 +1369,20 @@ export function registerSecretsCommands(program) {
                 console.error(chalk.red('--reveal in a non-TTY requires --plaintext.'));
                 process.exit(1);
             }
-            // Batch every backend read into one helper call where supported, so
-            // keychain --reveal pops Touch ID once and synced/file bundles use
-            // their declared storage.
+            // 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.
             const revealedValues = new Map();
             if (reveal) {
-                const items = entries
-                    .filter((e) => e.kind === 'keychain')
-                    .map((e) => secretsKeychainItem(bundle.name, e.detail));
-                try {
-                    const fetched = bundle.backend
-                        ? new Map(items.map((item) => [item, bundleItemStore(bundle.backend).get(item)]))
-                        : getKeychainTokens(items);
-                    for (const [item, value] of fetched)
-                        revealedValues.set(item, value);
-                }
-                catch {
-                    // Fall through to masked output on cancellation / batch failure.
+                const { env } = readAndResolveBundleEnv(bundle.name, {
+                    caller: 'view --reveal',
+                    keyMode: 'storage',
+                    agentOnly: true,
+                });
+                for (const entry of entries) {
+                    if (entry.kind === 'keychain' && env[entry.key] !== undefined) {
+                        revealedValues.set(secretsKeychainItem(bundle.name, entry.detail), env[entry.key]);
+                    }
                 }
                 // Revealing plaintext bypasses readAndResolveBundleEnv (the usual
                 // audit chokepoint), so emit here — a `--reveal` exposes real values
@@ -1475,10 +1472,9 @@ export function registerSecretsCommands(program) {
                 process.exit(1);
             }
             // `secrets get` is the scriptable automation primitive ($(agents secrets
-            // get bundle KEY)); when embedded in a headless routine/CI script — or run
-            // beneath any agent, which inherits AGENTS_RUNTIME — it must not pop an
-            // unwatched Touch ID prompt. Typed in a plain shell it still prompts.
-            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+            // get bundle KEY)). Every read is broker-only; a locked bundle points at
+            // the explicit unlock command instead of raising Touch ID.
+            const { env } = readAndResolveBundleEnv(item, { caller: 'secrets get', keys: [key], keyMode: 'storage', agentOnly: true });
             if (!(key in env)) {
                 console.error(chalk.red(`Key '${key}' not in bundle '${item}'.`));
                 process.exit(1);
@@ -2083,7 +2079,7 @@ Examples:
                     throw new Error('--to-file needs AGENTS_SECRETS_PASSPHRASE set to encrypt the bundle. ' +
                         'Set it for this command, then supply the same value when importing.');
                 }
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: 'export --to-file', keyMode: 'storage', agentOnly: true });
                 exportBundleToFile(env, opts.toFile, passphrase);
                 emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: 'export --to-file', source: 'file', status: 'success', keyCount: Object.keys(env).length });
                 console.log(chalk.green(`Exported ${Object.keys(env).length} key(s) to ${opts.toFile}`));
@@ -2111,7 +2107,7 @@ Examples:
                             'bundle at rest on the remote. Set it for this command, then unlock it the same way per run.');
                     }
                 }
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: true });
                 const dotenv = bundleEnvToDotenv(env);
                 const keyCount = Object.keys(env).length;
                 // Drive the remote's own `agents secrets import --from -` so the values
@@ -2200,7 +2196,7 @@ Examples:
             if (opts.to1password) {
                 assertOpAvailable();
                 const vault = await resolveVault(opts.vault);
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, keyMode: 'storage', agentOnly: isHeadlessSecretsContext() });
+                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `1Password vault ${vault}`, keyMode: 'storage', agentOnly: true });
                 let created = 0;
                 let overwritten = 0;
                 let skipped = 0;
@@ -2240,14 +2236,12 @@ Examples:
                 process.exit(1);
             }
             // `agents secrets export --plaintext` is what release/CI scripts eval.
-            // When it runs detached (both stdio non-TTY) or beneath ANY agent — which
-            // inherits AGENTS_RUNTIME — resolve broker-only so it can never pop a Touch
-            // ID sheet on the interactive user's screen. An `eval "$(...)"` typed in a
-            // plain shell carries no AGENTS_RUNTIME, so it is not headless and still prompts.
+            // Every caller is broker-only, including a plain shell, so export never
+            // raises Touch ID on the interactive user's screen.
             const { env } = readAndResolveBundleEnv(resolvedBundleName, {
                 caller: `export to shell`,
                 keyMode: 'process',
-                agentOnly: isHeadlessSecretsContext(),
+                agentOnly: true,
             });
             if (opts.format === 'json') {
                 // Machine-readable form consumed by `remoteResolveEnv` over SSH.
@@ -2309,7 +2303,7 @@ Examples:
                     caller: `command ${cmd}`,
                     keys: keysSubset,
                     allowExpired: execOpts.allowExpired,
-                    agentOnly: isHeadlessSecretsContext(),
+                    agentOnly: true,
                 }).env;
             }
             const { spawn } = await import('child_process');
@@ -2575,6 +2569,11 @@ Examples:
                     duration: humanRemaining(Date.now() + ttlMs),
                     keyMode: 'storage',
                 });
+                // Migrations are authorized only by this explicit unlock. The bundle
+                // metadata was included in the successful authenticated batch, so the
+                // ACL heal can rewrite that already-read value without another read.
+                maybeAutoRekey();
+                healKeychainBundleMetadataAclOnce(new Map([[bundle.name, JSON.stringify(bundle)]]));
                 if (await agentLoad(name, bundle, env, ttlMs, harness)) {
                     loaded++;
                     // Persist a durable session snapshot so the unlock survives a daemon

package/dist/commands/ssh.js

@@ -16,7 +16,7 @@ import * as path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
 import { getCliVersion } from '../lib/version.js';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
 import { registerFleetCaptureCommand } from './fleet-capture.js';
@@ -31,7 +31,7 @@ import { resolveDeviceTarget, splitUserHost } from '../lib/devices/resolve-targe
 import { clearPendingSentinel } from '../lib/devices/pending.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { hostNameFor, renderSshConfig } from '../lib/devices/ssh-config.js';
-import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, ASKPASS_AGENT_ONLY_ENV, buildSshInvocation, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
+import { ASKPASS_BUNDLE_ENV, ASKPASS_KEY_ENV, buildSshInvocation, fleetDialTarget, writeAskpassShim, } from '../lib/devices/connect.js';
 import { ensureManagedKnownHostsDir, isHostPinned } from '../lib/devices/known-hosts.js';
 import { shouldSyncTerminfo, syncTerminfoToDevice, terminfoHostKey } from '../lib/devices/terminfo.js';
 import { fanOutDevices, fleetHealthSkip, planFleetTargets, remoteFleetTargets, runFleet, skipLabel, upgradeCommand, } from '../lib/devices/fleet.js';
@@ -1514,9 +1514,8 @@ async function runAskpass() {
     }
     // A read-only stats probe sets ASKPASS_AGENT_ONLY_ENV to force a broker-only
     // resolve even under a TTY — so `agents devices` never pops Touch ID just to
-    // render load/mem for an uncached password-auth device (RUSH-1970). Otherwise
-    // fall back to the headless-context heuristic.
-    const agentOnly = process.env[ASKPASS_AGENT_ONLY_ENV] === '1' || isHeadlessSecretsContext();
+    // render load/mem for an uncached password-auth device (RUSH-1970).
+    const agentOnly = true;
     try {
         const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh', keys: [key], keyMode: 'storage', agentOnly });
         const value = env[key];

package/dist/commands/workflows.js

@@ -29,7 +29,7 @@ Structure:
     skills/            optional: knowledge packs scoped to this workflow
     plugins/           optional: plugin bundles scoped to this workflow
 
-Resolution: project (.agents/workflows/) > user (~/.agents/workflows/) > system.
+Resolution: project > user > plugin (plugins/*/workflows/) > extra > system.
 
 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/plugins.d.ts

@@ -2,11 +2,12 @@
  * Plugin discovery, validation, and syncing.
  *
  * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks,
- * commands, agents, bin scripts, MCP servers, and settings under a single
- * manifest (plugin.json). They are user-authored resources, sitting alongside
- * skills/, commands/, hooks/, etc. — git-tracked as source of truth. This
- * module discovers plugins, validates their manifests, and syncs their
- * contents into agent version homes.
+ * commands, agents, workflows, bin scripts, MCP servers, and settings under a
+ * single manifest (plugin.json). They are user-authored resources, sitting
+ * alongside skills/, commands/, hooks/, etc. — git-tracked as source of truth.
+ * This module discovers plugins, validates their manifests, and syncs their
+ * contents into agent version homes. Workflows under a plugin’s workflows/
+ * are resolved at run time by resolveWorkflowRef (Phase 5 packaging).
  */
 import type { AgentId, DiscoveredPlugin, PluginManifest, MarketplaceSpec } from './types.js';
 export interface PluginCapabilities {
@@ -95,6 +96,14 @@ export declare function discoverPluginHooks(pluginRoot: string): string[];
 export declare function discoverPluginCommands(pluginRoot: string): string[];
 /** Discover agent definition .md files inside a plugin's agents/ directory. */
 export declare function discoverPluginAgentDefs(pluginRoot: string): string[];
+/**
+ * Discover workflow directories inside a plugin's `workflows/` folder.
+ * A valid workflow is a directory containing WORKFLOW.md (same contract as
+ * project/user/system workflows). Phase 5: plugins package workflows as
+ * entrypoints so `agents run <name>` can resolve them without a separate
+ * install into ~/.agents/workflows/.
+ */
+export declare function discoverPluginWorkflows(pluginRoot: string): string[];
 /** Discover executable files in a plugin's bin/ directory. */
 export declare function discoverPluginBin(pluginRoot: string): string[];
 /** Discover MCP server names from .mcp.json at the plugin root. */

package/dist/lib/plugins.js

@@ -2,11 +2,12 @@
  * Plugin discovery, validation, and syncing.
  *
  * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks,
- * commands, agents, bin scripts, MCP servers, and settings under a single
- * manifest (plugin.json). They are user-authored resources, sitting alongside
- * skills/, commands/, hooks/, etc. — git-tracked as source of truth. This
- * module discovers plugins, validates their manifests, and syncs their
- * contents into agent version homes.
+ * commands, agents, workflows, bin scripts, MCP servers, and settings under a
+ * single manifest (plugin.json). They are user-authored resources, sitting
+ * alongside skills/, commands/, hooks/, etc. — git-tracked as source of truth.
+ * This module discovers plugins, validates their manifests, and syncs their
+ * contents into agent version homes. Workflows under a plugin’s workflows/
+ * are resolved at run time by resolveWorkflowRef (Phase 5 packaging).
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -107,6 +108,7 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         scripts: discoverPluginScripts(pluginRoot),
         commands: discoverPluginCommands(pluginRoot),
         agentDefs: discoverPluginAgentDefs(pluginRoot),
+        workflows: discoverPluginWorkflows(pluginRoot),
         memory: discoverPluginMemory(pluginRoot),
         bin: discoverPluginBin(pluginRoot),
         mcpServers: discoverPluginMcpServers(pluginRoot),
@@ -131,6 +133,7 @@ export function pluginResourceGroups(plugin) {
         { label: 'skills', items: plugin.skills.map((s) => `/${plugin.name}:${s}`) },
         { label: 'commands', items: plugin.commands.map((c) => `/${plugin.name}:${c}`) },
         { label: 'subagents', items: plugin.agentDefs },
+        { label: 'workflows', items: plugin.workflows },
         { label: 'hooks', items: plugin.hooks },
         { label: 'memory', items: plugin.memory },
         { label: 'mcp', items: plugin.mcpServers },
@@ -334,6 +337,27 @@ export function discoverPluginAgentDefs(pluginRoot) {
         .filter(f => f.endsWith('.md') && !f.startsWith('.'))
         .map(f => f.slice(0, -3));
 }
+/**
+ * Discover workflow directories inside a plugin's `workflows/` folder.
+ * A valid workflow is a directory containing WORKFLOW.md (same contract as
+ * project/user/system workflows). Phase 5: plugins package workflows as
+ * entrypoints so `agents run <name>` can resolve them without a separate
+ * install into ~/.agents/workflows/.
+ */
+export function discoverPluginWorkflows(pluginRoot) {
+    const workflowsDir = path.join(pluginRoot, 'workflows');
+    if (!fs.existsSync(workflowsDir))
+        return [];
+    try {
+        return fs.readdirSync(workflowsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith('.') &&
+            fs.existsSync(path.join(workflowsDir, e.name, 'WORKFLOW.md')))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
 /** Discover executable files in a plugin's bin/ directory. */
 export function discoverPluginBin(pluginRoot) {
     const binDir = path.join(pluginRoot, 'bin');

package/dist/lib/resources/types.d.ts

@@ -6,7 +6,8 @@
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi';
-export type Layer = 'system' | 'user' | 'project';
+/** Resource origin. Precedence (highest first): project > user > plugin > system. */
+export type Layer = 'system' | 'user' | 'project' | 'plugin';
 export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow' | 'memory';
 /** A resolved resource with its origin layer. */
 export interface ResolvedItem<T> {

package/dist/lib/resources/workflows.d.ts

@@ -3,7 +3,7 @@
  *
  * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
  * They optionally contain subagents/, skills/, and plugins/ subdirectories.
- * Resolution order: project > user > system.
+ * Resolution order (docs/07-entrypoints): project > user > plugin > extra > system.
  */
 import type { AgentId, ResolvedItem, ResourceHandler } from './types.js';
 export interface WorkflowItem {

package/dist/lib/resources/workflows.js

@@ -3,12 +3,12 @@
  *
  * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
  * They optionally contain subagents/, skills/, and plugins/ subdirectories.
- * Resolution order: project > user > system.
+ * Resolution order (docs/07-entrypoints): project > user > plugin > extra > system.
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getProjectAgentsDir, getUserWorkflowsDir, getSystemWorkflowsDir, getEnabledExtraRepos, } from '../state.js';
-import { parseWorkflowFrontmatter, countWorkflowSubagents } from '../workflows.js';
+import { parseWorkflowFrontmatter, countWorkflowSubagents, listPluginWorkflowDirs, isBareWorkflowName, } from '../workflows.js';
 function getLayerDirs(cwd) {
     const projectDir = getProjectAgentsDir(cwd);
     const extraRepos = getEnabledExtraRepos();
@@ -32,20 +32,27 @@ function listWorkflowsInDir(dir) {
         return [];
     }
 }
+/** Precedence-ordered (dir, layer) pairs for name lookup / listing. */
+function orderedWorkflowSearchDirs(cwd) {
+    const dirs = getLayerDirs(cwd);
+    const out = [];
+    if (dirs.project)
+        out.push({ dir: dirs.project, layer: 'project' });
+    out.push({ dir: dirs.user, layer: 'user' });
+    for (const pluginDir of listPluginWorkflowDirs(cwd ?? process.cwd())) {
+        out.push({ dir: pluginDir, layer: 'plugin' });
+    }
+    for (const extraDir of dirs.extra)
+        out.push({ dir: extraDir, layer: 'system' });
+    out.push({ dir: dirs.system, layer: 'system' });
+    return out;
+}
 class WorkflowsHandlerImpl {
     kind = 'workflow';
     listAll(_agent, cwd) {
-        const dirs = getLayerDirs(cwd);
         const seen = new Set();
         const results = [];
-        const layerDirs = [];
-        if (dirs.project)
-            layerDirs.push({ dir: dirs.project, layer: 'project' });
-        layerDirs.push({ dir: dirs.user, layer: 'user' });
-        layerDirs.push({ dir: dirs.system, layer: 'system' });
-        for (const extraDir of dirs.extra)
-            layerDirs.push({ dir: extraDir, layer: 'system' });
-        for (const { dir, layer } of layerDirs) {
+        for (const { dir, layer } of orderedWorkflowSearchDirs(cwd)) {
             for (const { name, path: workflowPath } of listWorkflowsInDir(dir)) {
                 if (seen.has(name))
                     continue;
@@ -69,15 +76,10 @@ class WorkflowsHandlerImpl {
         return results.sort((a, b) => a.name.localeCompare(b.name));
     }
     resolve(_agent, name, cwd) {
-        const dirs = getLayerDirs(cwd);
-        const searchDirs = [];
-        if (dirs.project)
-            searchDirs.push({ dir: dirs.project, layer: 'project' });
-        searchDirs.push({ dir: dirs.user, layer: 'user' });
-        searchDirs.push({ dir: dirs.system, layer: 'system' });
-        for (const extraDir of dirs.extra)
-            searchDirs.push({ dir: extraDir, layer: 'system' });
-        for (const { dir, layer } of searchDirs) {
+        // Same bare-name gate as resolveWorkflowRef — never path-join traversal refs.
+        if (!isBareWorkflowName(name))
+            return null;
+        for (const { dir, layer } of orderedWorkflowSearchDirs(cwd)) {
             const workflowPath = path.join(dir, name);
             const fm = parseWorkflowFrontmatter(workflowPath);
             if (fm) {

package/dist/lib/secrets/bundles.d.ts

@@ -23,6 +23,8 @@
 import { type BundleValue, type SecretRef } from './index.js';
 /** Which store carries a bundle's items. */
 export type SecretsBackend = 'keychain' | 'file' | 'vault';
+/** Disable the broker-only guard for in-memory keychain tests. */
+export declare function setKeychainAgentOnlyBypassForTest(bypass: boolean): void;
 /**
  * Discover a bundle's backend by location: a file-backed bundle's metadata
  * item exists in the encrypted-file store. This is a plain file-existence
@@ -184,6 +186,13 @@ export declare function deleteBundle(name: string): boolean;
  * extra keychain read is issued. Exported for tests. Returns the count healed.
  */
 export declare function healKeychainBundleMetadata(metaJsonByName: Map<string, string>): number;
+/**
+ * One-time driver around healKeychainBundleMetadata (RUSH-1759). macOS + real
+ * keychain only — libsecret/CredMan have no biometry ACL to shed, and a test
+ * backend has no real keychain — and gated by a sentinel so it runs at most
+ * once. Best-effort: a heal failure never breaks bundle listing.
+ */
+export declare function healKeychainBundleMetadataAclOnce(metaJsonByName: Map<string, string>): void;
 export declare function listBundles(): SecretsBundle[];
 export interface BundleEntryInfo {
     key: string;

package/dist/lib/secrets/bundles.js

@@ -86,6 +86,11 @@ const vaultStore = {
     delete: vaultDeleteItem,
     list: vaultListItems,
 };
+let keychainAgentOnlyBypassForTest = false;
+/** Disable the broker-only guard for in-memory keychain tests. */
+export function setKeychainAgentOnlyBypassForTest(bypass) {
+    keychainAgentOnlyBypassForTest = bypass;
+}
 function itemStore(backend) {
     if (backend === 'file')
         return fileItemStore;
@@ -606,7 +611,7 @@ export function healKeychainBundleMetadata(metaJsonByName) {
  * backend has no real keychain — and gated by a sentinel so it runs at most
  * once. Best-effort: a heal failure never breaks bundle listing.
  */
-function healKeychainBundleMetadataAclOnce(metaJsonByName) {
+export function healKeychainBundleMetadataAclOnce(metaJsonByName) {
     if (metaJsonByName.size === 0)
         return;
     if (process.platform !== 'darwin')
@@ -684,7 +689,6 @@ export function listBundles() {
                 // still prompt once; it heals on the next interactive scan.)
                 const fetched = getKeychainTokens(keychainServices, { silentNoAcl: true });
                 const keychainBundles = [];
-                const metaJsonByName = new Map();
                 for (const service of keychainServices) {
                     const json = fetched.get(service);
                     if (json === undefined)
@@ -695,7 +699,6 @@ export function listBundles() {
                     const bundle = parseBundleMeta(nameHint, json, 'keychain');
                     if (bundle) {
                         keychainBundles.push(bundle);
-                        metaJsonByName.set(bundle.name, json);
                     }
                 }
                 for (const bundle of keychainBundles)
@@ -707,13 +710,6 @@ export function listBundles() {
                 if (useAgent && keychainBundles.length > 0) {
                     agentAutoLoadMetaSync(nameSetHash, keychainBundles, secretsHoldMs());
                 }
-                // One-time RUSH-1759 heal: bundles written before the metadata-no-ACL
-                // change carry an ACL'd metadata item, so this fresh read (a broker miss)
-                // popped Touch ID just to enumerate them. Re-home each metadata item
-                // no-ACL now — reusing the JSON we just read, so the heal adds no extra
-                // prompt — and every later enumeration is silent. Runs at most once (a
-                // sentinel under the regenerable helpers dir).
-                healKeychainBundleMetadataAclOnce(metaJsonByName);
             }
         }
     }
@@ -1099,24 +1095,14 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
-    // Never/no-ACL bundles remain prompt-free regardless. No agent launch — harness,
-    // teammate, routine, or the always-on daemon — may raise the sheet itself.
-    // Explicit opt-in ONLY — a deliberate NARROWING of the agent-triggered approval
-    // added in RUSH-2032 (b99796f8 removed this throw so an agent could raise the
-    // sheet itself; 4eeada68 generalized the daemon rule into `!interactiveUnlock`).
-    // That default — true whenever an agent name was present — was the spec, not a
-    // bug. It is unwanted: each keychain read runs in its own helper process, so the
-    // biometric assertion never reuses and one agent launch meant one sheet per
-    // bundle. `agentOnly` decides alone now; a human in a plain shell carries no
-    // AGENTS_RUNTIME, so isHeadlessSecretsContext() is false, agentOnly is false, the
-    // guard never fires, and they still get their prompt. No caller passes this flag;
-    // it remains the seam for a future unlock path that wants the sheet on purpose.
+    // Never/no-ACL bundles remain prompt-free regardless. Every ordinary caller
+    // sets agentOnly; only the unlock handler opts into interactive authentication.
     const interactiveUnlock = opts.interactiveUnlock ?? false;
     // A `never`-policy bundle's items carry no biometry ACL, so once the policy
     // check below proves that, the batch read is silent even in a headless
     // context — attest it to the raw-read storm guard via `silentNoAcl`.
     let verifiedNoAclBundle = false;
-    if (opts.agentOnly && backend === 'keychain' && !interactiveUnlock) {
+    if (opts.agentOnly && backend === 'keychain' && !interactiveUnlock && !keychainAgentOnlyBypassForTest) {
         try {
             verifiedNoAclBundle = bundlePolicy(readBundle(name)) === 'never';
         }

package/dist/lib/secrets/headless.d.ts

@@ -5,22 +5,13 @@
  * importing bundles.ts (which already imports index.ts).
  */
 /**
- * True when the current process is a background / non-interactive context that
- * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
- * a prompt nobody is watching. Two signals, either sufficient:
+ * True when the current process was structurally launched by an agent runtime
+ * that must NEVER raise a Keychain biometry prompt on the user's screen:
  *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
  *     launch, interactive included, and inherited by everything spawned beneath
  *     one (set on the child env by `agents run --headless`, scheduled routines,
  *     teammates, and interactive runs — see exec.ts:430, runner.ts,
  *     teams/agents.ts).
- *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
- *     stdio is redirected to a log — e.g. a release script run in the
- *     background as `( ... ) >log 2>&1 </dev/null`).
- * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
- * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
- * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
- * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
- * broker-only — the agent, not the human, is the caller there.
  *
  * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
  * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
@@ -33,7 +24,4 @@
  * fast with an actionable error instead of hijacking Touch ID. This generalizes
  * the per-caller broker-only pattern used across the headless secrets readers.
  */
-export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: {
-    stdin?: boolean;
-    stdout?: boolean;
-}): boolean;
+export declare function isHeadlessSecretsContext(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;

package/dist/lib/secrets/headless.js

@@ -5,22 +5,13 @@
  * importing bundles.ts (which already imports index.ts).
  */
 /**
- * True when the current process is a background / non-interactive context that
- * must NEVER raise a Keychain biometry prompt on the interactive user's screen —
- * a prompt nobody is watching. Two signals, either sufficient:
+ * True when the current process was structurally launched by an agent runtime
+ * that must NEVER raise a Keychain biometry prompt on the user's screen:
  *   - `AGENTS_RUNTIME` is `headless`, `teams`, or `terminal` — i.e. ANY agent
  *     launch, interactive included, and inherited by everything spawned beneath
  *     one (set on the child env by `agents run --headless`, scheduled routines,
  *     teammates, and interactive runs — see exec.ts:430, runner.ts,
  *     teams/agents.ts).
- *   - neither stdin nor stdout is a TTY (a detached/backgrounded task whose
- *     stdio is redirected to a log — e.g. a release script run in the
- *     background as `( ... ) >log 2>&1 </dev/null`).
- * `AGENTS_SECRETS_NO_PROMPT=1` forces headless-safe; `=0` force-allows a prompt
- * even in a non-TTY context. An `eval "$(agents secrets export X)"` typed in a
- * PLAIN shell has no AGENTS_RUNTIME, so it is not classified headless and still
- * prompts. Run beneath an agent it inherits AGENTS_RUNTIME and resolves
- * broker-only — the agent, not the human, is the caller there.
  *
  * Only **macOS keychain** reads pop an interactive Touch ID sheet — the secrets
  * broker itself is a no-op off darwin (see agent.ts), and libsecret (Linux) /
@@ -33,31 +24,12 @@
  * fast with an actionable error instead of hijacking Touch ID. This generalizes
  * the per-caller broker-only pattern used across the headless secrets readers.
  */
-export function isHeadlessSecretsContext(env = process.env, platform = process.platform, 
-// Injected so the TTY branch below is testable: it is the branch that decides a
-// plain human shell still prompts, which is this guard's entire safety argument,
-// and reading process.* directly made it unreachable from a test.
-tty = { stdin: process.stdin.isTTY, stdout: process.stdout.isTTY }) {
+export function isHeadlessSecretsContext(env = process.env, platform = process.platform) {
     if (platform !== 'darwin')
         return false; // no biometry prompt to suppress off-darwin
-    const override = env.AGENTS_SECRETS_NO_PROMPT;
-    if (override === '1')
-        return true;
-    if (override === '0')
-        return false;
-    // Every AGENT-LAUNCH runtime resolves broker-only, interactive included.
-    // `terminal` was missing, which made an agent terminal the one launch path
-    // still allowed to pop Touch ID: exec.ts sets AGENTS_RUNTIME='terminal' for an
-    // interactive run (exec.ts:430), that fell through to the TTY check below, and
-    // a TTY meant "a human is watching, so prompting is fine". It is not fine —
-    // opening a terminal is not a request to authenticate, and a launch that needs
-    // a locked bundle should say so and point at `agents secrets unlock`, not grab
-    // the fingerprint sensor. AGENTS_RUNTIME is INHERITED by everything spawned under
-    // an agent, so `agents secrets export` run beneath one resolves broker-only too —
-    // correctly: there the agent, not the human, is the caller. A plain shell carries
-    // no AGENTS_RUNTIME, so a person running it themselves still gets the sheet.
+    // Every agent-launch runtime resolves broker-only, interactive included.
     const runtime = env.AGENTS_RUNTIME;
     if (runtime === 'headless' || runtime === 'teams' || runtime === 'terminal')
         return true;
-    return !tty.stdin && !tty.stdout;
+    return false;
 }

package/dist/lib/secrets/index.d.ts

@@ -143,6 +143,14 @@ export declare function healHmacKeyNoAclOnce(rec: HmacKeyRecord): boolean;
  * see readAndResolveBundleEnv.
  */
 export declare function keychainServiceAlias(item: string): string;
+/**
+ * One-shot per process: activate hashing on machines with nothing to move,
+ * finish a crash-interrupted delete phase (silent), and run the interactive
+ * one-time re-key when cleartext-named items exist and a human is present.
+ * Never throws — a failed attempt leaves the process on cleartext names
+ * (exact pre-#316 behavior) and the next process retries.
+ */
+export declare function maybeAutoRekey(): void;
 /** One re-keyed (or failed) item, by its old cleartext service name. */
 export interface RekeyPlanItem {
     oldService: string;

package/dist/lib/secrets/index.js

@@ -247,30 +247,7 @@ export function readHmacKeyRecord() {
     catch {
         return null;
     }
-    const record = parseHmacKeyRecord(raw);
-    // Converge a stale-ACL'd hmackey to silent, on the HOT read path. An old helper
-    // (pre the metadata/hmackey no-ACL migration fix) re-stamped this
-    // contractually-no-ACL item with a biometry ACL, so the read just above pops the
-    // generic "Agents CLI needs to authenticate" sheet on EVERY hashed lookup — the
-    // `agents devices list` stats probe the SessionStart hook runs, and every other
-    // background hashed read. `maybeAutoRekey`'s one-shot heal only fires on a
-    // cleartext-bundle resolve and is bypassed for the hmackey/hashed-name path
-    // (prepareServiceName returns early for HMAC_KEY_ITEM before maybeAutoRekey), so
-    // it never converged exactly these reads and the machine prompted forever.
-    // Re-store the record no-ACL once per machine here (the read that produced it has
-    // already happened — and already prompted if the item was ACL'd); every
-    // subsequent read, in this process and all future ones, is silent.
-    if (record && !record.healedNoAcl) {
-        try {
-            healHmacKeyNoAclOnce(record);
-            record.healedNoAcl = true;
-        }
-        catch {
-            // A failed no-ACL re-store leaves the item still ACL'd (a still-prompting
-            // read) rather than a silent wrong state; the next process retries.
-        }
-    }
-    return record;
+    return parseHmacKeyRecord(raw);
 }
 function writeHmacKeyRecord(rec) {
     // JSON.stringify drops undefined fields (used to clear pendingDeletes).
@@ -325,15 +302,13 @@ function resolveHashState() {
 export function keychainServiceAlias(item) {
     return prepareServiceName(item);
 }
-function prepareServiceName(item, opts) {
+function prepareServiceName(item) {
     if (rawScopeDepth > 0)
         return item;
     if (!isOurItem(item))
         return item;
     if (item === HMAC_KEY_ITEM || item.startsWith(HASHED_SERVICE_PREFIX))
         return item;
-    if (opts?.autoRekey)
-        maybeAutoRekey();
     const st = resolveHashState();
     if (!st.active || !st.key)
         return item;
@@ -354,7 +329,6 @@ function prepareListPrefix(prefix) {
         return { prefix };
     if (prefix.startsWith(HASHED_SERVICE_PREFIX))
         return { prefix };
-    maybeAutoRekey();
     const st = resolveHashState();
     if (!st.active || !st.key)
         return { prefix };
@@ -429,7 +403,7 @@ function finishPendingDeletes(rec) {
  * Never throws — a failed attempt leaves the process on cleartext names
  * (exact pre-#316 behavior) and the next process retries.
  */
-function maybeAutoRekey() {
+export function maybeAutoRekey() {
     if (autoRekeyAttempted || rekeyRunning || rawScopeDepth > 0)
         return;
     autoRekeyAttempted = true;
@@ -446,10 +420,14 @@ function maybeAutoRekey() {
         return;
     const st = resolveHashState();
     if (st.active) {
-        // The stale-ACL'd-hmackey heal now runs on the hot read path
-        // (readHmacKeyRecord), which the resolveHashState() above just went through —
-        // so st.record is already healed here regardless of how this machine reached
-        // "hashing active". Nothing to do but finish any pending deletes.
+        if (st.record && !st.record.healedNoAcl) {
+            try {
+                healHmacKeyNoAclOnce(st.record);
+            }
+            catch {
+                /* the next explicit unlock retries */
+            }
+        }
         if (st.record?.pendingDeletes?.length) {
             try {
                 finishPendingDeletes(st.record);
@@ -820,7 +798,7 @@ export function getKeychainToken(item, context = {}) {
     // Errors keep the requested (human-readable) name; the storage name may be
     // an opaque hash.
     const requested = item;
-    item = prepareServiceName(item, { autoRekey: true });
+    item = prepareServiceName(item);
     if (backend)
         return backend.get(item);
     assertRawKeychainReadAllowed(requested, context);
@@ -848,6 +826,7 @@ export function getKeychainToken(item, context = {}) {
             ...process.env,
             AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
             AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+            AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
         },
         stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -890,7 +869,7 @@ export function getKeychainTokens(items, context = {}) {
     // whether those were cleartext (hashed here) or already-hashed (enumerated).
     const requestedByStorage = new Map();
     const storageItems = items.map((item) => {
-        const storage = prepareServiceName(item, { autoRekey: true });
+        const storage = prepareServiceName(item);
         if (!requestedByStorage.has(storage))
             requestedByStorage.set(storage, item);
         return storage;
@@ -939,6 +918,7 @@ export function getKeychainTokens(items, context = {}) {
             ...process.env,
             AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
             AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
+            AGENTS_KEYCHAIN_SKIP_AUTH_UI: context.silentNoAcl ? '1' : '0',
             // The signed helper's own vocabulary is unchanged (it predates the rename
             // and ships as a separately-versioned binary), so map to its legacy token.
             AGENTS_KEYCHAIN_DEFAULT_POLICY: (context.defaultPolicy ?? 'hold') === 'hold' ? 'daily' : context.defaultPolicy,
@@ -1037,7 +1017,7 @@ export function setKeychainToken(item, value, opts) {
     if (/[\x00=\r\n]/.test(item))
         throw new Error('Secret item name contains invalid characters.');
     const requested = item;
-    item = prepareServiceName(item, { autoRekey: true });
+    item = prepareServiceName(item);
     if (backend) {
         backend.set(item, value, opts);
         return;

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