agents-relay 1.0.54 → 1.0.56

package/README.md

@@ -23,14 +23,21 @@ npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1
 npx agents-relay job show --repo OWNER/REPO --pr 12 --id job-1
 ~~~
 
-Mutable queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
+Task readiness is explicit: `DRAFT` means the durable task exists but is not executable yet; `QUEUED` means Relay may execute it now; `RUNNING` means worker execution has started. Tasks created with dependencies start `DRAFT` and become `QUEUED` when those dependencies succeed. A dependency-free task created with `--draft` stays held until `task update --queue`. Once a task has run, external waiting is represented as `BLOCKED`, never by returning to `DRAFT`.
+
+Mutable draft/queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
 
 ~~~sh
 npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child \
   --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high \
   --capabilities model,chatgpt,browser-harness
+
+# Explicitly release a held DRAFT task
+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
@@ -150,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

@@ -15,7 +15,7 @@ import { serveDashboard } from './dashboard.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
-import { extendRetryBudget, parseJobSchedule } from './scheduler.js';
+import { extendRetryBudget, parseJobSchedule, transitionTask } from './scheduler.js';
 import { dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.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,22 +89,28 @@ 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:
   npx agents-relay task <create|update|show|list|retry|cancel> [options]
 
 Actions:
-  create  Create one executable Task under an existing Job
+  create  Create one durable Task under an existing Job
   update  Update mutable Task fields
   show    Show one Task
   list    List Tasks for a Job
   retry   Retry a failed or blocked Task
   cancel  Cancel a Task`,
-    'task create': `Create one executable Task under an existing Job.
+    'task create': `Create one durable Task under an existing Job.
 
 Required: normal Job storage options plus --input TEXT and --output task-pr|file. Codex/ChatGPT tasks also require --model MODEL.
-Common: --task-id ID, --adapter codex|chatgpt|orchestrator, --priority P0|P1|P2|P3, --story-size S|M|L, --deps a,b, --parent ID.
+Common: --task-id ID, --adapter codex|chatgpt|orchestrator, --priority P0|P1|P2|P3, --story-size S|M|L, --deps a,b, --parent ID, --draft.\nTasks with dependencies start DRAFT; tasks without dependencies start QUEUED unless --draft is given.
 Directly-created Tasks are not wrapped in a synthetic Plan. Planner-generated Tasks are created internally by Relay from planner output.
 
 Example:
@@ -110,7 +118,7 @@ Example:
     'task update': `Update mutable durable Task fields in place.
 
 Required: --task-id ID and the normal Job storage options.
-Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --story-size, --input, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy.
+Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --story-size, --input, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy, --draft, --queue.
 Use --clear-routing to remove routing metadata.
 
 Example:
@@ -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,
@@ -340,6 +348,7 @@ function workerTaskFromArgs(job, args, now) {
     const routing = adapter === 'orchestrator' ? undefined : { provider: arg(args, '--provider', 'openai'), model, profile: arg(args, '--profile') || undefined, reasoning: arg(args, '--reasoning') || undefined, cwd: arg(args, '--cwd') || undefined, projectId: arg(args, '--chatgpt-project') || undefined, decidedBy: 'cli', decidedAt: now };
     const closePolicy = hasArg(args, '--chatgpt-tab-close-policy') ? chatGptTabClosePolicy(args) : undefined;
     const size = storySize(args);
+    const dependencies = arg(args, '--deps').split(',').filter(Boolean);
     const timeoutMs = adapter === 'orchestrator' ? 0 : hasArg(args, '--timeout') ? integerArg(args, '--timeout', taskOverallTimeoutMs(size, routing?.reasoning)) : taskOverallTimeoutMs(size, routing?.reasoning);
     return {
         jobId: job.id,
@@ -349,7 +358,7 @@ function workerTaskFromArgs(job, args, now) {
         projectName: arg(args, '--project') || undefined,
         agentName: arg(args, '--agent') || undefined,
         parentTaskId: arg(args, '--parent') || null,
-        dependencies: arg(args, '--deps').split(',').filter(Boolean),
+        dependencies,
         capabilities: arg(args, '--capabilities').split(',').filter(Boolean),
         adapter,
         chatgptTabClosePolicy: closePolicy,
@@ -359,7 +368,7 @@ function workerTaskFromArgs(job, args, now) {
         routing,
         continuation: continuation(args),
         continuationDeliveredAt: null,
-        state: 'QUEUED',
+        state: hasArg(args, '--draft') || dependencies.length > 0 ? 'DRAFT' : 'QUEUED',
         attempt: 0,
         maxAttempts: Number(arg(args, '--max-attempts', '3')),
         leaseOwner: null,
@@ -385,13 +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);
-        if (refreshed.state !== 'RUNNING') {
-            refreshed.state = 'RUNNING';
+        if (refreshed.state === 'DRAFT') {
+            refreshed.state = 'ACTIVE';
             refreshed.updatedAt = now;
             await store.saveJob(refreshed);
         }
@@ -415,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);
         }
@@ -456,6 +467,16 @@ async function runTaskCommand(action, args) {
         task.chatgptTabClosePolicy = chatGptTabClosePolicy(args);
     task.timeoutMs = integerArg(args, '--timeout', task.timeoutMs);
     task.maxAttempts = integerArg(args, '--max-attempts', task.maxAttempts);
+    if (hasArg(args, '--draft') && hasArg(args, '--queue'))
+        throw new Error('--draft and --queue are mutually exclusive');
+    if (hasArg(args, '--draft'))
+        transitionTask(task, 'DRAFT');
+    if (hasArg(args, '--queue')) {
+        const taskMap = new Map(job.tasks.map(item => [item.id, item]));
+        if (!task.dependencies.every(dep => taskMap.get(dep)?.state === 'SUCCEEDED'))
+            throw new Error('Task dependencies must succeed before queueing');
+        transitionTask(task, 'QUEUED');
+    }
     if (hasArg(args, '--max-attempts') && task.maxAttempts < task.attempt)
         throw new Error('--max-attempts cannot be less than the current attempt count');
     const routingFlags = ['--provider', '--model', '--profile', '--reasoning', '--cwd', '--chatgpt-project'];
@@ -504,11 +525,11 @@ 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') {
-        const taskOnlyFlags = ['--start', '--task-id', '--input', '--adapter', '--provider', '--model', '--profile', '--reasoning', '--story-size', '--project', '--agent', '--parent', '--deps', '--capabilities', '--attachments', '--max-attempts', '--timeout', '--cwd', '--chatgpt-project', '--chatgpt-tab-close-policy', '--output', '--output-path'];
+        const taskOnlyFlags = ['--start', '--task-id', '--input', '--adapter', '--provider', '--model', '--profile', '--reasoning', '--story-size', '--project', '--agent', '--parent', '--deps', '--capabilities', '--attachments', '--max-attempts', '--timeout', '--cwd', '--chatgpt-project', '--chatgpt-tab-close-policy', '--output', '--output-path', '--draft', '--queue'];
         const invalid = taskOnlyFlags.find(flag => hasArg(args, flag));
         if (invalid)
             throw new Error(`job create does not accept task execution option ${invalid}; create the job first, then let the orchestrator create the initial plan/task batch`);
@@ -555,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'))
@@ -689,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.warn,.badge.BLOCKED,.badge.WAITING,.badge.QUEUED,.badge.READY,.badge.OPEN { background:#fff1d2; color:var(--warn); }
+    .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; }
@@ -220,8 +221,7 @@ function markdownField(label,input){const box=element('div','detail-group');box.
 function rememberSelection(){if(selectedJob)sessionStorage.setItem('agents-relay:selected-job',selectedJob);else sessionStorage.removeItem('agents-relay:selected-job');if(selectedTaskId)sessionStorage.setItem('agents-relay:selected-task',selectedTaskId);else sessionStorage.removeItem('agents-relay:selected-task');}
 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','READY','WAITING','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 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 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,12 +2,12 @@ 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 => ['READY', 'QUEUED', 'WAITING'].includes(task.state)))
+    if (job.tasks.some(task => task.state === 'QUEUED' || (task.state === 'DRAFT' && task.dependencies.length > 0)))
         return true;
     return job.tasks.some(task => task.state === 'RUNNING' && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now);
 }
@@ -48,7 +48,7 @@ export class RepositoryWorkerPool {
             if (capacity <= 0)
                 break;
             const store = new GitHubStore(this.client, job.repository, job.prNumber, this.trustedAuthors);
-            const ready = job.tasks.filter(task => ['READY', 'QUEUED', 'WAITING'].includes(task.state)).length;
+            const ready = job.tasks.filter(task => task.state === 'QUEUED' || (task.state === 'DRAFT' && task.dependencies.length > 0)).length;
             const expiredRunning = job.tasks.some(task => task.state === 'RUNNING' && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= Date.now());
             if (!needsLifecycleReconciliation(job))
                 continue;

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 {
@@ -199,7 +201,7 @@ export class Reconciler {
             return;
         job.review = { ...job.review, outcome: 'stale', updatedAt: new Date().toISOString() };
         const staleTask = job.review.taskId ? job.tasks.find(task => task.id === job.review?.taskId) : undefined;
-        if (staleTask && ['QUEUED', 'RUNNING', 'WAITING'].includes(staleTask.state)) {
+        if (staleTask && ['DRAFT', 'QUEUED', 'RUNNING'].includes(staleTask.state)) {
             this.live.get(staleTask.id)?.execution.cancel();
             transitionTask(staleTask, 'CANCELLED');
             staleTask.error = 'Review evidence became stale after the PR head changed';
@@ -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;
@@ -218,7 +220,7 @@ export class Reconciler {
         if (review?.headSha === headSha && ['started', 'approved', 'changes_required', 'blocked'].includes(review.outcome))
             return;
         const reviewTasks = job.tasks.filter(task => task.agentName === 'reviewer' && task.reviewHeadSha === headSha);
-        if (reviewTasks.some(task => ['QUEUED', 'RUNNING', 'WAITING'].includes(task.state)))
+        if (reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
             return;
         if (reviewTasks.some(task => task.state === 'SUCCEEDED' && review?.headSha === headSha && review.outcome === 'approved'))
             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);
@@ -391,7 +391,7 @@ export class Reconciler {
         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', 'RUNNING', 'WAITING'].includes(task.state)))
+        if (planners.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
             return job;
         if (scopedTasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
             return job;
@@ -645,7 +645,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 ?? [], 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 };
+        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: (spec.dependencies?.length ?? 0) > 0 ? 'DRAFT' : '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

@@ -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 => ['READY', '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,26 +22,17 @@ 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) {
-        if (['QUEUED', 'WAITING'].includes(task.state) && dependencyReady(task, map))
+        const ready = dependencyReady(task, map);
+        if (task.state === 'DRAFT' && task.dependencies.length > 0 && ready)
+            transitionTask(task, 'QUEUED');
+        else if (task.state === 'QUEUED' && !ready)
+            transitionTask(task, 'DRAFT');
+        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 === 'WAITING');
-    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') {
@@ -50,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 taskTransitions = { QUEUED: ['RUNNING', 'BLOCKED', 'FAILED', 'CANCELLED'], RUNNING: ['WAITING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'QUEUED'], WAITING: ['QUEUED', 'BLOCKED', 'CANCELLED'], BLOCKED: ['QUEUED', 'CANCELLED'], SUCCEEDED: [], FAILED: ['QUEUED', 'RUNNING', 'CANCELLED'], CANCELLED: [] };
-export function assertJobTransition(from, to) { if (from !== to && !jobTransitions[from].includes(to))
+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 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.54",
+  "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

@@ -30,10 +30,33 @@ Relay derives the overall execution timeout from `storySize`. If `routing.reason
 
 Raw `timeoutMs` is a compatibility/debug/hotfix override, not the normal task-production interface.
 
+## Task readiness states
+
+Task readiness is explicit and must use these semantics:
+
+- `DRAFT`: durable Task exists but is not executable now. A DRAFT Task with dependencies is promoted to `QUEUED` when all dependencies succeed. A DRAFT Task with no dependencies remains held until an explicit release to `QUEUED`.
+- `QUEUED`: executable now; Relay may launch it immediately subject only to worker capacity/routing.
+- `RUNNING`: worker execution has actually started.
+- `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 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.
@@ -44,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.
@@ -55,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.