@phnx-labs/agents-cli 1.22.26 → 1.22.28

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

@@ -26,6 +26,7 @@
 import * as net from 'net';
 import type { SecretsBundle } from './bundles.js';
 import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
+import { type SecretLease } from './lease.js';
 export { GLOBAL_HARNESS, bundleScopeChain };
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export declare const DEFAULT_TTL_MS: number;
@@ -72,6 +73,7 @@ export interface StoredBundle {
     /** epoch ms; the entry is gone once Date.now() passes this. */
     expiresAt: number;
     harness: string;
+    lease?: SecretLease;
 }
 /** One unlocked bundle as reported by `status`. */
 export interface AgentStatusEntry {
@@ -79,6 +81,8 @@ export interface AgentStatusEntry {
     expiresAt: number;
     keyCount: number;
     harness: string;
+    leaseId?: string;
+    keys?: string[];
 }
 /**
  * Read the current broker capability token, or null if none is present. Clients
@@ -119,11 +123,16 @@ export type Request = {
     bundle: SecretsBundle;
     env: Record<string, string>;
     ttlMs: number;
+    lease?: SecretLease;
     token?: string;
 } | {
     cmd: 'lock';
     name?: string;
     token?: string;
+} | {
+    cmd: 'revoke';
+    leaseId: string;
+    token?: string;
 } | {
     cmd: 'status';
     token?: string;
@@ -143,6 +152,7 @@ export type Response = {
     hit: true;
     bundle: SecretsBundle;
     env: Record<string, string>;
+    lease?: SecretLease;
 } | {
     ok: true;
     cmd: 'load';
@@ -150,6 +160,10 @@ export type Response = {
     ok: true;
     cmd: 'lock';
     wiped: number;
+} | {
+    ok: true;
+    cmd: 'revoke';
+    wiped: number;
 } | {
     ok: true;
     cmd: 'status';
@@ -237,7 +251,7 @@ export declare function runSecretsAgent(opts?: {
  *
  * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
  * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
- * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ * keeps working through the versioned protocol — but it is daemon-safe:
  *
  *   - no pid-file single-instance guard (the daemon owns the instance);
  *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
@@ -296,6 +310,7 @@ export declare function syncClientLaunch(sub: string[], agentsBin?: string): {
 export declare function agentGetSync(name: string, harness?: string): {
     bundle: SecretsBundle;
     env: Record<string, string>;
+    lease?: SecretLease;
 } | null;
 /**
  * Last non-empty line of a child's stdout — the payload line.
@@ -410,7 +425,7 @@ export declare function clampHoldMs(v: unknown): number;
  * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
  * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
-export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string): void;
+export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string, lease?: SecretLease): void;
 /**
  * Body of the hidden `secrets _agent-load` worker. Reads one `{name, bundle,
  * env, ttlMs}` payload from stdin, ensures the broker is up (robust, generous
@@ -425,10 +440,11 @@ export declare function agentAutoLoadSync(name: string, bundle: SecretsBundle, e
  */
 export declare function runAgentLoadFromStdin(): Promise<void>;
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
-export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string): Promise<boolean>;
+export declare function agentLoad(name: string, bundle: SecretsBundle, env: Record<string, string>, ttlMs: number, harness?: string, lease?: SecretLease): Promise<boolean>;
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count
  * wiped, or 0 when no broker is running. */
 export declare function agentLock(name?: string): Promise<number>;
