@phnx-labs/agents-cli 1.20.78 → 1.20.83

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

@@ -206,6 +206,22 @@ type BrokerConnectionHandler = (conn: net.Socket) => void;
  * rotation on broker restart is picked up without rebuilding the handler.
  */
 export declare function makeConnectionHandler(handle: (req: Request) => Response, token: () => string | null): BrokerConnectionHandler;
+/**
+ * Whether a live process still owns the broker pid file.
+ *
+ * A single missed `agentPing` is NOT proof the owner is dead — the broker is
+ * single-threaded, so a big `get` or the rehydrate at startup can blow the
+ * 700ms ping budget while the process is perfectly healthy. Treating that as
+ * death let a starting broker unlink a live socket and rebind, leaving the old
+ * process alive holding every unlocked bundle in RAM that no client could reach
+ * any more (observed live: two brokers, one socket path, two kernel sockets).
+ * The pid file is the second, independent liveness signal that makes the reclaim
+ * safe.
+ */
+/** Drop our ownership record, but only if it is still ours — never clobber a
+ *  successor that already claimed the socket. */
+export declare function releaseBrokerPid(): void;
+export declare function brokerPidAlive(): boolean;
 /**
  * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
  * `agents secrets _agent-run`. Holds the store in memory, serves the socket,

package/dist/lib/secrets/agent.js

@@ -30,7 +30,7 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import { spawn, spawnSync, execFileSync } from 'child_process';
 import { getHelpersDir, readMeta } from '../state.js';
-import { isAlive } from '../platform/process.js';
+import { isAlive, waitForExit } from '../platform/process.js';
 import { getKeychainHelperPath } from './install-helper.js';
 import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { getCliLaunch } from '../cli-entry.js';
@@ -65,6 +65,19 @@ export const META_CACHE_PREFIX = '!meta:';
 const IDLE_EXIT_MS = 5 * 60 * 1000; // 5m
 /** How often the broker sweeps expired entries. */
 const SWEEP_INTERVAL_MS = 30 * 1000;
