agents-relay 1.0.41 → 1.0.43

package/README.md

@@ -48,6 +48,13 @@ retries and daemon restarts do not create duplicate work.
 Task producers must follow `skills/agents-relay/contracts/task-job-contract.md`; that shared skill contract defines story size, lifecycle events, review, and auto-merge semantics.
 All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 minutes, and `L`≈45 minutes of normal-reasoning execution, with `M` as the default. `high` reasoning doubles that overall window. ChatGPT Browser Worker start-ack timeout is derived as one third of the effective overall timeout, clamped between 1 and 5 minutes. Orchestrators and planners should choose `storySize`, not raw timeout milliseconds; `--timeout` remains only as an explicit compatibility/debug override.
 
+Autonomous jobs can also be scheduled without a Relay database. The job marker
+stores a five-field cron expression, IANA timezone, next run, and missed-run /
+concurrency policy; GitHub issue labels provide the indexed discovery surface.
+A repository heartbeat invokes `tick` at 10-minute resolution. See
+[Scheduled autonomous jobs](docs/scheduled-autonomous-jobs.md) for the exact
+operational contract.
+
 job create first resolves an existing open PR with the same head/base, then creates it only when needed. Re-running it is idempotent: it reuses the PR and maintains exactly one trusted agents-relay:job:v1 marker.
 Use `--start` to create/reuse the job and submit its initial task in one invocation. Start mode requires explicit `--adapter`, `--model`, `--output`, and non-empty `--input`; the task ID defaults to `initial`. Re-running with the same task definition reuses that task and never duplicates it. Omitting `--start` preserves create-only behavior, leaving an `OPEN` job with zero tasks until a caller submits work.
 

package/dist/cli.js