+export declare function agentRevoke(leaseId: string): Promise<number>;
 /** List currently-unlocked bundles, or [] when no broker is running. The
  * internal `secrets list` metadata-cache entry is filtered out here as well as
  * server-side: during a rollout a NEW client can talk to an OLD broker that

package/dist/lib/secrets/agent.js

@@ -35,8 +35,11 @@ import { getKeychainHelperPath } from './install-helper.js';
 import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { getCliLaunch } from '../cli-entry.js';
 import { GLOBAL_HARNESS, bundleScopeChain } from './scope.js';
-import { rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
+import { deleteLeaseSession, rehydrateSessions, pruneSessionsOnSleep } from './session-store.js';
 import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
+import { MAX_LEASE_MS, MIN_LEASE_MS } from './lease.js';
+import { selectLeasedEnv } from './lease.js';
+import { emitSecretAudit } from './audit.js';
 // Re-exported so callers already reaching for agent.js keep one obvious home for
 // the scope vocabulary; the definitions live in the leaf module scope.ts because
 // agent.ts and session-store.ts import each other and a cyclic `const` read can
@@ -44,7 +47,7 @@ import { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 export { GLOBAL_HARNESS, bundleScopeChain };
 /** Bumped when the wire protocol changes; a client that pings a mismatched
  * server kills and respawns it rather than talking a stale dialect. */