+/** How many times a starting broker probes an in-use socket before treating its
+ * owner as gone. One probe is not enough: the broker is single-threaded, so a
+ * large read or the startup rehydrate can outlast a single ping budget while the
+ * process is healthy. */
+const BIND_PROBE_ATTEMPTS = 3;
+/** How long a broker teardown waits for the old process to actually exit before
+ * clearing its socket + ownership record. */
+const BROKER_STOP_GRACE_MS = 3000;
+/** Pause between those probes. */
+const BIND_PROBE_INTERVAL_MS = 250;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 /**
  * Timeouts for the three synchronous broker clients, split across the process
  * boundary they now straddle.
@@ -170,6 +183,20 @@ function pidPath() {
 function tokenPath() {
     return path.join(agentDir(), 'agent.token');
 }
+/**
+ * Path of the CURRENT SOCKET OWNER's pid.
+ *
+ * Deliberately NOT `agent.pid`: that file is the standalone service's O_EXCL
+ * single-instance claim, and a standalone that loses the socket race stays alive
+ * and quiescent while holding it (so launchd's KeepAlive doesn't restart-loop
+ * it), ready to take over if the hosted broker stops. Overloading it as the
+ * socket-ownership record made the standalone see a live holder and exit
+ * immediately — the exact restart loop that guard exists to prevent. This file
+ * answers a different question: which pid is serving the socket right now.
+ */
+function ownerPath() {
+    return path.join(agentDir(), 'agent.owner');
+}
 /**
  * Read the current broker capability token, or null if none is present. Clients
  * read it fresh per request and attach it to every non-ping command; a broker
@@ -425,11 +452,45 @@ export function makeConnectionHandler(handle, token) {
         conn.on('error', () => { });
     };
 }
+/**
+ * Whether a live process still owns the broker pid file.
+ *
+ * A single missed `agentPing` is NOT proof the owner is dead — the broker is
+ * single-threaded, so a big `get` or the rehydrate at startup can blow the
+ * 700ms ping budget while the process is perfectly healthy. Treating that as
+ * death let a starting broker unlink a live socket and rebind, leaving the old
+ * process alive holding every unlocked bundle in RAM that no client could reach
+ * any more (observed live: two brokers, one socket path, two kernel sockets).
+ * The pid file is the second, independent liveness signal that makes the reclaim
+ * safe.
+ */
+/** Drop our ownership record, but only if it is still ours — never clobber a
+ *  successor that already claimed the socket. */
+export function releaseBrokerPid() {
+    try {
+        if (parseInt(fs.readFileSync(ownerPath(), 'utf-8').trim(), 10) === process.pid) {
+            fs.unlinkSync(ownerPath());
+        }
+    }
+    catch { /* absent or unreadable — nothing to release */ }
+}
+export function brokerPidAlive() {
+    try {
+        const holder = parseInt(fs.readFileSync(ownerPath(), 'utf-8').trim(), 10);
+        return !isNaN(holder) && holder !== process.pid && isAlive(holder);
+    }
+    catch {
+        return false; // no pid file → nothing claims ownership
+    }
+}
 /**
  * Bind the shared broker socket without stealing it from another live owner.
  * Both the standalone service and daemon-hosted broker use this single path so
  * either startup order is safe: a reachable owner wins, while an unreachable
  * stale socket is reclaimed once.
+ *
+ * "Unreachable" is established with retries plus a pid-file liveness check, never
+ * a single ping — see {@link brokerPidAlive}.
  */
 async function bindBrokerSocket(sock, onConnection) {
     const listenOnce = () => new Promise((resolve, reject) => {
@@ -453,14 +514,38 @@ async function bindBrokerSocket(sock, onConnection) {
                 writeAgentToken();
             }
             catch { /* dir 0700 gates the socket regardless */ }
+            // Record ownership at the same moment, for the same reason. The
+            // daemon-hosted broker deliberately skips the O_EXCL pid-file GUARD (the
+            // daemon owns its instance), but without an ownership RECORD
+            // brokerPidAlive() has nothing to read — so a later starter saw an
+            // ownerless socket and reclaimed the live hosted broker anyway, which is
+            // the primary configuration and the one that actually orphaned here.
+            // Writing it from the confirmed owner covers both broker flavours.
+            try {
+                fs.writeFileSync(ownerPath(), String(process.pid));
+            }
+            catch { /* dir 0700 gates it */ }
             resolve(server);
         });
     });
     let bound = await listenOnce();
     if (bound !== 'inuse')
         return bound;
-    if ((await agentPing()).reachable)
-        return null;
+    // Give a busy owner several chances before concluding it is gone. One slow
+    // ping used to be enough to evict a healthy broker and orphan its RAM.
+    for (let attempt = 0; attempt < BIND_PROBE_ATTEMPTS; attempt++) {
+        if ((await agentPing()).reachable)
+            return null;
+        if (attempt < BIND_PROBE_ATTEMPTS - 1)
+            await delay(BIND_PROBE_INTERVAL_MS);
+    }
+    // Silent but alive is still alive: refuse to steal the socket from a process
+    // that still owns the pid file, and let the caller surface the wedge instead
+    // of quietly starting a second broker on the same path.
+    if (brokerPidAlive()) {
+        throw new Error(`Secrets broker socket is held by a live process that is not answering: ${sock}. ` +
+            `Run 'agents secrets lock --all' then retry, or stop the stuck broker.`);
+    }
     try {
         fs.unlinkSync(sock);
     }
@@ -637,6 +722,7 @@ export async function runSecretsAgent(opts = {}) {
             fs.unlinkSync(sock);
         }
         catch { /* gone */ }
+        releaseBrokerPid();
         releasePid();
     };
     sweepTimer = setInterval(sweep, SWEEP_INTERVAL_MS);
