@phnx-labs/agents-cli 1.20.51 → 1.20.53

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

@@ -89,6 +89,9 @@ export interface LegacyBundleCandidate {
     file: string;
     keys: string[];
 }
+export declare const BUNDLE_NAME_PATTERN: RegExp;
+export declare const ENV_KEY_PATTERN: RegExp;
+export declare const BUNDLE_META_PREFIX = "agents-cli.bundles.";
 export declare const RESERVED_ENV_NAMES: Set<string>;
 export declare function bundleToEnvPrefix(name: string): string;
 export declare function isReservedEnvName(key: string): boolean;
@@ -114,7 +117,29 @@ export declare function readBundle(name: string): SecretsBundle;
 export declare function secretsDefaultPolicy(): SecretsPolicy;
 /** The effective prompt policy of a bundle (absent ⇒ the configured default). */
 export declare function bundlePolicy(bundle: SecretsBundle): SecretsPolicy;
-export declare function writeBundle(bundle: SecretsBundle): void;
+/** Options for writeBundle. */
+export interface WriteBundleOptions {
+    /**
+     * Skip evicting the bundle from the secrets-agent broker after the write.
+     * Only for writers that change nothing the broker serves — today that is
+     * stampLastUsed (a usage-telemetry timestamp, fired on every broker HIT):
+     * evicting there would make the cache destroy itself on first use. Every
+     * mutating writer (add / rotate / remove / rename / policy / import) must
+     * leave this unset so a broker-held copy never serves stale values for up
+     * to the ~7d hold.
+     */
+    skipBrokerEviction?: boolean;
+}
+/**
+ * Whether a bundle write should evict the broker-held copy. Pure + exported
+ * for regression coverage. Skips when the writer opted out (stampLastUsed),
+ * when the broker integration is disabled (AGENTS_SECRETS_NO_AGENT — the same
+ * kill-switch the read fast-path honors), or when a test keychain backend is
+ * installed (an in-memory backend has no real keychain behind it, and a test
+ * writing bundle 'prod' must never evict the user's real 'prod' unlock).
+ */
+export declare function shouldEvictAfterBundleWrite(skipRequested: boolean, noAgentEnv: string | undefined, backendOverridden: boolean): boolean;
+export declare function writeBundle(bundle: SecretsBundle, opts?: WriteBundleOptions): void;
 export declare function deleteBundle(name: string): boolean;
 export declare function listBundles(): SecretsBundle[];
 export interface BundleEntryInfo {
@@ -140,6 +165,13 @@ export interface ResolveBundleOptions {
      * needs live values. Also honored via AGENTS_SECRETS_NO_AGENT=1.
      */
     noAgent?: boolean;
+    /**
+     * Resolve only from an already-unlocked secrets-agent snapshot. If the
+     * broker has no snapshot, fail before touching Keychain or any other store.
+     * Background processes use this to guarantee they never surface a biometric
+     * prompt that nobody can answer.
+     */
+    agentOnly?: boolean;
     /**
      * Inject only this subset of keys from the bundle. Keys not in this list are
      * silently excluded from the returned env map. An error is thrown if any

package/dist/lib/secrets/bundles.js

@@ -21,11 +21,11 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, isKeychainBackendOverridden, keychainUsesFileFallback, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, isKeychainBackendOverridden, keychainServiceAlias, keychainUsesFileFallback, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
 import { readMeta } from '../state.js';
-import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
+import { agentGetSync, agentAutoLoadSync, agentGetMetaSync, agentAutoLoadMetaSync, agentEvictSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
 import { createHash } from 'node:crypto';
 const keychainStore = {
     has: hasKeychainToken,
@@ -105,9 +105,9 @@ export const SECRET_TYPES = [
 ];
 /** Minimum gap between last_used updates so the keychain isn't written on every secrets injection. */
 const LAST_USED_THROTTLE_MS = 60_000;
-const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9\-_.]{0,48}$/i;
-const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const BUNDLE_META_PREFIX = 'agents-cli.bundles.';
+export const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9\-_.]{0,48}$/i;
+export const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const BUNDLE_META_PREFIX = 'agents-cli.bundles.';
 const SECRETS_ITEM_PREFIX = 'agents-cli.secrets.';
 export const RESERVED_ENV_NAMES = new Set([
     'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD',
@@ -277,7 +277,24 @@ export function secretsDefaultPolicy() {
 export function bundlePolicy(bundle) {
     return bundle.policy ?? secretsDefaultPolicy();
 }
-export function writeBundle(bundle) {
+/**
+ * Whether a bundle write should evict the broker-held copy. Pure + exported
+ * for regression coverage. Skips when the writer opted out (stampLastUsed),
+ * when the broker integration is disabled (AGENTS_SECRETS_NO_AGENT — the same
+ * kill-switch the read fast-path honors), or when a test keychain backend is
+ * installed (an in-memory backend has no real keychain behind it, and a test
+ * writing bundle 'prod' must never evict the user's real 'prod' unlock).
+ */
+export function shouldEvictAfterBundleWrite(skipRequested, noAgentEnv, backendOverridden) {
+    if (skipRequested)
+        return false;
+    if (noAgentEnv === '1')
+        return false;
+    if (backendOverridden)
+        return false;
+    return true;
+}
+export function writeBundle(bundle, opts = {}) {
     validateBundleName(bundle.name);
     const backend = bundle.backend ?? 'keychain';
     if (backend === 'file')
@@ -311,6 +328,10 @@ export function writeBundle(bundle) {
         bundle.created_at = now;
     bundle.updated_at = now;
     const payload = {
+        // The bundle's own name, persisted since #316: with hashed service names
+        // the keychain item name is opaque, so listBundles recovers the display
+        // name from this field. Older CLIs drop unknown fields on read — safe.
+        name: bundle.name,
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
         backend: backend === 'file' ? 'file' : undefined,
@@ -337,12 +358,20 @@ export function writeBundle(bundle) {
     // no-ACL command is missing) rather than silently landing an ACL'd item.
     itemStore(backend).set(bundleMetaItem(bundle.name), json, { noAcl: bundle.policy === 'never' });
     emit('secrets.set', { module: 'secrets', bundle: bundle.name });
+    // A broker-held snapshot predates this write; evict it so the next read
+    // re-resolves from the keychain instead of serving stale values.
+    if (shouldEvictAfterBundleWrite(Boolean(opts.skipBrokerEviction), process.env.AGENTS_SECRETS_NO_AGENT, isKeychainBackendOverridden())) {
+        agentEvictSync(bundle.name);
+    }
 }
 export function deleteBundle(name) {
     validateBundleName(name);
     const deleted = itemStore(bundleBackend(name)).delete(bundleMetaItem(name));
     if (deleted) {
         emit('secrets.delete', { module: 'secrets', bundle: name });
+        if (shouldEvictAfterBundleWrite(false, process.env.AGENTS_SECRETS_NO_AGENT, isKeychainBackendOverridden())) {
+            agentEvictSync(name);
+        }
     }
     return deleted;
 }
@@ -351,8 +380,14 @@ export function deleteBundle(name) {
  * posture listBundles wants (skip malformed / invalid-key bundles rather than
  * throw). `backend` is authoritative from where the item was found. Returns
  * null to skip.
+ *
+ * `nameHint` is the name recovered from a cleartext service name (Linux, the
+ * file store, pre-re-key items) — authoritative when present, and the only
+ * source for legacy metadata that predates the persisted `name` field. With
+ * hashed service names (macOS, #316) the hint is undefined and the name comes
+ * from the JSON payload written by writeBundle.
  */
-function parseBundleMeta(name, json, backend) {
+function parseBundleMeta(nameHint, json, backend) {
     let parsed;
     try {
         parsed = JSON.parse(json);
@@ -362,6 +397,9 @@ function parseBundleMeta(name, json, backend) {
     }
     if (!parsed || typeof parsed !== 'object')
         return null;
+    const name = nameHint ?? (typeof parsed.name === 'string' ? parsed.name : undefined);
+    if (!name || !BUNDLE_NAME_PATTERN.test(name))
+        return null;
     const bundle = {
         name,
         description: parsed.description,
@@ -406,10 +444,12 @@ export function listBundles() {
         catch {
             keychainServices = [];
         }
-        const keychainNames = keychainServices
-            .map((s) => s.slice(BUNDLE_META_PREFIX.length))
-            .filter((n) => BUNDLE_NAME_PATTERN.test(n));
-        if (keychainNames.length > 0) {
+        // With hashed service names (macOS, #316) the enumerated services are
+        // opaque (`agents-cli.h.<ns>.m`) — the display name is recovered from the
+        // metadata JSON after the batch read below. Cleartext services (Linux,
+        // pre-re-key items) still carry the name; it's kept as the parse hint so
+        // legacy metadata without the persisted `name` field keeps listing.
+        if (keychainServices.length > 0) {
             // Daily-policy fast-path (macOS). Bundle metadata items are biometry-gated,
             // so the getKeychainTokens batch below pops Touch ID on every `secrets
             // list` — the broker/`daily` mechanism only ever covered value reads, not
@@ -427,7 +467,7 @@ export function listBundles() {
                 !isKeychainBackendOverridden() &&
                 secretsAgentAutoEnabled();
             const nameSetHash = createHash('sha256')
-                .update([...keychainNames].sort().join('\n'))
+                .update([...keychainServices].sort().join('\n'))
                 .digest('hex')
                 .slice(0, 32);
             const cached = useAgent ? agentGetMetaSync(nameSetHash) : null;
@@ -436,13 +476,16 @@ export function listBundles() {
                     out.push(bundle);
             }
             else {
-                const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
+                const fetched = getKeychainTokens(keychainServices);
                 const keychainBundles = [];
-                for (const name of keychainNames) {
-                    const json = fetched.get(bundleMetaItem(name));
+                for (const service of keychainServices) {
+                    const json = fetched.get(service);
                     if (json === undefined)
                         continue;
-                    const bundle = parseBundleMeta(name, json, 'keychain');
+                    const nameHint = service.startsWith(BUNDLE_META_PREFIX)
+                        ? service.slice(BUNDLE_META_PREFIX.length)
+                        : undefined;
+                    const bundle = parseBundleMeta(nameHint, json, 'keychain');
                     if (bundle)
                         keychainBundles.push(bundle);
                 }
@@ -513,7 +556,9 @@ function stampLastUsed(bundle) {
     }
     try {
         bundle.last_used = new Date(nowMs).toISOString();
-        writeBundle(bundle);
+        // skipBrokerEviction: this stamp fires on every broker HIT; letting it
+        // evict would make the cache destroy itself on first use.
+        writeBundle(bundle, { skipBrokerEviction: true });
     }
     catch {
         // Swallow — telemetry must never block secret resolution.
@@ -694,7 +739,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             emit('secrets.get', {
                 module: 'secrets',
                 bundle: name,
-                caller: opts.caller,
+                operation: opts.caller,
                 status: 'success',
                 source: 'agent',
                 keyCount: Object.keys(filtered.env).length,
@@ -702,6 +747,9 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             return filtered;
         }
     }
+    if (opts.agentOnly) {
+        throw new Error(`Secrets bundle '${name}' is not unlocked in the secrets agent.`);
+    }
     if (backend === 'file')
         assertFileBackendUsable(name);
     const store = itemStore(backend);
@@ -718,7 +766,11 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         ? `read ${name} secrets (for ${opts.caller})`
         : `read ${name} secrets`;
     void reason;
-    const fetched = store.getBatch([metaItem, ...secretItems]);
+    // secretItems are storage names as enumerated (opaque hashed names on macOS
+    // with #316 hashing active, cleartext elsewhere); metaItem is cleartext and
+    // hashed inside getBatch. Deduped because the hashed enumeration spans the
+    // bundle's whole namespace.
+    const fetched = store.getBatch([...new Set([metaItem, ...secretItems])]);
     const json = fetched.get(metaItem);
     if (json === undefined) {
         // For a file-backed bundle the metadata item is on disk (that's how
@@ -784,7 +836,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         emit('secrets.get', {
             module: 'secrets',
             bundle: bundle.name,
-            caller: opts.caller,
+            operation: opts.caller,
             status,
             keyCount: keys.length,
             keys,
@@ -805,7 +857,10 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             }
             if (p.ref.provider === 'keychain') {
                 const item = secretsKeychainItem(bundle.name, p.ref.value);
-                const value = fetched.get(item);
+                // The batch keys results by the names it was ASKED for: the cleartext
+                // metaItem, plus enumerated storage names. Look up the cleartext name
+                // first (Linux / file store), then its hashed storage alias (macOS).
+                const value = fetched.get(item) ?? fetched.get(keychainServiceAlias(item));
                 if (value === undefined) {
                     throw new Error(`Bundle '${bundle.name}' key '${key}': stored item '${item}' not found. ` +
                         `Run: agents secrets add ${bundle.name} ${key}`);

package/dist/lib/secrets/icloud-import.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Recovery for LEGACY SYNCHRONIZABLE (iCloud Keychain) bundles.
+ *
+ * The pre-biometry helper era defaulted bundles to iCloud Keychain sync. The
+ * device-local cutover (biometry ACL + kSecAttrSynchronizable false on every
+ * query) orphaned those items: they still sync back via iCloud Keychain, but
+ * neither `secrets list` nor `migrate-acl` can see them. This module powers
+ * `agents secrets import --from icloud` — discover the orphaned bundles,
+ * re-import them as normal device-local bundles, and optionally purge the
+ * iCloud copies.
+ *
+ * The item-name scheme is the same one the modern store uses (see bundles.ts):
+ * metadata under `agents-cli.bundles.<name>`, one value per key under
+ * `agents-cli.secrets.<bundle>.<key>`. Env keys can never contain a dot
+ * (ENV_KEY_PATTERN), so splitting a secret service at its LAST dot recovers
+ * the bundle/key boundary even for dotted bundle names like `hetzner.com`.
+ */
+import { type SecretsBackend } from './bundles.js';
+/** One orphaned iCloud bundle, as discovered from the synced item names. */
+export interface SyncedBundleCandidate {
+    /** Bundle name derived from the iCloud service names. */
+    name: string;
+    /** Env keys that have a per-key secret item in the iCloud keychain. */
+    keys: string[];
+    /** True when an `agents-cli.bundles.<name>` metadata item exists in iCloud. */
+    hasMeta: boolean;
+    /** Every iCloud service name belonging to this candidate (the purge set). */
+    services: string[];
+}
+/**
+ * Group raw synced service names into per-bundle candidates. Pure — separated
+ * from discovery so the parsing rules are unit-testable without a keychain.
+ *
+ * A bundle can surface as metadata only (`agents-cli.bundles.<name>`), as
+ * secret items only (`agents-cli.secrets.<bundle>.<KEY>` — metadata never
+ * synced), or both; all three shapes appear in real iCloud strays, so every
+ * one becomes a candidate.
+ */
+export declare function groupSyncedServices(services: string[]): SyncedBundleCandidate[];
+/** Enumerate the iCloud keychain and return every orphaned bundle candidate. */
+export declare function discoverSyncedBundles(): SyncedBundleCandidate[];
+export interface ImportSyncedOptions {
+    /** Overwrite keys that already exist in the local bundle. */
+    force?: boolean;
+    /** Store imported values as literals in the bundle metadata (no keychain items). */
+    allPlaintext?: boolean;
+    /** Backend for a newly created bundle (existing bundles keep theirs). */
+    backend?: SecretsBackend;
+    /** Delete the iCloud copies of successfully-read items after import. */
+    purge?: boolean;
+}
+export interface ImportSyncedResult {
+    name: string;
+    added: number;
+    skipped: number;
+    /** Keys whose iCloud value could not be read (left in place, never purged). */
+    missing: string[];
+    /**
+     * Keys the modern store refuses by policy (reserved env names like USER,
+     * loader/interpreter vars like DYLD_*) — the pre-cutover store accepted
+     * them. Left in iCloud, never purged: the iCloud item is the only copy.
+     */
+    unimportable: string[];
+    purged: number;
+}
+/**
+ * Import one discovered iCloud bundle into the local (device-local) store.
+ *
+ * Values come from the synced secret items; the synced metadata item, when
+ * present, contributes the description, literal vars, and non-keychain refs
+ * (env:/file:/exec: refs carry no stored secret, so copying the ref preserves
+ * them exactly). Existing local keys are skipped unless `force`. Keys the
+ * modern store refuses by policy (reserved / loader env names the pre-cutover
+ * store accepted) are reported as `unimportable` instead of aborting the whole
+ * bundle. With `purge`, only services whose value provably lives locally
+ * (imported now, or skipped-because-present) are deleted from iCloud — an
+ * unreadable or unimportable item is never destroyed.
+ */
+export declare function importSyncedBundle(candidate: SyncedBundleCandidate, opts?: ImportSyncedOptions): ImportSyncedResult;

package/dist/lib/secrets/icloud-import.js

@@ -0,0 +1,203 @@
+/**
+ * Recovery for LEGACY SYNCHRONIZABLE (iCloud Keychain) bundles.
+ *
+ * The pre-biometry helper era defaulted bundles to iCloud Keychain sync. The
+ * device-local cutover (biometry ACL + kSecAttrSynchronizable false on every
+ * query) orphaned those items: they still sync back via iCloud Keychain, but
+ * neither `secrets list` nor `migrate-acl` can see them. This module powers
+ * `agents secrets import --from icloud` — discover the orphaned bundles,
+ * re-import them as normal device-local bundles, and optionally purge the
+ * iCloud copies.
+ *
+ * The item-name scheme is the same one the modern store uses (see bundles.ts):
+ * metadata under `agents-cli.bundles.<name>`, one value per key under
+ * `agents-cli.secrets.<bundle>.<key>`. Env keys can never contain a dot
+ * (ENV_KEY_PATTERN), so splitting a secret service at its LAST dot recovers
+ * the bundle/key boundary even for dotted bundle names like `hetzner.com`.
+ */
+import { deleteSyncedKeychainItem, getSyncedKeychainTokens, listSyncedKeychainItems, parseBundleValue, secretsKeychainItem, serializeRef, SECRETS_ITEM_PREFIX, } from './index.js';
+import { BUNDLE_META_PREFIX, BUNDLE_NAME_PATTERN, ENV_KEY_PATTERN, bundleExists, bundleItemStore, bundlePolicy, isLoaderOrInterpreterEnv, isReservedEnvName, keychainRef, readBundle, writeBundle, } from './bundles.js';
+/**
+ * Group raw synced service names into per-bundle candidates. Pure — separated
+ * from discovery so the parsing rules are unit-testable without a keychain.
+ *
+ * A bundle can surface as metadata only (`agents-cli.bundles.<name>`), as
+ * secret items only (`agents-cli.secrets.<bundle>.<KEY>` — metadata never
+ * synced), or both; all three shapes appear in real iCloud strays, so every
+ * one becomes a candidate.
+ */
+export function groupSyncedServices(services) {
+    const byName = new Map();
+    const claim = (name) => {
+        let c = byName.get(name);
+        if (!c) {
+            c = { name, keys: [], hasMeta: false, services: [] };
+            byName.set(name, c);
+        }
+        return c;
+    };
+    for (const svc of services) {
+        if (svc.startsWith(BUNDLE_META_PREFIX)) {
+            const name = svc.slice(BUNDLE_META_PREFIX.length);
+            if (!BUNDLE_NAME_PATTERN.test(name))
+                continue;
+            const c = claim(name);
+            c.hasMeta = true;
+            c.services.push(svc);
+        }
+        else if (svc.startsWith(SECRETS_ITEM_PREFIX)) {
+            const rest = svc.slice(SECRETS_ITEM_PREFIX.length);
+            const cut = rest.lastIndexOf('.');
+            if (cut <= 0)
+                continue;
+            const name = rest.slice(0, cut);
+            const key = rest.slice(cut + 1);
+            if (!BUNDLE_NAME_PATTERN.test(name) || !ENV_KEY_PATTERN.test(key))
+                continue;
+            const c = claim(name);
+            if (!c.keys.includes(key))
+                c.keys.push(key);
+            c.services.push(svc);
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Enumerate the iCloud keychain and return every orphaned bundle candidate. */
+export function discoverSyncedBundles() {
+    return groupSyncedServices(listSyncedKeychainItems('agents-cli.'));
+}
+/**
+ * Import one discovered iCloud bundle into the local (device-local) store.
+ *
+ * Values come from the synced secret items; the synced metadata item, when
+ * present, contributes the description, literal vars, and non-keychain refs
+ * (env:/file:/exec: refs carry no stored secret, so copying the ref preserves
+ * them exactly). Existing local keys are skipped unless `force`. Keys the
+ * modern store refuses by policy (reserved / loader env names the pre-cutover
+ * store accepted) are reported as `unimportable` instead of aborting the whole
+ * bundle. With `purge`, only services whose value provably lives locally
+ * (imported now, or skipped-because-present) are deleted from iCloud — an
+ * unreadable or unimportable item is never destroyed.
+ */
+export function importSyncedBundle(candidate, opts = {}) {
+    const values = getSyncedKeychainTokens(candidate.services);
+    let bundle;
+    if (bundleExists(candidate.name)) {
+        bundle = readBundle(candidate.name);
+    }
+    else {
+        bundle = {
+            name: candidate.name,
+            backend: opts.backend === 'file' ? 'file' : undefined,
+            vars: {},
+        };
+    }
+    const metaService = BUNDLE_META_PREFIX + candidate.name;
+    let metaVars = {};
+    const metaJson = values.get(metaService);
+    if (metaJson !== undefined) {
+        try {
+            const parsed = JSON.parse(metaJson);
+            if (parsed && typeof parsed === 'object') {
+                if (typeof parsed.description === 'string' && !bundle.description) {
+                    bundle.description = parsed.description;
+                }
+                if (parsed.vars && typeof parsed.vars === 'object') {
+                    metaVars = parsed.vars;
+                }
+            }
+        }
+        catch {
+            // Corrupt legacy metadata — the per-key secret items still import.
+        }
+    }
+    const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
+    let added = 0;
+    let skipped = 0;
+    const missing = [];
+    const unimportable = [];
+    // Services whose value now provably lives in the local store — imported this
+    // run, or skipped because the local bundle already carries the key. Only
+    // these may be purged; a missing or unimportable key's iCloud item is its
+    // only copy and must survive.
+    const purgeable = new Set();
+    const rejectedByPolicy = (key) => isLoaderOrInterpreterEnv(key) || isReservedEnvName(key);
+    // Keys with a synced secret item: re-store the value device-locally.
+    for (const key of candidate.keys) {
+        // The pre-cutover store accepted keys the modern one refuses (writeBundle
+        // throws) — skip them instead of aborting the whole bundle.
+        if (rejectedByPolicy(key)) {
+            unimportable.push(key);
+            continue;
+        }
+        const value = values.get(secretsKeychainItem(candidate.name, key));
+        if (value === undefined) {
+            missing.push(key);
+            continue;
+        }
+        if (!opts.force && key in bundle.vars) {
+            skipped++;
+            purgeable.add(secretsKeychainItem(candidate.name, key));
+            continue;
+        }
+        if (opts.allPlaintext) {
+            bundle.vars[key] = { value };
+        }
+        else {
+            store.set(secretsKeychainItem(candidate.name, key), value);
+            bundle.vars[key] = keychainRef(key);
+        }
+        purgeable.add(secretsKeychainItem(candidate.name, key));
+        added++;
+    }
+    // Vars declared only in the synced metadata: literals and non-keychain refs
+    // carry everything they need; a keychain ref without its synced item is
+    // unrecoverable.
+    for (const [key, raw] of Object.entries(metaVars)) {
+        if (!ENV_KEY_PATTERN.test(key))
+            continue;
+        if (candidate.keys.includes(key))
+            continue; // the secret item already covered it
+        if (rejectedByPolicy(key)) {
+            if (!unimportable.includes(key))
+                unimportable.push(key);
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = parseBundleValue(raw);
+        }
+        catch {
+            continue; // malformed legacy entry
+        }
+        if ('ref' in parsed && parsed.ref.provider === 'keychain') {
+            if (!missing.includes(key))
+                missing.push(key);
+            continue;
+        }
+        if (!opts.force && key in bundle.vars) {
+            skipped++;
+            continue;
+        }
+        bundle.vars[key] = 'literal' in parsed ? { value: parsed.literal } : serializeRef(parsed.ref);
+        added++;
+    }
+    writeBundle(bundle);
+    // The metadata item is only a projection of what was just written locally —
+    // safe to purge once writeBundle has succeeded, UNLESS it still names keys
+    // that never made it over (missing/unimportable): then it stays as the only
+    // record of them.
+    if (metaJson !== undefined && missing.length === 0 && unimportable.length === 0) {
+        purgeable.add(metaService);
+    }
+    let purged = 0;
+    if (opts.purge) {
+        for (const svc of candidate.services) {
+            if (!purgeable.has(svc))
+                continue;
+            if (deleteSyncedKeychainItem(svc))
+                purged++;
+        }
+    }
+    return { name: candidate.name, added, skipped, missing, unimportable, purged };
+}