agents-relay 1.0.55 → 1.0.56

package/README.md

@@ -36,6 +36,8 @@ npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id chil
 npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child --queue
 ~~~
 
+Jobs separate durable lifecycle from derived runtime status. Durable lifecycle is `DRAFT | ACTIVE | COMPLETED | CANCELLED`: a newly created unscheduled Job is DRAFT, creating executable work activates it, and scheduled Jobs are ACTIVE because the scheduler is allowed to advance them. Runtime status (`IDLE`, `WAITING`, `QUEUED`, `RUNNING`, `BLOCKED`, `FAILED`, `REVIEWING`, `MERGE_PENDING`, `MERGED`, or `CANCELLED`) is computed from Tasks, Review, PR, and schedule facts and is never persisted as lifecycle truth.
+
 Jobs default to `fixed`. `job create` persists only the durable job and never
 creates executable tasks. The top-level orchestrator decides whether the user's
 request should start immediately and, if so, creates the first task batch
@@ -155,6 +157,6 @@ npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
   --input "Research the dashboard UX and write the final report to the declared output file."
 ~~~
 
-GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles its managed job to `COMPLETED`; a closed, unmerged PR reconciles to `CANCELLED` and cannot launch queued work. The dashboard exposes `/api/jobs` and shows repository-wide managed PR state beside each durable Agents Relay job state so stale markers are visible instead of being mistaken for current truth.
+GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles its managed job to `COMPLETED`; a closed, unmerged PR reconciles to `CANCELLED` and cannot launch queued work. The dashboard exposes `/api/jobs` and shows PR state, durable Job lifecycle, and derived runtime status separately. A merged PR reconciles lifecycle to `COMPLETED`; a closed, unmerged PR reconciles lifecycle to `CANCELLED`.
 
 For work that was completed outside the relay but must be represented truthfully in durable history, use `npx agents-relay record --task-id <id> --summary <summary> --commit <sha>`. Recorded tasks use the `orchestrator` adapter and terminal `SUCCEEDED` state; they do not pretend a shell/model worker executed the work. This is a repair/backfill mechanism—normal work should be created as a durable Task before execution. Managed jobs also retain the GitHub PR body as the job description for dashboard display.

package/dist/cli.js

@@ -27,7 +27,7 @@ Usage:
   npx agents-relay <command> [options]
 
 Commands:
-  job create|update|show|list  Manage durable GitHub-backed jobs
+  job create|update|show|list|merge|cancel  Manage durable GitHub-backed jobs
   task create|update|show|list|retry|cancel  Manage durable tasks
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
@@ -43,13 +43,15 @@ Use 'node dist/cli.js' only for explicit local development/demo mode.`,
     job: `Manage GitHub-backed durable jobs.
 
 Usage:
-  npx agents-relay job <create|update|show|list> [options]
+  npx agents-relay job <create|update|show|list|merge|cancel> [options]
 
 Actions:
   create  Create a durable Job, optionally binding an existing unmanaged PR
   update  Partially update mutable metadata on a healthy existing Job
   show    Show one durable Job
   list    List managed Jobs in a repository
+  merge   Merge the backing PR and complete the Job
+  cancel  Close the backing PR and cancel the Job
 
 Common options:
   --repo OWNER/REPO       GitHub repository
@@ -87,6 +89,12 @@ Required: --repo OWNER/REPO.
 
 Example:
   npx agents-relay job list --repo OWNER/REPO`,
+    'job merge': `Merge the backing pull request and complete the durable Job.
+
+Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. The current PR head SHA is pinned into the merge request.`,
+    'job cancel': `Cancel the durable Job and close its backing pull request.
+
+Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. Nonterminal Tasks are cancelled before the PR is closed.`,
     task: `Manage durable tasks.
 
 Usage:
@@ -307,7 +315,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         reviewEnabled: options.reviewEnabled ?? true,
         prNumber: pr.number,
         repository: repositoryName,
-        state: 'OPEN',
+        state: options.schedule ? 'ACTIVE' : 'DRAFT',
         continuation: options.continuation ?? null,
         createdAt: now,
         updatedAt: now,
