@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/runner.js

@@ -16,6 +16,7 @@ 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 { backgroundSpawnOptions } from './platform/process.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'],
@@ -152,8 +153,16 @@ function appendModelAndReasoning(cmd, config) {
 function generateRunId() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
-/** Execute a job synchronously (waits for completion or timeout before resolving). */
-export async function executeJob(config) {
+/**
+ * Execute a job synchronously (waits for completion or timeout before resolving).
+ *
+ * When `config.loop` is set the job is routed through the loop driver (`runLoop`
+ * from loop.ts) instead of a single spawn — same driver as `agents run --loop` and
+ * 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.
+ */
+export async function executeJob(config, deps) {
     maybeRotate();
     const timer = createTimer('agent.run', {
         agent: config.agent,
@@ -164,14 +173,11 @@ export async function executeJob(config) {
         schedule: config.schedule,
     });
     const resolvedPrompt = resolveJobPrompt(config);
-    const cmd = buildJobCommand(config, resolvedPrompt);
     const useSandbox = config.sandbox !== false;
     const overlayHome = useSandbox ? prepareJobHome(config) : undefined;
     const runId = generateRunId();
     const runDir = getRunDir(config.name, runId);
     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;
@@ -192,10 +198,46 @@ export async function executeJob(config) {
     };
     writeRunMeta(meta);
     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 execOptions = {
+            agent: effectiveAgent,
+            version: config.version,
+            prompt: resolvedPrompt,
+            mode: normalizeMode(config.mode),
+            effort: config.effort,
+            env: spawnEnv,
+            json: true,
+            headless: true,
+            ...(config.config?.model ? { model: config.config.model } : {}),
+            ...(config.allow?.dirs ? {
+                addDirs: config.allow.dirs
+                    .filter((d) => !d.startsWith('-'))
+                    .map((d) => d.replace(/^~/, os.homedir())),
+            } : {}),
+        };
+        const { runLoop } = await import('./loop.js');
+        const loopResult = await runLoop(execOptions, config.loop, {
+            runId,
+            runDir,
+            agent: effectiveAgent,
+            version: config.version,
+        }, deps);
+        meta.status = loopResult.stoppedBy === 'error' ? 'failed' : 'completed';
+        meta.completedAt = new Date().toISOString();
+        meta.exitCode = loopResult.stoppedBy === 'error' ? 1 : 0;
+        writeRunMeta(meta);
+        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);
+    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],
-            detached: true,
+            ...backgroundSpawnOptions({ fdStdio: true }),
             env: spawnEnv,
         });
         // Mark startup time (time from function call to process spawn)
@@ -290,7 +332,7 @@ export async function executeJobDetached(config) {
     };
     const child = spawn(cmd[0], cmd.slice(1), {
         stdio: ['ignore', stdoutFd, stdoutFd],
-        detached: true,
+        ...backgroundSpawnOptions({ fdStdio: true }),
         env: spawnEnv,
     });
     child.unref();

package/dist/lib/scheduler.js