@@ -746,6 +832,7 @@ export async function startHostedBroker() {
                 fs.unlinkSync(sock);
             }
             catch { /* gone */ }
+            releaseBrokerPid();
         },
     };
 }
@@ -1248,6 +1335,12 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             process.kill(stalePid, 'SIGTERM');
         }
         catch { /* already dead */ }
+        // Wait for it to actually go before clearing its socket and ownership
+        // record. Unlinking them under a live broker is what leaves an orphan
+        // holding every unlocked bundle in RAM with no way to reach it — and it also
+        // destroys the very record brokerPidAlive() reads, so the successor sees an
+        // ownerless socket and reclaims it regardless.
+        waitForExit(stalePid, BROKER_STOP_GRACE_MS);
     }
     try {
         fs.unlinkSync(socketPath());
@@ -1257,6 +1350,10 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
         fs.unlinkSync(pidPath());
     }
     catch { /* gone */ }
+    try {
+        fs.unlinkSync(ownerPath());
+    }
+    catch { /* gone */ }
     const { cmd, args } = brokerSpawn();
     spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
     const deadline = Date.now() + timeoutMs;
@@ -1286,6 +1383,7 @@ async function teardownStaleBroker() {
             process.kill(pid, 'SIGTERM');
         }
         catch { /* gone */ }
+        waitForExit(pid, BROKER_STOP_GRACE_MS); // same reason as ensureAgentRunning
     }
     try {
         fs.unlinkSync(socketPath());
@@ -1295,4 +1393,8 @@ async function teardownStaleBroker() {
         fs.unlinkSync(pidPath());
     }
     catch { /* gone */ }
+    try {
+        fs.unlinkSync(ownerPath());
+    }
+    catch { /* gone */ }
 }

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

@@ -0,0 +1,46 @@
+export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked';
+export interface SecretAuditParams {
+    /** Which audit event this is — a read (`secrets.get`) or an unlock grant. */
+    event: SecretAuditEvent;
+    /** Bundle name (never a value). */
+    bundle?: string;
+    /** Raw keychain item/service name for `secrets get <item>` (never a value). */
+    item?: string;
+    /** Free-form operation/caller label, e.g. 'export to shell', 'unlock'. */
+    operation?: string;
+    /**
+     * Where the read/grant originated: agent | session | reveal | raw-item |
+     * remote | sync-push | broker | broker+durable.
+     */
+    source?: string;
+    status?: 'success' | 'error';
+    /** Env/key NAMES exposed — names only, never values. */
+    keys?: string[];
+    keyCount?: number;
+    /** Subset of `keys` backed by the OS keychain — names only. */
+    keychainKeys?: string[];
+    /** Count of resolved values by kind (literal / keychain / env / ...). */
+    kindCounts?: Record<string, number>;
+    /**
+     * Resolving agent/harness identity the access was scoped to (`*` = a global
+     * grant readable by every harness). Falls back to `$AGENTS_AGENT_NAME`.
+     */
+    agent?: string;
+    /** Remote host the value was pulled from, when applicable. */
+    host?: string;
+    /** Grant lifetime in ms (`secrets.unlocked` only). */
+    ttlMs?: number;
+    error?: string;
+}
+/**
+ * The agent/harness identity to attribute a secret access to. Explicit callers
+ * (the bundle reader knows the scope it resolved under) win; otherwise fall back
+ * to the ambient `$AGENTS_AGENT_NAME` set on every agent launch.
+ */
+export declare function resolveAuditAgent(explicit?: string): string | undefined;
+/**
+ * Emit one value-free secret audit event to the raw/operational event stream and
+ * the persisted audit log. Only ever pass metadata — the secret value must never
+ * reach this function.
+ */
+export declare function emitSecretAudit(p: SecretAuditParams): void;