@@ -386,18 +394,15 @@ async function runTaskCommand(action, args) {
     if (!id)
         throw new Error(`task ${action} requires --task-id`);
     if (action === 'create') {
+        if (['COMPLETED', 'CANCELLED'].includes(job.state))
+            throw new Error(`Cannot create task on terminal job ${job.id} (${job.state})`);
         const now = new Date().toISOString();
         const task = workerTaskFromArgs(job, args, now);
         task.id = id;
         await store.appendTask(task);
         const refreshed = await store.load(job.id);
-        const hasActive = refreshed.tasks.some(item => ['QUEUED', 'RUNNING'].includes(item.state));
-        const hasBlocked = refreshed.tasks.some(item => item.state === 'BLOCKED');
-        const hasDraft = refreshed.tasks.some(item => item.state === 'DRAFT');
-        const hasFailed = refreshed.tasks.some(item => item.state === 'FAILED');
-        const nextState = hasActive ? 'RUNNING' : hasBlocked ? 'BLOCKED' : hasDraft ? 'WAITING' : hasFailed ? 'FAILED' : refreshed.state;
-        if (refreshed.state !== nextState) {
-            refreshed.state = nextState;
+        if (refreshed.state === 'DRAFT') {
+            refreshed.state = 'ACTIVE';
             refreshed.updatedAt = now;
             await store.saveJob(refreshed);
         }
@@ -421,8 +426,8 @@ async function runTaskCommand(action, args) {
         task.error = action === 'retry' ? null : 'Cancelled by user';
         task.updatedAt = new Date().toISOString();
         await store.saveTask(task);
-        if (action === 'retry' && job.state !== 'RUNNING') {
-            job.state = 'RUNNING';
+        if (action === 'retry' && job.state === 'DRAFT') {
+            job.state = 'ACTIVE';
             job.updatedAt = task.updatedAt;
             await store.saveJob(job);
         }
@@ -520,7 +525,7 @@ async function runContextCommand(action, args) {
     console.log(JSON.stringify(context, null, 2));
 }
 async function runJobCommand(action, args) {
-    if (!['create', 'update', 'show', 'list'].includes(action))
+    if (!['create', 'update', 'show', 'list', 'merge', 'cancel'].includes(action))
         throw new Error(usage);
     const repo = repository(args);
     if (action === 'create') {
@@ -571,6 +576,34 @@ async function runJobCommand(action, args) {
         return;
     }
     await store.validateJobBinding(id);
+    if (action === 'merge') {
+        if (job.state === 'CANCELLED')
+            throw new Error(`Cannot merge cancelled job ${job.id}`);
+        const headSha = await store.headSha();
+        await store.mergePullRequest(headSha ?? undefined);
+        job.state = 'COMPLETED';
+        job.updatedAt = new Date().toISOString();
+        await store.saveJob(job);
+        console.log(JSON.stringify(await store.load(id), null, 2));
+        return;
+    }
+    if (action === 'cancel') {
+        if (job.state === 'COMPLETED')
+            throw new Error(`Cannot cancel completed job ${job.id}`);
+        for (const task of job.tasks.filter(item => !['SUCCEEDED', 'CANCELLED'].includes(item.state))) {
+            transitionTask(task, 'CANCELLED');
+            task.error = 'Job cancelled';
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            await store.saveTask(task);
+        }
+        await store.closePullRequest();
+        job.state = 'CANCELLED';
+        job.updatedAt = new Date().toISOString();
+        await store.saveJob(job);
+        console.log(JSON.stringify(await store.load(id), null, 2));
+        return;
+    }
     if (hasArg(args, '--title'))
         job.title = arg(args, '--title');
     if (hasArg(args, '--objective'))
@@ -705,7 +738,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), 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: [] };
+        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: scheduleFromArgs(args) ? 'ACTIVE' : 'DRAFT', continuation: continuation(args), createdAt: now, updatedAt: now, tasks: [] };
         let store;
         let file = null;
         if (arg(args, '--repo') && arg(args, '--pr'))

package/dist/dashboard.js

@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { readUsageSnapshot } from './usage.js';
+import { deriveJobRuntimeStatus } from './runtime-status.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;
@@ -94,10 +95,10 @@ export const dashboardHtml = `<!doctype html>
     .job-meta { display:flex; gap:.4rem; flex-wrap:wrap; color:var(--muted); font-size:.7rem; }
     .job-meta span { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
     .status-pill,.badge { display:inline-flex; align-items:center; border-radius:999px; padding:.06rem .42rem; min-height:1.35rem; font-size:.68rem; font-weight:800; }
-    .status-pill.ok,.badge.RUNNING,.badge.SUCCEEDED,.badge.COMPLETED { background:#e5f3e9; color:var(--ok); }
+    .status-pill.ok,.badge.ACTIVE,.badge.RUNNING,.badge.SUCCEEDED,.badge.COMPLETED,.badge.MERGED { background:#e5f3e9; color:var(--ok); }
     .status-pill.warn,.badge.BLOCKED,.badge.DRAFT,.badge.QUEUED,.badge.WAITING,.badge.OPEN { background:#fff1d2; color:var(--warn); }
     .status-pill.bad,.badge.FAILED { background:#ffe8e8; color:var(--bad); }
-    .status-pill.neutral,.badge.CANCELLED { background:#edf0f4; color:var(--muted); }
+    .status-pill.neutral,.badge.IDLE,.badge.CANCELLED { background:#edf0f4; color:var(--muted); }
     .badge.DRAFT { background:#eef2ff; color:#3f51b5; }
     .badge.MERGE_PENDING { background:#ffe3a3; color:#7a4a00; }
     .job-summary,.detail-groups { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:.55rem; }
@@ -221,7 +222,6 @@ function rememberSelection(){if(selectedJob)sessionStorage.setItem('agents-relay
 function selected(){return jobs.find(job=>job.id===selectedJob)||jobs[0]||null;}
 function counts(tasks){const out={};for(const task of Array.isArray(tasks)?tasks:[])out[task.state]=(out[task.state]||0)+1;return out;}
 function compactCounts(input){const order=['RUNNING','BLOCKED','FAILED','QUEUED','DRAFT','SUCCEEDED','CANCELLED'];return order.filter(state=>input[state]).map(state=>input[state]+' '+state).join(', ')||'No tasks';}
-function awaitingInitialTask(job){return job?.state==='OPEN'&&Array.isArray(job?.tasks)&&job.tasks.length===0;}
 function relativeTime(timestamp){if(!timestamp)return '—';const parsed=Date.parse(timestamp);if(!Number.isFinite(parsed))return value(timestamp);const seconds=Math.max(0,Math.round((Date.now()-parsed)/1000));if(seconds<60)return 'just now';if(seconds<3600)return Math.floor(seconds/60)+'m ago';if(seconds<86400)return Math.floor(seconds/3600)+'h ago';return Math.floor(seconds/86400)+'d ago';}
 function safePrUrl(repository,prNumber){if(typeof repository!=='string'||!Number.isInteger(prNumber)||prNumber<=0)return null;const parts=repository.split('/');if(parts.length!==2)return null;const [owner,repo]=parts;if(!owner||!repo||owner==='.'||owner==='..'||repo==='.'||repo==='..')return null;if(!/^[A-Za-z0-9-]+$/.test(owner)||!/^[A-Za-z0-9._-]+$/.test(repo))return null;return 'https://github.com/'+owner+'/'+repo+'/pull/'+prNumber;}
 function prField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('GitHub PR')));const line=element('p','detail-value');const url=safePrUrl(job.repository,job.prNumber);if(url){const link=document.createElement('a');link.href=url;link.target='_blank';link.rel='noopener noreferrer';link.textContent='PR #'+job.prNumber;line.append(link);}else line.append(text('unavailable'));box.append(line);return box;}
@@ -237,15 +237,15 @@ function syncFilters(){
   selectedRepo=repos.includes(previousRepo)?previousRepo:'';
   repoFilter.value=selectedRepo;
 }
-function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const button=document.createElement('button');button.type='button';button.className='job-button'+(isCompleteUnmerged(job)?' complete-unmerged':'');button.setAttribute('aria-current',String(job.id===selectedJob));button.title=job.title||job.id;button.addEventListener('click',()=>selectJob(job.id));const meta=element('span','job-meta');meta.append(element('span','badge '+value(job.state),text(job.state)),element('span','badge mode-'+value(job.executionMode||'fixed'),text(value(job.executionMode||'fixed').toUpperCase())),element('span',job.draft?'badge DRAFT':'',text(job.draft?'DRAFT':value(job.githubState||'UNKNOWN'))));if(isCompleteUnmerged(job))meta.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));if(awaitingInitialTask(job))meta.append(element('span','badge WAITING',text('AWAITING INITIAL TASK')));meta.append(element('span','',text(job.repository||'unknown repo')),element('span','',text(relativeTime(job.updatedAt))));button.append(element('span','job-title',text('PR#'+value(job.prNumber)+': '+value(job.title||job.id))),meta,element('span','subtle',text(compactCounts(counts(job.tasks)))));jobList.append(element('li','',button));}}
+function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const button=document.createElement('button');button.type='button';button.className='job-button'+(isCompleteUnmerged(job)?' complete-unmerged':'');button.setAttribute('aria-current',String(job.id===selectedJob));button.title=job.title||job.id;button.addEventListener('click',()=>selectJob(job.id));const meta=element('span','job-meta');meta.append(element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))),element('span','badge '+value(job.state),text(job.state)),element('span','badge mode-'+value(job.executionMode||'fixed'),text(value(job.executionMode||'fixed').toUpperCase())),element('span',job.draft?'badge DRAFT':'',text(job.draft?'DRAFT':value(job.githubState||'UNKNOWN'))));if(isCompleteUnmerged(job))meta.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));meta.append(element('span','',text(job.repository||'unknown repo')),element('span','',text(relativeTime(job.updatedAt))));button.append(element('span','job-title',text('PR#'+value(job.prNumber)+': '+value(job.title||job.id))),meta,element('span','subtle',text(compactCounts(counts(job.tasks)))));jobList.append(element('li','',button));}}
 function taskNode(task,children,depth){const li=element('li');const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{selectedTaskId=task.id;eventTaskId=task.id;rememberSelection();clearEvents();renderAll();void loadEventHistory();});const id=element('span','task-id',text(task.id));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));li.append(row);const nested=children.get(task.id)||[];if(nested.length){const ul=element('ul','tree');for(const child of nested)ul.append(taskNode(child,children,depth+1));li.append(ul);}return li;}
 function buildTree(tasks){taskTree.replaceChildren();if(!Array.isArray(tasks)||!tasks.length){taskTree.append(element('li','empty',text('No tasks in durable state.')));return;}const known=new Set(tasks.map(task=>task.id));const children=new Map();const roots=[];for(const task of tasks){if(!task.parentTaskId||!known.has(task.parentTaskId))roots.push(task);else{const siblings=children.get(task.parentTaskId)||[];siblings.push(task);children.set(task.parentTaskId,siblings);}}for(const task of roots)taskTree.append(taskNode(task,children,0));}
 function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Number(task?.maxAttempts)||0;if(max>=3&&max%3===0){const effectiveMax=Math.max(max,Math.ceil(attempt/3)*3);return attempt+' / 3×'+(effectiveMax/3);}return attempt+' / '+max;}
 function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Task',task.id),field('Kind',task.kind||'work'),field('State',task.state),field('Planning decision',task.planningDecisionId||'—'),field('Planning source',task.planningSource||'—'),field('Planning round',task.planningRound===undefined?'—':String(task.planningRound)),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),chatField(task));if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));taskDetailRoot.append(groups);}
 function reviewStatus(job){const review=job?.review;if(!review)return 'Not started';if(review.outcome==='approved'&&review.headSha===job.headSha)return 'MERGE READY · approved';const stale=Array.isArray(job?.tasks)&&job.tasks.some(task=>task.agentName==='reviewer'&&task.reviewHeadSha&&job.headSha&&task.reviewHeadSha!==job.headSha);if(stale)return 'STALE · awaiting review';return String(review.outcome||'pending').replace('_',' ').toUpperCase();}
-function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent=value(job.title||job.id);if(job.id!==selectedJob){selectedJob=job.id;selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('GitHub state',job.githubState||'UNKNOWN'),field('Durable state',job.state),field('Execution mode',job.executionMode||'fixed'),field('Status',awaitingInitialTask(job)?'Awaiting initial task':job.state),field('Review',reviewStatus(job)),field('Review head SHA',job.review?.headSha||job.headSha||'—'),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}
+function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent=value(job.title||job.id);if(job.id!==selectedJob){selectedJob=job.id;selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('PR state',job.githubState||'UNKNOWN'),field('Lifecycle state',job.state),field('Runtime status',job.runtimeStatus||'IDLE'),field('Execution mode',job.executionMode||'fixed'),field('Review',reviewStatus(job)),field('Review head SHA',job.review?.headSha||job.headSha||'—'),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}
 function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();}
-function isCompleteUnmerged(job){return job.state==='COMPLETED'&&job.githubState==='OPEN';}
+function isCompleteUnmerged(job){return job.runtimeStatus==='MERGE_PENDING';}
 function isTerminalJob(job){return ['COMPLETED','CANCELLED'].includes(job.state)||['MERGED','CLOSED'].includes(job.githubState);}
 function compareJobs(a,b){const mergePendingDelta=Number(isCompleteUnmerged(b))-Number(isCompleteUnmerged(a));if(mergePendingDelta)return mergePendingDelta;const terminalDelta=Number(isTerminalJob(a))-Number(isTerminalJob(b));return terminalDelta||String(b.updatedAt).localeCompare(String(a.updatedAt));}
 async function loadJSON(url){const response=await fetch(url);if(!response.ok)throw new Error(response.status+' '+response.statusText);return response.json();}
@@ -295,7 +295,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
     const discoveredJobs = async (forceRefresh = false) => {
         try {
             const jobs = overviewProvider
-                ? (await overviewProvider(forceRefresh)).map(item => ({ ...item.job, githubState: item.githubState, mergedAt: item.mergedAt, closedAt: item.closedAt, draft: item.draft }))
+                ? (await overviewProvider(forceRefresh)).map(item => ({ ...item.job, githubState: item.githubState, runtimeStatus: deriveJobRuntimeStatus(item.job, item.githubState), mergedAt: item.mergedAt, closedAt: item.closedAt, draft: item.draft }))
                 : jobId ? [await store.load(jobId)] : [];
             lastKnownJobs = jobs;
             return jobs;

package/dist/pool.js

@@ -2,9 +2,9 @@ import { GitHubStore, listManagedGitHubJobs } from './store.js';
 import { eventFor } from './events.js';
 const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareJobPriority(a, b) { return RANK[a.priority ?? 'P2'] - RANK[b.priority ?? 'P2'] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
-export function runnableManagedJobs(items) { return items.filter(item => item.githubState === 'OPEN' && !item.draft && !['COMPLETED', 'CANCELLED'].includes(item.job.state)).map(item => item.job).sort(compareJobPriority); }
+export function runnableManagedJobs(items) { return items.filter(item => item.githubState === 'OPEN' && item.job.state === 'ACTIVE').map(item => item.job).sort(compareJobPriority); }
 export function needsLifecycleReconciliation(job, now = Date.now()) {
-    // Create-only Jobs stay OPEN until a caller explicitly creates work.
+    // DRAFT create-only Jobs stay dormant until a caller explicitly creates work.
     if (job.tasks.length === 0)
         return false;
     if (job.tasks.some(task => task.state === 'QUEUED' || (task.state === 'DRAFT' && task.dependencies.length > 0)))

package/dist/reconciler.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { storySizeTimeoutMs, taskOverallTimeoutMs, chatGptStartAckTimeoutMs } from './types.js';
 import { dependencyReady, schedule, transitionTask } from './scheduler.js';
+import { implementationComplete } from './runtime-status.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
 import { parsePlannerResult, plannerInput } from './planner.js';
@@ -129,7 +130,16 @@ export class Reconciler {
                     task.leaseExpiresAt = null;
                     await this.store.saveTask(task);
                 }
+                const terminalState = prState === 'MERGED' ? 'COMPLETED' : 'CANCELLED';
+                if (job.state !== terminalState) {
+                    job.state = terminalState;
+                    job.updatedAt = new Date().toISOString();
+                    await this.store.saveJob(job);
+                }
+                return this.store.load(jobId);
             }
+            if (job.state !== 'ACTIVE')
+                return job;
             await this.recoverLostExecutions(job, now);
             await this.recoverPlannerChildren(job);
             await this.routeExecutableTasks(await this.store.load(jobId));
@@ -138,7 +148,11 @@ export class Reconciler {
                     this.live.get(task.id)?.execution.cancel();
                     this.plannerLive.get(task.id)?.controller.abort();
                 }
-            let scheduled = schedule(await this.store.load(jobId));
+            const beforeSchedule = await this.store.load(jobId);
+            const scheduleBefore = JSON.stringify(beforeSchedule.schedule ?? null);
+            let scheduled = schedule(beforeSchedule);
+            if (scheduled.state !== previousState || JSON.stringify(scheduled.schedule ?? null) !== scheduleBefore)
+                await this.store.saveJob(scheduled);
             if (prState === 'OPEN') {
                 await this.ensureFinalReview(scheduled, prState, headSha);
                 scheduled = schedule(await this.store.load(jobId));
@@ -146,15 +160,7 @@ export class Reconciler {
             if (prState === 'OPEN' && scheduled.executionMode === 'autonomous') {
                 scheduled = schedule(await this.maybeCreatePlanner(scheduled));
             }
-            if (prState === 'MERGED') {
-                scheduled.state = 'COMPLETED';
-                scheduled.updatedAt = new Date().toISOString();
-            }
-            if (prState === 'CLOSED') {
-                scheduled.state = 'CANCELLED';
-                scheduled.updatedAt = new Date().toISOString();
-            }
-            if (scheduled.state !== previousState)
+            if (scheduled.state !== previousState || scheduled.updatedAt !== job.updatedAt)
                 await this.store.saveJob(scheduled);
             if (prState === 'OPEN') {
                 for (const task of scheduled.tasks.filter(item => item.state === 'SUCCEEDED' && (item.continuation || scheduled.continuation) && !item.continuationDeliveredAt))
@@ -176,17 +182,13 @@ export class Reconciler {
                 }
             }
             const finalState = schedule(await this.store.load(jobId));
-            if (prState === 'MERGED') {
-                finalState.state = 'COMPLETED';
-                finalState.updatedAt = new Date().toISOString();
-            }
-            if (prState === 'CLOSED') {
-                finalState.state = 'CANCELLED';
-                finalState.updatedAt = new Date().toISOString();
-            }
-            if (finalState.state !== scheduled.state || finalState.updatedAt !== scheduled.updatedAt)
+            if (finalState.updatedAt !== scheduled.updatedAt)
                 await this.store.saveJob(finalState);
             await this.ensureFinalReview(finalState, prState, headSha);
+            if (prState === 'OPEN' && finalState.reviewEnabled === false && implementationComplete(finalState) && finalState.autoMerge !== false && this.store.mergePullRequest && headSha) {
+                await this.store.mergePullRequest(headSha);
+                await this.emit(eventFor(finalState.id, 'job', null, 'job.merged', 'succeeded', 'Completed work merged PR #' + finalState.prNumber, 'user', { headSha, autoMerge: true }, { agent: 'relay', component: 'agents-relay' }));
+            }
             return this.store.load(jobId);
         }
         finally {
@@ -210,7 +212,7 @@ export class Reconciler {
         await this.store.saveJob(job);
     }
     async ensureFinalReview(job, prState, headSha) {
-        if (job.schedule || job.reviewEnabled === false || prState !== 'OPEN' || job.state !== 'COMPLETED' || !headSha)
+        if (job.schedule || job.reviewEnabled === false || prState !== 'OPEN' || job.state !== 'ACTIVE' || !implementationComplete(job) || !headSha)
             return;
         if (!this.preReviewGatesPass(job))
             return;
@@ -229,7 +231,6 @@ export class Reconciler {
         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} using ${reviewerRouting.reason}`, 'orchestrator', { headSha, agentName: 'reviewer', reviewerRouting: { workerId: reviewerRouting.selection.workerId, reason: reviewerRouting.reason, selectedBy: reviewerRouting.selection.selectedBy } }));
@@ -340,7 +341,6 @@ export class Reconciler {
                 await this.store.appendTask(fixTask);
                 await this.emit(eventFor(job.id, id, task.id, 'review.fix_task_created', 'queued', `Created one fix task ${id} for ${issues.length} reviewer finding(s)`, 'orchestrator', { headSha, issues }, { agent: 'relay', component: 'agents-relay' }));
             }
-            job.state = 'RUNNING';
         }
         job.updatedAt = job.review.updatedAt;
         await this.store.saveJob(job);

package/dist/relayd.js

@@ -14,6 +14,7 @@ import { githubAuthContext } from './github-auth.js';
 import { isEntrypoint, runtimePlanner, runtimeReviewer, startService, SERVICE_DEFAULTS } from './cli.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { defaultWorkspaceRoot, discoverWorkspaceRepositories, resolveManagedProjectPath } from './workspace.js';
+import { deriveJobRuntimeStatus } from './runtime-status.js';
 export const daemonHelp = `Agents Relay daemon runs the dashboard and worker pool.
 
 Usage:
@@ -151,7 +152,7 @@ export async function runDaemon(argv) {
             const refreshed = (await refreshPullRequest(cached.job.repository, cached.job.prNumber)).find(item => item.job.id === jobId);
             if (!refreshed)
                 return null;
-            return { ...refreshed.job, githubState: refreshed.githubState, mergedAt: refreshed.mergedAt, closedAt: refreshed.closedAt, draft: refreshed.draft };
+            return { ...refreshed.job, githubState: refreshed.githubState, runtimeStatus: deriveJobRuntimeStatus(refreshed.job, refreshed.githubState), mergedAt: refreshed.mergedAt, closedAt: refreshed.closedAt, draft: refreshed.draft };
         }
         catch (error) {
             process.stderr.write(`warning: selected job refresh unavailable: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/runtime-status.js

@@ -0,0 +1,52 @@
+function isSuperseded(task) {
+    return task.state === 'CANCELLED' && typeof task.error === 'string' && task.error.startsWith('Superseded ');
+}
+export function implementationTasks(job) {
+    return job.tasks.filter(task => task.agentName !== 'reviewer' && !isSuperseded(task));
+}
+export function implementationComplete(job) {
+    const tasks = implementationTasks(job);
+    return tasks.length > 0 && tasks.every(task => task.state === 'SUCCEEDED');
+}
+export function deriveJobRuntimeStatus(job, prState = 'OPEN') {
+    if (prState === 'MERGED')
+        return 'MERGED';
+    if (prState === 'CLOSED' || job.state === 'CANCELLED')
+        return 'CANCELLED';
+    if (job.state === 'DRAFT')
+        return 'IDLE';
+    if (job.schedule) {
+        if (job.tasks.some(task => task.state === 'RUNNING'))
+            return 'RUNNING';
+        if (job.tasks.some(task => task.state === 'QUEUED'))
+            return 'QUEUED';
+        if (job.tasks.some(task => task.state === 'BLOCKED'))
+            return 'BLOCKED';
+        if (job.tasks.some(task => task.state === 'FAILED'))
+            return 'FAILED';
+        if (job.tasks.some(task => task.state === 'DRAFT'))
+            return 'WAITING';
+        return 'WAITING';
+    }
+    const reviewTasks = job.tasks.filter(task => task.agentName === 'reviewer');
+    const reviewActive = reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state))
+        || job.review?.outcome === 'pending'
+        || job.review?.outcome === 'started';
+    if (job.review?.outcome === 'approved' && prState === 'OPEN')
+        return 'MERGE_PENDING';
+    if (reviewActive || (job.reviewEnabled !== false && implementationComplete(job) && job.review?.outcome !== 'approved'))
+        return 'REVIEWING';
+    if (job.tasks.some(task => task.state === 'RUNNING'))
+        return 'RUNNING';
+    if (job.tasks.some(task => task.state === 'QUEUED'))
+        return 'QUEUED';
+    if (job.tasks.some(task => task.state === 'BLOCKED'))
+        return 'BLOCKED';
+    if (job.tasks.some(task => task.state === 'FAILED'))
+        return 'FAILED';
+    if (job.tasks.some(task => task.state === 'DRAFT'))
+        return 'WAITING';
+    if (job.reviewEnabled === false && implementationComplete(job) && prState === 'OPEN')
+        return 'MERGE_PENDING';
+    return 'IDLE';
+}

