@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/lib/routines.d.ts

@@ -32,6 +32,7 @@ export interface JobConfig {
     config?: Record<string, unknown>;
     version?: string;
     runOnce?: boolean;
+    endAt?: string;
 }
 /** Metadata for a single job execution, persisted as JSON in the run directory. */
 export interface RunMeta {
@@ -45,10 +46,19 @@ export interface RunMeta {
     completedAt: string | null;
     exitCode: number | null;
 }
-/** List all job configs from ~/.agents/routines/. */
-export declare function listJobs(): JobConfig[];
-/** Read a single job config by name. Returns null if not found. */
-export declare function readJob(name: string): JobConfig | null;
+/**
+ * List all job configs, scanning project > user routine dirs.
+ * Project routines (`<project>/.agents/routines/`) shadow user routines of the
+ * same name. Project discovery is opt-in via `cwd`; the daemon (which calls
+ * `listJobs()` with no argument) only sees user routines.
+ */
+export declare function listJobs(cwd?: string): JobConfig[];
+/**
+ * Read a single job config by name, checking project > user.
+ * Project discovery is opt-in via `cwd`; daemon callers pass no argument and
+ * only resolve user routines.
+ */
+export declare function readJob(name: string, cwd?: string): JobConfig | null;
 /** Write a job config to disk, omitting fields that match defaults. */
 export declare function writeJob(config: JobConfig): void;
 /** Delete a job config file by name. Returns true if the file existed. */
@@ -57,6 +67,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[];
+/** 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. */
 export declare function resolveJobPrompt(config: JobConfig): string;
 /** Parse a human-readable timeout string (e.g. "10m", "2h", "1h30m", "3d", "1w") into milliseconds.

package/dist/lib/routines.js

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { Cron } from 'croner';
-import { getRoutinesDir, getRunsDir, ensureAgentsDir } from './state.js';
+import { getRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
 import { safeJoin } from './paths.js';
 import { ALL_AGENT_IDS } from './agents.js';
 /** Default values applied to every job config when fields are omitted. */
@@ -20,29 +20,59 @@ const JOB_DEFAULTS = {
     timeout: '10m',
     enabled: true,
 };
-/** List all job configs from ~/.agents/routines/. */
-export function listJobs() {
+/**
+ * List all job configs, scanning project > user routine dirs.
+ * Project routines (`<project>/.agents/routines/`) shadow user routines of the
+ * same name. Project discovery is opt-in via `cwd`; the daemon (which calls
+ * `listJobs()` with no argument) only sees user routines.
+ */
+export function listJobs(cwd) {
     ensureAgentsDir();
-    const jobsDir = getRoutinesDir();
-    if (!fs.existsSync(jobsDir))
-        return [];
-    const files = fs.readdirSync(jobsDir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+    const seen = new Set();
     const jobs = [];
-    for (const file of files) {
-        const job = readJobFile(path.join(jobsDir, file));
-        if (job)
+    const dirs = [];
+    if (cwd) {
+        const projectDir = getProjectRoutinesDir(cwd);
+        if (projectDir)
+            dirs.push(projectDir);
+    }
+    dirs.push(getRoutinesDir());
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        for (const file of files) {
+            const job = readJobFile(path.join(dir, file));
+            if (!job)
+                continue;
+            if (seen.has(job.name))
+                continue;
+            seen.add(job.name);
             jobs.push(job);
+        }
     }
     return jobs;
 }
-/** Read a single job config by name. Returns null if not found. */
-export function readJob(name) {
+/**
+ * Read a single job config by name, checking project > user.
+ * Project discovery is opt-in via `cwd`; daemon callers pass no argument and
+ * only resolve user routines.
+ */
+export function readJob(name, cwd) {
     ensureAgentsDir();
-    const jobsDir = getRoutinesDir();
-    for (const ext of ['.yml', '.yaml']) {
-        const filePath = safeJoin(jobsDir, name + ext);
-        if (fs.existsSync(filePath)) {
-            return readJobFile(filePath);
+    const dirs = [];
+    if (cwd) {
+        const projectDir = getProjectRoutinesDir(cwd);
+        if (projectDir)
+            dirs.push(projectDir);
+    }
+    dirs.push(getRoutinesDir());
+    for (const dir of dirs) {
+        for (const ext of ['.yml', '.yaml']) {
+            const filePath = safeJoin(dir, name + ext);
+            if (fs.existsSync(filePath)) {
+                return readJobFile(filePath);
+            }
         }
     }
     return null;
@@ -147,8 +177,28 @@ export function validateJob(config) {
     if (config.timeout && !parseTimeout(config.timeout)) {
         errors.push('timeout must be like 10m, 2h, 3d, 1w (max 1w)');
     }
+    if (config.endAt !== undefined) {
+        if (typeof config.endAt !== 'string' || !isParseableDate(config.endAt)) {
+            errors.push('endAt must be a parseable ISO 8601 / RFC3339 timestamp (e.g., 2026-12-31T23:59:00Z)');
+        }
+    }
     return errors;
 }
+function isParseableDate(value) {
+    if (!value.trim())
+        return false;
+    const ts = Date.parse(value);
+    return Number.isFinite(ts);
+}
+/** True when a job's endAt has already elapsed. False when endAt is unset or in the future. */
+export function isPastEndAt(config, now = new Date()) {
+    if (!config.endAt)
+        return false;
+    const end = Date.parse(config.endAt);
+    if (!Number.isFinite(end))
+        return false;
+    return now.getTime() >= end;
+}
 /** Expand built-in and user-defined template variables in a job's prompt string. */
 export function resolveJobPrompt(config) {
     const now = new Date();

package/dist/lib/rules/compile.js

@@ -10,8 +10,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
-import { AGENTS } from '../agents.js';
-import { getResolvedRulesDir, getVersionsDir } from '../state.js';
+import { AGENTS, agentConfigDirName } from '../agents.js';
+import { getVersionsDir } from '../state.js';
 import { composeRules, composeRulesFromState } from './compose.js';
 // Match `@path` preceded by start-of-string or whitespace. This avoids
 // matching emails ("foo@bar.com") and the middle of words. The leading
@@ -97,7 +97,7 @@ export function supportsRulesImports(agentId) {
 function getCompiledRulesPath(agentId, version) {
     const agentConfig = AGENTS[agentId];
     const versionHome = path.join(getVersionsDir(), agentId, version, 'home');
-    return path.join(versionHome, `.${agentId}`, agentConfig.instructionsFile);
+    return path.join(versionHome, agentConfigDirName(agentId), agentConfig.instructionsFile);
 }
 function getManifestPath(compiledPath) {
     return compiledPath + '.manifest.json';
@@ -151,14 +151,24 @@ export function compileRulesForAgent(agentId, version) {
     if (supportsRulesImports(agentId)) {
         return { compiled: false, compiledPath: '', sources: 0 };
     }
-    const rulesDir = getResolvedRulesDir();
-    const sourceAgents = path.join(rulesDir, 'AGENTS.md');
-    if (!fs.existsSync(sourceAgents)) {
+    // Route through the layered composer (project > user > extras > system).
+    // The previous implementation read only `<systemRules>/AGENTS.md` and
+    // inlined its @-imports — that dropped user/extras/project subrules
+    // entirely for @-import-incapable agents (Cursor, older Codex), so
+    // updates to ~/.agents/rules/subrules/ never reached the version home.
+    // composeRulesFromState already returns the concatenated content with
+    // every fragment resolved across layers; we just need to record the
+    // composed source list for staleness detection.
+    let composed;
+    try {
+        composed = composeRulesFromState({ preset: undefined });
+    }
+    catch {
+        // No rules.yaml in any layer, or the default preset is missing — leave
+        // the version home untouched (matches the previous file-missing branch).
         return { compiled: false, compiledPath: '', sources: 0 };
     }
-    const rootContent = fs.readFileSync(sourceAgents, 'utf8');
-    const { content, sources } = resolveImports(rootContent, rulesDir);
-    const newContent = COMPILED_HEADER + content;
+    const newContent = COMPILED_HEADER + composed.content;
     const compiledPath = getCompiledRulesPath(agentId, version);
     fs.mkdirSync(path.dirname(compiledPath), { recursive: true });
     const existing = fs.existsSync(compiledPath) ? fs.readFileSync(compiledPath, 'utf8') : null;
@@ -166,7 +176,9 @@ export function compileRulesForAgent(agentId, version) {
         return { compiled: false, compiledPath, sources: 0 };
     }
     fs.writeFileSync(compiledPath, newContent);
-    const allSources = [sourceAgents, ...sources];
+    // Track every concrete subrule file the composer included as a source for
+    // staleness. composeRulesFromState exposes sourcePath on each ComposedSubrule.
+    const allSources = composed.subrules.map(s => s.sourcePath);
     const manifest = {
         compiledAt: new Date().toISOString(),
         sources: allSources.map(p => {

package/dist/lib/rules/rules.js

@@ -8,7 +8,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { AGENTS, ALL_AGENT_IDS } from '../agents.js';
+import { AGENTS, ALL_AGENT_IDS, agentConfigDirName } from '../agents.js';
 import { getResolvedRulesDir, getUserRulesDir, getProjectAgentsDir } from '../state.js';
 import { getEffectiveHome } from '../versions.js';
 /**
@@ -65,7 +65,7 @@ function normalizeContent(content) {
  */
 function getUserConfigDir(agentId) {
     const home = getEffectiveHome(agentId);
-    return path.join(home, `.${agentId}`);
+    return path.join(home, agentConfigDirName(agentId));
 }
 export function getInstructionsPath(agentId, scope, cwd = process.cwd()) {
     const agent = AGENTS[agentId];
@@ -211,7 +211,7 @@ export function listInstalledInstructionsWithScope(agentId, cwd = process.cwd(),
     const agent = AGENTS[agentId];
     // User-scoped instructions (version-aware when home is provided)
     const home = options?.home || getEffectiveHome(agentId);
-    const userConfigDir = path.join(home, `.${agentId}`);
+    const userConfigDir = path.join(home, agentConfigDirName(agentId));
     const userPath = path.join(userConfigDir, agent.instructionsFile);
     results.push({
         agentId,

package/dist/lib/run-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Project-local `run:` config discovery.
+ *
+ * The user/system `agents.yaml` is read through state.ts. Project-local
+ * agents.yaml files are discovered from the current working directory upward.
+ */
+import type { RunConfig } from './types.js';
+/** Return project-local run configs from nearest directory upward. */
+export declare function getProjectRunConfigs(startPath?: string): RunConfig[];

package/dist/lib/run-config.js

@@ -0,0 +1,35 @@
+/**
+ * Project-local `run:` config discovery.
+ *
+ * The user/system `agents.yaml` is read through state.ts. Project-local
+ * agents.yaml files are discovered from the current working directory upward.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Return project-local run configs from nearest directory upward. */
+export function getProjectRunConfigs(startPath = process.cwd()) {
+    const configs = [];
+    let dir = path.resolve(startPath);
+    const userAgentsYaml = path.join(getUserAgentsDir(), 'agents.yaml');
+    while (dir !== path.dirname(dir)) {
+        const manifestPath = path.join(dir, 'agents.yaml');
+        if (manifestPath !== userAgentsYaml && fs.existsSync(manifestPath)) {
+            try {
+                const parsed = yaml.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (isRecord(parsed?.run)) {
+                    configs.push(parsed.run);
+                }
+            }
+            catch {
+                // Ignore malformed project config and keep walking.
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return configs;
+}

package/dist/lib/run-defaults.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Selector-based defaults for `agents run`.
+ *
+ * Stored under agents.yaml:
+ *
+ *   run:
+ *     defaults:
+ *       "claude:*":
+ *         mode: auto
+ *         model: opus
+ *       "claude:2.1.45":
+ *         mode: plan
+ */
+import type { AgentId, Mode, RunConfig, RunDefaults } from './types.js';
+export interface ParsedRunDefaultSelector {
+    agent: AgentId;
+    version: string;
+    selector: string;
+}
+export interface ResolvedRunDefaults extends RunDefaults {
+    sources: {
+        mode?: string;
+        model?: string;
+    };
+}
+export interface RunDefaultEntry {
+    selector: string;
+    defaults: RunDefaults;
+}
+type RunDefaultsInput = {
+    mode?: unknown;
+    model?: unknown;
+};
+export declare function normalizeRunDefaultMode(input: string): Mode;
+export declare function parseRunDefaultSelector(input: string): ParsedRunDefaultSelector;
+export declare function resolveRunDefaultsFromConfig(runConfig: RunConfig | undefined, agent: AgentId, version?: string | null): ResolvedRunDefaults;
+export declare function resolveRunDefaultsFromConfigs(runConfigs: Array<RunConfig | undefined>, agent: AgentId, version?: string | null): ResolvedRunDefaults;
+export declare function resolveRunDefaults(agent: AgentId, version?: string | null, startPath?: string): ResolvedRunDefaults;
+export declare function listRunDefaults(): RunDefaultEntry[];
+export declare function setRunDefault(selectorInput: string, defaultsInput: RunDefaultsInput): RunDefaultEntry;
+export declare function unsetRunDefault(selectorInput: string): boolean;
+export {};

package/dist/lib/run-defaults.js

@@ -0,0 +1,180 @@
+/**
+ * Selector-based defaults for `agents run`.
+ *
+ * Stored under agents.yaml:
+ *
+ *   run:
+ *     defaults:
+ *       "claude:*":
+ *         mode: auto
+ *         model: opus
+ *       "claude:2.1.45":
+ *         mode: plan
+ */
+import { ALL_MODES } from './types.js';
+import { AGENTS } from './agents.js';
+import { readMeta, updateMeta } from './state.js';
+import { getProjectRunConfigs } from './run-config.js';
+const VERSION_RE = /^(?:\*|latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
+function isAgentId(value) {
+    return value in AGENTS;
+}
+export function normalizeRunDefaultMode(input) {
+    const mode = input.trim().toLowerCase();
+    if (mode === 'full')
+        return 'skip';
+    if (ALL_MODES.includes(mode))
+        return mode;
+    throw new Error(`Invalid mode '${input}'. Use one of: ${ALL_MODES.join(', ')} (or 'full' as an alias for 'skip').`);
+}
+function normalizeRunDefaults(defaults, selector) {
+    const out = {};
+    if (defaults.mode !== undefined) {
+        if (typeof defaults.mode !== 'string') {
+            throw new Error(`Invalid mode in run.defaults.${selector}: expected a string.`);
+        }
+        out.mode = normalizeRunDefaultMode(defaults.mode);
+    }
+    if (defaults.model !== undefined) {
+        if (typeof defaults.model !== 'string' || defaults.model.trim() === '') {
+            throw new Error(`Invalid model in run.defaults.${selector}: expected a non-empty string.`);
+        }
+        out.model = defaults.model.trim();
+    }
+    return out;
+}
+export function parseRunDefaultSelector(input) {
+    const raw = input.trim();
+    if (!raw)
+        throw new Error('Selector is required. Use <agent>:<version>, <agent>@<version>, or <agent>:*.');
+    let agentPart;
+    let versionPart;
+    if (raw.includes('@')) {
+        const parts = raw.split('@');
+        if (parts.length !== 2)
+            throw new Error(`Invalid selector '${input}'. Use <agent>@<version>.`);
+        [agentPart, versionPart] = parts;
+    }
+    else if (raw.includes(':')) {
+        const idx = raw.indexOf(':');
+        agentPart = raw.slice(0, idx);
+        versionPart = raw.slice(idx + 1);
+    }
+    else {
+        agentPart = raw;
+        versionPart = '*';
+    }
+    const agent = agentPart.toLowerCase();
+    if (!isAgentId(agent)) {
+        throw new Error(`Invalid agent '${agentPart}'. Available agents: ${Object.keys(AGENTS).join(', ')}.`);
+    }
+    if (!VERSION_RE.test(versionPart)) {
+        throw new Error(`Invalid selector version '${versionPart}'. Use *, latest, or [A-Za-z0-9._+-]{1,64}.`);
+    }
+    return {
+        agent,
+        version: versionPart,
+        selector: `${agent}:${versionPart}`,
+    };
+}
+function sortedDefaults(defaults) {
+    return Object.fromEntries(Object.entries(defaults).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function resolveRunDefaultsFromConfig(runConfig, agent, version) {
+    const defaults = runConfig?.defaults ?? {};
+    const wildcardSelector = `${agent}:*`;
+    const exactSelector = version ? `${agent}:${version}` : null;
+    const resolved = { sources: {} };
+    const wildcard = defaults[wildcardSelector]
+        ? normalizeRunDefaults(defaults[wildcardSelector], wildcardSelector)
+        : null;
+    if (wildcard?.mode) {
+        resolved.mode = wildcard.mode;
+        resolved.sources.mode = wildcardSelector;
+    }
+    if (wildcard?.model) {
+        resolved.model = wildcard.model;
+        resolved.sources.model = wildcardSelector;
+    }
+    if (exactSelector && defaults[exactSelector]) {
+        const exact = normalizeRunDefaults(defaults[exactSelector], exactSelector);
+        if (exact.mode) {
+            resolved.mode = exact.mode;
+            resolved.sources.mode = exactSelector;
+        }
+        if (exact.model) {
+            resolved.model = exact.model;
+            resolved.sources.model = exactSelector;
+        }
+    }
+    return resolved;
+}
+export function resolveRunDefaultsFromConfigs(runConfigs, agent, version) {
+    const resolved = { sources: {} };
+    for (const runConfig of runConfigs) {
+        const next = resolveRunDefaultsFromConfig(runConfig, agent, version);
+        if (next.mode) {
+            resolved.mode = next.mode;
+            resolved.sources.mode = next.sources.mode;
+        }
+        if (next.model) {
+            resolved.model = next.model;
+            resolved.sources.model = next.sources.model;
+        }
+    }
+    return resolved;
+}
+export function resolveRunDefaults(agent, version, startPath = process.cwd()) {
+    const projectRunConfigs = getProjectRunConfigs(startPath).reverse();
+    return resolveRunDefaultsFromConfigs([readMeta().run, ...projectRunConfigs], agent, version);
+}
+export function listRunDefaults() {
+    const defaults = readMeta().run?.defaults ?? {};
+    return Object.entries(defaults)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([selector, value]) => ({
+        selector,
+        defaults: normalizeRunDefaults(value, selector),
+    }));
+}
+export function setRunDefault(selectorInput, defaultsInput) {
+    const parsed = parseRunDefaultSelector(selectorInput);
+    const defaults = normalizeRunDefaults(defaultsInput, parsed.selector);
+    if (!defaults.mode && !defaults.model) {
+        throw new Error('Set at least one default: --mode <mode> or --model <model>.');
+    }
+    updateMeta((meta) => {
+        const run = { ...(meta.run ?? {}) };
+        const currentDefaults = { ...(run.defaults ?? {}) };
+        currentDefaults[parsed.selector] = {
+            ...(currentDefaults[parsed.selector] ?? {}),
+            ...defaults,
+        };
+        run.defaults = sortedDefaults(currentDefaults);
+        return { ...meta, run };
+    });
+    return {
+        selector: parsed.selector,
+        defaults: {
+            ...(readMeta().run?.defaults?.[parsed.selector] ?? {}),
+        },
+    };
+}
+export function unsetRunDefault(selectorInput) {
+    const parsed = parseRunDefaultSelector(selectorInput);
+    let removed = false;
+    updateMeta((meta) => {
+        const run = { ...(meta.run ?? {}) };
+        const currentDefaults = { ...(run.defaults ?? {}) };
+        removed = Object.prototype.hasOwnProperty.call(currentDefaults, parsed.selector);
+        delete currentDefaults[parsed.selector];
+        if (Object.keys(currentDefaults).length > 0) {
+            run.defaults = sortedDefaults(currentDefaults);
+        }
+        else {
+            delete run.defaults;
+        }
+        return { ...meta, run };
+    });
+    return removed;
+}

package/dist/lib/runner.js

@@ -21,6 +21,7 @@ const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
     codex: ['codex', 'exec', '--sandbox', 'workspace-write', '{prompt}', '--json'],
     gemini: ['gemini', '{prompt}', '--output-format', 'stream-json'],
+    kimi: ['kimi', '--prompt', '{prompt}', '--output-format', 'stream-json'],
 };
 /** Build the full CLI argv for executing a job, applying mode, model, and permission flags. */
 export function buildJobCommand(config, resolvedPrompt) {
@@ -72,14 +73,14 @@ export function buildJobCommand(config, resolvedPrompt) {
     }
     if (config.agent === 'codex') {
         if (mode === 'edit') {
-            cmd.push('--full-auto');
+            cmd.push('--dangerously-bypass-approvals-and-sandbox');
         }
         else if (mode === 'skip') {
-            // Remove sandbox restriction, just --full-auto
+            // Remove sandbox restriction, just --dangerously-bypass-approvals-and-sandbox
             const sbIndex = cmd.indexOf('--sandbox');
             if (sbIndex !== -1)
                 cmd.splice(sbIndex, 2);
-            cmd.push('--full-auto');
+            cmd.push('--dangerously-bypass-approvals-and-sandbox');
         }
         appendModelAndReasoning(cmd, config);
     }
@@ -92,6 +93,18 @@ export function buildJobCommand(config, resolvedPrompt) {
         }
         appendModelAndReasoning(cmd, config);
     }
+    if (config.agent === 'kimi') {
+        if (mode === 'plan') {
+            cmd.push('--plan');
+        }
+        else if (mode === 'auto') {
+            cmd.push('--auto');
+        }
+        else if (mode === 'skip') {
+            cmd.push('--yolo');
+        }
+        appendModelAndReasoning(cmd, config);
+    }
     return cmd;
 }
 /**

package/dist/lib/scheduler.js

@@ -6,7 +6,7 @@
  * on startup and reloads them on SIGHUP.
  */
 import { Cron } from 'croner';
-import { listJobs, deleteJob } from './routines.js';
+import { listJobs, deleteJob, isPastEndAt, setJobEnabled } from './routines.js';
 /** In-memory cron scheduler that triggers a callback when jobs fire. */
 export class JobScheduler {
     jobs = new Map();
@@ -32,6 +32,20 @@ export class JobScheduler {
         if (config.timezone)
             cronOptions.timezone = config.timezone;
         const cron = new Cron(config.schedule, cronOptions, async () => {
+            // endAt: once the configured end time has passed, auto-disable and stop
+            // firing. We persist enabled=false to disk so the next daemon reload
+            // doesn't re-schedule, and unschedule in-memory so this cron stops.
+            if (isPastEndAt(config)) {
+                this.unschedule(config.name);
+                try {
+                    setJobEnabled(config.name, false);
+                }
+                catch (err) {
+                    console.error(`Job '${config.name}' endAt auto-disable failed:`, err.message);
+                }
+                console.log(`Job '${config.name}' reached endAt (${config.endAt}); auto-disabled.`);
+                return;
+            }
             try {
                 await this.onTrigger(config);
             }

package/dist/lib/secrets/Agents CLI.app/Contents/_CodeSignature/CodeResources

@@ -5,7 +5,15 @@
 	<key>files</key>
 	<dict/>
 	<key>files2</key>
-	<dict/>
+	<dict>
+		<key>embedded.provisionprofile</key>
+		<dict>
+			<key>hash2</key>
+			<data>
+			2vfA/eR3dTYgNc/fXhdADUPkp5tRIepPzE3FCLfDx4w=
+			</data>
+		</dict>
+	</dict>
 	<key>rules</key>
 	<dict>
 		<key>^Resources/</key>

package/dist/lib/secrets/install-helper.d.ts

@@ -12,10 +12,14 @@
  * modules in `src/lib/secrets/` must import `getKeychainHelperPath()` rather
  * than recomputing it.
  */
+/** Redirect the install root (test only). Returns the previous override so callers can restore. */
+export declare function setInstallRootForTest(dir: string | null): string | null;
 /**
  * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
- * if the destination already exists and `codesign --verify` passes, unless
- * `forceReinstall=true`.
+ * if the destination already exists, `codesign --verify` passes, AND the
+ * installed executable matches the bundled one byte-for-byte — a valid
+ * signature alone is not enough, because an outdated helper signs clean too.
+ * `forceReinstall=true` skips all checks and always copies.
  *
  * Notarization is checked via `spctl --assess` after install — a failure is
  * logged as a warning but does NOT throw. Notarization checks require network
@@ -27,7 +31,11 @@ export declare function ensureKeychainHelperInstalled(opts?: {
 }): void;
 /**
  * Return the absolute path to the helper executable. If the installed bundle
- * is missing, performs a lazy install first.
+ * is missing, or is stale relative to the bundled source helper, performs a
+ * lazy (re)install first. The staleness check is what lets an upgraded CLI
+ * replace a helper a previous version installed — `agents helper install`
+ * never runs on `npm i -g`, so this call site is the only one every machine
+ * is guaranteed to pass through.
  *
  * Throws on non-darwin.
  */