package/dist/lib/secrets/audit.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical audit emitter for `agents secrets` value access and unlock grants.
+ *
+ * Every path that reads a secret VALUE or grants an unlock 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, 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 payload; this
+ * helper only ever receives metadata, and `emit()`'s `sanitizePayload` is a
+ * second redaction layer.
+ *
+ * Two event types, both audit-level and non-milestone (so they surface in
+ * `agents events` and the persisted audit trail, but are NOT required in the
+ * curated `agents activity` / `agents feed` surfaces):
+ *  - `secrets.get`      — a value was READ (exec inject, export, `view --reveal`,
+ *                         raw `get <item>`, remote resolve, sync push,
+ *                         `run --secrets`, and every other bundle read).
+ *  - `secrets.unlocked` — a bundle was GRANTED into the secrets broker / durable
+ *                         session by `agents secrets unlock`, then readable
+ *                         prompt-free for the grant TTL.
+ */
+import { emit } from '../events.js';
+/**
+ * The agent/harness identity to attribute a secret access to. Explicit callers
+ * (the bundle reader knows the scope it resolved under) win; otherwise fall back
+ * to the ambient `$AGENTS_AGENT_NAME` set on every agent launch.
+ */
+export function resolveAuditAgent(explicit) {
+    const a = explicit || process.env.AGENTS_AGENT_NAME;
+    return a && a.length > 0 ? a : undefined;
+}
+/**
+ * Emit one value-free secret audit event to the raw/operational event stream and
+ * the persisted audit log. Only ever pass metadata — the secret value must never
+ * reach this function.
+ */
+export function emitSecretAudit(p) {
+    const agent = resolveAuditAgent(p.agent);
+    emit(p.event, {
+        module: 'secrets',
+        ...(p.bundle !== undefined ? { bundle: p.bundle } : {}),
+        ...(p.item !== undefined ? { item: p.item } : {}),
+        ...(p.operation !== undefined ? { operation: p.operation } : {}),
+        ...(p.source !== undefined ? { source: p.source } : {}),
+        ...(p.status !== undefined ? { status: p.status } : {}),
+        ...(p.keys !== undefined ? { keys: p.keys } : {}),
+        ...(p.keyCount !== undefined ? { keyCount: p.keyCount } : {}),
+        ...(p.keychainKeys !== undefined ? { keychainKeys: p.keychainKeys } : {}),
+        ...(p.kindCounts !== undefined ? { kindCounts: p.kindCounts } : {}),
+        ...(agent !== undefined ? { agent } : {}),
+        ...(p.host !== undefined ? { host: p.host } : {}),
+        ...(p.ttlMs !== undefined ? { ttlMs: p.ttlMs } : {}),
+        ...(p.error !== undefined ? { error: p.error } : {}),
+    });
+}

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

@@ -43,7 +43,9 @@ export interface VarMeta {
 }
 /**
  * A bundle's prompt policy — how often macOS asks for Touch ID to read it:
- * - `daily` (default): ask once, then hold it silently for up to ~7 days.
+ * - `hold` (default): ask once, then serve it silently for the configured hold
+ *   duration (`secrets.agent.holdMs`, 7d by default). Named for what it does —
+ *   it was called `daily`, which stated a period it never had.
  *   (Historical name — the window is now a rolling ~1 week, not one calendar day.)
  *   Eligible for the secrets-agent — the first real keychain read auto-loads it
  *   (auto-cache is on by default) so concurrent runs read it silently, or `unlock`
@@ -61,12 +63,12 @@ export interface VarMeta {
  *   it loudly rather than silently downgrading to `always`.
  *
  * The default is configurable via `secrets.policy` in agents.yaml. Stored on disk
- * under the legacy `tier` key (`session` == `daily`, `biometry` == explicit
+ * under the legacy `tier` key (`session` == `hold`, `biometry` == explicit
  * `always`, `none` == `never`, absent == inherit the default) so bundles stay
  * readable across mixed CLI versions on synced machines. The user-facing
- * vocabulary is `policy`/`always`/`daily`/`never`.
+ * vocabulary is `policy`/`always`/`hold`/`never`.
  */