-const PROTOCOL_VERSION = 2;
+const PROTOCOL_VERSION = 3;
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7d
 /**
@@ -153,7 +156,7 @@ function rehydrateStore(now = Date.now()) {
     const store = new Map();
     for (const { name, entry } of rehydrateSessions(now)) {
         const harness = entry.harness || GLOBAL_HARNESS;
-        store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness });
+        store.set(scopedBundleKey(name, harness), { bundle: entry.bundle, env: entry.env, expiresAt: entry.expiresAt, harness, lease: entry.lease });
     }
     return store;
 }
@@ -351,16 +354,30 @@ export function handleAgentRequest(store, req, now = Date.now()) {
                     continue;
                 if (now >= e.expiresAt) {
                     store.delete(key);
+                    if (e.lease) {
+                        deleteLeaseSession(e.lease.id);
+                        emitSecretAudit({ event: 'secrets.lease-expire', bundle: e.bundle.name, operation: 'lease-expire', source: 'broker', status: 'success', keys: e.lease.keys, keyCount: e.lease.keys.length, agent: e.lease.harness });
+                    }
                     continue;
-                } // drop expired on read
-                return { ok: true, cmd: 'get', hit: true, bundle: e.bundle, env: e.env };
+                }
+                return { ok: true, cmd: 'get', hit: true, bundle: e.bundle, env: e.env, lease: e.lease };
             }
             return { ok: true, cmd: 'get', hit: false };
         }
-        case 'load':
+        case 'load': {
             const harness = req.harness || GLOBAL_HARNESS;
-            store.set(scopedBundleKey(req.name, harness), { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs, harness });
+            let env = req.env;
+            if (req.lease) {
+                try {
+                    env = selectLeasedEnv(req.lease, req.env, now);
+                }
+                catch (err) {
+                    return { ok: false, error: err.message };
+                }
+            }
+            store.set(scopedBundleKey(req.name, harness), { bundle: req.bundle, env, expiresAt: req.lease?.expiresAt ?? now + req.ttlMs, harness, lease: req.lease });
             return { ok: true, cmd: 'load' };
+        }
         case 'lock': {
             if (req.name) {
                 let wiped = 0;
@@ -373,6 +390,13 @@ export function handleAgentRequest(store, req, now = Date.now()) {
             store.clear();
             return { ok: true, cmd: 'lock', wiped };
         }
+        case 'revoke': {
+            let wiped = 0;
+            for (const [key, entry] of store)
+                if (entry.lease?.id === req.leaseId && store.delete(key))
+                    wiped++;
+            return { ok: true, cmd: 'revoke', wiped };
+        }
         case 'status': {
             const entries = [];
             for (const [name, e] of store) {
@@ -380,7 +404,7 @@ export function handleAgentRequest(store, req, now = Date.now()) {
                     continue;
                 if (e.bundle.name.startsWith(META_CACHE_PREFIX))
                     continue; // internal list cache
-                entries.push({ name: e.bundle.name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length, harness: e.harness });
+                entries.push({ name: e.bundle.name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length, harness: e.harness, leaseId: e.lease?.id, keys: e.lease?.keys });
             }
             return { ok: true, cmd: 'status', entries };
         }
@@ -648,8 +672,13 @@ export async function runSecretsAgent(opts = {}) {
     const sweep = () => {
         const now = Date.now();
         for (const [name, e] of store)
-            if (now >= e.expiresAt)
+            if (now >= e.expiresAt) {
                 store.delete(name);
+                if (e.lease) {
+                    deleteLeaseSession(e.lease.id);
+                    emitSecretAudit({ event: 'secrets.lease-expire', bundle: e.bundle.name, operation: 'lease-expire', source: 'broker', status: 'success', keys: e.lease.keys, keyCount: e.lease.keys.length, agent: e.lease.harness });
+                }
+            }
         const live = realBundleCount(store);
         // Self-heal onto a newer in-place install — but ONLY while no real unlocks
         // are held, so we never wipe live unlocks and force a re-prompt (#435). A
@@ -766,7 +795,7 @@ export async function runSecretsAgent(opts = {}) {
  *
  * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
  * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
- * keeps working unchanged, no PROTOCOL_VERSION bump — but it is daemon-safe:
+ * keeps working through the versioned protocol — but it is daemon-safe:
  *
  *   - no pid-file single-instance guard (the daemon owns the instance);
  *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
@@ -795,9 +824,15 @@ export async function startHostedBroker() {
     // whole daemon down with it.
     const sweepTimer = setInterval(() => {
         const now = Date.now();
-        for (const [name, e] of store)
-            if (now >= e.expiresAt)
-                store.delete(name);
+        for (const [name, e] of store) {
+            if (now < e.expiresAt)
+                continue;
+            store.delete(name);
+            if (e.lease) {
+                deleteLeaseSession(e.lease.id);
+                emitSecretAudit({ event: 'secrets.lease-expire', bundle: e.bundle.name, operation: 'lease-expire', source: 'broker', status: 'success', keys: e.lease.keys, keyCount: e.lease.keys.length, agent: e.lease.harness });
+            }
+        }
     }, SWEEP_INTERVAL_MS);
     // Auto-lock on sleep, same as the standalone broker: the signed helper emits
     // LOCK/SLEEP lines; wipe the in-memory store on a wipe-worthy event.
@@ -943,7 +978,7 @@ export function agentGetSync(name, harness = GLOBAL_HARNESS) {
         const o = JSON.parse(lastLine(r.stdout));
         if (!o || typeof o !== 'object' || !o.env)
             return null;
-        return { bundle: o.bundle, env: o.env };
+        return { bundle: o.bundle, env: o.env, lease: o.lease };
     }
     catch {
         return null;
@@ -1025,7 +1060,7 @@ export async function runAgentGetSync(name, harness = GLOBAL_HARNESS) {
         // truncated on exit — the parent would see a partial or empty payload, treat
         // it as a miss, and fall through to a keychain read, silently costing the
         // Touch ID prompt this whole path exists to avoid.
-        const payload = JSON.stringify({ bundle: r.bundle, env: r.env }) + '\n';
+        const payload = JSON.stringify({ bundle: r.bundle, env: r.env, lease: r.lease }) + '\n';
         await new Promise((resolve) => { process.stdout.write(payload, () => resolve()); });
         return 0;
     }
@@ -1120,8 +1155,8 @@ export function secretsAgentDurable() {
 /** Minimum / maximum bounds for the configurable hold window. A too-small value
  * would defeat the broker (constant re-prompts); a too-large one pins secrets in
  * memory far longer than intended. */
-export const MIN_HOLD_MS = 60 * 1000; // 1m
-export const MAX_HOLD_MS = 30 * 24 * 60 * 60 * 1000; // 30d
+export const MIN_HOLD_MS = MIN_LEASE_MS;
+export const MAX_HOLD_MS = MAX_LEASE_MS;
 /**
  * How long an unlocked / auto-cached bundle is held before the next read
  * re-prompts. Defaults to DEFAULT_TTL_MS (7d); override with
@@ -1165,10 +1200,10 @@ export function clampHoldMs(v) {
  * The worker reuses the robust `ensureAgentRunning` path (spawn-then-ping) rather
  * than a tight inline retry loop. Best-effort; never throws. macOS only.
  */
