@phnx-labs/agents-cli 1.22.9 → 1.22.11

package/dist/lib/events.js

@@ -1,7 +1,7 @@
 /**
  * Centralized event logging for agents-cli.
  *
- * Structured JSONL audit log at ~/.agents/events.jsonl with lossless numbered
+ * Structured JSONL audit log at ~/.agents/.history/events/events.jsonl with lossless numbered
  * gzip rotation at 10 MB and rich metadata for debugging/auditing.
  *
  * Features:
@@ -17,7 +17,7 @@ import * as os from 'os';
 import { createHash } from 'node:crypto';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { ensureLockTarget, withFileLock } from './fs-atomic.js';
-import { getUserAgentsDir } from './state.js';
+import { getHistoryDir } from './state.js';
 import { stampProvenance, resetEventProvenanceForTest } from './event-provenance.js';
 /** Lazy perf warehouse write — avoids a hard cycle at module load. */
 function recordPerfTiming(payload) {
@@ -48,7 +48,7 @@ function recordPerfTiming(payload) {
 // a test spawns, so fixture events can never land in the user's real log (#910).
 let _eventsPath;
 function eventsPath() {
-    return (_eventsPath ??= process.env.AGENTS_EVENTS_PATH || path.join(getUserAgentsDir(), 'events.jsonl'));
+    return (_eventsPath ??= process.env.AGENTS_EVENTS_PATH || path.join(getHistoryDir(), 'events', 'events.jsonl'));
 }
 function eventsDir() {
     return path.dirname(eventsPath());

package/dist/lib/feed-broadcast.d.ts

@@ -48,8 +48,14 @@ export interface FeedBroadcastContext {
     class?: string;
     /** Block-only: cost-of-delay tag used by the urgency filter. */
     cost?: string;
-    /** Block-only: the literal `agents focus <id>` command that unblocks it. */
+    /** Block-only: the literal `agents focus <id>` command (for a `{focus}` sink). */
     focus?: string;
+    /** Block-only: the answer choices the operator can pick, in order. */
+    options?: string[];
+    /** Block-only: the fallback applied if nobody answers in time. */
+    safeDefault?: string;
+    /** Block-only: minutes before `safeDefault` applies. */
+    timeoutMinutes?: number;
 }
 /**
  * Map an open block onto the broadcast context, so a block reaches the same sinks
@@ -69,9 +75,14 @@ export declare function blockBroadcastContext(block: {
     host?: string;
     questions?: Array<{
         text?: string;
+        options?: Array<{
+            label?: string;
+        }>;
     }>;
     blockClass?: string;
     costOfDelay?: string;
+    safeDefault?: string;
+    timeoutMinutes?: number;
     ticket?: string;
     pr?: string;
 }, extras?: {
@@ -137,14 +148,17 @@ export declare function composeBroadcastFooter(ctx: FeedBroadcastContext): strin
  * Title in a few words
  *
  * Body of what happened or the ask.
+ * Options: publish / wait          (blocks with choices)
+ * Default in 15 min: wait          (blocks with a safe default)
  *
  * Sent from grok/a02da0e2 on mac-mini
- * agents focus a02da0e2          (blocks only)
- * https://…                      (optional attach URL)
+ * https://…                        (optional attach URL)
  * ```
  *
- * Title first (scannable subject). Blank line. Body. Footer provenance so a
- * fleet of agents is attributable without crowding the ask. Prefer `{message}`
+ * Title first (scannable subject). Blank line. Body. Then the phone-actionable
+ * choices + default (a block that has stopped for the human), then footer
+ * provenance. No `agents focus <id>` line: a CLI command is unusable from a phone,
+ * so the safe default is the fallback and the message carries it. Prefer `{message}`
  * over bare `{text}` in messaging sinks.
  */
 export declare function composeBroadcastMessage(ctx: FeedBroadcastContext): string;

package/dist/lib/feed-broadcast.js

@@ -62,6 +62,12 @@ export function parseFeedPostLevel(raw) {
 export function blockBroadcastContext(block, extras = {}) {
     const ask = block.questions?.[0]?.text?.trim() || 'agent is blocked';
     const links = [block.pr].filter((l) => !!l && /^https?:\/\//i.test(l));
+    // The answer choices + the safe default are what make the phone message
+    // actionable: the operator sees the options and what happens if they do not
+    // reply, instead of a `agents focus <id>` CLI command they cannot run from a phone.
+    const options = (block.questions?.[0]?.options ?? [])
+        .map((o) => o?.label?.trim())
+        .filter((l) => !!l);
     // Prefer explicit title/body from the feed post; fall back to the ask as body.
     const title = extras.title?.trim() || undefined;
     const text = extras.body?.trim() || ask;
@@ -78,8 +84,12 @@ export function blockBroadcastContext(block, extras = {}) {
         class: block.blockClass,
         cost: block.costOfDelay,
         // Short id: `agents focus` matches on a prefix, and a full uuid in a phone
-        // message is noise the operator has to skip past to reach the verb.
+        // message is noise. Kept for a `{focus}` sink; the human message no longer
+        // shows it (a CLI command is unusable from a phone).
         focus: `agents focus ${block.sessionId.slice(0, 8)}`,
+        ...(options.length ? { options } : {}),
+        ...(block.safeDefault ? { safeDefault: block.safeDefault } : {}),
+        ...(block.timeoutMinutes ? { timeoutMinutes: block.timeoutMinutes } : {}),
         ...(links.length ? { links } : {}),
     };
 }
@@ -179,14 +189,17 @@ export function composeBroadcastFooter(ctx) {
  * Title in a few words
  *
  * Body of what happened or the ask.
+ * Options: publish / wait          (blocks with choices)
+ * Default in 15 min: wait          (blocks with a safe default)
  *
  * Sent from grok/a02da0e2 on mac-mini
- * agents focus a02da0e2          (blocks only)
- * https://…                      (optional attach URL)
+ * https://…                        (optional attach URL)
  * ```
  *
- * Title first (scannable subject). Blank line. Body. Footer provenance so a
- * fleet of agents is attributable without crowding the ask. Prefer `{message}`
+ * Title first (scannable subject). Blank line. Body. Then the phone-actionable
+ * choices + default (a block that has stopped for the human), then footer
+ * provenance. No `agents focus <id>` line: a CLI command is unusable from a phone,
+ * so the safe default is the fallback and the message carries it. Prefer `{message}`
  * over bare `{text}` in messaging sinks.
  */
 export function composeBroadcastMessage(ctx) {
@@ -197,9 +210,21 @@ export function composeBroadcastMessage(ctx) {
     const mid = title && body && title !== body ? body : undefined;
     const footer = composeBroadcastFooter(ctx);
     const link = ctx.links?.find((l) => /^https?:\/\//i.test(l));
-    // Block focus and link trail after the "Sent from" footer so the human
-    // sentence stays at the top and the action/link are still one glance away.
-    const trail = [footer, ctx.focus, link].filter(Boolean);
+    // The action block: the one thing the operator can act on from a phone. Show the
+    // choices, then what happens if they do not answer. Deliberately NOT a CLI command
+    // (`agents focus <id>` is unusable from a phone) -- the safe default is the real
+    // fallback, so a block meant for a phone should always carry one.
+    const choices = ctx.options?.length
+        ? `Options: ${ctx.options.map((o) => scrubOutboundDashes(o)).join(' / ')}`
+        : undefined;
+    const fallback = ctx.safeDefault
+        ? (ctx.timeoutMinutes && ctx.timeoutMinutes > 0
+            ? `Default in ${ctx.timeoutMinutes} min: ${scrubOutboundDashes(ctx.safeDefault)}`
+            : `Default: ${scrubOutboundDashes(ctx.safeDefault)}`)
+        : undefined;
+    const action = [choices, fallback].filter(Boolean).join('\n') || undefined;
+    // Link trail after the "Sent from" footer so the human sentence stays at the top.
+    const trail = [footer, link].filter(Boolean);
     const parts = [];
     if (head)
         parts.push(head);
@@ -208,6 +233,12 @@ export function composeBroadcastMessage(ctx) {
         parts.push('');
         parts.push(mid);
     }
+    if (action) {
+        // The choices/default hug the ask under a blank line so they read as the reply.
+        if (parts.length)
+            parts.push('');
+        parts.push(action);
+    }
     if (trail.length) {
         // Blank line before the footer block (iPhone "Sent from my iPhone" spacing).
         if (parts.length)
@@ -233,6 +264,8 @@ function templateVars(ctx) {
         class: ctx.class,
         cost: ctx.cost,
         focus: ctx.focus,
+        options: ctx.options?.length ? ctx.options.join(' / ') : undefined,
+        default: ctx.safeDefault,
     };
 }
 /**

package/dist/lib/migrate.js

@@ -998,6 +998,7 @@ function migrateRuntimeToHistory() {
     moveDirOnce(path.join(USER_DIR, '.backups'), path.join(HISTORY_DIR, 'backups'));
     moveDirOnce(path.join(USER_DIR, 'routines', 'runs'), path.join(HISTORY_DIR, 'runs'));
     moveDirOnce(path.join(USER_DIR, 'teams', 'agents'), path.join(HISTORY_DIR, 'teams', 'agents'));
+    migrateEventLogsToHistory();
     // Drop any empty leftover skeletons created mid-rename (e.g. `versions/<agent>/<v>/home/`
     // recreated by a concurrent process). The real data is already under .history/.
     rmEmptyDirTree(path.join(USER_DIR, 'versions'));
@@ -1013,6 +1014,66 @@ function migrateRuntimeToHistory() {
         catch { /* best-effort */ }
     }
 }
+/** Move the operational event stream out of the git-backed user-repo root. */
+function migrateEventLogsToHistory() {
+    const destination = path.join(HISTORY_DIR, 'events');
+    let files = [];
+    try {
+        files = fs.readdirSync(USER_DIR).filter((file) => file === 'events.jsonl' || /^events\.\d+\.jsonl\.gz$/.test(file));
+    }
+    catch {
+        return;
+    }
+    try {
+        fs.mkdirSync(destination, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        return;
+    }
+    const active = files.find((file) => file === 'events.jsonl');
+    if (active) {
+        const src = path.join(USER_DIR, active);
+        const dest = path.join(destination, active);
+        if (!fs.existsSync(dest)) {
+            moveFileOnce(src, dest);
+        }
+        else {
+            try {
+                const lines = [fs.readFileSync(src, 'utf-8'), fs.readFileSync(dest, 'utf-8')]
+                    .flatMap((content) => content.split('\n').filter(Boolean))
+                    .map((line, index) => {
+                    try {
+                        const timestamp = Date.parse(JSON.parse(line).ts ?? '');
+                        return { line, index, timestamp: Number.isNaN(timestamp) ? Number.MAX_SAFE_INTEGER : timestamp };
+                    }
+                    catch {
+                        return { line, index, timestamp: Number.MAX_SAFE_INTEGER };
+                    }
+                })
+                    .sort((a, b) => a.timestamp - b.timestamp || a.index - b.index)
+                    .map(({ line }) => line);
+                atomicWriteFileSync(dest, `${lines.join('\n')}\n`, { mode: 0o600 });
+                fs.unlinkSync(src);
+            }
+            catch { /* preserve the source for a later retry */ }
+        }
+    }
+    const archives = files
+        .map((file) => ({ file, match: file.match(/^events\.(\d+)\.jsonl\.gz$/) }))
+        .filter((entry) => entry.match !== null)
+        .sort((a, b) => Number(a.match[1]) - Number(b.match[1]));
+    let nextArchive = fs.readdirSync(destination).reduce((max, file) => {
+        const match = file.match(/^events\.(\d+)\.jsonl\.gz$/);
+        return match ? Math.max(max, Number(match[1])) : max;
+    }, 0) + 1;
+    for (const archive of archives) {
+        const preferred = path.join(destination, archive.file);
+        const dest = fs.existsSync(preferred)
+            ? path.join(destination, `events.${nextArchive++}.jsonl.gz`)
+            : preferred;
+        moveFileOnce(path.join(USER_DIR, archive.file), dest);
+    }
+}
 /**
  * Restore plugins from the cache bucket back to the user-root.
  *

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

@@ -1,5 +1,5 @@
 /**
- * Project workspace probing — the drift signal behind `projects status --fleet`.
+ * Project workspace probing — the drift signal behind `projects status`.
  *
  * Projects are natively multi-device: the same definition (home-relative paths)
  * re-roots on every fleet machine, and the question is whether the project's

package/dist/lib/project-probe.js

@@ -1,5 +1,5 @@
 /**
- * Project workspace probing — the drift signal behind `projects status --fleet`.
+ * Project workspace probing — the drift signal behind `projects status`.
  *
  * Projects are natively multi-device: the same definition (home-relative paths)
  * re-roots on every fleet machine, and the question is whether the project's

package/dist/lib/projects.d.ts

@@ -36,7 +36,7 @@ export interface ProjectRepo {
     /**
      * Optional home-relative local checkout of this repo. The def's `root` only
      * knows the primary repo on disk; `path` opts an additional repo into
-     * workspace probing (`projects status --fleet`).
+     * workspace probing (`projects status`).
      */
     path?: string;
 }

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/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/events.jsonl` audit log — carries a uniform,
+ * by the append-only `~/.agents/.history/events/events.jsonl` 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/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;