package/dist/scheduled-jobs.js

@@ -147,7 +147,9 @@ export async function runScheduledBucket(client, repository, trustedAuthors, ref
         await syncScheduleLabels(client, repository, job);
         return { job, status: 'skipped-idempotent' };
     }
-    const active = job.state === 'RUNNING' || job.tasks.some(task => ['QUEUED', 'RUNNING'].includes(task.state));
+    if (job.state !== 'ACTIVE')
+        return { job, status: 'skipped-idempotent' };
+    const active = job.tasks.some(task => ['QUEUED', 'RUNNING'].includes(task.state));
     if (active && schedule.concurrencyPolicy === 'skip') {
         schedule.lastScheduledSlot = slot.toISOString();
         schedule.nextRunAt = nextScheduleRun(schedule, now).toISOString();
@@ -166,7 +168,6 @@ export async function runScheduledBucket(client, repository, trustedAuthors, ref
     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);

package/dist/scheduler.js

@@ -1,4 +1,4 @@
-import { assertJobTransition, assertTaskTransition } from './types.js';
+import { assertTaskTransition } from './types.js';
 export function dependencyReady(task, tasks) { return task.dependencies.every(id => tasks.get(id)?.state === 'SUCCEEDED'); }
 export function detectCycles(tasks) { const map = new Map(tasks.map(t => [t.id, t])); const visiting = new Set(); const done = new Set(); const visit = (id) => { if (visiting.has(id))
     throw new Error(`Dependency cycle at ${id}`); if (done.has(id))
@@ -22,14 +22,6 @@ export function completionGateSatisfied(job) {
 export function schedule(job) {
     detectCycles(job.tasks);
     const scopedTasks = scheduledCycleTasks(job);
-    if (scopedTasks.length === 0) {
-        if (job.executionMode === 'autonomous' && job.state !== 'WAITING') {
-            assertJobTransition(job.state, 'WAITING');
-            job.state = 'WAITING';
-            job.updatedAt = new Date().toISOString();
-        }
-        return job;
-    }
     const map = new Map(job.tasks.map(t => [t.id, t]));
     for (const task of scopedTasks) {
         const ready = dependencyReady(task, map);
@@ -40,13 +32,7 @@ export function schedule(job) {
         else if (task.state === 'QUEUED' && ready && task.error !== null)
             transitionTask(task, 'QUEUED');
     }
-    const active = scopedTasks.some(t => ['QUEUED', 'RUNNING'].includes(t.state));
-    const blocked = scopedTasks.some(t => t.state === 'BLOCKED');
-    const waiting = scopedTasks.some(t => t.state === 'DRAFT');
-    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') {
+    if (job.schedule) {
         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') {
@@ -55,13 +41,9 @@ export function schedule(job) {
             if (Number.isFinite(slot) && (!Number.isFinite(lastRun) || lastRun < slot))
                 job.schedule.lastRunAt = new Date().toISOString();
             job.schedule.currentRunSlot = null;
+            job.updatedAt = new Date().toISOString();
         }
     }
-    if (job.state !== next) {
-        assertJobTransition(job.state, next);
-        job.state = next;
-        job.updatedAt = new Date().toISOString();
-    }
     return job;
 }
 export function extendRetryBudget(task, windowSize = 3) {

package/dist/store.js

@@ -65,6 +65,7 @@ export class InMemoryStore {
         this.values.set(key, renderTaskComment(task));
     }
     async saveTask(task) { this.values.set(`${TASK_MARKER}:${task.jobId ?? ''}:${task.id}`, renderTaskComment(task)); }
+    async closePullRequest() { }
     async headSha() { const jobs = [...this.values.values()].map(parseJob).filter((x) => x !== null); return jobs[0]?.headSha ?? jobs[0]?.review?.headSha ?? null; }
     async listAgents() { return [...this.values.values()].map(parseAgent).filter((x) => x !== null); }
     async saveAgent(agent) { this.values.set(`${AGENT_MARKER}:${agent.id}`, renderAgentComment(agent)); }
@@ -473,6 +474,9 @@ export class GitHubStore {
         if (result.merged !== true)
             throw new Error(typeof result.message === 'string' ? result.message : 'Pull request #' + this.prNumber + ' was not merged');
     }
+    async closePullRequest() {
+        await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ state: 'closed' }) });
+    }
     async headSha() {
         const { owner, name } = this.repoParts();
         const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid}}}', { owner, name, number: this.prNumber });