-export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS) {
+export function agentAutoLoadSync(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease) {
     if (!onDarwin())
         return;
-    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness });
+    const payload = JSON.stringify({ name, bundle, env, ttlMs, harness, lease });
     // Broker actually LISTENING → deterministic synchronous warm (bounded; the read
     // already paid a Touch ID, so <1s here is invisible). We gate on a real liveness
     // ping, NOT mere socket-file existence: a broker that died leaving its socket
@@ -1235,13 +1270,13 @@ export async function runAgentLoadFromStdin() {
         process.exitCode = 1; // broker couldn't be brought up — did NOT load
         return;
     }
-    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS, payload.harness ?? GLOBAL_HARNESS);
+    const loaded = await agentLoad(payload.name, payload.bundle, payload.env, payload.ttlMs ?? DEFAULT_TTL_MS, payload.harness ?? GLOBAL_HARNESS, payload.lease);
     if (!loaded)
         process.exitCode = 1; // transport failed — did NOT load
 }
 /** Store a resolved bundle in the broker. Returns false on transport failure. */
-export async function agentLoad(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS) {
-    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness });
+export async function agentLoad(name, bundle, env, ttlMs, harness = GLOBAL_HARNESS, lease) {
+    const r = await request({ cmd: 'load', name, bundle, env, ttlMs, harness, lease });
     return r?.ok === true && r.cmd === 'load';
 }
 /** Wipe one bundle (or all if name omitted) from the broker. Returns the count
@@ -1250,6 +1285,10 @@ export async function agentLock(name) {
     const r = await request({ cmd: 'lock', name });
     return r?.ok === true && r.cmd === 'lock' ? r.wiped : 0;
 }
+export async function agentRevoke(leaseId) {
+    const r = await request({ cmd: 'revoke', leaseId });
+    return r?.ok === true && r.cmd === 'revoke' ? r.wiped : 0;
+}
 /** List currently-unlocked bundles, or [] when no broker is running. The
  * internal `secrets list` metadata-cache entry is filtered out here as well as
  * server-side: during a rollout a NEW client can talk to an OLD broker that

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

@@ -1,4 +1,4 @@
-export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view';
+export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.lease-denied' | 'secrets.lease-expire';
 export interface SecretAuditParams {
     /** Which audit event this is — a read (`secrets.get`) or an unlock grant. */
     event: SecretAuditEvent;

package/dist/lib/secrets/audit.js