-export type SecretsPolicy = 'always' | 'daily' | 'never';
+export type SecretsPolicy = 'always' | 'hold' | 'never';
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
@@ -74,7 +76,7 @@ export interface SecretsBundle {
     allow_exec?: boolean;
     /** Which store carries this bundle's items. Absent ⇒ `keychain` (the default). */
     backend?: SecretsBackend;
-    /** Prompt policy. Absent ⇒ the configured default (`daily`). Serialized under
+    /** Prompt policy. Absent ⇒ the configured default (`hold`). Serialized under
      * the legacy `tier` key — see SecretsPolicy. */
     policy?: SecretsPolicy;
     /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
@@ -142,9 +144,10 @@ export declare class BundleUndecryptableError extends Error {
 export declare function readBundleIfDecryptable(name: string): SecretsBundle | null;
 export declare function readBundle(name: string): SecretsBundle;
 /** The default prompt policy applied to bundles without an explicit per-bundle
- * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
- * ID per ~7d) unless the user explicitly opts back into prompt-every-time with
- * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
+ * policy. Configurable via `secrets.policy` in agents.yaml; `hold` (one Touch ID
+ * per hold window — `secrets.agent.holdMs`, 7d by default) unless the user
+ * explicitly opts back into prompt-every-time with `always`. Best-effort: an
+ * unreadable config falls back to the `hold` default. */
 export declare function secretsDefaultPolicy(): SecretsPolicy;
 /** The effective prompt policy of a bundle (absent ⇒ the configured default). */
 export declare function bundlePolicy(bundle: SecretsBundle): SecretsPolicy;

package/dist/lib/secrets/bundles.js

@@ -28,6 +28,7 @@ import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainTo
 import { fileStore } from './filestore.js';
 import { getVaultSession, vaultDeleteItem, vaultExists, vaultGetItems, vaultGetItem, vaultHasItem, vaultListItems, vaultSetItems, vaultSetItem, } from './vault.js';
 import { emit } from '../events.js';
+import { emitSecretAudit } from './audit.js';
 import { readMeta, getHelpersDir } from '../state.js';
 import { assertNameActiveInResourceProfile, filterNamesForActiveResourceProfile } from '../resource-profiles.js';
 import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, secretsHoldMs } from './agent.js';
@@ -324,7 +325,7 @@ export function readBundle(name) {
         // Absent ⇒ keychain; only set when non-keychain so a keychain bundle
         // round-trips byte-for-byte.
         backend: backend === 'keychain' ? undefined : backend,
-        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `hold`).
         policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
@@ -343,14 +344,14 @@ export function readBundle(name) {
     return bundle;
 }
 /** Normalize the persisted prompt policy. The on-disk `tier` key uses legacy
- * tokens for cross-version compatibility: `session` ⇒ `daily`, `biometry` ⇒ an
+ * tokens for cross-version compatibility: `session` ⇒ `hold`, `biometry` ⇒ an
  * explicit `always`. An absent token ⇒ undefined, which resolves to the
- * configured default policy (`daily`). Persisting an explicit `always` as the
- * legacy `biometry` token keeps older CLIs correct — they don't know `daily`,
+ * configured default policy (`hold`). Persisting an explicit `always` as the
+ * legacy `biometry` token keeps older CLIs correct — they don't know `hold`,
  * read `biometry` as undefined, and fall back to their own always default. */
 function parsePolicy(raw) {
-    if (raw === 'daily' || raw === 'session')
-        return 'daily';
+    if (raw === 'hold' || raw === 'daily' || raw === 'session')
+        return 'hold';
     if (raw === 'always' || raw === 'biometry')
         return 'always';
     if (raw === 'never' || raw === 'none')
@@ -358,15 +359,16 @@ function parsePolicy(raw) {
     return undefined;
 }
 /** The default prompt policy applied to bundles without an explicit per-bundle
- * policy. Configurable via `secrets.policy` in agents.yaml; `daily` (one Touch
- * ID per ~7d) unless the user explicitly opts back into prompt-every-time with
- * `always`. Best-effort: an unreadable config falls back to the `daily` default. */
+ * policy. Configurable via `secrets.policy` in agents.yaml; `hold` (one Touch ID
+ * per hold window — `secrets.agent.holdMs`, 7d by default) unless the user
+ * explicitly opts back into prompt-every-time with `always`. Best-effort: an
+ * unreadable config falls back to the `hold` default. */
 export function secretsDefaultPolicy() {
     try {
-        return readMeta().secrets?.policy === 'always' ? 'always' : 'daily';
+        return readMeta().secrets?.policy === 'always' ? 'always' : 'hold';
     }
     catch {
-        return 'daily';
+        return 'hold';
     }
 }
 /** The effective prompt policy of a bundle (absent ⇒ the configured default). */
@@ -434,12 +436,12 @@ function prepareBundleWrite(bundle) {
         allow_exec: bundle.allow_exec ? true : undefined,
         backend: backend === 'keychain' ? undefined : backend,
         // Wire format: persist the policy under the legacy `tier` token so older CLI
-        // versions on other synced machines keep reading it — `daily`⇒`session`,
+        // versions on other synced machines keep reading it — `hold`⇒`session`,
         // explicit `always`⇒`biometry`, `never`⇒`none`. An absent policy omits the
-        // token entirely and resolves to the configured default (`daily`) on read.
+        // token entirely and resolves to the configured default (`hold`) on read.
         // An older CLI that doesn't know `none` reads it as undefined and falls back
         // to its own default — safe, since it also lacks the no-ACL write path.
-        tier: bundle.policy === 'daily' ? 'session'
+        tier: bundle.policy === 'hold' ? 'session'
             : bundle.policy === 'always' ? 'biometry'
                 : bundle.policy === 'never' ? 'none'
                     : undefined,
@@ -546,7 +548,7 @@ function parseBundleMeta(nameHint, json, backend) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'keychain' ? undefined : backend,
-        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `hold`).
         policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
@@ -1111,13 +1113,14 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             // the first cache-populating run.
             const filtered = filterAgentHitBySubsetAndExpiry(hit, opts);
             stampLastUsed(filtered.bundle);
-            emit('secrets.get', {
-                module: 'secrets',
+            emitSecretAudit({
+                event: 'secrets.get',
                 bundle: name,
                 operation: opts.caller,
                 status: 'success',
                 source: 'agent',
                 keyCount: Object.keys(filtered.env).length,
+                agent: harness,
             });
             return filtered;
         }
@@ -1137,13 +1140,14 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             // MADE in (resolved.harness), never the asking scope — re-warming a global
             // grant as `claude` would silently narrow it for every other harness.
             agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), resolved.harness);
-            emit('secrets.get', {
-                module: 'secrets',
+            emitSecretAudit({
+                event: 'secrets.get',
                 bundle: name,
                 operation: opts.caller,
                 status: 'success',
                 source: 'session',
                 keyCount: Object.keys(filtered.env).length,
+                agent: harness,
             });
             return filtered;
         }
@@ -1198,6 +1202,9 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         ? getKeychainTokens([...new Set([metaItem, ...secretItems])], {
             agent: opts.agent || process.env.AGENTS_AGENT_NAME || 'Agents CLI',
             bundle: name,
+            // The session that triggered the read, so a Touch ID prompt is
+            // attributable when several agents run at once. Exported by exec.ts.
+            sessionId: process.env.AGENT_SESSION_ID || process.env.AGENTS_SESSION_ID,
             reason: opts.caller ? `to ${opts.caller}` : reason,
             duration: opts.duration || humanUnlockDuration(secretsHoldMs()),
             defaultPolicy: secretsDefaultPolicy(),
@@ -1233,7 +1240,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'keychain' ? undefined : backend,
-        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `hold`).
         policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
@@ -1269,8 +1276,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     const keys = [...selectedKeys].sort();
     keychainKeys.sort();
     const emitReadAudit = (status, err) => {
-        emit('secrets.get', {
-            module: 'secrets',
+        emitSecretAudit({
+            event: 'secrets.get',
             bundle: bundle.name,
             operation: opts.caller,
             status,
@@ -1278,6 +1285,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             keys,
             keychainKeys,
             kindCounts,
+            agent: opts.agent,
             error: err instanceof Error ? err.message : (err ? String(err) : undefined),
         });
     };
@@ -1328,7 +1336,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         if (backend === 'keychain' &&
             !opts.noAgent &&
             process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
-            bundlePolicy(bundle) === 'daily' &&
+            bundlePolicy(bundle) === 'hold' &&
             secretsAgentAutoEnabled() &&
             canCacheResolvedEnv(bundle, selectedKeys, opts.keyMode)) {
             agentAutoLoadSync(name, bundle, env, secretsHoldMs(), opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS);

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

@@ -213,9 +213,10 @@ export declare function hasKeychainToken(item: string): boolean;
 export interface KeychainReadContext {
     agent?: string;
     bundle?: string;
+    sessionId?: string;
     reason?: string;
     duration?: string;
-    defaultPolicy?: 'daily' | 'always' | 'never';
+    defaultPolicy?: 'hold' | 'always' | 'never';
     forceDuration?: boolean;
 }
 export declare function keychainOperationPrompt(context?: KeychainReadContext): string;

package/dist/lib/secrets/index.js

@@ -30,6 +30,7 @@ import * as path from 'path';
 import { linuxBackend, usesFileFallback as linuxUsesFileFallback, importNativeSecretToolItems } from './linux.js';
 import { windowsBackend, usesFileFallback as windowsUsesFileFallback, importNativeCredManItems } from './windows.js';
 import { getKeychainHelperPath } from './install-helper.js';
+import { deriveShortId } from '../session/short-id.js';
 const SERVICE_PREFIX = 'agents-cli';
 export const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
 const BUNDLES_ITEM_PREFIX = `${SERVICE_PREFIX}.bundles.`;
@@ -710,9 +711,12 @@ export function hasKeychainToken(item) {
 export function keychainOperationPrompt(context = {}) {
     const agent = context.agent || 'Agents CLI';
     const bundle = context.bundle ? ` the '${context.bundle}' bundle` : ' secrets';
+    // Which session triggered the read — the short-id disambiguates an unexpected
+    // prompt when several agents run at once (interactive + headless + exec).
+    const session = context.sessionId ? ` (session ${deriveShortId(context.sessionId)})` : '';
     const duration = context.duration ? ` for ${context.duration}` : '';
     const reason = context.reason ? ` ${context.reason}` : '';
-    return `${agent} is requesting to unlock${bundle}${duration}${reason}.`;
+    return `${agent} is requesting to unlock${bundle}${session}${duration}${reason}.`;
 }
 export function getKeychainToken(item, context = {}) {
     // Errors keep the requested (human-readable) name; the storage name may be
@@ -820,7 +824,9 @@ export function getKeychainTokens(items, context = {}) {
             ...process.env,
             AGENTS_KEYCHAIN_PROMPT: keychainOperationPrompt(context),
             AGENTS_KEYCHAIN_PROMPT_BASE: keychainOperationPrompt({ ...context, duration: undefined }),
-            AGENTS_KEYCHAIN_DEFAULT_POLICY: context.defaultPolicy || 'daily',
+            // 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,
             AGENTS_KEYCHAIN_FORCE_DURATION: context.forceDuration ? '1' : '0',
         },
         stdio: ['ignore', 'pipe', 'pipe'],