package/dist/types.js

@@ -2,9 +2,9 @@ export const STORY_SIZE_TIMEOUT_MS = { S: 300000, M: 900000, L: 2700000 };
 export function storySizeTimeoutMs(size) { return STORY_SIZE_TIMEOUT_MS[size]; }
 export function taskOverallTimeoutMs(size, reasoning) { return storySizeTimeoutMs(size) * (reasoning?.toLowerCase() === 'high' ? 2 : 1); }
 export function chatGptStartAckTimeoutMs(overallTimeoutMs) { return Math.min(600000, Math.max(120000, Math.floor(overallTimeoutMs / 3))); }
-const jobTransitions = { OPEN: ['RUNNING', 'WAITING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], RUNNING: ['OPEN', 'WAITING', 'BLOCKED', 'COMPLETED', 'FAILED', 'CANCELLED'], WAITING: ['RUNNING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], BLOCKED: ['RUNNING', 'COMPLETED', 'CANCELLED'], COMPLETED: ['RUNNING', 'CANCELLED'], FAILED: ['RUNNING', 'COMPLETED', 'CANCELLED'], CANCELLED: ['RUNNING', 'COMPLETED'] };
+const jobLifecycleTransitions = { DRAFT: ['ACTIVE', 'COMPLETED', 'CANCELLED'], ACTIVE: ['COMPLETED', 'CANCELLED'], COMPLETED: [], CANCELLED: ['COMPLETED'] };
 const taskTransitions = { DRAFT: ['QUEUED', 'BLOCKED', 'CANCELLED'], QUEUED: ['DRAFT', 'RUNNING', 'BLOCKED', 'FAILED', 'CANCELLED'], RUNNING: ['BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'QUEUED'], BLOCKED: ['QUEUED', 'CANCELLED'], SUCCEEDED: [], FAILED: ['QUEUED', 'RUNNING', 'CANCELLED'], CANCELLED: [] };
-export function assertJobTransition(from, to) { if (from !== to && !jobTransitions[from].includes(to))
+export function assertJobLifecycleTransition(from, to) { if (from !== to && !jobLifecycleTransitions[from].includes(to))
     throw new Error(`Invalid job transition ${from} -> ${to}`); }
 export function assertTaskTransition(from, to) { if (from !== to && !taskTransitions[from].includes(to))
     throw new Error(`Invalid task transition ${from} -> ${to}`); }

package/package.json

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

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

@@ -40,12 +40,23 @@ Task readiness is explicit and must use these semantics:
 - `BLOCKED`: execution cannot continue without an external resolution or intervention. Once a Task has entered `RUNNING`, it must not return to `DRAFT`; waiting discovered during execution is `BLOCKED`.
 - `SUCCEEDED`, `FAILED`, and `CANCELLED` are terminal outcomes, except that retry explicitly requeues a failed/blocked Task.
 
-Do not use `WAITING` as a Task state. `WAITING` remains a Job state for an active Job that is intentionally awaiting a future trigger, schedule slot, or condition.
+Do not use `WAITING` as a Task state or durable Job lifecycle state. `WAITING` is a derived Job runtime status for an `ACTIVE` Job whose next progress depends on a future trigger, schedule slot, dependency release, or other condition.
 
 ## Worker lifecycle
 
 Relay owns process lifecycle. Workers own semantic task lifecycle. A worker must publish canonical `task.started` as its first execution action, then exactly one of `task.completed`, `task.failed`, `task.blocked`, or `task.cancelled`. Process launch/exit events do not substitute for worker semantic events.
 
+## Job lifecycle and runtime status
+
+Durable Job lifecycle is intentionally small: `DRAFT | ACTIVE | COMPLETED | CANCELLED`.
+
+- `DRAFT`: durable objective exists, but the execution engine must not run it.
+- `ACTIVE`: the execution engine may reconcile the Job. Scheduler, external triggers, manual actions, dependency release, workers, and review may all advance an ACTIVE Job.
+- `COMPLETED`: terminal successful lifecycle. `job merge` merges the backing PR; a merged PR is authoritative and reconciles the Job to COMPLETED.
+- `CANCELLED`: terminal cancellation. `job cancel` closes the backing PR; a closed, unmerged managed PR also reconciles the Job to CANCELLED.
+
+Job runtime status is derived, not persisted. Relay computes it from lifecycle plus Task, Review, PR, and schedule facts. Runtime values include `IDLE`, `WAITING`, `QUEUED`, `RUNNING`, `BLOCKED`, `FAILED`, `REVIEWING`, `MERGE_PENDING`, `MERGED`, and `CANCELLED`. A blocked Task does not by itself make the Job runtime BLOCKED when other runnable/running work can still advance the objective. Lifecycle is the execution gate; runtime status is observation.
+
 ## Job and review lifecycle
 
 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.
@@ -56,7 +67,7 @@ Final-review routing follows the same worker-selection boundary as executable wo
 
 The public CLI resource surface is:
 
-- `job create|update|show|list`
+- `job create|update|show|list|merge|cancel`
 - `task create|update|show|list|retry|cancel`
 
 `job create` persists only durable Job state. It never creates executable work. `task create` creates a real executable Task directly under the Job; direct orchestrator-created Tasks are not wrapped in synthetic planner Tasks and have no planner-round provenance.
@@ -67,4 +78,4 @@ A zero-task autonomous Job stays idle. An autonomous Job may begin with one or m
 
 Planner-produced Tasks 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.
+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, the durable Job remains `ACTIVE`; between runs its derived runtime status is `WAITING`. Scheduled recurring Jobs do not enter one-shot final-review/auto-merge after each satisfied run; older-cycle failures are historical evidence and do not block a later slot.