@phnx-labs/agents-cli 1.20.20 → 1.20.22

package/dist/lib/menubar/install-menubar.js

@@ -0,0 +1,291 @@
+/**
+ * Install + lifecycle for the macOS menu-bar helper (`MenubarHelper.app`).
+ *
+ * Mirrors `src/lib/secrets/install-helper.ts` (stable Application Support path,
+ * survives npm re-sign) and the secrets-agent launchd pattern in
+ * `src/lib/secrets/agent.ts` (RunAtLoad + KeepAlive user service).
+ *
+ * The helper is a no-Dock `.accessory` status-bar app. It reads live agent
+ * state directly from disk and shells `agents` only for actions, so the plist
+ * bakes in the node interpreter + entry point + bin path so the GUI process can
+ * find the CLI without a login PATH.
+ *
+ * Opt-out is sticky: `agents menubar disable` drops a sentinel that the upgrade
+ * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
+ * menu bar never silently comes back on the next release.
+ */
+import { fileURLToPath } from 'url';
+import { execFileSync, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getRuntimeStateDir, getHelpersDir } from '../state.js';
+const APP_BUNDLE_NAME = 'MenubarHelper.app';
+const INSTALL_DIR_NAME = 'agents-cli';
+const SERVICE_LABEL = 'com.phnx-labs.agents-menubar';
+function onDarwin() {
+    return process.platform === 'darwin';
+}
+/** ~/Library/Application Support/agents-cli/MenubarHelper.app */
+function installedAppPath() {
+    return path.join(os.homedir(), 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
+}
+/** Executable inside the installed bundle. */
+function installedExecutablePath() {
+    return path.join(installedAppPath(), 'Contents', 'MacOS', 'MenubarHelper');
+}
+/** ~/Library/LaunchAgents/com.phnx-labs.agents-menubar.plist */
+function servicePlistPath() {
+    return path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+}
+/** Sticky opt-out marker written by `agents menubar disable`. */
+function disabledSentinelPath() {
+    return path.join(getRuntimeStateDir(), 'menubar.disabled');
+}
+/** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
+export function menubarDisabledByUser() {
+    return fs.existsSync(disabledSentinelPath());
+}
+/** True if the launchd plist for the menu-bar service is installed. */
+export function menubarServiceInstalled() {
+    return onDarwin() && fs.existsSync(servicePlistPath());
+}
+/**
+ * Locate the source `.app` shipped alongside the compiled JS.
+ *   1. dist/lib/menubar/MenubarHelper.app — npm install layout (sibling of this file)
+ *   2. <repo>/bin/MenubarHelper.app       — raw working tree (tsx/dev)
+ *   3. <repo>/packages/menubar-helper/dist/MenubarHelper.app — fresh local build
+ */
+function sourceAppPath() {
+    const candidates = [];
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        candidates.push(path.join(here, APP_BUNDLE_NAME));
+        candidates.push(path.resolve(here, '..', '..', '..', 'bin', APP_BUNDLE_NAME));
+        candidates.push(path.resolve(here, '..', '..', '..', 'packages', 'menubar-helper', 'dist', APP_BUNDLE_NAME));
+    }
+    catch {
+        /* import.meta.url unavailable */
+    }
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+/** Resolve the `agents` launcher binary on PATH-less GUI processes. */
+function resolveAgentsBin() {
+    const home = os.homedir();
+    const candidates = [
+        path.join(home, '.local', 'bin', 'agents'),
+        '/opt/homebrew/bin/agents',
+        '/usr/local/bin/agents',
+        path.join(home, '.npm-global', 'bin', 'agents'),
+    ];
+    for (const c of candidates) {
+        try {
+            fs.accessSync(c, fs.constants.X_OK);
+            return c;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+/** Resolve the compiled CLI entry (dist/index.js) so the helper can exec node directly. */
+function resolveCliEntry() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // dist/lib/menubar/install-menubar.js -> dist/index.js
+        const entry = path.resolve(here, '..', '..', 'index.js');
+        if (fs.existsSync(entry))
+            return entry;
+    }
+    catch {
+        /* ignore */
+    }
+    return null;
+}
+function copyAppBundle(src, dest) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest))
+        fs.rmSync(dest, { recursive: true, force: true });
+    // `cp -R` preserves the bundle's signature and resource forks (see install-helper.ts).
+    const r = spawnSync('cp', ['-R', src, dest], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+    if (r.status !== 0) {
+        const msg = (r.stderr || r.stdout || '').toString().trim();
+        throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
+    }
+}
+/**
+ * Copy the bundled `.app` to the stable user path (idempotent unless forced).
+ * Returns the installed executable path, or null if no source bundle ships
+ * with this install (e.g. Linux package, or a build without the helper).
+ */
+export function ensureMenubarAppInstalled(opts = {}) {
+    if (!onDarwin())
+        return null;
+    const src = sourceAppPath();
+    if (!src)
+        return null;
+    const dest = installedAppPath();
+    if (!opts.forceReinstall && fs.existsSync(dest))
+        return installedExecutablePath();
+    copyAppBundle(src, dest);
+    return installedExecutablePath();
+}
+function xmlEscape(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function generateServicePlist(execPath) {
+    const home = os.homedir();
+    const logPath = path.join(getHelpersDir(), 'menubar', 'menubar.log');
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    // Bake interpreter + entry + bin so the GUI helper can reach the CLI with no
+    // login PATH. AgentsCLI.swift prefers [AGENTS_NODE, AGENTS_ENTRY] when both
+    // exist, else falls back to AGENTS_BIN, else probes well-known paths.
+    const env = {
+        PATH: `/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${path.dirname(process.execPath)}:${home}/.local/bin`,
+    };
+    const node = process.execPath;
+    const entry = resolveCliEntry();
+    const bin = resolveAgentsBin();
+    if (node && entry) {
+        env.AGENTS_NODE = node;
+        env.AGENTS_ENTRY = entry;
+    }
+    if (bin)
+        env.AGENTS_BIN = bin;
+    const envXml = Object.entries(env)
+        .map(([k, v]) => `    <key>${xmlEscape(k)}</key>\n    <string>${xmlEscape(v)}</string>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(execPath)}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+</dict>
+</plist>`;
+}
+/**
+ * Install + start the menu-bar helper as a launchd user service (idempotent).
+ * Clears the sticky opt-out, installs the .app, writes the plist, and
+ * bootstraps it into the GUI domain. Returns false on non-darwin or when no
+ * helper bundle ships with this install.
+ */
+export function enableMenubarService(opts = { clearOptOut: true }) {
+    if (!onDarwin())
+        return false;
+    const exec = ensureMenubarAppInstalled({ forceReinstall: true });
+    if (!exec)
+        return false;
+    if (opts.clearOptOut) {
+        try {
+            fs.rmSync(disabledSentinelPath(), { force: true });
+        }
+        catch { /* already gone */ }
+    }
+    const plist = servicePlistPath();
+    fs.mkdirSync(path.dirname(plist), { recursive: true });
+    fs.writeFileSync(plist, generateServicePlist(exec));
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync('launchctl', ['bootstrap', `gui/${uid}`, plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch {
+        try {
+            execFileSync('launchctl', ['load', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* may already be loaded */ }
+    }
+    try {
+        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch { /* best effort */ }
+    return true;
+}
+/**
+ * Stop + remove the menu-bar service and write the sticky opt-out so the
+ * upgrade migration won't re-enable it.
+ */
+export function disableMenubarService() {
+    if (!onDarwin())
+        return;
+    const plist = servicePlistPath();
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync('launchctl', ['bootout', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch {
+        try {
+            execFileSync('launchctl', ['unload', '-w', plist], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* not loaded */ }
+    }
+    try {
+        fs.unlinkSync(plist);
+    }
+    catch { /* already gone */ }
+    try {
+        fs.mkdirSync(path.dirname(disabledSentinelPath()), { recursive: true });
+        fs.writeFileSync(disabledSentinelPath(), `disabled ${new Date().toISOString()}\n`);
+    }
+    catch { /* best effort */ }
+}
+/**
+ * Upgrade-time auto-enable. Runs from runMigration() once per sentinel bump.
+ * No-ops if: not darwin, the user opted out, no helper bundle ships, or the
+ * service is already installed. Best-effort — never throws into migration.
+ */
+export function installMenubarLaunchAgentOnUpgrade() {
+    try {
+        if (!onDarwin())
+            return;
+        if (menubarDisabledByUser())
+            return;
+        if (menubarServiceInstalled())
+            return;
+        if (!sourceAppPath())
+            return;
+        enableMenubarService({ clearOptOut: false });
+    }
+    catch {
+        /* never block migration on the menu bar */
+    }
+}
+export function getMenubarStatus() {
+    const dest = installedAppPath();
+    let running = false;
+    if (onDarwin()) {
+        const r = spawnSync('pgrep', ['-f', 'MenubarHelper'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+        running = r.status === 0 && (r.stdout || '').trim().length > 0;
+    }
+    return {
+        platform: process.platform,
+        source: sourceAppPath(),
+        installedApp: fs.existsSync(dest) ? dest : null,
+        serviceInstalled: menubarServiceInstalled(),
+        running,
+        disabledByUser: menubarDisabledByUser(),
+    };
+}

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

@@ -46,6 +46,13 @@ export declare function secretsAgentServiceInstalled(): boolean;
  * so it can boot even when the machine is loaded. Returns true once reachable.
  */
 export declare function installSecretsAgentService(timeoutMs?: number): Promise<boolean>;
+/**
+ * Kickstart the already-installed persistent broker so launchd relaunches it
+ * onto the current on-disk code. Used by postinstall heal-on-upgrade. No-op if
+ * the service isn't installed; never rewrites the plist or waits, so it's safe
+ * and fast to call from an installer.
+ */
+export declare function kickstartSecretsAgentService(): void;
 /** Stop + remove the persistent broker service, and wipe whatever it held. */
 export declare function uninstallSecretsAgentService(): Promise<void>;
 export type Request = {
@@ -69,6 +76,7 @@ export type Response = {
     ok: true;
     cmd: 'ping';
     version: number;
+    cliVersion: string;
 } | {
     ok: true;
     cmd: 'get';
@@ -127,7 +135,7 @@ export declare function secretsAgentAutoEnabled(): boolean;
 /**
  * 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
+ * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
  * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
  * over stdin, never argv) and returns immediately.
  *

package/dist/lib/secrets/agent.js

@@ -30,6 +30,7 @@ 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';
+import { getCliVersion, getCliVersionFresh } from '../version.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;
@@ -164,12 +165,27 @@ export async function installSecretsAgentService(timeoutMs = 30000) {
     catch { /* best effort */ }
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (await agentPing())
+        if ((await agentPing()).reachable)
             return true;
         await new Promise((r) => setTimeout(r, 200));
     }
     return false;
 }
+/**
+ * Kickstart the already-installed persistent broker so launchd relaunches it
+ * onto the current on-disk code. Used by postinstall heal-on-upgrade. No-op if
+ * the service isn't installed; never rewrites the plist or waits, so it's safe
+ * and fast to call from an installer.
+ */
+export function kickstartSecretsAgentService() {
+    if (!onDarwin() || !secretsAgentServiceInstalled())
+        return;
+    const uid = process.getuid?.() ?? 0;
+    try {
+        execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+    }
+    catch { /* best effort */ }
+}
 /** Stop + remove the persistent broker service, and wipe whatever it held. */
 export async function uninstallSecretsAgentService() {
     if (!onDarwin())
@@ -201,7 +217,11 @@ export async function uninstallSecretsAgentService() {
 export function handleAgentRequest(store, req, now = Date.now()) {
     switch (req.cmd) {
         case 'ping':
-            return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION };
+            // Report the version of the code this broker is RUNNING (getCliVersion
+            // caches the value from the broker's startup), not the on-disk version.
+            // A client compares this to its own fresh on-disk read; a mismatch means
+            // the broker is running pre-upgrade code and should be restarted.
+            return { ok: true, cmd: 'ping', version: PROTOCOL_VERSION, cliVersion: getCliVersion() };
         case 'get': {
             const e = store.get(req.name);
             if (!e || now >= e.expiresAt) {
@@ -278,11 +298,25 @@ export async function runSecretsAgent(opts = {}) {
         fs.unlinkSync(sock);
     }
     catch { /* no stale socket */ }
+    // Capture the version of the code we're running so the sweep can detect when
+    // an in-place upgrade has landed and self-heal onto it. getCliVersion caches
+    // this value for the process lifetime; getCliVersionFresh re-reads on disk.
+    const runningVersion = getCliVersion();
     const sweep = () => {
         const now = Date.now();
         for (const [name, e] of store)
             if (now >= e.expiresAt)
                 store.delete(name);
+        // Self-heal: a newer version was installed in place — exit so launchd
+        // relaunches us on the new code. Only meaningful when launchd will restart
+        // us (persistent); a one-off broker just keeps serving until idle.
+        if (persistent) {
+            const onDisk = getCliVersionFresh();
+            if (onDisk !== 'unknown' && runningVersion !== 'unknown' && onDisk !== runningVersion) {
+                shutdown(0); // KeepAlive relaunches on the new code
+                return;
+            }
+        }
         if (store.size === 0) {
             if (!persistent && now - emptySince >= IDLE_EXIT_MS)
                 shutdown(0);
@@ -489,7 +523,7 @@ export function secretsAgentAutoEnabled() {
 /**
  * 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
+ * real keychain read of a `daily`-policy bundle. Adds no latency to the caller
  * — it spawns a detached `secrets _agent-load` worker (passing the resolved env
  * over stdin, never argv) and returns immediately.
  *
@@ -556,12 +590,16 @@ 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? */
+/** Ping result: whether a broker is reachable + speaking our protocol, and the
+ * version of the code it's running (for staleness detection). */
 async function agentPing() {
     if (!agentSocketExists())
-        return false;
+        return { reachable: false };
     const r = await request({ cmd: 'ping' });
-    return r?.ok === true && r.cmd === 'ping' && r.version === PROTOCOL_VERSION;
+    if (r?.ok === true && r.cmd === 'ping' && r.version === PROTOCOL_VERSION) {
+        return { reachable: true, cliVersion: r.cliVersion };
+    }
+    return { reachable: false };
 }
 /**
  * Ensure a broker is running and reachable. Returns true once the socket answers
@@ -576,8 +614,16 @@ async function agentPing() {
 export async function ensureAgentRunning(timeoutMs = 5000) {
     if (!onDarwin())
         return false;
-    if (await agentPing())
-        return true;
+    // Self-heal: if a broker is reachable but running pre-upgrade code (its
+    // reported version != the version on disk now), tear it down so the paths
+    // below bring up a fresh one on current code. A current, reachable broker is
+    // accepted immediately.
+    const ping = await agentPing();
+    if (ping.reachable) {
+        if (ping.cliVersion === undefined || ping.cliVersion === getCliVersionFresh())
+            return true;
+        await teardownStaleBroker();
+    }
     // Path 1: the persistent service. installSecretsAgentService is idempotent and
     // waits for the socket; for an already-installed service we kickstart and wait.
     try {
@@ -593,7 +639,7 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
             catch { /* may already be running */ }
             const d = Date.now() + timeoutMs;
             while (Date.now() < d) {
-                if (await agentPing())
+                if ((await agentPing()).reachable)
                     return true;
                 await new Promise((r) => setTimeout(r, 150));
             }
@@ -627,9 +673,44 @@ export async function ensureAgentRunning(timeoutMs = 5000) {
     spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (await agentPing())
+        if ((await agentPing()).reachable)
             return true;
         await new Promise((r) => setTimeout(r, 100));
     }
     return false;
 }
+/**
+ * Tear down a stale broker (running pre-upgrade code) so a fresh one can take
+ * over. If the persistent service is installed, bootout makes launchd relaunch
+ * it on the new code; otherwise kill the process and clear its socket/pid.
+ */
+async function teardownStaleBroker() {
+    if (secretsAgentServiceInstalled()) {
+        const uid = process.getuid?.() ?? 0;
+        try {
+            execFileSync('launchctl', ['kickstart', '-k', `gui/${uid}/${SERVICE_LABEL}`], { stdio: ['ignore', 'ignore', 'ignore'] });
+        }
+        catch { /* best effort */ }
+        return; // kickstart -k restarts the service onto current code; socket/pid managed by it
+    }
+    const pid = (() => { try {
+        return parseInt(fs.readFileSync(pidPath(), 'utf-8').trim(), 10);
+    }
+    catch {
+        return NaN;
+    } })();
+    if (!isNaN(pid) && isAlive(pid)) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch { /* gone */ }
+    }
+    try {
+        fs.unlinkSync(socketPath());
+    }
+    catch { /* gone */ }
+    try {
+        fs.unlinkSync(pidPath());
+    }
+    catch { /* gone */ }
+}

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

@@ -39,15 +39,21 @@ export interface VarMeta {
     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.
+ * A bundle's prompt policy — how often macOS asks for Touch ID to read it:
+ * - `always` (default): asks every time. Only an explicit `agents secrets
+ *   unlock` ever holds it in the secrets-agent; every other read pops Touch ID.
+ *   Use for high-value bundles you want to confirm every time.
+ * - `daily`: ask once, then hold it silently. Eligible for the secrets-agent —
+ *   `unlock` it, or (when `secrets.agent.auto` is enabled) the first real
+ *   keychain read auto-loads it so concurrent runs read it silently. Held up to
+ *   ~24h from that unlock (not refreshed on use); re-asks sooner after
+ *   screen-lock, sleep, logout, or `agents secrets lock`.
+ *
+ * Stored on disk under the legacy `tier` key (`session` == `daily`; absent ==
+ * `always`) so bundles stay readable across mixed CLI versions on synced
+ * machines. The in-memory and user-facing vocabulary is `policy`/`always`/`daily`.
  */
-export type SecretsTier = 'biometry' | 'session';
+export type SecretsPolicy = 'always' | 'daily';
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
@@ -55,8 +61,9 @@ export interface SecretsBundle {
     allow_exec?: boolean;
     /** Which store carries this bundle's items. Absent ⇒ `keychain` (the default). */
     backend?: SecretsBackend;
-    /** Secrets-agent interaction tier. Absent ⇒ `biometry` (the safe default). */
-    tier?: SecretsTier;
+    /** Prompt policy. Absent ⇒ `always` (the safe default). Serialized under the
+     * legacy `tier` key — see SecretsPolicy. */
+    policy?: SecretsPolicy;
     /** ISO 8601 UTC timestamp. Set once on the first writeBundle() for a bundle. */
     created_at?: string;
     /** ISO 8601 UTC timestamp. Refreshed on every writeBundle(). */
@@ -90,8 +97,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;
+/** The effective prompt policy of a bundle (absent ⇒ `always`). */
+export declare function bundlePolicy(bundle: SecretsBundle): SecretsPolicy;
 export declare function writeBundle(bundle: SecretsBundle): void;
 export declare function deleteBundle(name: string): boolean;
 export declare function listBundles(): SecretsBundle[];

package/dist/lib/secrets/bundles.js

@@ -223,10 +223,11 @@ export function readBundle(name) {
         name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
-        // Absent ⇒ keychain (mirrors `tier`); only set when file-backed so a
-        // keychain bundle round-trips byte-for-byte.
+        // Absent ⇒ keychain; only set when file-backed so a keychain bundle
+        // round-trips byte-for-byte.
         backend: backend === 'file' ? 'file' : undefined,
-        tier: parseTier(parsed.tier),
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -243,13 +244,16 @@ export function readBundle(name) {
     }
     return bundle;
 }
-/** Normalize a persisted `tier` value; anything but `session` ⇒ default tier. */
-function parseTier(raw) {
-    return raw === 'session' ? 'session' : undefined;
+/** Normalize the persisted prompt policy. The on-disk `tier` key uses the
+ * legacy `session` token for `daily` (and `biometry`/absent for the default),
+ * so accept both the legacy and current tokens. Anything but `daily`/`session`
+ * ⇒ undefined (resolves to the `always` default). */
+function parsePolicy(raw) {
+    return raw === 'daily' || raw === 'session' ? 'daily' : undefined;
 }
-/** The effective tier of a bundle (absent ⇒ `biometry`). */
-export function bundleTier(bundle) {
-    return bundle.tier ?? 'biometry';
+/** The effective prompt policy of a bundle (absent ⇒ `always`). */
+export function bundlePolicy(bundle) {
+    return bundle.policy ?? 'always';
 }
 export function writeBundle(bundle) {
     validateBundleName(bundle.name);
@@ -288,7 +292,9 @@ export function writeBundle(bundle) {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
         backend: backend === 'file' ? 'file' : undefined,
-        tier: bundle.tier === 'session' ? 'session' : undefined,
+        // Wire format: persist `daily` under the legacy `tier`/`session` token so
+        // older CLI versions on other synced machines keep reading the policy.
+        tier: bundle.policy === 'daily' ? 'session' : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,
@@ -328,7 +334,8 @@ function parseBundleMeta(name, json, backend) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'file' ? 'file' : undefined,
-        tier: parseTier(parsed.tier),
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -568,7 +575,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
         backend: backend === 'file' ? 'file' : undefined,
-        tier: parseTier(parsed.tier),
+        // Legacy wire key: the policy is persisted under `tier` (`session` == `daily`).
+        policy: parsePolicy(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -639,14 +647,14 @@ 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
+        // earlier on a hit). If the bundle opts into the `daily` policy 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 (backend === 'keychain' &&
             !opts.noAgent &&
             process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
-            bundleTier(bundle) === 'session' &&
+            bundlePolicy(bundle) === 'daily' &&
             secretsAgentAutoEnabled()) {
             agentAutoLoadSync(name, bundle, env, DEFAULT_TTL_MS);
         }