@@ -15,10 +15,11 @@ import { serveDashboard } from './dashboard.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner, orchestratorPlanningDecision } from './planner.js';
-import { extendRetryBudget } from './scheduler.js';
+import { extendRetryBudget, parseJobSchedule } from './scheduler.js';
+import { dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.js';
-const usage = 'agents-relay <job|task|context|init|submit|record|agent-register|agent-discover|status|reconcile|retry|cancel|serve> [options]';
+const usage = 'agents-relay <job|task|context|init|submit|record|agent-register|agent-discover|status|reconcile|tick|retry|cancel|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -36,6 +37,7 @@ Commands:
   agent-discover           Find registered agents matching hard filters
   status                   Show the durable job state
   reconcile                Run reconciliation once
+  tick                     Run the indexed autonomous scheduler heartbeat
   retry|cancel             Change a task state
   serve                    Run the dashboard and reconciliation service
 
@@ -58,6 +60,11 @@ Common options:
   --title TEXT             Job title
   --objective TEXT         Objective for autonomous mode
   --mode fixed|autonomous  Execution mode (default: fixed)
+  --schedule CRON          Autonomous schedule; minute resolution is 10 minutes
+  --schedule-timezone TZ   IANA timezone for --schedule (default: UTC)
+  --schedule-next-run ISO  Optional first run (must match the cron expression)
+  --missed-run-policy run|skip   Run each missed slot or skip to the next future slot
+  --schedule-concurrency skip|queue  Skip or retain the slot while work is active
   --start                   Create/reuse the job and submit its initial task
 
 Example:
@@ -140,6 +147,13 @@ Required: --file PATH for local demo mode, or --repo OWNER/REPO --pr NUMBER --id
 
 Example:
   npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1`,
+    tick: `Process autonomous jobs indexed into current/recent GitHub next-run buckets.
+
+Required: --repo OWNER/REPO.
+Common: --lookback-buckets N (default 3).
+
+Example:
+  npx agents-relay tick --repo OWNER/REPO`,
     init: `Initialize a new job. GitHub mode requires --repo and --pr; local mode requires explicit --file.
 
 Common: --id ID, --title TEXT, --objective TEXT, --mode fixed|autonomous, --priority P0|P1|P2|P3.
@@ -257,6 +271,19 @@ export function chatGptTabClosePolicy(args) {
 }
 function requestedExecutionMode(args) { const value = arg(args, '--mode', arg(args, '--execution-mode')); return value ? executionMode(args) : undefined; }
 function continuation(args) { const kind = arg(args, '--continue-kind'); const target = arg(args, '--continue-target'); return kind && target ? { kind: kind, target, input: arg(args, '--continue-input') || undefined } : null; }
+function scheduleFromArgs(args) {
+    const cron = arg(args, '--schedule');
+    if (!cron)
+        return undefined;
+    const nextRunAt = arg(args, '--schedule-next-run') || undefined;
+    return parseJobSchedule({
+        cron,
+        timezone: arg(args, '--schedule-timezone', 'UTC'),
+        nextRunAt,
+        missedRunPolicy: arg(args, '--missed-run-policy', 'skip'),
+        concurrencyPolicy: arg(args, '--schedule-concurrency', 'skip'),
+    });
+}
 export async function ensureManagedGitHubJob(client, repositoryName, trustedAuthors, options) {
     if (!options.id)
         throw new Error('--id is required for managed GitHub jobs');
@@ -278,6 +305,8 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         job.objective = options.objective;
     if (options.executionMode)
         job.executionMode = options.executionMode;
+    if (options.schedule)
+        job.schedule = options.schedule;
     if (options.autoMerge !== undefined)
         job.autoMerge = options.autoMerge;
     if (options.reviewEnabled !== undefined)
@@ -307,6 +336,8 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
     }
     else
         await store.saveJob(job);
+    if (job.schedule)
+        await syncScheduleLabels(client, repositoryName, job);
     return { job: await store.load(options.id), pr };
 }
 async function appendPlannedTask(store, job, task) {
@@ -494,6 +525,7 @@ async function runJobCommand(action, args) {
         objective: arg(args, '--objective') || undefined,
         priority: priority(args),
         executionMode: requestedExecutionMode(args),
+        schedule: scheduleFromArgs(args),
         autoMerge: !hasArg(args, '--no-auto-merge'),
         reviewEnabled: !hasArg(args, '--no-review'),
         continuation: continuation(args),
@@ -508,16 +540,16 @@ async function runJobCommand(action, args) {
     console.log(JSON.stringify({ repository: repo, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state, task: start ? arg(args, '--task-id', 'initial') : undefined }, null, 2));
 }
 export function runtimePlanner(args) { const plannerCommand = arg([...args], '--planner-command'); const modelRuntime = arg([...args], '--codex', 'codex'); return plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); }
-export function runtimeReviewer() { return { adapter: 'chatgpt', routing: { provider: 'chatgpt', model: 'account-defaults', decidedBy: 'fixed-chatgpt-reviewer', decidedAt: new Date().toISOString() } }; }
-export function runtime(store, args, bus) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, reviewer: runtimeReviewer(), eventBus: bus, emit, chatgptTabClosePolicy: policy, projectPathForJob: job => resolveManagedProjectPath(job.repository, arg(args, '--project-path'), arg(args, '--workspace-root') || defaultWorkspaceRoot()) }); }
+export function runtimeReviewer() { return { requirements: { capabilities: ['model'] } }; }
+export function runtime(store, args, bus, usageRegistry = codexAndZaiUsageRegistry()) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, usageSnapshotProvider: () => usageRegistry.snapshot(), reviewer: runtimeReviewer(), eventBus: bus, emit, chatgptTabClosePolicy: policy, projectPathForJob: job => resolveManagedProjectPath(job.repository, arg(args, '--project-path'), arg(args, '--workspace-root') || defaultWorkspaceRoot()) }); }
 export async function createService(args) {
     const loaded = await storeFor(args);
     const upstream = eventBus(args);
     const bus = upstream ? new ServiceEventBus(upstream) : undefined;
-    const reconciler = runtime(loaded.store, args, bus);
     const requestedUsageDays = Number(arg(args, '--usage-window-days', '1'));
     const usageWindowDays = Number.isInteger(requestedUsageDays) && requestedUsageDays > 0 ? requestedUsageDays : 1;
     const usageRegistry = codexAndZaiUsageRegistry(undefined, usageWindowDays);
+    const reconciler = runtime(loaded.store, args, bus, usageRegistry);
     const repo = arg(args, '--repo');
     let overviewProvider;
     if (repo) {
@@ -607,7 +639,7 @@ async function main() {
     }
     if (command === 'init') {
         const now = new Date().toISOString();
-        const job = { id: arg(args, '--id', randomUUID()), title: arg(args, '--title', 'Agents Relay job'), objective: arg(args, '--objective') || undefined, priority: priority(args), executionMode: executionMode(args), autoMerge: !hasArg(args, '--no-auto-merge'), reviewEnabled: !hasArg(args, '--no-review'), prNumber: Number(arg(args, '--pr', '0')), repository: arg(args, '--repo'), state: 'OPEN', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };
+        const job = { id: arg(args, '--id', randomUUID()), title: arg(args, '--title', 'Agents Relay job'), objective: arg(args, '--objective') || undefined, priority: priority(args), executionMode: executionMode(args), schedule: scheduleFromArgs(args), autoMerge: !hasArg(args, '--no-auto-merge'), reviewEnabled: !hasArg(args, '--no-review'), prNumber: Number(arg(args, '--pr', '0')), repository: arg(args, '--repo'), state: 'OPEN', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };
         let store;
         let file = null;
         if (arg(args, '--repo') && arg(args, '--pr'))
@@ -623,9 +655,26 @@ async function main() {
         console.log(`Initialized ${job.id}`);
         return;
     }
+    const bus = eventBus(args);
+    if (command === 'tick') {
+        const repo = repository(args);
+        const auth = await githubAuthContext(args);
+        const nowValue = arg(args, '--now');
+        const now = nowValue ? new Date(nowValue) : new Date();
+        if (Number.isNaN(now.getTime()))
+            throw new Error('--now must be a valid ISO timestamp');
+        const results = await processDueScheduledJobs({
+            client: auth.client,
+            repository: repo,
+            trustedAuthors: auth.trustedAuthors,
+            buckets: dueBuckets(now, integerArg(args, '--lookback-buckets', 3)),
+            now,
+        });
+        console.log(JSON.stringify({ repository: repo, processed: results.length, results }, null, 2));
+        return;
+    }
     const loaded = await storeFor(args);
     const { store, job, localFile } = loaded;
-    const bus = eventBus(args);
     if (command === 'agent-register') {
         const now = new Date().toISOString();
         const agent = { id: arg(args, '--agent-id', randomUUID()), name: arg(args, '--name'), responsibility: arg(args, '--responsibility'), role: arg(args, '--role'), capabilities: arg(args, '--capabilities').split(',').filter(Boolean), boundaries: arg(args, '--boundaries').split('|').filter(Boolean), endpoint: { kind: arg(args, '--endpoint-kind', 'adapter'), target: arg(args, '--endpoint') }, runtime: { adapter: arg(args, '--runtime', arg(args, '--adapter', 'shell')), provider: arg(args, '--provider') || undefined, model: arg(args, '--model') || undefined }, availability: arg(args, '--availability', 'available'), routing: { labels: arg(args, '--labels').split(',').filter(Boolean).reduce((out, item) => { const [key, value] = item.split('=', 2); if (key && value)

package/dist/dashboard.js

@@ -2,6 +2,7 @@ import { createServer } from 'node:http';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { readUsageSnapshot } from './usage.js';
 import { DeliveryDeduper, parseGitHubWebhook, verifyGitHubWebhook } from './github-webhook.js';
 const GITHUB_REPOSITORY_PATTERN = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,36}[A-Za-z0-9])?)\/([A-Za-z0-9._-]{1,100})$/;
 const SSE_HEARTBEAT_MS = 15000;
@@ -363,7 +364,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
     const usage = async () => {
         if (!usageRegistry)
             throw new Error('Account usage telemetry is unavailable');
-        return JSON.stringify(await usageRegistry.snapshot());
+        return JSON.stringify(await readUsageSnapshot(usageRegistry));
     };
     const server = createServer(async (req, res) => {
         if (req.url === '/') {

package/dist/events.js

@@ -50,5 +50,11 @@ export class NatsEventBus {
         })();
         return async () => { active = false; subscription.unsubscribe(); };
     }
+    async close() {
+        if (this.connection) {
+            await this.connection.close();
+            this.connection = null;
+        }
+    }
 }
 export function eventFor(jobId, taskId, parentTaskId, type, status, message, visibility = 'orchestrator', data, source) { return { version: 1, event_id: randomUUID(), job_id: jobId, task_id: taskId, parent_task_id: parentTaskId, type, status, timestamp: new Date().toISOString(), visibility, level: status === 'failed' || status === 'blocked' ? 'error' : 'info', message, data, source }; }

package/dist/planner.js

@@ -9,7 +9,7 @@ export function planningSpec(task) {
         throw new Error(`Initial task ${task.id} requires an output contract`);
     if (!['codex', 'chatgpt', 'orchestrator'].includes(task.adapter))
         throw new Error(`Initial task ${task.id} requires a supported adapter`);
-    return { id: task.id, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
+    return { id: task.id, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
 }
 export function orchestratorPlanningDecision(job, tasks, id, parentTaskId, round, source = 'orchestrator') {
     const now = new Date().toISOString();
@@ -34,6 +34,26 @@ function stringArray(value, field, fallback = []) {
         throw new Error(`Planner ${field} must be an array of non-empty strings`);
     return [...value];
 }
+function workerRequirements(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    const root = record(value);
+    const capabilities = stringArray(root.capabilities, `${field}.capabilities`);
+    const optional = (name) => optionalString(root[name], `${field}.${name}`);
+    const labelsValue = root.labels;
+    let labels;
+    if (labelsValue !== undefined) {
+        if (!labelsValue || typeof labelsValue !== 'object' || Array.isArray(labelsValue))
+            throw new Error(`Planner ${field}.labels must be an object`);
+        labels = {};
+        for (const [key, item] of Object.entries(labelsValue)) {
+            if (typeof item !== 'string' || item.length === 0)
+                throw new Error(`Planner ${field}.labels values must be non-empty strings`);
+            labels[key] = item;
+        }
+    }
+    return { capabilities, runtime: optional('runtime'), taskKind: optional('taskKind'), trustDomain: optional('trustDomain'), region: optional('region'), labels };
+}
 function rawValue(value) {
     if (typeof value === 'string')
         return JSON.stringify(value);
@@ -88,8 +108,8 @@ export function parsePlannerResult(value) {
         if (typeof task.input !== 'string' || task.input.length === 0)
             throw new Error(`Planner next_tasks[${index}].input is required`);
         const adapter = task.adapter;
-        if (adapter === undefined || !['codex', 'chatgpt'].includes(String(adapter)))
-            throw new Error(`Planner next_tasks[${index}].adapter must be codex or chatgpt`);
+        if (adapter !== undefined && !['codex', 'chatgpt'].includes(String(adapter)))
+            throw new Error(`Planner next_tasks[${index}].adapter must be codex or chatgpt when provided`);
         const output = task.output === undefined ? undefined : record(task.output);
         if (!output || (output.kind !== 'task_pr' && output.kind !== 'file'))
             throw new Error(`Planner next_tasks[${index}].output is required`);
@@ -102,6 +122,7 @@ export function parsePlannerResult(value) {
         const storySize = sizeValue;
         const maxAttempts = task.maxAttempts === undefined ? 3 : task.maxAttempts;
         const route = routing(task.routing, 'next_tasks[' + index + '].routing');
+        const requirements = workerRequirements(task.workerRequirements ?? task.requirements, 'next_tasks[' + index + '].workerRequirements');
         const timeoutMs = task.timeoutMs === undefined ? taskOverallTimeoutMs(storySize, route?.reasoning) : task.timeoutMs;
         if (typeof maxAttempts !== 'number' || !Number.isInteger(maxAttempts) || maxAttempts < 1)
             throw new Error(`Planner next_tasks[${index}].maxAttempts is invalid`);
@@ -110,7 +131,7 @@ export function parsePlannerResult(value) {
         return {
             id, input: task.input, priority, storySize,
             projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'),
-            dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'),
+            dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'), workerRequirements: requirements,
             adapter: adapter, output: output, routing: route,
             continuation: task.continuation, maxAttempts, timeoutMs
         };

package/dist/reconciler.js

@@ -5,6 +5,8 @@ import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
 import { parsePlannerResult, plannerInput } from './planner.js';
 import { executionContextPrompt, resolveExecutionContext } from './execution-context.js';
+import { selectReviewer } from './reviewer-routing.js';
+import { selectWorker, usageForProvider, workerCandidates } from './worker-routing.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
 export function managedWorkerInput(job, task, context) {
@@ -130,6 +132,7 @@ export class Reconciler {
             }
             await this.recoverLostExecutions(job, now);
             await this.recoverPlannerChildren(job);
+            await this.routeExecutableTasks(await this.store.load(jobId));
             for (const task of job.tasks)
                 if (task.state === 'CANCELLED') {
                     this.live.get(task.id)?.execution.cancel();
@@ -207,7 +210,7 @@ export class Reconciler {
         await this.store.saveJob(job);
     }
     async ensureFinalReview(job, prState, headSha) {
-        if (job.reviewEnabled === false || prState !== 'OPEN' || job.state !== 'COMPLETED' || !headSha)
+        if (job.schedule || job.reviewEnabled === false || prState !== 'OPEN' || job.state !== 'COMPLETED' || !headSha)
             return;
         if (!this.preReviewGatesPass(job))
             return;
@@ -221,19 +224,64 @@ export class Reconciler {
             return;
         const id = `final-review-${headSha.slice(0, 12)}`;
         const now = new Date().toISOString();
-        const task = { jobId: job.id, id, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer', parentTaskId: null, dependencies: job.tasks.filter(item => item.agentName !== 'reviewer' && !this.isSupersededTask(item)).map(item => item.id), capabilities: ['review'], adapter: this.options.reviewer?.adapter ?? 'codex', input: `Review PR #${job.prNumber} at head SHA ${headSha}. Objective: ${job.objective ?? job.description ?? job.title}. First publish task.started as the worker start acknowledgement with data.worker_owned=true, then verify the deterministic pre-review gates have passed and inspect the completed work. Emit review.started, then exactly one of review.approved, review.changes_required, or review.blocked with data.review.headSha set to ${headSha}. For review.changes_required, include every actionable finding in data.review.issues as an array of concise issue strings; Relay will create one durable fix task containing all findings. Do not modify code. When auto-merge is enabled, Relay will merge this exact reviewed head after review.approved.`, output: { kind: 'task_pr' }, routing: this.options.reviewer?.routing, continuation: null, continuationDeliveredAt: null, reviewHeadSha: headSha, state: 'QUEUED', attempt: 0, maxAttempts: this.options.reviewer?.maxAttempts ?? 2, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.reviewer?.timeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now };
+        const implementationTasks = job.tasks.filter(item => item.agentName !== 'reviewer' && !this.isSupersededTask(item));
+        const reviewerRouting = await this.selectReviewer(implementationTasks);
+        const task = { jobId: job.id, id, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer', parentTaskId: null, dependencies: implementationTasks.map(item => item.id), capabilities: ['review'], workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter, input: `Review PR #${job.prNumber} at head SHA ${headSha}. Objective: ${job.objective ?? job.description ?? job.title}. First publish task.started as the worker start acknowledgement with data.worker_owned=true, then verify the deterministic pre-review gates have passed and inspect the completed work. Emit review.started, then exactly one of review.approved, review.changes_required, or review.blocked with data.review.headSha set to ${headSha}. For review.changes_required, include every actionable finding in data.review.issues as an array of concise issue strings; Relay will create one durable fix task containing all findings. Do not modify code. When auto-merge is enabled, Relay will merge this exact reviewed head after review.approved.`, output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.routing, continuation: null, continuationDeliveredAt: null, reviewHeadSha: headSha, state: 'QUEUED', attempt: 0, maxAttempts: this.options.reviewer?.maxAttempts ?? 2, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.reviewer?.timeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now };
         await this.store.appendTask(task);
         job.review = { outcome: 'pending', headSha, taskId: id, evidence: null, updatedAt: now };
         job.state = 'RUNNING';
         job.updatedAt = now;
         await this.store.saveJob(job);
-        await this.emit(eventFor(job.id, id, null, 'review.created', 'queued', `Final review task ${id} created for ${headSha}`, 'orchestrator', { headSha, agentName: 'reviewer' }));
+        await this.emit(eventFor(job.id, id, null, 'review.created', 'queued', `Final review task ${id} created for ${headSha} using ${reviewerRouting.reason}`, 'orchestrator', { headSha, agentName: 'reviewer', reviewerRouting: { workerId: reviewerRouting.selection.workerId, reason: reviewerRouting.reason, selectedBy: reviewerRouting.selection.selectedBy } }));
         const ready = schedule(await this.store.load(job.id));
         await this.store.saveJob(ready);
         const reviewTask = ready.tasks.find(item => item.id === id && item.state === 'READY');
         if (reviewTask && (this.options.maxConcurrent ?? 4) > this.live.size + this.plannerLive.size)
             await this.launch(ready, reviewTask);
     }
+    async selectReviewer(implementationTasks) {
+        const configured = this.options.reviewer;
+        const registered = await this.store.listAgents();
+        const usage = this.options.usageSnapshotProvider ? await this.options.usageSnapshotProvider() : undefined;
+        const candidates = workerCandidates(this.options.adapters, registered, usage);
+        let constrained = candidates.filter(candidate => {
+            if (configured?.workerId && configured.workerId !== candidate.workerId)
+                return false;
+            if (configured?.adapter && configured.adapter !== candidate.adapter)
+                return false;
+            if (configured?.routing?.provider && configured.routing.provider !== candidate.routing.provider)
+                return false;
+            if (configured?.routing?.model && configured.routing.model !== candidate.routing.model)
+                return false;
+            return true;
+        }).map(candidate => ({ ...candidate, routing: configured?.routing ? { ...candidate.routing, ...configured.routing } : candidate.routing }));
+        // Explicit reviewer routing is a caller-owned hard constraint and remains
+        // readable in isolated/test runtimes that do not instantiate that adapter.
+        if (constrained.length === 0 && configured?.adapter && configured.routing) {
+            constrained = [{ workerId: configured.workerId ?? configured.adapter, adapter: configured.adapter, capabilities: ['model'], runtime: configured.adapter, routing: configured.routing }];
+        }
+        const result = selectReviewer(constrained, implementationTasks, configured?.requirements ?? { capabilities: ['model'] });
+        const resource = usageForProvider(usage, result.candidate.routing.provider);
+        result.selection.resourceHealthy = resource.healthy;
+        result.selection.resourceProvider = resource.healthy === undefined ? undefined : result.candidate.routing.provider;
+        result.selection.resourceUsedPercent = resource.usedPercent;
+        return result;
+    }
+    async routeExecutableTasks(job) {
+        const usage = this.options.usageSnapshotProvider ? await this.options.usageSnapshotProvider() : undefined;
+        const candidates = workerCandidates(this.options.adapters, await this.store.listAgents(), usage);
+        for (const task of job.tasks.filter(item => item.kind !== 'planner' && item.agentName !== 'reviewer' && item.adapter !== 'orchestrator' && ['QUEUED', 'READY', 'BLOCKED'].includes(item.state) && item.output && !item.workerSelection && (item.workerRequirements || item.planningSource === 'model-planner'))) {
+            const requirements = task.workerRequirements ?? { capabilities: task.capabilities.length > 0 ? task.capabilities : ['model'] };
+            const routed = selectWorker(candidates, requirements);
+            task.workerSelection = routed.selection;
+            task.adapter = routed.candidate.adapter;
+            task.routing = routed.candidate.routing;
+            task.timeoutMs = task.timeoutMs || taskOverallTimeoutMs(task.storySize ?? 'M', task.routing.reasoning);
+            task.updatedAt = new Date().toISOString();
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'worker.selected', 'queued', `Worker ${routed.selection.workerId} selected for task ${task.id}`, 'orchestrator', { workerSelection: routed.selection, workerRequirements: requirements }, { agent: 'relay', component: 'agents-relay' }));
+        }
+    }
     isSupersededTask(task) {
         return task.state === 'CANCELLED' && typeof task.error === 'string' && task.error.startsWith('Superseded ');
     }
@@ -337,31 +385,35 @@ export class Reconciler {
             return job;
         if (job.initialPlanning?.status === 'pending')
             return job;
-        const planners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        const allPlanners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
+        const scopedTasks = Number.isFinite(slot) ? job.tasks.filter(task => Date.parse(task.createdAt) >= slot) : job.tasks;
+        const planners = scopedTasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
         if (planners.some(task => ['QUEUED', 'READY', 'RUNNING', 'WAITING'].includes(task.state)))
             return job;
-        if (job.tasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
+        if (scopedTasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
             return job;
-        if (job.tasks.length > 0 && !planners.some(task => task.state === 'SUCCEEDED'))
+        if (scopedTasks.length > 0 && !planners.some(task => task.state === 'SUCCEEDED'))
             return job;
-        if (job.tasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
+        if (scopedTasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
             return job;
         if (planners.length > 0 && planners.at(-1)?.plannerResult?.objective_status === 'in_progress' && !job.tasks.some(task => task.planningDecisionId === planners.at(-1)?.id))
             return job;
         const latest = planners.at(-1);
         if (latest?.plannerResult?.objective_status === 'satisfied')
             return job;
-        if (latest && job.review && job.review.outcome !== 'approved')
+        if (latest && !job.schedule && job.review && job.review.outcome !== 'approved')
             return job;
+        const previousPlanner = allPlanners.at(-1);
         const used = new Set(job.tasks.map(task => task.id));
-        let number = planners.length + 1;
+        let number = allPlanners.length + 1;
         let id = `planner-${number}`;
         while (used.has(id)) {
             number += 1;
             id = `planner-${number}`;
         }
         const now = new Date().toISOString();
-        const task = { jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner', parentTaskId: latest?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: latest?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: planners.length + 1 };
+        const task = { jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner', parentTaskId: previousPlanner?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: previousPlanner?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: allPlanners.length + 1 };
         await this.store.appendTask(task);
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
         return this.store.load(job.id);
@@ -591,7 +643,7 @@ export class Reconciler {
     }
     plannerChild(job, planner, spec) {
         const now = new Date().toISOString();
-        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], adapter: spec.adapter, input: spec.input, output: spec.output, routing: spec.routing, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M', spec.routing?.reasoning), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
     }
     clearExecution(taskId, executionId) {
         const live = this.live.get(taskId);

package/dist/relayd.js

@@ -69,7 +69,8 @@ export async function runDaemon(argv) {
     const repositories = normalized.repository ? [normalized.repository] : discoveredRepositories.map(item => item.repository);
     const repositoryPaths = new Map(discoveredRepositories.map(item => [item.repository, item.path]));
     const explicitProjectPath = value(argv, '--project-path');
-    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), eventBus: bus, reviewer: runtimeReviewer(), projectPathForJob: job => repositoryPaths.get(job.repository) ?? resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot) });
+    const usageRegistry = codexAndZaiUsageRegistry();
+    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), usageSnapshotProvider: () => usageRegistry.snapshot(), eventBus: bus, reviewer: runtimeReviewer(), projectPathForJob: job => repositoryPaths.get(job.repository) ?? resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot) });
     if (repositories.length === 0)
         throw new Error(`No Git repositories with GitHub origins found under ${normalized.workspaceRoot ?? defaultWorkspaceRoot()}`);
     const pool = new RepositoryWorkerPool(client, repositories, trusted, concurrency, makeReconciler);
@@ -157,7 +158,6 @@ export async function runDaemon(argv) {
             return null;
         }
     };
-    const usageRegistry = codexAndZaiUsageRegistry();
     const server = serveDashboard(dashboardStore, Number(value(argv, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(value(argv, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), fallback?.id, usageRegistry, overviews, webhook, () => client.rateLimitStatus(), exactJob);
     await once(server, 'listening');
     const reconcileSafely = async () => {

package/dist/reviewer-routing.js

@@ -0,0 +1,64 @@
+function satisfies(candidate, requirements) {
+    if (candidate.availability && candidate.availability !== 'available')
+        return false;
+    if (candidate.resourceHealthy === false)
+        return false;
+    if (!requirements)
+        return true;
+    if (!requirements.capabilities.every(capability => candidate.capabilities.includes(capability)))
+        return false;
+    if (requirements.runtime && candidate.runtime !== requirements.runtime)
+        return false;
+    if (requirements.taskKind && candidate.taskKind !== requirements.taskKind)
+        return false;
+    if (requirements.trustDomain && !candidate.trustDomains?.includes(requirements.trustDomain))
+        return false;
+    if (requirements.region && candidate.region !== requirements.region)
+        return false;
+    if (requirements.labels && Object.entries(requirements.labels).some(([key, value]) => candidate.labels?.[key] !== value))
+        return false;
+    return true;
+}
+function producedWorkerIds(tasks) {
+    return new Set(tasks
+        .filter(task => task.agentName !== 'reviewer')
+        .map(task => task.workerSelection?.workerId ?? task.adapter));
+}
+function producedRoutes(tasks) {
+    return new Set(tasks
+        .filter(task => task.agentName !== 'reviewer' && task.routing)
+        .map(task => `${task.routing?.provider}\0${task.routing?.model}`));
+}
+/** Select a review worker only after hard gates, then prefer execution diversity. */
+export function selectReviewer(candidates, implementationTasks, requirements) {
+    const eligible = candidates.filter(candidate => satisfies(candidate, requirements));
+    if (eligible.length === 0)
+        throw new Error('No eligible reviewer worker satisfies the declared requirements');
+    const usedWorkers = producedWorkerIds(implementationTasks);
+    const usedRoutes = producedRoutes(implementationTasks);
+    const ranked = eligible.map((candidate, index) => ({
+        candidate,
+        index,
+        differentWorker: !usedWorkers.has(candidate.workerId),
+        differentRoute: !usedRoutes.has(`${candidate.routing.provider}\0${candidate.routing.model}`),
+    })).sort((left, right) => {
+        if (left.differentWorker !== right.differentWorker)
+            return left.differentWorker ? -1 : 1;
+        if (left.differentRoute !== right.differentRoute)
+            return left.differentRoute ? -1 : 1;
+        return left.index - right.index;
+    });
+    const selected = ranked[0];
+    const reason = selected.differentWorker ? 'worker-diversity' : selected.differentRoute ? 'provider-model-diversity' : 'eligible-fallback';
+    return {
+        candidate: selected.candidate,
+        selection: {
+            workerId: selected.candidate.workerId,
+            adapter: selected.candidate.adapter,
+            capabilities: [...selected.candidate.capabilities],
+            selectedBy: `worker-router:reviewer-diversity:${reason}`,
+            selectedAt: new Date().toISOString(),
+        },
+        reason,
+    };
+}

package/dist/scheduled-jobs.js

@@ -0,0 +1,195 @@
+import { GitHubStore, loadManagedGitHubPullRequestGraphql } from './store.js';
+import { bucketStart, nextScheduleRun, parseRunBucketLabel, runBucketLabel, scheduleBucket } from './scheduler.js';
+export const AUTONOMOUS_LABEL = 'agents-relay:autonomous';
+function searchPath(query, page) {
+    return `search/issues?q=${encodeURIComponent(query)}&sort=created&order=asc&per_page=100&page=${page}`;
+}
+export function dueBuckets(now, lookbackBuckets) {
+    if (!Number.isInteger(lookbackBuckets) || lookbackBuckets < 1 || lookbackBuckets > 36)
+        throw new Error('--lookback-buckets must be an integer from 1 to 36');
+    const result = [];
+    for (let age = lookbackBuckets - 1; age >= 0; age -= 1) {
+        result.push(scheduleBucket(new Date(bucketStart(now).getTime() - age * 600_000)));
+    }
+    return result;
+}
+export function indexedDueQuery(repository, bucket) {
+    const label = runBucketLabel(bucket);
+    return `repo:${repository} is:open is:pr label:"${AUTONOMOUS_LABEL}" label:"${label}"`;
+}
+async function issueLabels(client, repository, prNumber) {
+    const labels = [];
+    let page = 1;
+    for (;;) {
+        const response = await client.request(`repos/${repository}/issues/${prNumber}/labels?per_page=100&page=${page}`);
+        const items = Array.isArray(response) ? response : response.items;
+        if (!Array.isArray(items))
+            throw new Error(`GitHub label response for PR #${prNumber} was invalid`);
+        for (const item of items) {
+            const name = item.name;
+            if (typeof name === 'string')
+                labels.push(name);
+        }
+        if (items.length < 100)
+            return labels;
+        page += 1;
+    }
+}
+async function addLabel(client, repository, prNumber, label) {
+    await client.request(`repos/${repository}/issues/${prNumber}/labels`, {
+        method: 'POST',
+        body: JSON.stringify({ labels: [label] }),
+    });
+}
+async function removeLabel(client, repository, prNumber, label) {
+    await client.request(`repos/${repository}/issues/${prNumber}/labels/${encodeURIComponent(label)}`, { method: 'DELETE' });
+}
+async function ensureRepositoryLabel(client, repository, label, color) {
+    try {
+        await client.request(`repos/${repository}/labels/${encodeURIComponent(label)}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/404|Not Found/i.test(message))
+            throw error;
+        await client.request(`repos/${repository}/labels`, {
+            method: 'POST',
+            body: JSON.stringify({ name: label, color }),
+        });
+    }
+}
+export async function syncScheduleLabels(client, repository, job) {
+    const current = await issueLabels(client, repository, job.prNumber);
+    const target = job.schedule ? runBucketLabel(scheduleBucket(new Date(job.schedule.nextRunAt))) : null;
+    const expected = new Set(job.schedule ? [AUTONOMOUS_LABEL, target] : []);
+    if (job.schedule || current.includes(AUTONOMOUS_LABEL))
+        await ensureRepositoryLabel(client, repository, AUTONOMOUS_LABEL, '0E8A16');
+    if (target !== null)
+        await ensureRepositoryLabel(client, repository, target, 'D4C5F9');
+    for (const label of current) {
+        const isSchedulerLabel = label === AUTONOMOUS_LABEL || parseRunBucketLabel(label) !== null || /^agents-relay:next-run:\d{8}T\d{4}Z$/.test(label);
+        if (isSchedulerLabel && !expected.has(label))
+            await removeLabel(client, repository, job.prNumber, label);
+    }
+    if (job.schedule) {
+        if (!current.includes(AUTONOMOUS_LABEL))
+            await addLabel(client, repository, job.prNumber, AUTONOMOUS_LABEL);
+        if (target !== null && !current.includes(target))
+            await addLabel(client, repository, job.prNumber, target);
+    }
+}
+const SCHEDULE_WAKE_MARKER = '<!-- agents-relay:schedule-wake:v1 -->';
+async function pulseScheduleWake(client, repository, job) {
+    const body = `${SCHEDULE_WAKE_MARKER}
+Scheduled autonomous wake for \`${job.id}\` at \`${job.schedule?.lastScheduledSlot ?? 'unknown'}\`.`;
+    let page = 1;
+    for (;;) {
+        const response = await client.request(`repos/${repository}/issues/${job.prNumber}/comments?per_page=100&page=${page}`);
+        const items = Array.isArray(response) ? response : [];
+        const existing = items.find(item => typeof item.body === 'string' && String(item.body).includes(SCHEDULE_WAKE_MARKER));
+        if (existing && Number.isInteger(Number(existing.id))) {
+            await client.request(`repos/${repository}/issues/comments/${Number(existing.id)}`, { method: 'PATCH', body: JSON.stringify({ body }) });
+            return;
+        }
+        if (items.length < 100)
+            break;
+        page += 1;
+    }
+    await client.request(`repos/${repository}/issues/${job.prNumber}/comments`, { method: 'POST', body: JSON.stringify({ body }) });
+}
+export async function listIndexedScheduledJobs(client, repository, trustedAuthors, buckets) {
+    const found = new Map();
+    const seenPrs = new Set();
+    for (const bucket of buckets) {
+        const query = indexedDueQuery(repository, bucket);
+        for (let page = 1; page <= 10; page += 1) {
+            const response = await client.request(searchPath(query, page));
+            const items = Array.isArray(response?.items) ? response.items : [];
+            for (const item of items) {
+                const prNumber = Number(item.number);
+                if (!Number.isInteger(prNumber) || prNumber <= 0 || seenPrs.has(prNumber))
+                    continue;
+                seenPrs.add(prNumber);
+                const overviews = await loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trustedAuthors).catch((error) => {
+                    if (error instanceof Error && error.message.includes('has no durable'))
+                        return [];
+                    throw error;
+                });
+                const job = overviews.find(overview => overview.githubState === 'OPEN' && overview.job.schedule !== undefined)?.job;
+                if (!job?.schedule)
+                    continue;
+                const slotBucket = scheduleBucket(new Date(job.schedule.nextRunAt));
+                if (!buckets.includes(slotBucket))
+                    continue;
+                found.set(`${prNumber}:${job.id}`, { prNumber, jobId: job.id, bucket: slotBucket });
+            }
+            if (items.length < 100)
+                break;
+        }
+    }
+    return [...found.values()];
+}
+async function refresh(client, repository, trustedAuthors, ref) {
+    const store = new GitHubStore(client, repository, ref.prNumber, trustedAuthors);
+    return await store.load(ref.jobId);
+}
+export async function runScheduledBucket(client, repository, trustedAuthors, ref, engine, now = new Date()) {
+    let job = await refresh(client, repository, trustedAuthors, ref);
+    const schedule = job.schedule;
+    if (!schedule)
+        throw new Error(`Scheduled job ${job.id} has no schedule metadata`);
+    const slot = new Date(schedule.nextRunAt);
+    if (scheduleBucket(slot) !== ref.bucket || slot.getTime() > now.getTime()) {
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-idempotent' };
+    }
+    if (schedule.lastScheduledSlot && new Date(schedule.lastScheduledSlot).getTime() >= slot.getTime()) {
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-idempotent' };
+    }
+    const active = job.state === 'RUNNING' || job.tasks.some(task => ['READY', 'RUNNING'].includes(task.state));
+    if (active && schedule.concurrencyPolicy === 'skip') {
+        schedule.lastScheduledSlot = slot.toISOString();
+        schedule.nextRunAt = nextScheduleRun(schedule, now).toISOString();
+        job.updatedAt = now.toISOString();
+        await new GitHubStore(client, repository, ref.prNumber, trustedAuthors).saveJob(job);
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-active' };
+    }
+    if (active && schedule.concurrencyPolicy === 'queue') {
+        await syncScheduleLabels(client, repository, job);
+        return { job, status: 'skipped-active' };
+    }
+    const missedRunPolicy = schedule.missedRunPolicy;
+    schedule.lastScheduledSlot = slot.toISOString();
+    schedule.currentRunSlot = slot.toISOString();
+    schedule.nextRunAt = nextScheduleRun(schedule, missedRunPolicy === 'run' ? slot : now).toISOString();
+    job.updatedAt = now.toISOString();
+    const schedulerStore = new GitHubStore(client, repository, ref.prNumber, trustedAuthors);
+    job.state = 'RUNNING';
+    await schedulerStore.saveJob(job);
+    job = await schedulerStore.load(job.id);
+    await syncScheduleLabels(client, repository, job);
+    if (engine) {
+        await engine.reconcile(job.id);
+        await engine.idle();
+        const finished = await schedulerStore.load(job.id);
+        if (!finished.schedule)
+            throw new Error(`Scheduled job ${job.id} lost its schedule metadata`);
+        finished.schedule.lastRunAt = now.toISOString();
+        finished.updatedAt = now.toISOString();
+        await schedulerStore.saveJob(finished);
+        return { job: finished, status: 'completed' };
+    }
+    await pulseScheduleWake(client, repository, job);
+    return { job, status: 'dispatched' };
+}
+export async function processDueScheduledJobs(options) {
+    const due = await listIndexedScheduledJobs(options.client, options.repository, options.trustedAuthors, options.buckets);
+    const results = [];
+    for (const ref of due) {
+        const engine = options.engine ? options.engine(await refresh(options.client, options.repository, options.trustedAuthors, ref)) : undefined;
+        results.push(await runScheduledBucket(options.client, options.repository, options.trustedAuthors, ref, engine, options.now));
+    }
+    return results;
+}

package/dist/scheduler.js

@@ -5,7 +5,15 @@ export function detectCycles(tasks) { const map = new Map(tasks.map(t => [t.id,
     return; visiting.add(id); for (const dep of map.get(id)?.dependencies ?? [])
     visit(dep); visiting.delete(id); done.add(id); }; for (const task of tasks)
     visit(task.id); }
+function scheduledCycleTasks(job) {
+    const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
+    if (!Number.isFinite(slot))
+        return job.tasks;
+    return job.tasks.filter(task => Date.parse(task.createdAt) >= slot);
+}
 export function completionGateSatisfied(job) {
+    if (job.schedule)
+        return false;
     if (job.executionMode !== 'autonomous')
         return true;
     const planners = job.tasks.filter(task => task.kind === 'planner');
@@ -13,7 +21,8 @@ export function completionGateSatisfied(job) {
 }
 export function schedule(job) {
     detectCycles(job.tasks);
-    if (job.tasks.length === 0) {
+    const scopedTasks = scheduledCycleTasks(job);
+    if (scopedTasks.length === 0) {
         if (job.executionMode === 'autonomous' && job.state !== 'WAITING') {
             assertJobTransition(job.state, 'WAITING');
             job.state = 'WAITING';
@@ -22,16 +31,27 @@ export function schedule(job) {
         return job;
     }
     const map = new Map(job.tasks.map(t => [t.id, t]));
-    for (const task of job.tasks) {
+    for (const task of scopedTasks) {
         if (['QUEUED', 'WAITING'].includes(task.state) && dependencyReady(task, map))
             transitionTask(task, 'READY');
     }
-    const active = job.tasks.some(t => ['READY', 'RUNNING'].includes(t.state));
-    const blocked = job.tasks.some(t => t.state === 'BLOCKED');
-    const waiting = job.tasks.some(t => ['QUEUED', 'WAITING'].includes(t.state));
-    const failed = job.tasks.some(t => t.state === 'FAILED');
-    const cancelled = job.tasks.every(t => t.state === 'CANCELLED');
+    const active = scopedTasks.some(t => ['READY', 'RUNNING'].includes(t.state));
+    const blocked = scopedTasks.some(t => t.state === 'BLOCKED');
+    const waiting = scopedTasks.some(t => ['QUEUED', 'WAITING'].includes(t.state));
+    const failed = scopedTasks.some(t => t.state === 'FAILED');
+    const cancelled = scopedTasks.every(t => t.state === 'CANCELLED');
     const next = active ? 'RUNNING' : failed ? 'FAILED' : blocked ? 'BLOCKED' : waiting ? 'WAITING' : cancelled ? 'CANCELLED' : completionGateSatisfied(job) ? 'COMPLETED' : 'WAITING';
+    if (job.schedule && next === 'WAITING') {
+        const planners = scopedTasks.filter(task => task.kind === 'planner');
+        const latest = planners.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)).at(-1);
+        if (latest?.state === 'SUCCEEDED' && latest.plannerResult?.objective_status === 'satisfied') {
+            const slot = job.schedule.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
+            const lastRun = job.schedule.lastRunAt ? Date.parse(job.schedule.lastRunAt) : Number.NaN;
+            if (Number.isFinite(slot) && (!Number.isFinite(lastRun) || lastRun < slot))
+                job.schedule.lastRunAt = new Date().toISOString();
+            job.schedule.currentRunSlot = null;
+        }
+    }
     if (job.state !== next) {
         assertJobTransition(job.state, next);
         job.state = next;
@@ -47,3 +67,149 @@ export function extendRetryBudget(task, windowSize = 3) {
 }
 export function transitionTask(task, state) { assertTaskTransition(task.state, state); task.state = state; if (['READY', 'RUNNING', 'SUCCEEDED'].includes(state))
     task.error = null; task.updatedAt = new Date().toISOString(); }
+export const SCHEDULE_RESOLUTION_MS = 600_000;
+export const RUN_BUCKET_LABEL_COUNT = 144;
+const CRON_PART = /^(?:\*|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/;
+function cronField(raw, name, minimum, maximum) {
+    const values = new Set();
+    for (const part of raw.split(',')) {
+        const match = CRON_PART.exec(part);
+        if (!match)
+            throw new Error(`Invalid schedule ${name}: ${part}`);
+        const [whole, firstText, lastText, stepText] = match;
+        if (whole === undefined)
+            continue;
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            throw new Error(`Invalid schedule ${name} step: ${part}`);
+        let start = minimum;
+        let end = maximum;
+        if (firstText !== undefined) {
+            start = Number(firstText);
+            end = lastText === undefined ? (stepText === undefined ? start : maximum) : Number(lastText);
+            if (start < minimum || end > maximum || start > end)
+                throw new Error(`Invalid schedule ${name} range: ${part}`);
+        }
+        for (let value = start; value <= end; value += step) {
+            if (value > maximum)
+                break;
+            values.add(name === 'weekday' && value === 7 ? 0 : value);
+        }
+    }
+    if (values.size === 0)
+        throw new Error(`Invalid schedule ${name}: ${raw}`);
+    return values;
+}
+export function parseCron(cron) {
+    const fields = cron.trim().split(/\s+/);
+    if (fields.length !== 5)
+        throw new Error('Schedule cron must contain exactly five fields');
+    const parsed = {
+        minute: cronField(fields[0], 'minute', 0, 59),
+        hour: cronField(fields[1], 'hour', 0, 23),
+        dayOfMonth: cronField(fields[2], 'day-of-month', 1, 31),
+        month: cronField(fields[3], 'month', 1, 12),
+        weekday: cronField(fields[4], 'weekday', 0, 7),
+    };
+    for (const minute of parsed.minute)
+        if (minute % (SCHEDULE_RESOLUTION_MS / 60_000) !== 0)
+            throw new Error(`Schedule minute ${minute} is finer than the 10-minute scheduler resolution`);
+    return parsed;
+}
+function timezoneParts(time, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-US', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', weekday: 'short', hourCycle: 'h23' }).formatToParts(time);
+    const value = (type) => parts.find(part => part.type === type)?.value ?? '';
+    const weekdays = new Map([['Sun', 0], ['Mon', 1], ['Tue', 2], ['Wed', 3], ['Thu', 4], ['Fri', 5], ['Sat', 6]]);
+    const weekday = weekdays.get(value('weekday'));
+    if (weekday === undefined)
+        throw new Error(`Unable to resolve timezone weekday ${timeZone}`);
+    return { year: Number(value('year')), month: Number(value('month')), day: Number(value('day')), hour: Number(value('hour')), minute: Number(value('minute')), weekday };
+}
+function cronMatches(fields, time, timeZone) {
+    const local = timezoneParts(time, timeZone);
+    if (!fields.minute.has(local.minute) || !fields.hour.has(local.hour) || !fields.month.has(local.month))
+        return false;
+    const domWildcard = fields.dayOfMonth.size === 31;
+    const dowWildcard = fields.weekday.size === 7;
+    const domMatch = fields.dayOfMonth.has(local.day);
+    const dowMatch = fields.weekday.has(local.weekday);
+    const dayMatch = domWildcard && dowWildcard ? true : domWildcard ? dowMatch : dowWildcard ? domMatch : domMatch || dowMatch;
+    return dayMatch;
+}
+export function nextCronRun(cron, timeZone, after = new Date()) {
+    const fields = parseCron(cron);
+    if (!isValidTimeZone(timeZone))
+        throw new Error(`Invalid schedule timezone: ${timeZone}`);
+    const candidate = new Date(Math.floor((after.getTime() + 60_000) / 60_000) * 60_000);
+    const limit = candidate.getTime() + 366 * 24 * 60 * 60_000;
+    while (candidate.getTime() < limit) {
+        if (cronMatches(fields, candidate, timeZone))
+            return new Date(candidate);
+        candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+    }
+    throw new Error(`Schedule ${cron} has no next run within one year`);
+}
+export function isValidTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseJobSchedule(options) {
+    const fields = parseCron(options.cron);
+    if (!isValidTimeZone(options.timezone))
+        throw new Error(`Invalid schedule timezone: ${options.timezone}`);
+    const missedRunPolicy = options.missedRunPolicy ?? 'skip';
+    const concurrencyPolicy = options.concurrencyPolicy ?? 'skip';
+    if (!['run', 'skip'].includes(missedRunPolicy))
+        throw new Error('Invalid missed-run policy');
+    if (!['skip', 'queue'].includes(concurrencyPolicy))
+        throw new Error('Invalid schedule concurrency policy');
+    const next = options.nextRunAt ? new Date(options.nextRunAt) : nextCronRun(options.cron, options.timezone);
+    if (Number.isNaN(next.getTime()))
+        throw new Error('Invalid schedule next-run time');
+    const aligned = new Date(Math.floor(next.getTime() / 60_000) * 60_000);
+    if (!cronMatches(fields, aligned, options.timezone))
+        throw new Error('Schedule next-run time does not match the cron expression');
+    return {
+        cron: options.cron.trim(),
+        timezone: options.timezone,
+        nextRunAt: aligned.toISOString(),
+        missedRunPolicy,
+        concurrencyPolicy,
+        lastScheduledSlot: null,
+        currentRunSlot: null,
+        lastRunAt: null,
+    };
+}
+export function nextScheduleRun(schedule, after = new Date()) {
+    return nextCronRun(schedule.cron, schedule.timezone, after);
+}
+export function bucketStart(time = new Date()) {
+    return new Date(Math.floor(time.getTime() / SCHEDULE_RESOLUTION_MS) * SCHEDULE_RESOLUTION_MS);
+}
+export function scheduleBucket(time) {
+    const bucket = bucketStart(time);
+    return `${bucket.toISOString().slice(0, 4)}${bucket.toISOString().slice(5, 7)}${bucket.toISOString().slice(8, 10)}T${bucket.toISOString().slice(11, 13)}${bucket.toISOString().slice(14, 16)}Z`;
+}
+export function runBucketLabel(bucket) {
+    if (!/^\d{8}T\d{4}Z$/.test(bucket))
+        throw new Error(`Invalid schedule bucket: ${bucket}`);
+    const hour = Number(bucket.slice(9, 11));
+    const minute = Number(bucket.slice(11, 13));
+    const slot = hour * 6 + minute / 10;
+    return `agents-relay:next-run:${slot}`;
+}
+export function parseRunBucketLabel(label) {
+    const prefix = 'agents-relay:next-run:';
+    if (!label.startsWith(prefix))
+        return null;
+    const value = label.slice(prefix.length);
+    if (!/^\d{1,3}$/.test(value))
+        return null;
+    const slot = Number(value);
+    return Number.isInteger(slot) && slot >= 0 && slot < RUN_BUCKET_LABEL_COUNT ? value : null;
+}

package/dist/store.js

@@ -82,7 +82,7 @@ function immutableTaskDefinition(task) {
     } : undefined;
     return {
         jobId: task.jobId, id: task.id, priority: task.priority, storySize: task.storySize ?? 'M', projectName: task.projectName, agentName: task.agentName,
-        kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter,
+        kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, workerSelection: task.workerSelection, adapter: task.adapter,
         input: task.input, attachments: task.attachments, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
     };
 }

package/dist/usage.js

@@ -348,6 +348,10 @@ export class UsageRegistry {
         };
     }
 }
+/** Read one fresh, on-demand snapshot from the shared usage source. */
+export function readUsageSnapshot(source) {
+    return source.snapshot();
+}
 export class UnavailableUsageReader {
     reason;
     now;

package/dist/worker-routing.js

@@ -0,0 +1,76 @@
+export function usageForProvider(snapshot, provider) {
+    const usage = snapshot?.providers.find(item => item.id === provider)?.usage;
+    if (!usage || !usage.available)
+        return {};
+    const usedPercent = Math.max(usage.fiveHour?.usedPercent ?? 0, usage.weekly?.usedPercent ?? 0);
+    return { healthy: usedPercent < 100, usedPercent };
+}
+export function workerCandidates(adapters, registered, snapshot) {
+    return adapters.filter(adapter => adapter.name !== 'orchestrator').flatMap(adapter => {
+        const defaults = adapter.name === 'chatgpt' ? { provider: 'chatgpt', model: 'account-defaults' } : { provider: 'openai', model: 'gpt-5.6-luna' };
+        const workers = registered.filter(worker => worker.runtime.adapter === adapter.name);
+        return (workers.length > 0 ? workers : [undefined]).map(worker => {
+            const provider = worker?.runtime.provider ?? defaults.provider;
+            const resource = usageForProvider(snapshot, provider);
+            return {
+                workerId: worker?.id ?? adapter.id,
+                adapter: adapter.name,
+                capabilities: worker?.capabilities ?? [
+                    ...adapter.capabilities,
+                    ...(adapter.name === 'codex' ? ['local_repo', 'iterative_tools', 'long_running'] : ['web_session', 'attachments', 'interactive_ui', 'one_shot']),
+                ],
+                runtime: worker?.runtime.adapter ?? adapter.name,
+                trustDomains: worker?.routing.trustDomains,
+                region: worker?.routing.regions?.[0],
+                labels: worker?.routing.labels,
+                availability: worker?.availability,
+                resourceHealthy: resource.healthy,
+                resourceProvider: provider,
+                resourceUsedPercent: resource.usedPercent,
+                routing: { provider, model: worker?.runtime.model ?? defaults.model, decidedBy: 'model-router', decidedAt: new Date().toISOString() },
+            };
+        });
+    });
+}
+function satisfies(candidate, requirements) {
+    if (candidate.availability && candidate.availability !== 'available')
+        return false;
+    if (candidate.resourceHealthy === false)
+        return false;
+    if (!requirements.capabilities.every(capability => candidate.capabilities.includes(capability)))
+        return false;
+    if (requirements.runtime && candidate.runtime !== requirements.runtime)
+        return false;
+    if (requirements.taskKind && candidate.taskKind !== requirements.taskKind)
+        return false;
+    if (requirements.trustDomain && !candidate.trustDomains?.includes(requirements.trustDomain))
+        return false;
+    if (requirements.region && candidate.region !== requirements.region)
+        return false;
+    if (requirements.labels && Object.entries(requirements.labels).some(([key, value]) => candidate.labels?.[key] !== value))
+        return false;
+    return true;
+}
+export function selectWorker(candidates, requirements) {
+    const eligible = candidates.filter(candidate => satisfies(candidate, requirements));
+    if (eligible.length === 0)
+        throw new Error('No eligible worker satisfies the declared requirements');
+    const ranked = eligible.map((candidate, index) => ({ candidate, index })).sort((a, b) => {
+        const pressure = (item) => item.resourceUsedPercent === undefined ? 1 : item.resourceUsedPercent >= 90 ? 2 : 0;
+        return pressure(a.candidate) - pressure(b.candidate) || a.index - b.index;
+    });
+    const selected = ranked[0].candidate;
+    return {
+        candidate: selected,
+        selection: {
+            workerId: selected.workerId,
+            adapter: selected.adapter,
+            capabilities: [...selected.capabilities],
+            selectedBy: 'worker-router:requirements',
+            selectedAt: new Date().toISOString(),
+            resourceHealthy: selected.resourceHealthy,
+            resourceProvider: selected.resourceProvider,
+            resourceUsedPercent: selected.resourceUsedPercent,
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.41",
+  "version": "1.0.43",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/skills/agents-relay/agents/planner.agent.md

@@ -13,12 +13,13 @@ Inspect the durable objective and task tree, then decide whether the objective i
 - Prefer small independently verifiable tasks.
 - Preserve parent/subtask causality and stable IDs.
 - A child task describes what an agent must accomplish. Never emit a shell command as a worker task.
-- Every child task must use adapter `codex` or `chatgpt`.
+- Every child task must declare `workerRequirements` (capabilities plus any runtime, task-kind, trust-domain, region, or label constraints). The worker-router resolves those requirements against the fresh usage snapshot and available workers before model-router chooses provider/model details.
+- Do not choose `codex`/`chatgpt` or provider/model heuristically. When a selected worker is supplied by the caller, consume that selection; otherwise leave worker selection to the worker-router.
 - Every child task must declare exactly one output: `task_pr` or `file`.
-- Include routing metadata for every model-backed child task.
+- Do not emit provider/model routing metadata; worker-router and model-router add it after planning.
 - Every child task must include `storySize` according to the shared Task / Job Contract. Use `M` when uncertain.
 - Return no prose outside the JSON result.
 
 ## Output
 
-Return exactly one JSON object with `objective_status`, `assessment`, and `next_tasks`. Each next task contains id, input, adapter, output, routing, storySize, and may also contain priority, projectName, agentName, dependencies, capabilities, maxAttempts, and timeoutMs. When the objective is satisfied, next_tasks must be empty.
+Return exactly one JSON object with `objective_status`, `assessment`, and `next_tasks`. Each next task contains id, input, `workerRequirements`, output, and storySize. Adapter/routing fields are selected by the runtime after worker-router runs; do not invent them. Each task may also contain priority, projectName, agentName, dependencies, capabilities, maxAttempts, and timeoutMs. When the objective is satisfied, next_tasks must be empty.

package/skills/agents-relay/contracts/task-job-contract.md

@@ -5,7 +5,18 @@ This contract is the shared protocol for every component that creates, schedules
 ## Task producers
 
 Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.
-Task producers choose semantic task properties such as objective, dependencies, adapter/routing, priority, and `storySize`. They do not normally choose raw timeout milliseconds.
+Task producers choose semantic task properties such as objective, dependencies, worker requirements, priority, and `storySize`. They do not normally choose an adapter, provider/model, or raw timeout milliseconds.
+
+## Worker routing order
+
+Every new model-backed executable task follows this order:
+
+1. The planner declares `workerRequirements` (capabilities and optional runtime, task-kind, trust-domain, region, and label constraints).
+2. `worker-router` resolves those requirements against available workers and a fresh on-demand usage snapshot from the shared usage registry. It applies capability/availability hard gates before considering resource evidence.
+3. `model-router` chooses provider/model/reasoning details for the selected worker.
+4. Relay persists the selected worker and model routing on the durable task before launch.
+
+Planner output must not hard-code `codex`/`chatgpt`, provider preference, or usage probes. The worker-router and model-router are separate responsibilities; usage readers remain owned by `src/usage.ts` and are not duplicated in either router. Legacy task records that already contain adapter/routing metadata remain readable, but newly produced planner tasks must carry worker requirements.
 
 ## Story size
 
@@ -27,6 +38,10 @@ Relay owns process lifecycle. Workers own semantic task lifecycle. A worker must
 
 A normal task never merges a PR. After all non-superseded work gates pass, Relay creates a SHA-bound final review task. The reviewer emits exactly one of `review.approved`, `review.changes_required`, or `review.blocked`. When `autoMerge` is enabled (default), Relay merges only after `review.approved`, pinned to the exact reviewed head SHA. A new task or new PR head makes earlier final-review evidence stale and requires a fresh review.
 
+Final-review routing follows the same worker-selection boundary as executable work. Capability, availability, explicit reviewer constraints, and resource health are hard gates. Among eligible workers, Relay prefers a reviewer with a different worker identity from the implementation tasks; when that is unavailable it prefers a different provider/model, then falls back to the first eligible worker. The selected worker, `selectedBy` reason, and `reviewerRouting` event data are durable evidence. No provider is a universal reviewer default.
+
 ## Fixed and autonomous jobs
 
 `fixed` jobs execute the orchestrator-provided task set and then proceed to final review. `autonomous` jobs may ask the planner for additional task batches. Planner-produced tasks must obey this same contract, including explicit `storySize`.
+
+A scheduled autonomous job adds cron/timezone/next-run and missed-run/concurrency policy to the trusted job marker, plus the `agents-relay:autonomous` label and one bounded time-of-day `agents-relay:next-run:*` index label. The GitHub heartbeat discovers only indexed due candidates, validates the marker's exact `nextRunAt`, claims the slot idempotently, advances the durable next run, and pulses `agents-relay:schedule-wake`. GitHub webhook delivery then wakes local Relay for planner/worker execution. While the schedule is active, each satisfied run returns the job to `WAITING` instead of entering final-review/auto-merge; older-cycle failures are historical evidence and do not block a later slot.