@@ -46,6 +46,8 @@ const USAGE_KIND = {
     'secrets.import': 'import',
     'secrets.export': 'export',
     'secrets.view': 'view',
+    'secrets.lease-denied': 'access',
+    'secrets.lease-expire': 'access',
 };
 /**
  * The agent/harness identity to attribute a secret access to. Explicit callers

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

@@ -264,9 +264,9 @@ export interface ResolveBundleOptions {
 export declare function canCacheResolvedEnv(bundle: SecretsBundle, selectedKeys: Set<string>, keyMode: ResolveBundleOptions['keyMode']): boolean;
 /**
  * Apply the --keys subset + expiry gate to an already-resolved snapshot from
- * the secrets-agent fast-path. The agent stores the FULL bundle env, so a
- * naive fast-path return would silently defeat --keys and inject expired
- * values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
+ * the secrets-agent fast-path. The agent stores either a full unlock or a
+ * scoped lease env, so a naive fast-path return could silently defeat --keys
+ * and inject expired values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
  * `readAndResolveBundleEnv` and returns a new env whose keys match the subset.
  *
  * Exported for tests; production callers reach it via the fast-path branch in

package/dist/lib/secrets/bundles.js

@@ -1033,9 +1033,9 @@ export function canCacheResolvedEnv(bundle, selectedKeys, keyMode) {
 }
 /**
  * Apply the --keys subset + expiry gate to an already-resolved snapshot from
- * the secrets-agent fast-path. The agent stores the FULL bundle env, so a
- * naive fast-path return would silently defeat --keys and inject expired
- * values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
+ * the secrets-agent fast-path. The agent stores either a full unlock or a
+ * scoped lease env, so a naive fast-path return could silently defeat --keys
+ * and inject expired values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
  * `readAndResolveBundleEnv` and returns a new env whose keys match the subset.
  *
  * Exported for tests; production callers reach it via the fast-path branch in
@@ -1230,7 +1230,12 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         const harness = opts.agent || process.env.AGENTS_AGENT_NAME || GLOBAL_HARNESS;
         const hit = agentGetSync(name, harness);
         if (hit) {
-            // The agent stores the FULL bundle env. Apply the same subset filter and
+            const denied = (opts.keys ?? []).filter((key) => hit.lease && !hit.lease.keys.includes(key));
+            if (denied.length > 0) {
+                emitSecretAudit({ event: 'secrets.lease-denied', bundle: name, operation: opts.caller, source: 'agent', status: 'error', keys: denied, keyCount: denied.length, agent: harness, error: 'key outside lease scope' });
+                throw new Error(`Secret lease '${hit.lease?.id}' does not grant key(s): ${denied.join(', ')}`);
+            }
+            // The agent stores a full unlock or a scoped lease env. Apply the same subset filter and
             // expiry gate as the slow path — without this, `--secrets-keys X` would
             // silently inject every key and an expired key would flow through after
             // the first cache-populating run.
@@ -1256,13 +1261,18 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         const resolved = resolveSession(name, Date.now(), harness);
         if (resolved) {
             const session = resolved.entry;
+            const denied = (opts.keys ?? []).filter((key) => session.lease && !session.lease.keys.includes(key));
+            if (denied.length > 0) {
+                emitSecretAudit({ event: 'secrets.lease-denied', bundle: name, operation: opts.caller, source: 'session', status: 'error', keys: denied, keyCount: denied.length, agent: harness, error: 'key outside lease scope' });
+                throw new Error(`Secret lease '${session.lease?.id}' does not grant key(s): ${denied.join(', ')}`);
+            }
             const filtered = filterAgentHitBySubsetAndExpiry({ bundle: session.bundle, env: session.env }, opts);
             stampLastUsed(filtered.bundle);
             // Re-warm the broker with the remaining TTL so later reads hit RAM and
             // `agents secrets status` is honest. Re-warm under the scope the grant was
             // 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);
+            agentAutoLoadSync(name, session.bundle, session.env, Math.max(1, session.expiresAt - Date.now()), resolved.harness, session.lease);
             emitSecretAudit({
                 event: 'secrets.get',
                 bundle: name,

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

@@ -51,6 +51,8 @@ export declare function encryptForFallback(plaintext: string, passphrase: string
 /** Decrypt an EncFile under a passphrase. Throws on wrong key or tampered
  *  ciphertext (auth-tag mismatch). Exported for tests. */
 export declare function decryptForFallback(enc: EncFile, passphrase: string): string;
+/** Absolute path of one encrypted file-store item. No read or decrypt occurs. */
+export declare function fileStoreItemPath(item: string): string;
 declare function fileHas(item: string): boolean;
 declare function fileGet(item: string): string;
 declare function fileGetBatch(items: string[]): Map<string, string>;

package/dist/lib/secrets/filestore.js

