@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/profiles.d.ts

@@ -22,6 +22,14 @@ export interface Profile {
     description?: string;
     preset?: string;
     provider?: string;
+    /**
+     * Optional secondary model retried on the same host when the primary model
+     * env value hits a rate limit. Reuses the `--fallback` cascade in
+     * `runWithFallback` (src/lib/exec.ts) — the swap is expressed as an
+     * envOverride on a same-agent FallbackEntry, so only the model env var
+     * changes; auth, base URL, and every other profile env value are preserved.
+     */
+    fallback_model?: string;
 }
 /**
  * Stable, machine-readable summary used by `agents view` and `--json`.
@@ -59,6 +67,13 @@ export declare function profileHostLabel(profile: Profile): string;
 export declare function profileProviderLabel(profile: Profile): string;
 /** Return the configured model env value for display. */
 export declare function profileModelLabel(profile: Profile): string;
+/**
+ * Return the env var key that carries this profile's model (e.g.
+ * `ANTHROPIC_MODEL`), or null when the profile has no recognizable model env.
+ * `fallback_model` swaps THIS key so provider selection, auth, and base URL
+ * are all preserved on retry.
+ */
+export declare function profileModelEnvKey(profile: Profile): string | null;
 /**
  * Build a non-secret auth identity/status label for list surfaces.
  *
@@ -89,6 +104,16 @@ export interface ResolvedProfileRun {
     version?: string;
     env: Record<string, string>;
     profileName: string;
+    /**
+     * Same-host model swap for the `--fallback` cascade. Present only when the
+     * profile declares `fallback_model` AND the profile has an identifiable
+     * model env key to swap. `envKey` names the var (e.g. `ANTHROPIC_MODEL`),
+     * `model` is the value to write on the retry attempt.
+     */
+    fallbackModel?: {
+        envKey: string;
+        model: string;
+    };
 }
 /**
  * Resolve a name into (agent, version, env). Throws if the name is not a

package/dist/lib/profiles.js

@@ -111,16 +111,25 @@ const MODEL_ENV_KEYS = [
 ];
 /** Return the configured model env value for display. */
 export function profileModelLabel(profile) {
+    const key = profileModelEnvKey(profile);
+    return key ? profile.env[key] : '-';
+}
+/**
+ * Return the env var key that carries this profile's model (e.g.
+ * `ANTHROPIC_MODEL`), or null when the profile has no recognizable model env.
+ * `fallback_model` swaps THIS key so provider selection, auth, and base URL
+ * are all preserved on retry.
+ */
+export function profileModelEnvKey(profile) {
     for (const key of MODEL_ENV_KEYS) {
-        const value = profile.env[key];
-        if (value)
-            return value;
+        if (profile.env[key])
+            return key;
     }
     for (const [key, value] of Object.entries(profile.env)) {
         if ((key === 'MODEL' || key.endsWith('_MODEL')) && value)
-            return value;
+            return key;
     }
-    return '-';
+    return null;
 }
 function decodeJwtPayload(token) {
     const parts = token.split('.');
@@ -239,12 +248,19 @@ export function resolveProfileEnv(profile) {
  */
 export function resolveProfileForRun(name) {
     const profile = readProfile(name);
-    return {
+    const resolved = {
         agent: profile.host.agent,
         version: profile.host.version,
         env: resolveProfileEnv(profile),
         profileName: profile.name,
     };
+    if (profile.fallback_model) {
+        const envKey = profileModelEnvKey(profile);
+        if (envKey) {
+            resolved.fallbackModel = { envKey, model: profile.fallback_model };
+        }
+    }
+    return resolved;
 }
 /**
  * Look up the preset a profile was created from, if any. Used by

package/dist/lib/pty-client.js

@@ -10,6 +10,7 @@ import { spawn, execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import * as path from 'path';
 import { getSocketPath, getPtyLogPath, isPtyServerRunning } from './pty-server.js';
+import { backgroundSpawnOptions } from './platform/process.js';
 const CONNECT_TIMEOUT_MS = 5000;
 const RESPONSE_TIMEOUT_MS = 30000;
 const IS_WINDOWS = process.platform === 'win32';
@@ -38,7 +39,7 @@ async function ensureServer() {
     const logFd = fs.openSync(logPath, 'a');
     const child = spawn(bin, args, {
         stdio: ['ignore', logFd, logFd],
-        detached: true,
+        ...backgroundSpawnOptions({ fdStdio: true }),
     });
     child.unref();
     fs.closeSync(logFd);

package/dist/lib/rotate.d.ts

@@ -5,6 +5,7 @@
  * authentication tokens so users maintain active sessions across version switches.
  */
 import type { AgentId, RunStrategy } from './types.js';
+import type { FallbackEntry } from './exec.js';
 import { type AccountInfo } from './agents.js';
 import { type UsageSnapshot } from './usage.js';
 export interface RotateCandidate {
@@ -101,3 +102,63 @@ export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy,
     version: string | null;
     rotation: RotateResult | null;
 }>;
+/**
+ * Cap on the number of healthy accounts a single run will re-dispatch through
+ * after a mid-run rate limit. Bounds the synthesized chain so a machine signed
+ * into many accounts can't turn one 429 into an unbounded cascade of retries.
+ */
+export declare const DEFAULT_ROTATION_FAILOVER_LIMIT = 3;
+/**
+ * Synthesize a same-agent, cross-account fallback chain from a pre-flight
+ * rotation result (issue #348: mid-run rate-limit failover).
+ *
+ * The account rotation picks ONE version pre-spawn; today a 429 mid-run kills
+ * the run with no recovery. `runWithFallback` + `detectRateLimit` already
+ * re-dispatch to the NEXT chain entry on a rate limit and hand off the session
+ * via `/continue <id>` — but only for explicit `--fallback` chains. This turns
+ * the OTHER healthy rotation candidates (every account except the one already
+ * picked as the primary) into `FallbackEntry`s so that SAME machinery re-runs
+ * the task on the next healthy account of the same agent when the primary 429s.
+ *
+ * Each account is a distinct installed version (its own home/auth), so the
+ * entries are same-agent, different-version — exactly what runWithFallback
+ * spawns and what buildFallbackPrompt continues (claude→claude via `/continue`).
+ * Candidates are consumed in `rotation.healthy` order, which is sorted by
+ * remaining capacity (most headroom first, see compareCandidates), so failover
+ * prefers the freshest account.
+ *
+ * Returns `[]` when there is no rotation (pinned strategy) or the picked account
+ * is the only healthy one — so single-account users and non-rotation runs are
+ * completely unchanged.
+ */
+export declare function rotationFailoverChain(rotation: RotateResult | null, pickedVersion: string, limit?: number): FallbackEntry[];
+/**
+ * Whether a run is eligible to have a mid-run rate-limit failover chain armed
+ * (issue #348). Failover injects synthesized `FallbackEntry`s into the same
+ * `fallback` array that `--fallback` uses — so it must NOT arm for run shapes
+ * that reject a non-empty fallback chain, or the run hard-exits on a flag the
+ * user never passed. Specifically:
+ *
+ * - `acp` and `loop` runs bail with "not compatible with --fallback yet" the
+ *   moment `fallback.length > 0` (src/commands/exec.ts), so arming failover
+ *   would break a previously-working `agents run … --loop` / `--acp`.
+ * - `resumeCheckpoint` runs take the loop path (same guard).
+ * - `interactive` / no-prompt runs can't be re-dispatched headlessly.
+ * - `explicitFallback` (a user `--fallback` chain OR a profile fallback already
+ *   unshifted) defines its own recovery; don't layer rotation failover on top.
+ * - `hasRotation`/`hasVersion` gate on an actual pre-flight rotation having
+ *   picked an account, so pinned and non-rotation runs are untouched.
+ *
+ * Pure so the arming matrix is unit-testable without invoking the run command.
+ */
+export interface FailoverArmingContext {
+    hasRotation: boolean;
+    hasVersion: boolean;
+    hasPrompt: boolean;
+    explicitFallback: boolean;
+    interactive: boolean;
+    acp: boolean;
+    loop: boolean;
+    resumeCheckpoint: boolean;
+}
+export declare function shouldArmRotationFailover(ctx: FailoverArmingContext): boolean;

package/dist/lib/rotate.js

@@ -341,3 +341,55 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd()) {
     }
     return { version: fallback, rotation: null };
 }
+/**
+ * Cap on the number of healthy accounts a single run will re-dispatch through
+ * after a mid-run rate limit. Bounds the synthesized chain so a machine signed
+ * into many accounts can't turn one 429 into an unbounded cascade of retries.
+ */
+export const DEFAULT_ROTATION_FAILOVER_LIMIT = 3;
+/**
+ * Synthesize a same-agent, cross-account fallback chain from a pre-flight
+ * rotation result (issue #348: mid-run rate-limit failover).
+ *
+ * The account rotation picks ONE version pre-spawn; today a 429 mid-run kills
+ * the run with no recovery. `runWithFallback` + `detectRateLimit` already
+ * re-dispatch to the NEXT chain entry on a rate limit and hand off the session
+ * via `/continue <id>` — but only for explicit `--fallback` chains. This turns
+ * the OTHER healthy rotation candidates (every account except the one already
+ * picked as the primary) into `FallbackEntry`s so that SAME machinery re-runs
+ * the task on the next healthy account of the same agent when the primary 429s.
+ *
+ * Each account is a distinct installed version (its own home/auth), so the
+ * entries are same-agent, different-version — exactly what runWithFallback
+ * spawns and what buildFallbackPrompt continues (claude→claude via `/continue`).
+ * Candidates are consumed in `rotation.healthy` order, which is sorted by
+ * remaining capacity (most headroom first, see compareCandidates), so failover
+ * prefers the freshest account.
+ *
+ * Returns `[]` when there is no rotation (pinned strategy) or the picked account
+ * is the only healthy one — so single-account users and non-rotation runs are
+ * completely unchanged.
+ */
+export function rotationFailoverChain(rotation, pickedVersion, limit = DEFAULT_ROTATION_FAILOVER_LIMIT) {
+    if (!rotation || limit <= 0)
+        return [];
+    const chain = [];
+    for (const candidate of rotation.healthy) {
+        if (candidate.version === pickedVersion)
+            continue; // the primary account
+        chain.push({ agent: candidate.agent, version: candidate.version });
+        if (chain.length >= limit)
+            break;
+    }
+    return chain;
+}
+export function shouldArmRotationFailover(ctx) {
+    return (ctx.hasRotation &&
+        ctx.hasVersion &&
+        ctx.hasPrompt &&
+        !ctx.explicitFallback &&
+        !ctx.interactive &&
+        !ctx.acp &&
+        !ctx.loop &&
+        !ctx.resumeCheckpoint);
+}

package/dist/lib/routines.d.ts

@@ -7,16 +7,50 @@
  * scheduling.
  */
 import type { AgentId } from './types.js';
+import type { LoopConfig } from './loop.js';
 /** Tool/site/directory allow-list for sandboxed job execution. */
 export interface JobAllowConfig {
     tools?: string[];
     sites?: string[];
     dirs?: string[];
 }
-/** Full configuration for a scheduled routine (persisted as YAML). */
+/** GitHub webhook events a routine can be triggered by. */
+export type GithubTriggerEvent = 'pull_request' | 'push' | 'issue_comment' | 'workflow_run';
+/** Canonical set of accepted GitHub trigger events — single source for validation. */
+export declare const GITHUB_TRIGGER_EVENTS: readonly GithubTriggerEvent[];
+/**
+ * Map a user-facing `--on` alias to a canonical GitHub trigger event.
+ * Accepts the canonical names plus friendly shortcuts (e.g. `pr`, `pr_opened`
+ * → `pull_request`, `comment` → `issue_comment`). Returns null when unknown.
+ */
+export declare function normalizeTriggerEvent(input: string): GithubTriggerEvent | null;
+/**
+ * Event-based fire condition for a routine — an alternative (or complement) to
+ * `schedule`. Currently only `github_event`: an incoming GitHub webhook whose
+ * event (and optional repo/branch) match fires the job through the same
+ * dispatch path a cron fire uses. See `src/lib/triggers/webhook.ts`.
+ */
+export interface JobTrigger {
+    type: 'github_event';
+    event: GithubTriggerEvent;
+    /** `owner/name` — when set, only payloads for this repo match. */
+    repo?: string;
+    /** git branch (ref short name) — when set, only payloads for this branch match. */
+    branch?: string;
+}
+/**
+ * Full configuration for a routine (persisted as YAML).
+ *
+ * A job fires on a `schedule` (cron), on a `trigger` (event/webhook), or both.
+ * `schedule` remains a first-class field; trigger-only jobs omit it and are
+ * skipped by the cron scheduler (they fire only via the webhook receiver).
+ */
 export interface JobConfig {
     name: string;
-    schedule: string;
+    /** Cron expression. Optional when `trigger` is set (event-only routine). */
+    schedule?: string;
+    /** Event/webhook fire condition. Optional when `schedule` is set. */
+    trigger?: JobTrigger;
     agent: AgentId;
     workflow?: string;
     mode: 'plan' | 'edit' | 'auto' | 'skip' | 'full';
@@ -33,6 +67,8 @@ export interface JobConfig {
     version?: string;
     runOnce?: boolean;
     endAt?: string;
+    /** When set, executeJob runs this job through the loop driver instead of once. */
+    loop?: LoopConfig;
 }
 /** Metadata for a single job execution, persisted as JSON in the run directory. */
 export interface RunMeta {
@@ -67,6 +103,8 @@ export declare function deleteJob(name: string): boolean;
 export declare function setJobEnabled(name: string, enabled: boolean): void;
 /** Validate a partial job config, returning a list of human-readable errors. */
 export declare function validateJob(config: Partial<JobConfig>): string[];
+/** Validate a job trigger block, returning a list of human-readable errors. */
+export declare function validateTrigger(trigger: unknown): string[];
 /** True when a job's endAt has already elapsed. False when endAt is unset or in the future. */
 export declare function isPastEndAt(config: Pick<JobConfig, 'endAt'>, now?: Date): boolean;
 /** Expand built-in and user-defined template variables in a job's prompt string. */

package/dist/lib/routines.js

@@ -13,6 +13,33 @@ import { Cron } from 'croner';
 import { getRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
 import { safeJoin } from './paths.js';
 import { ALL_AGENT_IDS } from './agents.js';
+/** Canonical set of accepted GitHub trigger events — single source for validation. */
+export const GITHUB_TRIGGER_EVENTS = [
+    'pull_request',
+    'push',
+    'issue_comment',
+    'workflow_run',
+];
+/**
+ * Map a user-facing `--on` alias to a canonical GitHub trigger event.
+ * Accepts the canonical names plus friendly shortcuts (e.g. `pr`, `pr_opened`
+ * → `pull_request`, `comment` → `issue_comment`). Returns null when unknown.
+ */
+export function normalizeTriggerEvent(input) {
+    const key = input.trim().toLowerCase();
+    const aliases = {
+        pull_request: 'pull_request',
+        pr: 'pull_request',
+        pr_opened: 'pull_request',
+        pull: 'pull_request',
+        push: 'push',
+        issue_comment: 'issue_comment',
+        comment: 'issue_comment',
+        workflow_run: 'workflow_run',
+        workflow: 'workflow_run',
+    };
+    return aliases[key] ?? null;
+}
 /** Default values applied to every job config when fields are omitted. */
 const JOB_DEFAULTS = {
     mode: 'plan',
@@ -137,18 +164,28 @@ export function validateJob(config) {
     if (!config.name || typeof config.name !== 'string') {
         errors.push('name is required');
     }
-    if (!config.schedule || typeof config.schedule !== 'string') {
-        errors.push('schedule (cron expression) is required');
+    const hasSchedule = Boolean(config.schedule && typeof config.schedule === 'string');
+    const hasTrigger = config.trigger !== undefined;
+    if (!hasSchedule && !hasTrigger) {
+        errors.push('schedule (cron expression) or trigger is required');
     }
-    else {
-        // Validate cron expression is parseable
-        try {
-            new Cron(config.schedule);
+    if (config.schedule !== undefined) {
+        if (typeof config.schedule !== 'string') {
+            errors.push('schedule must be a cron expression string');
         }
-        catch {
-            errors.push(`invalid cron expression: "${config.schedule}"`);
+        else {
+            // Validate cron expression is parseable
+            try {
+                new Cron(config.schedule);
+            }
+            catch {
+                errors.push(`invalid cron expression: "${config.schedule}"`);
+            }
         }
     }
+    if (config.trigger !== undefined) {
+        errors.push(...validateTrigger(config.trigger));
+    }
     const hasAgent = Boolean(config.agent && typeof config.agent === 'string');
     const hasWorkflow = Boolean(config.workflow && typeof config.workflow === 'string');
     if (!hasAgent && !hasWorkflow) {
@@ -184,6 +221,27 @@ export function validateJob(config) {
     }
     return errors;
 }
+/** Validate a job trigger block, returning a list of human-readable errors. */
+export function validateTrigger(trigger) {
+    const errors = [];
+    if (!trigger || typeof trigger !== 'object') {
+        return ['trigger must be an object'];
+    }
+    const t = trigger;
+    if (t.type !== 'github_event') {
+        errors.push("trigger.type must be 'github_event'");
+    }
+    if (!t.event || !GITHUB_TRIGGER_EVENTS.includes(t.event)) {
+        errors.push(`trigger.event must be one of: ${GITHUB_TRIGGER_EVENTS.join(', ')}`);
+    }
+    if (t.repo !== undefined && (typeof t.repo !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(t.repo))) {
+        errors.push('trigger.repo must be in owner/name form');
+    }
+    if (t.branch !== undefined && typeof t.branch !== 'string') {
+        errors.push('trigger.branch must be a string');
+    }
+    return errors;
+}
 function isParseableDate(value) {
     if (!value.trim())
         return false;

package/dist/lib/runner.d.ts

@@ -8,6 +8,7 @@
  */
 import type { JobConfig, RunMeta } from './routines.js';
 import type { AgentId } from './types.js';
+import type { LoopDeps } from './loop.js';
 /** Result of a completed job execution, including metadata and optional report. */
 export interface RunResult {
     meta: RunMeta;
@@ -15,8 +16,16 @@ export interface RunResult {
 }
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export declare function buildJobCommand(config: JobConfig, resolvedPrompt: string): string[];
-/** Execute a job synchronously (waits for completion or timeout before resolving). */
-export declare function executeJob(config: JobConfig): Promise<RunResult>;
+/**
+ * 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 declare function executeJob(config: JobConfig, deps?: LoopDeps): Promise<RunResult>;
 /** Spawn a job as a detached process and return immediately with run metadata. */
 export declare function executeJobDetached(config: JobConfig): Promise<RunMeta>;
 /** Extract the final assistant message from a stream-JSON log file as a markdown report. */

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;