@phnx-labs/agents-cli 1.20.16 → 1.20.18

package/dist/lib/secrets/agent.js

@@ -0,0 +1,501 @@
+/**
+ * The secrets-agent: a local broker that holds resolved bundle env in memory
+ * after a single Touch ID unlock, so concurrent agent processes don't each pop
+ * their own prompt.
+ *
+ * Why this exists: every secret item carries a biometry access control, and
+ * macOS refuses to cache that across processes — N concurrent `agents run`
+ * spawns = N Touch ID prompts (see src/lib/secrets/bundles.ts). The Swift
+ * helper's LAContext only deduplicates reads *within one process*. This broker
+ * is the ssh-agent answer: `agents secrets unlock <bundle>` decrypts the bundle
+ * once (one prompt), ships the resolved env here, and every later read returns
+ * from memory over a user-only Unix socket — no prompt.
+ *
+ * Security model (deliberate): while a bundle is unlocked, any same-user
+ * process that can reach the socket reads it silently. That's strictly the same
+ * trust boundary the keychain already concedes (docs/secrets.md: the ACL is
+ * user-presence, not code-identity — any same-user process can pop the prompt
+ * and read), minus the visible prompt. We bound it with: explicit per-bundle
+ * opt-in (nothing is held unless you `unlock` it), an absolute TTL, auto-lock
+ * on screen-lock / sleep, and `agents secrets lock`. Nothing ever touches disk.
+ *
+ * macOS only: Linux libsecret has no biometry prompt, so there's nothing to
+ * deduplicate — every entry point here no-ops off darwin.
+ */
+import * as net from 'net';
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn, spawnSync, execFileSync } from 'child_process';
+import { getHelpersDir, readMeta } from '../state.js';
+import { isAlive } from '../platform/process.js';
+import { getKeychainHelperPath } from './install-helper.js';
+/** 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 = 1;
+/** Default lifetime of an unlocked bundle when `--ttl` is not given. */
+export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+/** After the store goes empty (all bundles locked or expired) for this long,
+ * the broker exits so no idle process lingers holding a socket. */
+const IDLE_EXIT_MS = 5 * 60 * 1000; // 5m
+/** How often the broker sweeps expired entries. */
+const SWEEP_INTERVAL_MS = 30 * 1000;
+function onDarwin() {
+    return process.platform === 'darwin';
+}
+/** Broker runtime dir under the regenerable cache, locked to the user (0700).
+ * AGENTS_SECRETS_AGENT_DIR overrides the location — a test seam so the suite can
+ * run a real broker on a temp socket without touching the user's real dir. */
+function agentDir() {
+    const dir = process.env.AGENTS_SECRETS_AGENT_DIR || path.join(getHelpersDir(), 'secrets-agent');
+    fs.mkdirSync(dir, { recursive: true });
+    try {
+        fs.chmodSync(dir, 0o700);
+    }
+    catch { /* best effort */ }
+    return dir;
+}
+function socketPath() {
+    return path.join(agentDir(), 'agent.sock');
+}
+function pidPath() {
+    return path.join(agentDir(), 'agent.pid');
+}
+/**
+ * Argv for re-invoking THIS cli to run the broker, so a side-by-side dev build
+ * spawns its own broker rather than the registry-installed one. We always go
+ * through `process.execPath` (the node binary) with the JS entrypoint as the
+ * first arg — the entrypoint isn't reliably executable in dev builds (invoked
+ * as `node dist/index.js`, no +x), so spawning it directly EACCES'd.
+ */
+function brokerSpawn() {
+    const argv1 = process.argv[1];
+    const entry = argv1 && fs.existsSync(argv1) ? argv1 : null;
+    if (entry)
+        return { cmd: process.execPath, args: [entry, 'secrets', '_agent-run'] };
+    // No resolvable entrypoint (unusual) — fall back to the PATH shim.
+    let bin = 'agents';
+    try {
+        bin = execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
+    }
+    catch { /* default */ }
+    return { cmd: bin, args: ['secrets', '_agent-run'] };
+}
+// ─── Broker server (runs in the detached `secrets _agent-run` process) ───────
+/**
+ * Pure request handler over the in-memory store. Extracted so the store
+ * semantics (lazy expiry on get/status, lock-one vs lock-all, load TTL) are
+ * unit-testable with a controlled `now`, without a socket or a spawned process.
+ * Mutates `store` in place; returns the wire response.
+ */
+export function handleAgentRequest(store, req, now = Date.now()) {
+    switch (req.cmd) {
+        case 'ping':
+            return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION };
+        case 'get': {
+            const e = store.get(req.name);
+            if (!e || now >= e.expiresAt) {
+                if (e)
+                    store.delete(req.name); // drop expired on read
+                return { ok: true, cmd: 'get', hit: false };
+            }
+            return { ok: true, cmd: 'get', hit: true, bundle: e.bundle, env: e.env };
+        }
+        case 'load':
+            store.set(req.name, { bundle: req.bundle, env: req.env, expiresAt: now + req.ttlMs });
+            return { ok: true, cmd: 'load' };
+        case 'lock': {
+            if (req.name) {
+                return { ok: true, cmd: 'lock', wiped: store.delete(req.name) ? 1 : 0 };
+            }
+            const wiped = store.size;
+            store.clear();
+            return { ok: true, cmd: 'lock', wiped };
+        }
+        case 'status': {
+            const entries = [];
+            for (const [name, e] of store) {
+                if (now >= e.expiresAt)
+                    continue;
+                entries.push({ name, expiresAt: e.expiresAt, keyCount: Object.keys(e.env).length });
+            }
+            return { ok: true, cmd: 'status', entries };
+        }
+    }
+}
+/**
+ * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
+ * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
+ * sweeps expired entries, wipes on screen-lock/sleep, and self-exits when idle.
+ */
+export async function runSecretsAgent() {
+    if (!onDarwin())
+        return; // nothing to broker without biometry prompts
+    // Single-instance guard: O_EXCL pid file. If a live broker already holds it,
+    // exit quietly — the existing one keeps serving.
+    const pidFile = pidPath();
+    try {
+        const fd = fs.openSync(pidFile, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
+        fs.writeSync(fd, String(process.pid));
+        fs.closeSync(fd);
+    }
+    catch (err) {
+        if (err?.code === 'EEXIST') {
+            const holder = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+            if (!isNaN(holder) && isAlive(holder))
+                return; // another broker is live
+            // Stale pid — reclaim it.
+            try {
+                fs.unlinkSync(pidFile);
+            }
+            catch { /* race; fall through */ }
+            fs.writeFileSync(pidFile, String(process.pid));
+        }
+        else {
+            throw err;
+        }
+    }
+    const store = new Map();
+    // emptySince tracks the last moment the store held something; the sweep exits
+    // the process once it's been empty for IDLE_EXIT_MS so no idle broker lingers.
+    let emptySince = Date.now();
+    const sock = socketPath();
+    try {
+        fs.unlinkSync(sock);
+    }
+    catch { /* no stale socket */ }
+    const sweep = () => {
+        const now = Date.now();
+        for (const [name, e] of store)
+            if (now >= e.expiresAt)
+                store.delete(name);
+        if (store.size === 0) {
+            if (now - emptySince >= IDLE_EXIT_MS)
+                shutdown(0);
+        }
+        else {
+            emptySince = now;
+        }
+    };
+    const handle = (req) => {
+        const resp = handleAgentRequest(store, req);
+        if (store.size > 0)
+            emptySince = Date.now();
+        return resp;
+    };
+    const server = net.createServer((conn) => {
+        conn.setEncoding('utf-8');
+        let buf = '';
+        conn.on('data', (chunk) => {
+            buf += chunk;
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                let resp;
+                try {
+                    resp = handle(JSON.parse(line));
+                }
+                catch (err) {
+                    resp = { ok: false, error: err.message };
+                }
+                conn.write(JSON.stringify(resp) + '\n');
+            }
+        });
+        conn.on('error', () => { });
+    });
+    let watcher = null;
+    let sweepTimer = null;
+    let shuttingDown = false;
+    const shutdown = (code) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        store.clear();
+        if (sweepTimer)
+            clearInterval(sweepTimer);
+        try {
+            watcher?.kill();
+        }
+        catch { /* already gone */ }
+        try {
+            server.close();
+        }
+        catch { /* not listening */ }
+        try {
+            fs.unlinkSync(sock);
+        }
+        catch { /* gone */ }
+        try {
+            if (parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10) === process.pid)
+                fs.unlinkSync(pidFile);
+        }
+        catch { /* gone */ }
+        process.exit(code);
+    };
+    process.on('SIGTERM', () => shutdown(0));
+    process.on('SIGINT', () => shutdown(0));
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(sock, () => {
+            try {
+                fs.chmodSync(sock, 0o600);
+            }
+            catch { /* dir 0700 already gates it */ }
+            resolve();
+        });
+    });
+    sweepTimer = setInterval(sweep, SWEEP_INTERVAL_MS);
+    // Auto-lock on screen-lock / sleep. The signed helper emits LOCK / SLEEP
+    // lines; on any of them we wipe everything. If the installed helper predates
+    // watch-lock (exits non-zero immediately), we fall back to TTL-only and log
+    // nothing — the unlock already warned when lock_on_sleep couldn't be armed.
+    try {
+        watcher = spawn(getKeychainHelperPath(), ['watch-lock'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        watcher.stdout?.setEncoding('utf-8');
+        watcher.stdout?.on('data', (chunk) => {
+            if (/\b(LOCK|SLEEP)\b/.test(chunk)) {
+                store.clear();
+                emptySince = Date.now();
+            }
+        });
+        watcher.on('error', () => { watcher = null; });
+    }
+    catch {
+        watcher = null;
+    }
+}
+// ─── Client ──────────────────────────────────────────────────────────────────
+/** Open the socket, send one request, resolve the one response. Async path —
+ * used by the unlock/lock/status commands, which already run in async actions. */
+function request(req, timeoutMs = 2000) {
+    return new Promise((resolve) => {
+        const conn = net.createConnection(socketPath());
+        let buf = '';
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            try {
+                conn.destroy();
+            }
+            catch { /* already closed */ }
+            resolve(r);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        conn.on('error', () => finish(null));
+        conn.on('connect', () => conn.write(JSON.stringify(req) + '\n'));
+        conn.setEncoding('utf-8');
+        conn.on('data', (chunk) => {
+            buf += chunk;
+            const nl = buf.indexOf('\n');
+            if (nl < 0)
+                return;
+            try {
+                finish(JSON.parse(buf.slice(0, nl)));
+            }
+            catch {
+                finish(null);
+            }
+        });
+    });
+}
+/** True if a broker socket exists at all. Cheap; gates the sync read so the
+ * never-unlocked path stays a single stat. */
+export function agentSocketExists() {
+    return onDarwin() && fs.existsSync(socketPath());
+}
+/**
+ * Inline node program for the synchronous read fast-path. `readAndResolveBundleEnv`
+ * is synchronous and called synchronously everywhere, so we can't await a socket
+ * round-trip — but spawning the full CLI to do it would load every command. This
+ * minimal `node -e` client connects, asks for one bundle, prints the resolved
+ * {bundle, env} as JSON, and exits 0 (hit) / 3 (miss or agent down). argv after
+ * -e: [execPath, <socket>, <name>].
+ */
+const SYNC_GET_PROGRAM = `
+const net = require('net');
+const sock = process.argv[1], name = process.argv[2];
+const c = net.createConnection(sock);
+let buf = '';
+const miss = () => { try { c.destroy(); } catch (e) {} process.exit(3); };
+const timer = setTimeout(miss, 2000);
+c.on('error', miss);
+c.on('connect', () => c.write(JSON.stringify({ cmd: 'get', name }) + '\\n'));
+c.setEncoding('utf-8');
+c.on('data', (d) => {
+  buf += d;
+  const nl = buf.indexOf('\\n');
+  if (nl < 0) return;
+  clearTimeout(timer);
+  let r; try { r = JSON.parse(buf.slice(0, nl)); } catch (e) { return miss(); }
+  try { c.destroy(); } catch (e) {}
+  if (r && r.ok && r.hit) { process.stdout.write(JSON.stringify({ bundle: r.bundle, env: r.env })); process.exit(0); }
+  process.exit(3);
+});
+`;
+/**
+ * Synchronous read for the hot path. Returns the cached resolved bundle, or
+ * null if the agent isn't running / doesn't hold this bundle / anything fails
+ * (soft — caller falls through to the real keychain). macOS only.
+ */
+export function agentGetSync(name) {
+    if (!agentSocketExists())
+        return null;
+    const r = spawnSync(process.execPath, ['-e', SYNC_GET_PROGRAM, socketPath(), name], {
+        encoding: 'utf-8',
+        timeout: 3000,
+    });
+    if (r.status !== 0 || !r.stdout)
+        return null;
+    try {
+        const o = JSON.parse(r.stdout);
+        if (!o || typeof o !== 'object' || !o.env)
+            return null;
+        return { bundle: o.bundle, env: o.env };
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `secrets.agent.auto` is enabled in agents.yaml. Best-effort; a
+ * missing/unreadable meta reads as off. */
+export function secretsAgentAutoEnabled() {
+    try {
+        return readMeta().secrets?.agent?.auto === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Inline node program that loads one bundle into the broker, started detached
+ * from the hot path. Reads the JSON payload from stdin (so secret values never
+ * appear in argv / `ps`), retries the socket for a few seconds to absorb a
+ * cold-started agent, sends the load, and exits. argv after -e: [execPath, <socket>].
+ */
+const DETACHED_LOAD_PROGRAM = `
+const net = require('net');
+const sock = process.argv[1];
+let input = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (d) => { input += d; });
+process.stdin.on('end', () => {
+  let payload; try { payload = JSON.parse(input); } catch (e) { process.exit(1); }
+  let attempts = 0;
+  const tryConnect = () => {
+    const c = net.createConnection(sock);
+    c.on('connect', () => {
+      c.write(JSON.stringify({ cmd: 'load', name: payload.name, bundle: payload.bundle, env: payload.env, ttlMs: payload.ttlMs }) + '\\n');
+    });
+    c.setEncoding('utf-8');
+    c.on('data', () => { try { c.destroy(); } catch (e) {} process.exit(0); });
+    c.on('error', () => {
+      try { c.destroy(); } catch (e) {}
+      if (++attempts >= 30) process.exit(1);
+      setTimeout(tryConnect, 100);
+    });
+  };
+  tryConnect();
+});
+`;
+/**
+ * Fire-and-forget: populate the broker with a freshly-resolved bundle so the
+ * NEXT process reads it without a prompt. Used by the auto-cache path after a
+ * real keychain read of a `session`-tier bundle. Adds no latency to the caller
+ * — it spawns the agent (if needed) and a detached loader, both unref'd, then
+ * returns immediately. Entirely best-effort; never throws. macOS only.
+ */
+export function agentAutoLoadSync(name, bundle, env, ttlMs) {
+    if (!onDarwin())
+        return;
+    try {
+        if (!agentSocketExists()) {
+            const { cmd, args } = brokerSpawn();
+            spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+        }
+        const loader = spawn(process.execPath, ['-e', DETACHED_LOAD_PROGRAM, socketPath()], {
+            stdio: ['pipe', 'ignore', 'ignore'],
+            detached: true,
+        });
+        loader.stdin?.write(JSON.stringify({ name, bundle, env, ttlMs }));
+        loader.stdin?.end();
+        loader.unref();
+    }
+    catch {
+        // best-effort: the next read just pops Touch ID as it would today
+    }
+}
+/** Store a resolved bundle in the broker. Returns false on transport failure. */
+export async function agentLoad(name, bundle, env, ttlMs) {
+    const r = await request({ cmd: 'load', name, bundle, env, ttlMs });
+    return r?.ok === true && r.cmd === 'load';
+}
+/** Wipe one bundle (or all if name omitted) from the broker. Returns the count
+ * wiped, or 0 when no broker is running. */
+export async function agentLock(name) {
+    const r = await request({ cmd: 'lock', name });
+    return r?.ok === true && r.cmd === 'lock' ? r.wiped : 0;
+}
+/** List currently-unlocked bundles, or [] when no broker is running. */
+export async function agentStatus() {
+    const r = await request({ cmd: 'status' });
+    return r?.ok === true && r.cmd === 'status' ? r.entries : [];
+}
+/** Is a broker live and speaking our protocol version? */
+async function agentPing() {
+    if (!agentSocketExists())
+        return false;
+    const r = await request({ cmd: 'ping' });
+    return r?.ok === true && r.cmd === 'ping' && r.version === PROTOCOL_VERSION;
+}
+/**
+ * Ensure a broker is running and reachable, spawning one detached if not.
+ * Returns true once the socket answers a ping. On protocol-version skew, kills
+ * the stale broker and respawns. macOS only.
+ */
+export async function ensureAgentRunning(timeoutMs = 5000) {
+    if (!onDarwin())
+        return false;
+    if (await agentPing())
+        return true;
+    // Socket exists but ping failed → stale/old broker. Kill it before respawn.
+    const stalePid = (() => {
+        try {
+            return parseInt(fs.readFileSync(pidPath(), 'utf-8').trim(), 10);
+        }
+        catch {
+            return NaN;
+        }
+    })();
+    if (!isNaN(stalePid) && isAlive(stalePid)) {
+        try {
+            process.kill(stalePid, 'SIGTERM');
+        }
+        catch { /* already dead */ }
+    }
+    try {
+        fs.unlinkSync(socketPath());
+    }
+    catch { /* gone */ }
+    try {
+        fs.unlinkSync(pidPath());
+    }
+    catch { /* gone */ }
+    const { cmd, args } = brokerSpawn();
+    const child = spawn(cmd, args, {
+        stdio: 'ignore',
+        detached: true,
+    });
+    child.unref();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (await agentPing())
+            return true;
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    return false;
+}

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

@@ -23,11 +23,23 @@ export interface VarMeta {
     /** Singular freeform note. */
     note?: string;
 }
+/**
+ * How a bundle interacts with the macOS secrets-agent:
+ * - `biometry` (default): only an explicit `agents secrets unlock` populates the
+ *   agent; every other read pops Touch ID. Use for high-value bundles you want
+ *   to confirm each session.
+ * - `session`: eligible for the agent — `unlock`, and (when `secrets.agent.auto`
+ *   is enabled) the first real keychain read auto-loads it so concurrent runs
+ *   read it silently.
+ */
+export type SecretsTier = 'biometry' | 'session';
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
     description?: string;
     allow_exec?: boolean;
+    /** Secrets-agent interaction tier. Absent ⇒ `biometry` (the safe default). */
+    tier?: SecretsTier;
     /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
     created_at?: string;
     /** ISO 8601 UTC timestamp. Refreshed on every writeBundle(). */
@@ -61,6 +73,8 @@ export declare function validateSecretType(t: string): asserts t is SecretType;
 export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
 export declare function readBundle(name: string): SecretsBundle;
+/** The effective tier of a bundle (absent ⇒ `biometry`). */
+export declare function bundleTier(bundle: SecretsBundle): SecretsTier;
 export declare function writeBundle(bundle: SecretsBundle): void;
 export declare function deleteBundle(name: string): boolean;
 export declare function listBundles(): SecretsBundle[];
@@ -80,6 +94,13 @@ export interface ResolveBundleOptions {
      * about to read the bundle.
      */
     caller?: string;
+    /**
+     * Skip the secrets-agent fast-path and read straight from the keychain
+     * (popping Touch ID). Set by callers that must NOT serve a cached snapshot —
+     * `unlock` (which populates the agent in the first place) and any flow that
+     * needs live values. Also honored via AGENTS_SECRETS_NO_AGENT=1.
+     */
+    noAgent?: boolean;
 }
 export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveBundleOptions): Record<string, string>;
 /**

package/dist/lib/secrets/bundles.js

@@ -17,6 +17,7 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { emit } from '../events.js';
+import { agentGetSync, agentAutoLoadSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
 /** Allowed values for a secret's `type` metadata field. */
 export const SECRET_TYPES = [
     'api-key',
@@ -142,6 +143,7 @@ export function readBundle(name) {
         name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
+        tier: parseTier(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -158,6 +160,14 @@ export function readBundle(name) {
     }
     return bundle;
 }
+/** Normalize a persisted `tier` value; anything but `session` ⇒ default tier. */
+function parseTier(raw) {
+    return raw === 'session' ? 'session' : undefined;
+}
+/** The effective tier of a bundle (absent ⇒ `biometry`). */
+export function bundleTier(bundle) {
+    return bundle.tier ?? 'biometry';
+}
 export function writeBundle(bundle) {
     validateBundleName(bundle.name);
     for (const key of Object.keys(bundle.vars)) {
@@ -191,6 +201,7 @@ export function writeBundle(bundle) {
     const payload = {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
+        tier: bundle.tier === 'session' ? 'session' : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,
@@ -249,6 +260,7 @@ export function listBundles() {
             name,
             description: parsed.description,
             allow_exec: Boolean(parsed.allow_exec),
+            tier: parseTier(parsed.tier),
             vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
         };
         if (typeof parsed.created_at === 'string')
@@ -375,6 +387,25 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  */
 export function readAndResolveBundleEnv(name, opts = {}) {
     validateBundleName(name);
+    // Fast-path: if the secrets-agent holds this bundle (user ran
+    // `agents secrets unlock <name>`), return the cached snapshot with no Touch
+    // ID. Soft — any failure falls through to the real keychain read below. macOS
+    // only; the never-unlocked path is a single stat (agentSocketExists) so it
+    // costs nothing when the agent isn't running.
+    if (!opts.noAgent && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
+        const hit = agentGetSync(name);
+        if (hit) {
+            stampLastUsed(hit.bundle);
+            emit('secrets.get', {
+                bundle: name,
+                caller: opts.caller,
+                status: 'success',
+                source: 'agent',
+                keyCount: Object.keys(hit.env).length,
+            });
+            return hit;
+        }
+    }
     const metaItem = bundleMetaItem(name);
     const bundleSecretPrefix = `${SECRETS_ITEM_PREFIX}${name}.`;
     let secretItems;
@@ -407,6 +438,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
+        tier: parseTier(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -476,6 +508,17 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             }
         }
         emitReadAudit('success');
+        // Auto-cache: this was a real keychain read (the agent fast-path returned
+        // earlier on a hit). If the bundle opts into the session tier and the user
+        // enabled `secrets.agent.auto`, populate the broker in the background so the
+        // next concurrent run reads silently. Skipped when noAgent (e.g. `unlock`,
+        // which loads the agent itself). Fire-and-forget — never blocks this read.
+        if (!opts.noAgent &&
+            process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
+            bundleTier(bundle) === 'session' &&
+            secretsAgentAutoEnabled()) {
+            agentAutoLoadSync(name, bundle, env, DEFAULT_TTL_MS);
+        }
         return { bundle, env };
     }
     catch (err) {

package/dist/lib/secrets/drivers/rush.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Rush `SyncBackend` driver — the original (and currently default) transport
+ * for `agents secrets push/pull`. Talks to api.prix.dev and authenticates with
+ * the session token written by `rush login` (`~/.rush/user.yaml`).
+ *
+ * This is the ONE place in the secrets module allowed to reference Rush
+ * (api.prix.dev / ~/.rush). It is an opt-in driver kept for backwards
+ * compatibility with bundles already pushed to Rush; `sync.ts` selects it as
+ * the default but the transport seam (`SyncBackend`) lets other backends drop
+ * in without touching the crypto or push/pull logic.
+ */
+import type { SyncBackend } from '../sync-backend.js';
+/** The Rush transport. Plaintext never reaches here — only ciphertext envelopes. */
+export declare const rushSyncBackend: SyncBackend;