@@ -214,6 +214,10 @@ export function decryptForFallback(enc, passphrase) {
 function fileFor(item) {
     return path.join(fileDir(), `${item}.enc`);
 }
+/** Absolute path of one encrypted file-store item. No read or decrypt occurs. */
+export function fileStoreItemPath(item) {
+    return fileFor(item);
+}
 function fileHas(item) {
     return fs.existsSync(fileFor(item));
 }

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

@@ -0,0 +1,25 @@
+export declare const MIN_LEASE_MS: number;
+export declare const MAX_LEASE_MS: number;
+export interface SecretLease {
+    id: string;
+    bundle: string;
+    keys: string[];
+    createdAt: number;
+    expiresAt: number;
+    harness: string;
+    sleepPersist: boolean;
+}
+export declare function clampLeaseTtlMs(ttlMs: number): number;
+export declare function normalizeLeaseKeys(keys: readonly string[], availableKeys: readonly string[]): string[];
+export declare function createSecretLease(input: {
+    bundle: string;
+    keys: readonly string[];
+    availableKeys: readonly string[];
+    ttlMs: number;
+    now?: number;
+    id?: string;
+    harness?: string;
+    sleepPersist?: boolean;
+}): SecretLease;
+export declare function leaseIsActive(lease: SecretLease, now?: number): boolean;
+export declare function selectLeasedEnv(lease: SecretLease, env: Record<string, string>, now?: number): Record<string, string>;

package/dist/lib/secrets/lease.js

@@ -0,0 +1,44 @@
+import { randomBytes } from 'crypto';
+import { GLOBAL_HARNESS } from './scope.js';
+export const MIN_LEASE_MS = 60 * 1000;
+export const MAX_LEASE_MS = 30 * 24 * 60 * 60 * 1000;
+export function clampLeaseTtlMs(ttlMs) {
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new Error('Lease duration must be a positive finite number.');
+    }
+    return Math.min(Math.max(Math.floor(ttlMs), MIN_LEASE_MS), MAX_LEASE_MS);
+}
+export function normalizeLeaseKeys(keys, availableKeys) {
+    const requested = [...new Set(keys.map((key) => key.trim()).filter(Boolean))].sort();
+    if (requested.length === 0)
+        throw new Error('A secret lease requires at least one key.');
+    const available = new Set(availableKeys);
+    const missing = requested.filter((key) => !available.has(key));
+    if (missing.length > 0)
+        throw new Error(`Unknown secret lease key(s): ${missing.join(', ')}`);
+    return requested;
+}
+export function createSecretLease(input) {
+    const createdAt = input.now ?? Date.now();
+    const ttlMs = clampLeaseTtlMs(input.ttlMs);
+    return {
+        id: input.id ?? randomBytes(12).toString('hex'),
+        bundle: input.bundle,
+        keys: normalizeLeaseKeys(input.keys, input.availableKeys),
+        createdAt,
+        expiresAt: createdAt + ttlMs,
+        harness: input.harness ?? GLOBAL_HARNESS,
+        sleepPersist: input.sleepPersist ?? false,
+    };
+}
+export function leaseIsActive(lease, now = Date.now()) {
+    return now < lease.expiresAt;
+}
+export function selectLeasedEnv(lease, env, now = Date.now()) {
+    if (!leaseIsActive(lease, now))
+        throw new Error(`Secret lease '${lease.id}' has expired.`);
+    const missing = lease.keys.filter((key) => typeof env[key] !== 'string');
+    if (missing.length > 0)
+        throw new Error(`Secret lease '${lease.id}' is missing value(s): ${missing.join(', ')}`);
+    return Object.fromEntries(lease.keys.map((key) => [key, env[key]]));
+}

package/dist/lib/secrets/session-store.d.ts

@@ -25,6 +25,7 @@
  * persistence is an optimization, not a correctness dependency.
  */
 import type { SecretsBundle } from './bundles.js';
+import type { SecretLease } from './lease.js';
 /** Prefix for all durable session items (device-local, no-ACL). */
 export declare const SESSION_ITEM_PREFIX = "agents-cli.session.";
 /** Fixed-name index item — the ONLY thing we ever need to find without a known
@@ -39,6 +40,7 @@ export interface SessionEntry {
     /** true only for `--durable` unlocks — survives SLEEP. */
     sleepPersist: boolean;
     harness?: string;
+    lease?: SecretLease;
 }
 /** Metadata for one held bundle, kept in the index so we can rehydrate / prune
  * without reading every blob. */