@@ -17,12 +17,17 @@ export class JobScheduler {
     loadAll() {
         const configs = listJobs();
         for (const config of configs) {
-            if (config.enabled) {
+            // Trigger-only jobs (no cron schedule) fire via the webhook receiver,
+            // not the cron loop — skip them here.
+            if (config.enabled && config.schedule) {
                 this.schedule(config);
             }
         }
     }
     schedule(config) {
+        // A schedule-less (trigger-only) job has nothing to hand to croner.
+        if (!config.schedule)
+            return;
         this.unschedule(config.name);
         // catch: true — a throw from one job's callback should not kill the
         // whole cron loop. Each invocation of onTrigger is already wrapped in

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

@@ -48,13 +48,20 @@ export interface VarMeta {
  * - `always`: asks every time. Never auto-held — only an explicit `agents
  *   secrets unlock` ever holds it; every other read pops Touch ID. Opt a
  *   high-value bundle into this when you want to confirm every single read.
+ * - `never`: stored WITHOUT the biometry access control — reads are fully
+ *   silent (no Touch ID, no broker). The least-safe tier: any code running as
+ *   the user reads it with no user-presence check. Reserved for low-sensitivity,
+ *   automation-only credentials. Writing a `never` item needs the signed helper's
+ *   `set-no-acl` path (see keychain-helper.swift); an older pinned helper rejects
+ *   it loudly rather than silently downgrading to `always`.
  *
  * The default is configurable via `secrets.policy` in agents.yaml. Stored on disk
  * under the legacy `tier` key (`session` == `daily`, `biometry` == explicit
- * `always`, absent == inherit the default) so bundles stay readable across mixed
- * CLI versions on synced machines. The user-facing vocabulary is `policy`/`always`/`daily`.
+ * `always`, `none` == `never`, absent == inherit the default) so bundles stay
+ * readable across mixed CLI versions on synced machines. The user-facing
+ * vocabulary is `policy`/`always`/`daily`/`never`.
  */
-export type SecretsPolicy = 'always' | 'daily';
+export type SecretsPolicy = 'always' | 'daily' | 'never';
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
@@ -131,7 +138,54 @@ export interface ResolveBundleOptions {
      * needs live values. Also honored via AGENTS_SECRETS_NO_AGENT=1.
      */
     noAgent?: 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
+     * requested key is absent from the bundle (fail-loud, never silent skip).
+     * When absent or empty, all keys are injected (original behaviour).
+     */
+    keys?: string[];
+    /**
+     * When true, skip the pre-run expiry check and inject keys even if their
+     * `expires` date is in the past. By default any expired key (or a key whose
+     * bundle-level expiry has passed) aborts the run before Touch ID is popped.
+     */
+    allowExpired?: boolean;
 }
+/**
+ * Apply the --keys subset + expiry gate to an already-resolved snapshot from
+ * the secrets-agent fast-path. The agent stores the FULL bundle env, so a
+ * naive fast-path return would silently defeat --keys and inject expired
+ * values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
+ * `readAndResolveBundleEnv` and returns a new env whose keys match the subset.
+ *
+ * Exported for tests; production callers reach it via the fast-path branch in
+ * `readAndResolveBundleEnv`.
+ */
+export declare function filterAgentHitBySubsetAndExpiry(hit: {
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+}, opts: ResolveBundleOptions): {
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+};
+/**
+ * Guard for remote-bundle callers (`bundle@host` / `--host`) — the SSH
+ * resolver in `remoteResolveEnv` does not thread --keys or --allow-expired
+ * yet. Silently applying them would inject the full remote env or an expired
+ * value, defeating the least-privilege intent, so we fail loud.
+ *
+ * Exported so `agents run --secrets bundle@host` and `agents secrets exec
+ * --host` share the exact same error text; the tests exercise this helper
+ * directly instead of driving the whole CLI.
+ */
+export declare function assertRemoteBundleFlagsUnsupported(bundleName: string, host: string, opts: {
+    keys?: string[];
+    allowExpired?: boolean;
+}, flagLabels: {
+    keysFlag: string;
+    allowExpiredFlag: string;
+}): void;
 export declare function resolveBundleEnv(bundle: SecretsBundle, _opts?: ResolveBundleOptions): Record<string, string>;
 /**
  * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
@@ -193,7 +247,9 @@ export declare function renameBundle(oldName: string, newName: string, opts?: Re
  * `import` / `remove` / `delete`. Pass the bundle's resolved backend
  * (`bundle.backend ?? 'keychain'`).
  */
-export declare function bundleItemStore(backend: SecretsBackend | undefined): {
+export declare function bundleItemStore(backend: SecretsBackend | undefined, opts?: {
+    noAcl?: boolean;
+}): {
     set(item: string, value: string): void;
     delete(item: string): boolean;
     get(item: string): string;

package/dist/lib/secrets/bundles.js

@@ -257,6 +257,8 @@ function parsePolicy(raw) {
         return 'daily';
     if (raw === 'always' || raw === 'biometry')
         return 'always';
+    if (raw === 'never' || raw === 'none')
+        return 'never';
     return undefined;
 }
 /** The default prompt policy applied to bundles without an explicit per-bundle
@@ -314,9 +316,14 @@ export function writeBundle(bundle) {
         backend: backend === 'file' ? 'file' : undefined,
         // Wire format: persist the policy under the legacy `tier` token so older CLI
         // versions on other synced machines keep reading it — `daily`⇒`session`,
-        // explicit `always`⇒`biometry`. An absent policy omits the token entirely
-        // and resolves to the configured default (`daily`) on read.
-        tier: bundle.policy === 'daily' ? 'session' : bundle.policy === 'always' ? 'biometry' : undefined,
+        // explicit `always`⇒`biometry`, `never`⇒`none`. An absent policy omits the
+        // token entirely and resolves to the configured default (`daily`) on read.
+        // An older CLI that doesn't know `none` reads it as undefined and falls back
+        // to its own default — safe, since it also lacks the no-ACL write path.
+        tier: bundle.policy === 'daily' ? 'session'
+            : bundle.policy === 'always' ? 'biometry'
+                : bundle.policy === 'never' ? 'none'
+                    : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,
@@ -324,7 +331,11 @@ export function writeBundle(bundle) {
         meta,
     };
     const json = JSON.stringify(payload);
-    itemStore(backend).set(bundleMetaItem(bundle.name), json);
+    // A `never` bundle's metadata is stored without the biometry ACL too, so
+    // `view` and the metadata half of a read resolve silently — the whole point
+    // of the tier. On an un-updated pinned helper this write fails loudly (the
+    // 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', { bundle: bundle.name });
 }
 export function deleteBundle(name) {
@@ -504,6 +515,87 @@ function stampLastUsed(bundle) {
         // Swallow — telemetry must never block secret resolution.
     }
 }
+/**
+ * Abort if any of the selected keys has an `expires` date in the past.
+ * Bundle-level expiry is not a concept today (expiry is per-key via `meta`),
+ * so we iterate only the per-key meta entries.
+ */
+function assertNotExpired(bundle, selectedKeys, allowExpired) {
+    if (allowExpired)
+        return;
+    if (!bundle.meta)
+        return;
+    const now = Date.now();
+    for (const key of selectedKeys) {
+        const meta = bundle.meta[key];
+        if (!meta?.expires)
+            continue;
+        // expires is 'YYYY-MM-DD'; treat as end-of-day UTC.
+        const expiry = new Date(meta.expires + 'T23:59:59Z').getTime();
+        if (expiry < now) {
+            throw new Error(`Bundle '${bundle.name}' key '${key}' expired on ${meta.expires}. ` +
+                `Rotate it with: agents secrets rotate ${bundle.name} ${key}` +
+                ` (or pass --allow-expired to skip this check).`);
+        }
+    }
+}
+/**
+ * Resolve the requested key subset against a bundle's `vars` map. Throws a
+ * fail-loud error listing available keys if any requested key is absent. When
+ * `requested` is undefined or empty, every key in the bundle is selected.
+ */
+function selectRequestedKeys(bundle, requested) {
+    const req = requested?.length ? requested : undefined;
+    if (req) {
+        const missing = req.filter((k) => !(k in bundle.vars));
+        if (missing.length > 0) {
+            const available = Object.keys(bundle.vars).join(', ') || '(none)';
+            throw new Error(`Bundle '${bundle.name}' does not contain key(s): ${missing.join(', ')}. Available: ${available}.`);
+        }
+    }
+    return new Set(req ?? Object.keys(bundle.vars));
+}
+/**
+ * Apply the --keys subset + expiry gate to an already-resolved snapshot from
+ * the secrets-agent fast-path. The agent stores the FULL bundle env, so a
+ * naive fast-path return would silently defeat --keys and inject expired
+ * values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
+ * `readAndResolveBundleEnv` and returns a new env whose keys match the subset.
+ *
+ * Exported for tests; production callers reach it via the fast-path branch in
+ * `readAndResolveBundleEnv`.
+ */
+export function filterAgentHitBySubsetAndExpiry(hit, opts) {
+    const selectedKeys = selectRequestedKeys(hit.bundle, opts.keys);
+    assertNotExpired(hit.bundle, [...selectedKeys], opts.allowExpired ?? false);
+    // When no subset was requested, return the cached env untouched — same
+    // reference the agent handed back, so no per-call allocation on the hot path.
+    if (!opts.keys?.length)
+        return hit;
+    const env = {};
+    for (const key of selectedKeys) {
+        if (key in hit.env)
+            env[key] = hit.env[key];
+    }
+    return { bundle: hit.bundle, env };
+}
+/**
+ * Guard for remote-bundle callers (`bundle@host` / `--host`) — the SSH
+ * resolver in `remoteResolveEnv` does not thread --keys or --allow-expired
+ * yet. Silently applying them would inject the full remote env or an expired
+ * value, defeating the least-privilege intent, so we fail loud.
+ *
+ * Exported so `agents run --secrets bundle@host` and `agents secrets exec
+ * --host` share the exact same error text; the tests exercise this helper
+ * directly instead of driving the whole CLI.
+ */
+export function assertRemoteBundleFlagsUnsupported(bundleName, host, opts, flagLabels) {
+    const hasKeys = Array.isArray(opts.keys) && opts.keys.length > 0;
+    if (!hasKeys && !opts.allowExpired)
+        return;
+    throw new Error(`Bundle '${bundleName}@${host}': ${flagLabels.keysFlag} and ${flagLabels.allowExpiredFlag} are not supported for remote (bundle@host) bundles yet. ` +
+        `Drop the flag or resolve the bundle locally.`);
+}
 // Walk the bundle and produce a flat env map. Every keychain: ref is gathered
 // into a single batch read so macOS shows ONE Touch ID prompt for the whole
 // bundle — including the metadata fetch that already happened in readBundle
@@ -513,9 +605,14 @@ function stampLastUsed(bundle) {
 // resolved inline and never reach the keychain.
 export function resolveBundleEnv(bundle, _opts = {}) {
     stampLastUsed(bundle);
+    // Key-subset validation and expiry pre-check.
+    const selectedKeys = selectRequestedKeys(bundle, _opts.keys);
+    assertNotExpired(bundle, [...selectedKeys], _opts.allowExpired ?? false);
     const parsedByKey = new Map();
     const keychainItemsToFetch = [];
     for (const [key, raw] of Object.entries(bundle.vars)) {
+        if (!selectedKeys.has(key))
+            continue;
         const parsed = parseBundleValue(raw);
         parsedByKey.set(key, parsed);
         if ('ref' in parsed && parsed.ref.provider === 'keychain') {
@@ -528,6 +625,8 @@ export function resolveBundleEnv(bundle, _opts = {}) {
         : new Map();
     const env = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
+        if (!selectedKeys.has(key))
+            continue;
         const parsed = parsedByKey.get(key);
         if ('literal' in parsed) {
             env[key] = parsed.literal;
@@ -582,15 +681,20 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     if (backend === 'keychain' && !opts.noAgent && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
         const hit = agentGetSync(name);
         if (hit) {
-            stampLastUsed(hit.bundle);
+            // The agent stores the FULL bundle env. Apply the same subset filter and
+            // expiry gate as the slow path — without this, `--secrets-keys X` would
+            // silently inject every key and an expired key would flow through after
+            // the first cache-populating run.
+            const filtered = filterAgentHitBySubsetAndExpiry(hit, opts);
+            stampLastUsed(filtered.bundle);
             emit('secrets.get', {
                 bundle: name,
                 caller: opts.caller,
                 status: 'success',
                 source: 'agent',
-                keyCount: Object.keys(hit.env).length,
+                keyCount: Object.keys(filtered.env).length,
             });
-            return hit;
+            return filtered;
         }
     }
     if (backend === 'file')
@@ -651,11 +755,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
+    // Key-subset validation and expiry pre-check (mirrors resolveBundleEnv logic).
+    const selectedKeys = selectRequestedKeys(bundle, opts.keys);
+    assertNotExpired(bundle, [...selectedKeys], opts.allowExpired ?? false);
     stampLastUsed(bundle);
     const parsedByKey = new Map();
     const keychainKeys = [];
     const kindCounts = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
+        if (!selectedKeys.has(key))
+            continue;
         const p = parseBundleValue(raw);
         parsedByKey.set(key, p);
         const kind = 'literal' in p ? 'literal' : p.ref.provider;
@@ -664,7 +773,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             keychainKeys.push(key);
         }
     }
-    const keys = Object.keys(bundle.vars).sort();
+    const keys = [...selectedKeys].sort();
     keychainKeys.sort();
     const emitReadAudit = (status, err) => {
         emit('secrets.get', {
@@ -681,6 +790,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     try {
         const env = {};
         for (const [key] of Object.entries(bundle.vars)) {
+            if (!selectedKeys.has(key))
+                continue;
             const p = parsedByKey.get(key);
             if ('literal' in p) {
                 env[key] = p.literal;
@@ -749,7 +860,7 @@ export function rotateBundleSecret(bundle, key, opts) {
     }
     const shortId = raw.slice('keychain:'.length);
     const item = secretsKeychainItem(bundle.name, shortId);
-    itemStore(bundle.backend ?? 'keychain').set(item, opts.newValue);
+    itemStore(bundle.backend ?? 'keychain').set(item, opts.newValue, { noAcl: bundlePolicy(bundle) === 'never' });
     if (opts.clearMeta) {
         if (bundle.meta)
             delete bundle.meta[key];
@@ -817,7 +928,7 @@ export function renameBundle(oldName, newName, opts = {}) {
         const shortId = raw.slice('keychain:'.length);
         const newItem = secretsKeychainItem(newName, shortId);
         const value = store.get(oldItem);
-        store.set(newItem, value);
+        store.set(newItem, value, { noAcl: bundlePolicy(source) === 'never' });
     }
     // writeBundle preserves source.created_at, refreshes updated_at, and keeps
     // the source backend (spread carries source.backend).
@@ -837,8 +948,16 @@ export function renameBundle(oldName, newName, opts = {}) {
  * `import` / `remove` / `delete`. Pass the bundle's resolved backend
  * (`bundle.backend ?? 'keychain'`).
  */
-export function bundleItemStore(backend) {
-    return itemStore(backend ?? 'keychain');
+export function bundleItemStore(backend, opts) {
+    const store = itemStore(backend ?? 'keychain');
+    // `never`-policy bundles write their per-key values without the biometry ACL
+    // (same rationale as the metadata write in writeBundle). Wrap `set` so every
+    // value the add/import paths write inherits the no-ACL flag; reads, deletes,
+    // and existence checks are ACL-independent and pass through untouched.
+    if (opts?.noAcl) {
+        return { ...store, set: (item, value) => store.set(item, value, { noAcl: true }) };
+    }
+    return store;
 }
 // Iterate all keychain-backed keys in a bundle for cleanup on rm/unset.
 export function keychainItemsForBundle(bundle) {

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

@@ -74,9 +74,12 @@ export declare const fileStore: {
 /** File-only KeychainBackend (exported for tests; the Linux backend uses these
  *  ops with auto-provision allowed). */
 export declare const fileBackend: KeychainBackend;
+/** Resolved passphrase directory (exported for integration tests). */
+export declare function resolvePassphraseDir(): string;
 /** Test-only: reset module state (file dir + cached passphrase). */
 export declare function _resetFileStoreForTest(opts?: {
     fileDir?: string | null;
+    passphraseDir?: string | null;
     passphrase?: string | null;
 }): void;
 export {};

package/dist/lib/secrets/filestore.js

@@ -28,6 +28,7 @@ import * as path from 'path';
 import { encodePwshBase64 } from '../pwsh.js';
 // ---------- file store location ----------
 let fileDirOverride = null;
+let passphraseDirOverride = null;
 let cachedPassphrase = null;
 let warnedAutoPassphrase = false;
 export function fileDir() {
@@ -106,29 +107,40 @@ function readPassphraseFromTty() {
         fs.closeSync(fd);
     }
 }
-/** Path of the auto-provisioned machine-local passphrase. Lives alongside the
- *  encrypted items but is never itself an item (no `.enc` suffix, so it's
- *  excluded from list/has/get and from fileFallbackPreviouslyActivated). */
+/**
+ * Directory for the auto-provisioned machine-local passphrase. Kept outside
+ * `fileDir()` so a scan of the encrypted store never co-locates key + ciphertext.
+ */
+function passphraseDir() {
+    return passphraseDirOverride ?? path.join(os.homedir(), '.agents', '.secrets-key');
+}
+function ensurePassphraseDir() {
+    fs.mkdirSync(passphraseDir(), { recursive: true, mode: 0o700 });
+}
+/** Path of the auto-provisioned machine-local passphrase (not an `.enc` item). */
 function passphraseFilePath() {
+    return path.join(passphraseDir(), 'passphrase');
+}
+/** Legacy co-located path — read-only for machines provisioned before #479. */
+function legacyPassphraseFilePath() {
     return path.join(fileDir(), '.passphrase');
 }
 /** True if a machine-local passphrase has already been provisioned. */
 export function machinePassphraseExists() {
-    try {
-        return fs.readFileSync(passphraseFilePath(), 'utf8').trim().length > 0;
-    }
-    catch {
-        return false;
-    }
+    return readMachinePassphrase() !== null;
 }
 function readMachinePassphrase() {
-    try {
-        const p = fs.readFileSync(passphraseFilePath(), 'utf8').trim();
-        return p.length > 0 ? p : null;
-    }
-    catch {
-        return null;
+    for (const fp of [passphraseFilePath(), legacyPassphraseFilePath()]) {
+        try {
+            const p = fs.readFileSync(fp, 'utf8').trim();
+            if (p.length > 0)
+                return p;
+        }
+        catch {
+            // try next location
+        }
     }
+    return null;
 }
 /**
  * Provision (or read back) a stable machine-local passphrase for the encrypted
@@ -146,7 +158,7 @@ function provisionMachinePassphrase() {
     const existing = readMachinePassphrase();
     if (existing)
         return existing;
-    ensureFileDir();
+    ensurePassphraseDir();
     const generated = randomBytes(32).toString('base64');
     const fp = passphraseFilePath();
     try {
@@ -317,9 +329,23 @@ export const fileBackend = {
     delete: fileDelete,
     list: fileList,
 };
+/** Resolved passphrase directory (exported for integration tests). */
+export function resolvePassphraseDir() {
+    return passphraseDir();
+}
 /** Test-only: reset module state (file dir + cached passphrase). */
 export function _resetFileStoreForTest(opts = {}) {
     fileDirOverride = opts.fileDir ?? null;
+    if (opts.passphraseDir !== undefined) {
+        passphraseDirOverride = opts.passphraseDir;
+    }
+    else if (opts.fileDir) {
+        // Hermetic sibling when only the store dir is overridden (linux.test.ts).
+        passphraseDirOverride = path.resolve(opts.fileDir, '..', `${path.basename(opts.fileDir)}-key`);
+    }
+    else {
+        passphraseDirOverride = null;
+    }
     cachedPassphrase = opts.passphrase ?? null;
     warnedAutoPassphrase = false;
 }

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

@@ -103,8 +103,16 @@ export declare function getKeychainToken(item: string): string;
  * lookups — no biometric prompt path on those platforms.
  */
 export declare function getKeychainTokens(items: string[]): Map<string, string>;
-/** Store or update a secret value in the keychain/keyring. Device-local; biometry-gated on macOS. */
-export declare function setKeychainToken(item: string, value: string): void;
+/** Store or update a secret value in the keychain/keyring. Device-local;
+ * biometry-gated on macOS. `opts.noAcl` (the `never` prompt-policy) writes our
+ * item WITHOUT the biometry access control so later reads are fully silent — it
+ * routes through the signed helper's `set-no-acl` path. A pinned helper that
+ * predates that path rejects the unknown command (exit 2) and this throws,
+ * rather than silently falling back to an ACL'd `set` (which would behave like
+ * `always`). Ignored by the Linux/Windows/test backends, which have no ACL. */
+export declare function setKeychainToken(item: string, value: string, opts?: {
+    noAcl?: boolean;
+}): void;
 /** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
 export declare function deleteKeychainToken(item: string): boolean;
 /**
@@ -140,6 +148,39 @@ export declare function listLegacyKeychainItems(prefix: string): string[];
  * concept, so the call is a no-op there.
  */
 export declare function migrateKeychainItem(item: string): boolean;
+/**
+ * Enumerate data-protection items whose service starts with `prefix` that live
+ * under a NON-concrete access group — pre-#279 "orphans" filed under the implicit
+ * default group (the literal `2HTP252L87.*`) that the pinned-group queries can't
+ * see. Attributes only: never decrypts, never prompts. macOS only — Linux/Windows
+ * and the test backend have no access-group concept, so this returns [].
+ */
+export declare function listOrphanedKeychainItems(prefix: string): string[];
+/** Outcome of re-homing one orphaned keychain item. */
+export interface OrphanMigrationResult {
+    item: string;
+    status: 'ok' | 'warn' | 'fail';
+    detail?: string;
+}
+/**
+ * Parse the `migrate-orphans` helper summary (one record per line):
+ *   OK <service>               re-homed
+ *   WARN <service> <detail>    pinned copy written but orphan not removed
+ *   FAIL <service> <detail>    could not re-home (orphan left intact)
+ * Unknown lines are ignored. Exported for unit testing without a keychain.
+ */
+export declare function parseOrphanMigrationOutput(stdout: string): OrphanMigrationResult[];
+/**
+ * Re-home every pre-#279 orphaned data-protection item under `prefix` into the
+ * concrete access group, behind a SINGLE Touch ID prompt for the whole batch.
+ * The helper reads each orphan by its exact persistent ref, adds the pinned copy
+ * (add-before-delete: a failed add leaves the orphan intact), then deletes the
+ * orphan by ref. Returns one result per item. macOS only — no-op elsewhere.
+ *
+ * Throws on Touch ID cancellation (exit 4) so callers can distinguish "user
+ * aborted" from "nothing to do" (empty array).
+ */
+export declare function migrateOrphanedKeychainItems(prefix: string): OrphanMigrationResult[];
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {
     /** Translate a short keychain ID to a fully namespaced item name. */