@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/plugins.js

@@ -18,7 +18,7 @@ import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
 import { shouldInstallCommandAsSkill, installCommandSkillToVersion } from './command-skills.js';
-import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, } from './plugin-marketplace.js';
+import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, registerDroidInstalledPlugin, unregisterDroidInstalledPlugin, isDroidPluginInstalled, registerCopilotInstalledPlugin, unregisterCopilotInstalledPlugin, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, } from './plugin-marketplace.js';
 const PLUGIN_MANIFEST_DIR = '.claude-plugin';
 const PLUGIN_MANIFEST_FILE = 'plugin.json';
 const USER_CONFIG_FILE = '.user-config.json';
@@ -172,16 +172,26 @@ export function loadPluginManifest(pluginRoot) {
     }
 }
 export function validatePluginName(name) {
-    return name.length > 0
-        && !/[/\\]/.test(name)
-        && !name.includes('..')
-        && !name.includes('\0');
+    if (!name || name.length === 0 || name === '.' || name === '..') {
+        return false;
+    }
+    const normalized = path.normalize(name);
+    if (normalized === '.' || normalized === '' || normalized === '..') {
+        return false;
+    }
+    if (/[/\\]/.test(name) || name.includes('\0')) {
+        return false;
+    }
+    if (path.basename(normalized) !== name) {
+        return false;
+    }
+    return true;
 }
 export function assertPluginTargetContained(targetRoot, pluginsDir) {
     const resolvedPluginsDir = path.resolve(pluginsDir);
     const resolvedTargetRoot = path.resolve(targetRoot);
-    if (resolvedTargetRoot !== resolvedPluginsDir
-        && !resolvedTargetRoot.startsWith(`${resolvedPluginsDir}${path.sep}`)) {
+    if (resolvedTargetRoot === resolvedPluginsDir
+        || !resolvedTargetRoot.startsWith(`${resolvedPluginsDir}${path.sep}`)) {
         throw new Error(`Plugin install target escapes plugins directory: ${targetRoot}`);
     }
 }
@@ -416,7 +426,7 @@ export function marketplaceSpecForName(name, cwd = process.cwd()) {
  * carries, not just the user one.
  */
 function listVersionMarketplaceNames(agent, versionHome) {
-    const dir = path.join(versionHome, `.${agent}`, 'plugins', 'marketplaces');
+    const dir = path.join(versionHome, agentConfigDirName(agent), 'plugins', 'marketplaces');
     if (!fs.existsSync(dir))
         return [];
     try {
@@ -444,6 +454,11 @@ function listVersionMarketplaceNames(agent, versionHome) {
  * MCP servers, bin/, settings.json, and permissions once the plugin lives at the
  * native install path and is marked enabled — see
  * https://code.claude.com/docs/en/plugins.
+ *
+ * Droid (Factory CLI) reuses this same marketplace layout but additionally
+ * requires an installed_plugins.json registry entry and a "local"-source
+ * known_marketplaces.json entry before `droid plugin list` will see the plugin
+ * (steps handled by registerMarketplace's droid branch + step 5c below).
  */
 export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     const result = {
@@ -491,9 +506,25 @@ export function syncPluginToVersion(plugin, agent, versionHome, options = {}) {
     // .mcp.json, settings.json, permissions/) are only auto-enabled when the
     // caller explicitly opts in. addPluginToSettings does no gating — that moved
     // here, where plugin capabilities are inspected.
-    if (options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root))) {
+    const enablePlugin = options.allowExecSurfaces === true || !hasPluginExecSurfaces(inspectPluginCapabilities(plugin.root));
+    if (enablePlugin) {
         addPluginToSettings(plugin.name, marketplaceName, agent, versionHome);
     }
+    // 5c. Droid diverges from Claude's marketplace+enabledPlugins model: it only
+    //     "sees" a plugin that also has an entry in installed_plugins.json (with
+    //     the marketplace registered as source "local"). Register the install so
+    //     `droid plugin list` shows it — Active when enabled, Inactive otherwise.
+    if (agent === 'droid') {
+        registerDroidInstalledPlugin(plugin.name, marketplaceName, installDir, plugin.manifest.version, agent, versionHome);
+    }
+    // 5d. Copilot, like Droid, only "sees" a plugin that also has an entry in its
+    //     auto-managed config.json#installedPlugins (registerMarketplace already
+    //     wrote settings.json#extraKnownMarketplaces, and addPluginToSettings the
+    //     enabledPlugins flag). cache_path points at the marketplace copy; the
+    //     `enabled` flag mirrors the exec-surface trust gate above.
+    if (agent === 'copilot') {
+        registerCopilotInstalledPlugin(plugin.name, marketplaceName, installDir, plugin.manifest.version, enablePlugin, agent, versionHome);
+    }
     // 5b. Convert plugin commands/ to skills for agents that dropped command support
     //     (Codex >= 0.117.0). Skill name is prefixed with plugin name to avoid
     //     collision with standalone command skills.
@@ -718,7 +749,15 @@ function migrateLegacyFlatLayout(plugin, agent, versionHome) {
 export function isPluginSynced(plugin, agent, versionHome) {
     if (!isCapable(agent, 'plugins'))
         return false;
-    return isInstalledInMarketplace(plugin.name, marketplaceSpecForName(plugin.marketplace), agent, versionHome);
+    const spec = marketplaceSpecForName(plugin.marketplace);
+    if (!isInstalledInMarketplace(plugin.name, spec, agent, versionHome))
+        return false;
+    // Droid additionally requires its installed_plugins.json registry entry —
+    // without it the marketplace copy is invisible to `droid plugin list`.
+    if (agent === 'droid') {
+        return isDroidPluginInstalled(plugin.name, marketplaceNameFor(spec), agent, versionHome);
+    }
+    return true;
 }
 // ─── Removal ─────────────────────────────────────────────────────────────────
 /**
@@ -746,6 +785,12 @@ export function removePluginFromVersion(pluginName, pluginRoot, agent, versionHo
             removedAny = true;
         }
         removePluginFromSettings(pluginName, name, agent, versionHome);
+        if (agent === 'droid') {
+            unregisterDroidInstalledPlugin(pluginName, name, agent, versionHome);
+        }
+        if (agent === 'copilot') {
+            unregisterCopilotInstalledPlugin(pluginName, name, agent, versionHome);
+        }
         // Refresh marketplace.json so it reflects what's left under plugins/.
         syncMarketplaceManifest(spec, agent, versionHome);
         // If we just removed the last plugin, drop the marketplace dir and the
@@ -930,6 +975,12 @@ export function cleanOrphanedPluginSkills(agent, versionHome, activePluginNames,
                 fs.mkdirSync(trashDir, { recursive: true, mode: 0o700 });
                 fs.renameSync(path.join(mktPluginsDir, entry.name), trashDest);
                 removePluginFromSettings(entry.name, name, agent, versionHome);
+                if (agent === 'droid') {
+                    unregisterDroidInstalledPlugin(entry.name, name, agent, versionHome);
+                }
+                if (agent === 'copilot') {
+                    unregisterCopilotInstalledPlugin(entry.name, name, agent, versionHome);
+                }
                 removed.push(entry.name);
                 trashedHere = true;
             }

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. */