@@ -90,6 +92,11 @@ export declare function loadSession(name: string, now?: number, harness?: string
 export declare function deleteBundleSessions(name: string): void;
 /** Delete one bundle's session blob and prune it from the index. */
 export declare function deleteSession(name: string, harness?: string): void;
+export declare function deleteLeaseSession(leaseId: string): number;
+export declare function activeLeaseSessions(now?: number): Array<{
+    name: string;
+    lease: SecretLease;
+}>;
 /** Delete every session blob + the index (for `secrets lock --all`). */
 export declare function deleteAllSessions(): void;
 /** Rehydrate every unexpired session into `[name, entry]` pairs for the broker to

package/dist/lib/secrets/session-store.js

@@ -192,6 +192,27 @@ export function deleteSession(name, harness = GLOBAL_HARNESS) {
         /* best-effort */
     }
 }
+export function deleteLeaseSession(leaseId) {
+    if (!shouldPersist())
+        return 0;
+    const index = readIndex();
+    let deleted = 0;
+    for (const [key, meta] of Object.entries(index.bundles)) {
+        const bundleName = key.split(':').slice(1).join(':');
+        const harness = meta.harness || GLOBAL_HARNESS;
+        const entry = loadSession(bundleName, Date.now(), harness);
+        if (entry?.lease?.id !== leaseId)
+            continue;
+        deleteSession(bundleName, harness);
+        deleted++;
+    }
+    return deleted;
+}
+export function activeLeaseSessions(now = Date.now()) {
+    return rehydrateSessions(now)
+        .filter((item) => Boolean(item.entry.lease))
+        .map(({ name, entry }) => ({ name, lease: entry.lease }));
+}
 /** Delete every session blob + the index (for `secrets lock --all`). */
 export function deleteAllSessions() {
     if (!shouldPersist())

package/dist/lib/self-update.d.ts

@@ -136,15 +136,30 @@ export declare function verifyInstalledVersion(packageRoot: string, expectedVers
  */
 export declare function refreshAliasShims(packageRoot: string): void;
 export interface AgentsCliInstall {
-    /** The PATH entry (`<dir>/agents`) that resolves to this install. */
-    binPath: string;
+    /** The PATH entry (`<dir>/agents`) that resolves to this install, when found through PATH. */
+    binPath?: string;
     /** Package root containing package.json and dist/. */
     packageRoot: string;
     version: string;
+    /** Whether this copy uses the serialized, atomic helper-bundle installer. */
+    atomicHelperInstall: boolean;
 }
+export interface FindAgentsCliInstallsOptions {
+    homeDir?: string;
+    fnmDir?: string;
+    npmCacheDir?: string;
+    globalNodeModulesDirs?: string[];
+}
+export interface MultiInstallInventoryEntry {
+    packageRoot: string;
+    version: string;
+    note: string;
+}
+export declare function buildMultiInstallInventory(runningRoot: string, runningVersion: string, installs: AgentsCliInstall[]): MultiInstallInventoryEntry[];
 /**
- * Scan PATH for `agents` entrypoints and resolve each to the agents-cli
- * package root it executes. More than one distinct root means upgrades,
+ * Resolve every `agents` entrypoint on PATH, then inspect the bounded global
+ * install layouts used by NVM, fnm, Volta, Bun, npm, and npx. More than one
+ * distinct package root means upgrades,
  * shims, and the command the user types can act on different copies — the
  * divergence behind silently-failing self-updates.
  *
@@ -158,4 +173,4 @@ export interface AgentsCliInstall {
  * @phnx-labs/agents-cli is some other tool and is skipped.
  * POSIX-only: Windows npm bins are .cmd wrappers, not symlinks.
  */
-export declare function findAgentsCliInstalls(pathEnv: string): AgentsCliInstall[];
+export declare function findAgentsCliInstalls(pathEnv: string, opts?: FindAgentsCliInstallsOptions): AgentsCliInstall[];