@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/lib/runner.js

@@ -5,6 +5,13 @@
  * sandboxed or unsandboxed environments, captures stdout to log files,
  * enforces timeouts, and extracts the final assistant report from the
  * agent's stream-JSON output.
+ *
+ * Version/account selection mirrors `agents run`: when a routine does not pin
+ * `version:`, the runner uses the configured run strategy (default `balanced`)
+ * to pick a healthy install, pins the absolute binary via `getBinaryPath`, and
+ * arms same-agent failover across other healthy accounts when a rate/usage
+ * limit is detected mid-run (foreground `executeJob` only — detached daemon
+ * fires once with the pre-flight pick).
  */
 import { spawn } from 'child_process';
 import * as fs from 'fs';
@@ -15,8 +22,10 @@ import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
 import { createTimer, maybeRotate, redactPrompt } from './events.js';
-import { normalizeMode } from './exec.js';
+import { normalizeMode, buildExecEnv, detectRateLimit, } from './exec.js';
 import { backgroundSpawnOptions } from './platform/process.js';
+import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
+import { getConfiguredRunStrategy, resolveRunVersion, rotationFailoverChain, readinessFromCandidate, } from './rotate.js';
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
@@ -161,6 +170,201 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/**
+ * Resolve the version/account chain for a routine the same way `agents run`
+ * does: honor an explicit `version:` pin; otherwise use the configured run
+ * strategy (default `balanced`) so credit-exhausted / rate-limited accounts
+ * are skipped pre-flight, and synthesize a same-agent failover chain from the
+ * other healthy accounts for mid-run rate limits.
+ *
+ * Workflows are left alone — `agents run <workflow>` owns selection.
+ */
+export async function resolveRoutineLaunch(config, cwd = process.cwd()) {
+    if (config.workflow) {
+        return { chain: [], rotation: null, pinned: false };
+    }
+    const agent = config.agent;
+    if (config.version) {
+        const version = config.version;
+        if (!isVersionInstalled(agent, version)) {
+            process.stderr.write(`[agents] routine ${config.name}: pinned ${agent}@${version} is not installed\n`);
+        }
+        return {
+            chain: [{ agent, version }],
+            rotation: null,
+            pinned: true,
+        };
+    }
+    const strategy = getConfiguredRunStrategy(agent, cwd);
+    let version;
+    let rotation = null;
+    try {
+        const resolved = await resolveRunVersion(agent, strategy, cwd);
+        version = resolved.version ?? undefined;
+        rotation = resolved.rotation;
+        if (rotation) {
+            const label = rotation.picked.email
+                ? `${rotation.picked.email} · ${agent}@${rotation.picked.version}`
+                : `${agent}@${rotation.picked.version}`;
+            const ratio = `${rotation.healthy.length} of ${rotation.healthy.length + rotation.excluded.length} healthy`;
+            process.stderr.write(`[agents] routine ${config.name}: ${strategy} picked ${label} (${ratio})\n`);
+            if (rotation.excluded.length > 0) {
+                const reasons = rotation.excluded
+                    .map((c) => {
+                    const r = readinessFromCandidate(c);
+                    const why = r.ready ? 'deduped' : r.reason;
+                    return `${c.agent}@${c.version}=${why}`;
+                })
+                    .join(', ');
+                process.stderr.write(`[agents] routine ${config.name}: skipped ${reasons}\n`);
+            }
+        }
+        else if (!version) {
+            process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} found no usable ${agent} version; ` +
+                `falling back to default pin\n`);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`[agents] routine ${config.name}: strategy ${strategy} skipped: ${err.message}\n`);
+    }
+    if (!version) {
+        version = resolveVersion(agent, cwd) ?? undefined;
+    }
+    if (!version) {
+        process.stderr.write(`[agents] routine ${config.name}: no version of ${agent} configured — ` +
+            `run: agents add ${agent}@<version> && agents use ${agent} <version>\n`);
+        return { chain: [{ agent }], rotation: null, pinned: false };
+    }
+    const failover = rotationFailoverChain(rotation, version);
+    if (failover.length > 0) {
+        const labels = failover.map((f) => `${f.agent}@${f.version}`).join(', ');
+        process.stderr.write(`[agents] routine ${config.name}: credit/rate-limit failover armed → ${labels}\n`);
+    }
+    return {
+        chain: [{ agent, version }, ...failover],
+        rotation,
+        pinned: false,
+    };
+}
+/**
+ * Rewrite `cmd[0]` to the absolute binary for `agent@version` when installed.
+ * Bypasses the bare-name shim so a sandboxed HOME / missing default pin cannot
+ * surface as "agents: no version of X configured".
+ */
+export function pinJobBinary(cmd, agent, version) {
+    if (!version || cmd.length === 0)
+        return cmd;
+    if (!isVersionInstalled(agent, version))
+        return cmd;
+    const binary = getBinaryPath(agent, version);
+    if (!binary || !fs.existsSync(binary))
+        return cmd;
+    const next = [...cmd];
+    next[0] = binary;
+    return next;
+}
+/**
+ * Merge sandbox/base env with the canonical per-version exec env
+ * (CLAUDE_CONFIG_DIR / CODEX_HOME / …) so routines share account isolation
+ * with `agents run`.
+ */
+export function buildRoutineSpawnEnv(baseEnv, agent, version, timezone) {
+    const execEnv = buildExecEnv({
+        agent,
+        version,
+        mode: 'plan',
+        effort: 'auto',
+        headless: true,
+        env: baseEnv,
+    });
+    const out = {};
+    for (const [k, v] of Object.entries(execEnv)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    if (timezone)
+        out.TZ = timezone;
+    return out;
+}
+/**
+ * Spawn one attempt, capture logs to `attemptLogPath`, enforce timeout.
+ * Rate-limit scanning uses only this attempt's log (not prior failover output).
+ * The attempt log is also appended into `combinedLogPath` for a continuous trail.
+ */
+function spawnJobAttempt(cmd, env, attemptLogPath, timeoutMs, combinedLogPath) {
+    // Isolate this attempt's output so detectRateLimit never sees prior attempts.
+    fs.writeFileSync(attemptLogPath, '', { mode: 0o600 });
+    const stdoutFd = fs.openSync(attemptLogPath, 'a', 0o600);
+    return new Promise((resolve) => {
+        const child = spawn(cmd[0], cmd.slice(1), {
+            stdio: ['ignore', stdoutFd, stdoutFd],
+            ...backgroundSpawnOptions({ fdStdio: true }),
+            env,
+        });
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                fs.closeSync(stdoutFd);
+            }
+            catch { /* fd already closed */ }
+            let logText = '';
+            try {
+                logText = fs.readFileSync(attemptLogPath, 'utf-8');
+            }
+            catch { /* missing log */ }
+            if (combinedLogPath) {
+                try {
+                    fs.appendFileSync(combinedLogPath, logText);
+                }
+                catch { /* best-effort trail */ }
+            }
+            resolve({ ...result, logText });
+        };
+        const timeoutTimer = setTimeout(() => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGTERM');
+            }
+            catch { /* process already exited */ }
+            setTimeout(() => {
+                try {
+                    if (child.pid)
+                        process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* process already exited */ }
+            }, 5000);
+            finish({
+                exitCode: null,
+                status: 'timeout',
+                pid: child.pid || null,
+                logText: '',
+            });
+        }, timeoutMs);
+        child.on('exit', (code) => {
+            clearTimeout(timeoutTimer);
+            finish({
+                exitCode: code,
+                status: code === 0 ? 'completed' : 'failed',
+                pid: child.pid || null,
+                logText: '',
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeoutTimer);
+            finish({
+                exitCode: 1,
+                status: 'failed',
+                error: err.message,
+                pid: child.pid || null,
+                logText: '',
+            });
+        });
+        child.unref();
+    });
+}
 /**
  * Execute a job synchronously (waits for completion or timeout before resolving).
  *
@@ -169,12 +373,17 @@ function generateRunId() {
  * workflow `loop:` blocks (issue #400). The optional `deps` parameter provides
  * injectable seams (runIteration, sleep, writeCheckpoint) used by tests; production
  * callers omit it and get the defaults.
+ *
+ * Single-shot path: pre-flight version/account selection + mid-run rate-limit
+ * failover across healthy same-agent accounts (RUSH-1016).
  */
 export async function executeJob(config, deps) {
     maybeRotate();
+    const launch = await resolveRoutineLaunch(config);
+    const primaryVersion = launch.chain[0]?.version ?? config.version;
     const timer = createTimer('agent.run', {
         agent: config.agent,
-        version: config.version,
+        version: primaryVersion,
         jobName: config.name,
         mode: config.mode,
         ...redactPrompt(config.prompt),
@@ -186,10 +395,9 @@ export async function executeJob(config, deps) {
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
     fs.mkdirSync(runDir, { recursive: true });
-    let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
-    if (config.timezone) {
-        spawnEnv.TZ = config.timezone;
-    }
+    const baseEnv = useSandbox
+        ? buildSpawnEnv(overlayHome)
+        : { ...process.env };
     // Workflows run via `agents run <workflow>` which delegates to claude under the hood.
     // Use 'claude' as the effective agent for report extraction and metadata when workflow is set.
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
@@ -208,9 +416,10 @@ export async function executeJob(config, deps) {
     const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
     // Loop path: delegate to runLoop (same driver as `agents run --loop` / workflow loop:).
     if (config.loop) {
+        const spawnEnv = buildRoutineSpawnEnv(baseEnv, effectiveAgent, primaryVersion, config.timezone);
         const execOptions = {
             agent: effectiveAgent,
-            version: config.version,
+            version: primaryVersion,
             prompt: resolvedPrompt,
             mode: normalizeMode(config.mode),
             effort: config.effort,
@@ -229,7 +438,7 @@ export async function executeJob(config, deps) {
             runId,
             runDir,
             agent: effectiveAgent,
-            version: config.version,
+            version: primaryVersion,
         }, deps);
         meta.status = loopResult.stoppedBy === 'error' ? 'failed' : 'completed';
         meta.completedAt = new Date().toISOString();
@@ -238,83 +447,105 @@ export async function executeJob(config, deps) {
         timer.end({ status: meta.status, exitCode: meta.exitCode ?? undefined, runId });
         return { meta, reportPath: null };
     }
-    // Single-shot path (no loop): build the command, open a log file, and spawn once.
-    const cmd = buildJobCommand(config, resolvedPrompt);
+    // Single-shot path: build the command once, then walk the launch chain on
+    // rate/usage-limit failures (same detectRateLimit patterns as agents run).
+    const baseCmd = buildJobCommand(config, resolvedPrompt);
     const stdoutPath = path.join(runDir, 'stdout.log');
-    const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
-    return new Promise((resolve) => {
-        const child = spawn(cmd[0], cmd.slice(1), {
-            stdio: ['ignore', stdoutFd, stdoutFd],
-            ...backgroundSpawnOptions({ fdStdio: true }),
-            env: spawnEnv,
-        });
-        // Mark startup time (time from function call to process spawn)
-        timer.mark('startup');
-        meta.pid = child.pid || null;
+    // Truncate the log for a clean run; failover attempts append.
+    fs.writeFileSync(stdoutPath, '', { mode: 0o600 });
+    const chain = launch.chain.length > 0
+        ? launch.chain
+        : [{ agent: effectiveAgent, version: primaryVersion }];
+    timer.mark('startup');
+    for (let i = 0; i < chain.length; i++) {
+        const entry = chain[i];
+        const attemptAgent = entry.agent;
+        const attemptVersion = entry.version;
+        const label = attemptVersion ? `${attemptAgent}@${attemptVersion}` : attemptAgent;
+        if (i === 0) {
+            process.stderr.write(`[agents] routine ${config.name}: running ${label}\n`);
+        }
+        const cmd = config.workflow
+            ? baseCmd
+            : pinJobBinary(baseCmd, attemptAgent, attemptVersion);
+        const spawnEnv = config.workflow
+            ? (() => {
+                const e = { ...baseEnv };
+                if (config.timezone)
+                    e.TZ = config.timezone;
+                return e;
+            })()
+            : buildRoutineSpawnEnv(baseEnv, attemptAgent, attemptVersion, config.timezone);
+        // Remaining timeout budget shared across failover attempts.
+        const elapsed = Date.now() - Date.parse(meta.startedAt);
+        const remaining = Math.max(1_000, timeoutMs - (Number.isFinite(elapsed) ? elapsed : 0));
+        const attemptLogPath = path.join(runDir, `stdout.attempt-${i}.log`);
+        const attempt = await spawnJobAttempt(cmd, spawnEnv, attemptLogPath, remaining, stdoutPath);
+        meta.pid = attempt.pid;
         writeRunMeta(meta);
-        let settled = false;
-        const timeoutTimer = setTimeout(() => {
-            if (settled)
-                return;
-            settled = true;
-            try {
-                if (child.pid)
-                    process.kill(-child.pid, 'SIGTERM');
-            }
-            catch { /* process already exited */ }
-            setTimeout(() => {
-                try {
-                    if (child.pid)
-                        process.kill(-child.pid, 'SIGKILL');
-                }
-                catch { /* process already exited */ }
-            }, 5000);
+        if (attempt.status === 'timeout') {
             meta.status = 'timeout';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
             timer.end({ status: 'timeout', runId });
             const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
-            resolve({ meta, reportPath });
-        }, timeoutMs);
-        child.on('exit', (code) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeoutTimer);
-            try {
-                fs.closeSync(stdoutFd);
-            }
-            catch { /* fd already closed */ }
-            meta.exitCode = code;
-            meta.status = code === 0 ? 'completed' : 'failed';
+            return { meta, reportPath };
+        }
+        if (attempt.status === 'completed') {
+            meta.exitCode = 0;
+            meta.status = 'completed';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
-            timer.end({ status: meta.status, exitCode: code ?? undefined, runId });
+            timer.end({ status: 'completed', exitCode: 0, runId });
             const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
-            resolve({ meta, reportPath });
-        });
-        child.on('error', (err) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timeoutTimer);
-            try {
-                fs.closeSync(stdoutFd);
-            }
-            catch { /* fd already closed */ }
-            meta.status = 'failed';
-            meta.completedAt = new Date().toISOString();
-            writeRunMeta(meta);
-            timer.end({ status: 'failed', error: err.message, runId });
-            resolve({ meta, reportPath: null });
+            return { meta, reportPath };
+        }
+        // Failed — cascade only on rate/usage limit when more chain entries remain.
+        const isLast = i === chain.length - 1;
+        const rateLimited = detectRateLimit(attempt.logText) || (attempt.error ? detectRateLimit(attempt.error) : false);
+        if (!isLast && rateLimited) {
+            const next = chain[i + 1];
+            const nextLabel = next.version ? `${next.agent}@${next.version}` : next.agent;
+            process.stderr.write(`[agents] routine ${config.name}: ${label} failed with credit/rate limit, trying ${nextLabel}\n`);
+            fs.appendFileSync(stdoutPath, `\n[agents] ${label} hit rate/usage limit — failover → ${nextLabel}\n`);
+            continue;
+        }
+        if (attempt.error) {
+            process.stderr.write(`[agents] routine ${config.name}: spawn failed for ${label}: ${attempt.error}\n`);
+        }
+        meta.exitCode = attempt.exitCode ?? 1;
+        meta.status = 'failed';
+        meta.completedAt = new Date().toISOString();
+        writeRunMeta(meta);
+        timer.end({
+            status: 'failed',
+            exitCode: meta.exitCode ?? undefined,
+            runId,
+            ...(attempt.error ? { error: attempt.error } : {}),
         });
-        child.unref();
-    });
+        const reportPath = extractAndSaveReport(stdoutPath, effectiveAgent, runDir);
+        return { meta, reportPath };
+    }
+    // Unreachable: chain is always non-empty, but keep a safe fallback.
+    meta.status = 'failed';
+    meta.exitCode = 1;
+    meta.completedAt = new Date().toISOString();
+    writeRunMeta(meta);
+    timer.end({ status: 'failed', exitCode: 1, runId });
+    return { meta, reportPath: null };
 }
 /** Spawn a job as a detached process and return immediately with run metadata. */
 export async function executeJobDetached(config) {
+    // Pre-flight: pick a healthy version/account so the daemon does not launch
+    // into a credit-exhausted install. Detached cannot mid-run failover (no exit
+    // wait); the next schedule tick re-selects if this attempt still fails.
+    const launch = await resolveRoutineLaunch(config);
+    const version = launch.chain[0]?.version ?? config.version;
     const resolvedPrompt = resolveJobPrompt(config);
-    const cmd = buildJobCommand(config, resolvedPrompt);
+    let cmd = buildJobCommand(config, resolvedPrompt);
+    if (!config.workflow && version) {
+        cmd = pinJobBinary(cmd, config.agent, version);
+    }
     const useSandbox = config.sandbox !== false;
     const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
     const runId = generateRunId();
@@ -322,10 +553,17 @@ export async function executeJobDetached(config) {
     fs.mkdirSync(runDir, { recursive: true });
     const stdoutPath = path.join(runDir, 'stdout.log');
     const stdoutFd = fs.openSync(stdoutPath, 'w', 0o600);
-    let spawnEnv = useSandbox ? buildSpawnEnv(overlayHome) : { ...process.env };
-    if (config.timezone) {
-        spawnEnv.TZ = config.timezone;
-    }
+    const baseEnv = useSandbox
+        ? buildSpawnEnv(overlayHome)
+        : { ...process.env };
+    const spawnEnv = config.workflow
+        ? (() => {
+            const e = { ...baseEnv };
+            if (config.timezone)
+                e.TZ = config.timezone;
+            return e;
+        })()
+        : buildRoutineSpawnEnv(baseEnv, config.agent, version, config.timezone);
     const effectiveAgent = config.workflow ? 'claude' : config.agent;
     const meta = {
         jobName: config.name,
@@ -343,6 +581,17 @@ export async function executeJobDetached(config) {
         ...backgroundSpawnOptions({ fdStdio: true }),
         env: spawnEnv,
     });
+    child.on('error', (err) => {
+        try {
+            fs.closeSync(stdoutFd);
+        }
+        catch { /* fd already closed */ }
+        meta.status = 'failed';
+        meta.exitCode = 1;
+        meta.completedAt = new Date().toISOString();
+        writeRunMeta(meta);
+        process.stderr.write(`[agents] daemon: spawn failed for job "${config.name}": ${err.message}\n`);
+    });
     child.unref();
     try {
         fs.closeSync(stdoutFd);

package/dist/lib/sandbox.js

@@ -43,6 +43,12 @@ const ENV_ALLOWLIST = [
     'VISUAL',
     'NO_COLOR',
     'FORCE_COLOR',
+    // Headless Claude auth: the routines daemon injects CLAUDE_CODE_OAUTH_TOKEN
+    // from the `claude` secrets bundle (see daemon.ts). Without this allowlist
+    // entry, sandboxed routine spawns drop the token and look "unconfigured".
+    // Intentionally NOT ANTHROPIC_API_KEY / other provider secrets — those stay
+    // stripped (see tests/sandbox.test.ts "does not include sensitive env vars").
+    'CLAUDE_CODE_OAUTH_TOKEN',
 ];
 /** Tools safe to grant as wildcards (no filesystem access). */
 const SAFE_TOOLS = {

package/dist/lib/secrets/bundles.js

@@ -21,7 +21,7 @@ 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';
@@ -328,6 +328,10 @@ export function writeBundle(bundle, opts = {}) {
         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,
@@ -376,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);
@@ -387,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,
@@ -431,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
@@ -452,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;
@@ -461,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);
                 }
@@ -748,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
@@ -835,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

@@ -55,6 +55,12 @@ export interface ImportSyncedResult {
     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;
 }
 /**
@@ -63,8 +69,11 @@ export interface ImportSyncedResult {
  * 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`. With `purge`,
- * only services whose value was successfully read are deleted from iCloud —
- * an unreadable item is never destroyed.
+ * 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;