agents-relay 1.0.71 → 1.0.73

package/README.md

@@ -1,6 +1,6 @@
 # Agents Relay
 
-Agents Relay is a generic TypeScript runtime for durable asynchronous agent jobs coordinated through GitHub pull requests. GitHub PR comments store durable workflow state; correlated terminal events are authoritative for model-backed task lifecycle transitions.
+Agents Relay is a generic TypeScript runtime for durable asynchronous agent jobs coordinated through GitHub pull requests. The PR body stores the durable Job marker plus human-readable Job objective, while PR comments store durable Task and other append-friendly records; correlated terminal events are authoritative for model-backed task lifecycle transitions.
 
 ## Quick start
 
@@ -53,7 +53,7 @@ Lifecycle transition authority lives in the directly renderable canonical source
 
 Graph-engine rollout is confidence-gated with `AGENTS_RELAY_WORKFLOW_MODE=legacy|shadow|graph` (default `legacy`). `shadow` keeps legacy authoritative while comparing the Mermaid decision and exposing `{mode,matches,mismatches}` at `/api/workflow-rollout`; `graph` is explicit opt-in until the shadow cutover gate is approved.
 
-Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat; its objective becomes the default PR body and objective updates keep the PR body synchronized.
+Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. Its PR body contains exactly one hidden `agents-relay:job:v1` metadata marker followed by the objective Markdown; there is no separate Job comment duplicating the objective. Objective and Job metadata updates rewrite that same PR body. Legacy Job-comment markers remain readable and are migrated into the PR body on the next Job save.
 
 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
@@ -141,7 +141,7 @@ reconcile leases and launches ready tasks without waiting inside the runtime sch
 
 For automation, Agents Relay can use GitHub App installation authentication via `AGENTS_RELAY_GITHUB_APP_ID`, `AGENTS_RELAY_GITHUB_APP_INSTALLATION_ID`, and `AGENTS_RELAY_GITHUB_APP_PRIVATE_KEY_FILE` (or matching CLI flags). Webhook mode is cache-first: targeted webhook reconciliation is primary, dashboard auto-refresh reads cached job state, and the broad watchdog drops to a 30-minute fallback. See [docs/github-app-rate-limit.md](docs/github-app-rate-limit.md).
 
-V1 assumes one active runner/daemon per job. Use a distributed atomic lease before running multiple reconcilers. Do not put secrets, credentials, private prompts, or large private payloads in PR marker comments; store only summaries and artifact references.
+V1 assumes one active runner/daemon per job. Use a distributed atomic lease before running multiple reconcilers. Do not put secrets, credentials, private prompts, or large private payloads in the PR-body Job marker or PR-comment Task markers; store only summaries and artifact references.
 
 Codex/model-backed tasks require --provider and --model (or equivalent routing metadata) before launch. See [docs/architecture.md](docs/architecture.md) and [skills/agents-relay/SKILL.md](skills/agents-relay/SKILL.md).
 
@@ -176,4 +176,4 @@ npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \
 
 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.
+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. For managed jobs, the GitHub PR body is the canonical Job surface: hidden Job metadata marker plus the visible Markdown objective.

package/dist/cli.js

@@ -635,7 +635,6 @@ async function runJobCommand(action, args) {
         if (!objective.trim())
             throw new Error('Job objective cannot be empty');
         job.objective = objective;
-        await store.updatePullRequestBody?.(objective);
     }
     if (hasArg(args, '--priority'))
         job.priority = priority(args, job.priority ?? 'P2');

package/dist/dashboard.js

@@ -80,6 +80,8 @@ export const dashboardHtml = `<!doctype html>
     .panel-actions { display:flex; align-items:center; gap:.45rem; }
     .job-filters { display:flex; gap:.35rem; align-items:center; flex-wrap:wrap; }
     .job-filter { max-width:145px; border:1px solid var(--border); border-radius:.35rem; background:var(--surface); color:var(--text); padding:.27rem .4rem; font:inherit; font-size:.72rem; }
+    .quick-filter { border:1px solid var(--border); border-radius:.35rem; background:var(--surface); color:var(--muted); padding:.27rem .42rem; font:inherit; font-size:.7rem; font-weight:750; cursor:pointer; }
+    .quick-filter[aria-pressed="true"] { border-color:var(--accent); background:var(--accent2); color:var(--accent); }
     .refresh-button { border:1px solid var(--border); border-radius:.35rem; background:var(--surface); color:var(--muted); padding:.28rem .55rem; font:inherit; font-size:.72rem; font-weight:700; cursor:pointer; }
     .refresh-button:disabled { cursor:default; opacity:.55; }
     .panel-body { padding:.75rem; overflow:auto; max-height:calc(100vh - 11.5rem); }
@@ -88,14 +90,13 @@ export const dashboardHtml = `<!doctype html>
     .workspace { display:grid; gap:1rem; }
     .job-list,.tree,.event-list { list-style:none; margin:0; padding:0; }
     .job-list { display:grid; gap:.35rem; }
-    .job-row { display:grid; gap:.2rem; padding:.35rem .45rem; border:1px solid transparent; border-radius:.4rem; }
+    .job-row { display:grid; gap:.2rem; padding:.35rem .45rem; border:1px solid transparent; border-radius:.4rem; cursor:pointer; }
     .job-row[aria-current="true"] { border-color:var(--accent); background:var(--accent2); }
     .job-row.complete-unmerged { border-color:#d69a1b; background:#fff8df; }
     .job-row.complete-unmerged[aria-current="true"] { border-color:#b77900; background:#fff0bd; }
-    .job-button { min-width:0; display:grid; gap:.2rem; padding:.12rem 0; border:0; background:transparent; color:inherit; text-align:left; font:inherit; cursor:pointer; }
+    .job-content { min-width:0; display:grid; gap:.2rem; }
+    .job-button { min-width:0; display:block; padding:.12rem 0; border:0; background:transparent; color:inherit; text-align:left; font:inherit; cursor:pointer; }
     .job-title { font-weight:750; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
-    .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; }
     .job-last-line { display:flex; align-items:center; justify-content:space-between; gap:.5rem; min-width:0; }
     .job-last-line .subtle:first-child { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
     .job-last-line .subtle:last-child { flex:none; white-space:nowrap; }
@@ -157,7 +158,7 @@ export const dashboardHtml = `<!doctype html>
 </header>
 <main>
   <section id="jobs-view" role="tabpanel" aria-labelledby="jobs-tab" class="panel jobs-panel">
-    <div class="panel-head"><h2>Jobs</h2><div class="panel-actions"><div class="job-filters"><select id="repo-filter" class="job-filter" aria-label="Filter jobs by repository"><option value="">All repos</option></select></div><button id="jobs-refresh" class="refresh-button" type="button">Refresh</button></div></div>
+    <div class="panel-head"><h2>Jobs</h2><div class="panel-actions"><div class="job-filters"><button id="quick-jobs" class="quick-filter" type="button" aria-pressed="true">JOBS</button><select id="quick-status" class="job-filter" aria-label="Filter jobs by derived status"><option value="">STATUS</option></select><button id="quick-autonomous" class="quick-filter" type="button" aria-pressed="false">AUTONOMOUS</button><button id="quick-draft" class="quick-filter" type="button" aria-pressed="false">DRAFT</button><select id="repo-filter" class="job-filter" aria-label="Filter jobs by repository"><option value="">All repos</option></select></div><button id="jobs-refresh" class="refresh-button" type="button">Refresh</button></div></div>
     <div class="panel-body" aria-live="polite"><ul id="job-list" class="job-list"><li class="skeleton" aria-hidden="true"></li></ul></div>
   </section>
   <div class="workspace" id="jobs-workspace">
@@ -206,6 +207,10 @@ const jobsWorkspace=document.querySelector('#jobs-workspace');
 const jobList=document.querySelector('#job-list');
 const jobsRefresh=document.querySelector('#jobs-refresh');
 const repoFilter=document.querySelector('#repo-filter');
+const quickJobs=document.querySelector('#quick-jobs');
+const quickStatus=document.querySelector('#quick-status');
+const quickAutonomous=document.querySelector('#quick-autonomous');
+const quickDraft=document.querySelector('#quick-draft');
 const selectedJobRefresh=document.querySelector('#selected-job-refresh');
 const jobDetail=document.querySelector('#job-detail');
 const taskTree=document.querySelector('#task-tree');
@@ -222,6 +227,8 @@ let jobs=[];
 let selectedJob=sessionStorage.getItem('agents-relay:selected-job');
 let selectedTaskId=sessionStorage.getItem('agents-relay:selected-task');
 let selectedRepo=sessionStorage.getItem('agents-relay:repo-filter')||'';
+let quickMode=sessionStorage.getItem('agents-relay:quick-filter')||'jobs';
+let selectedRuntimeStatus=sessionStorage.getItem('agents-relay:runtime-status-filter')||'';
 let eventTaskId=selectedTaskId;
 const displayedEventIds=new Set();
 
@@ -241,20 +248,31 @@ function chatField(task){const box=element('div','detail-group');box.append(elem
 function clearEvents(){displayedEventIds.clear();eventFeed.replaceChildren(element('li','empty',text('Waiting for events.')));}
 async function loadEventHistory(){if(!selectedJob){clearEvents();return;}const params=new URLSearchParams({job:selectedJob,limit:String(MAX_EVENTS)});if(eventTaskId)params.set('task',eventTaskId);try{const history=await loadJSON('/api/events?'+params.toString());clearEvents();for(const event of Array.isArray(history)?history.slice().reverse():[])addEvent(event);}catch{clearEvents();}}
 function selectJob(id){selectedJob=id;selectedTaskId=null;eventTaskId=null;rememberSelection();clearEvents();location.hash=id?'#/jobs/'+encodeURIComponent(id):'#/jobs';renderAll();void loadEventHistory();}
-function filteredJobs(){return jobs.filter(job=>!selectedRepo||job.repository===selectedRepo);}
+function matchesQuickFilter(job){if(quickMode==='autonomous')return job.executionMode==='autonomous';if(quickMode==='draft')return job.draft||job.state==='DRAFT';if(quickMode==='status')return !!selectedRuntimeStatus&&(job.runtimeStatus||'IDLE')===selectedRuntimeStatus;return true;}
+function filteredJobs(){return jobs.filter(job=>(!selectedRepo||job.repository===selectedRepo)&&matchesQuickFilter(job));}
+function setQuickMode(mode,status=''){quickMode=mode;selectedRuntimeStatus=mode==='status'?status:'';sessionStorage.setItem('agents-relay:quick-filter',quickMode);if(selectedRuntimeStatus)sessionStorage.setItem('agents-relay:runtime-status-filter',selectedRuntimeStatus);else sessionStorage.removeItem('agents-relay:runtime-status-filter');syncFilters();renderJobList();}
 function syncFilters(){
   const repos=[...new Set(jobs.map(job=>job.repository).filter(Boolean))].sort();
   const previousRepo=selectedRepo;
   repoFilter.replaceChildren(new Option('All repos',''),...repos.map(repo=>new Option(repo,repo)));
   selectedRepo=repos.includes(previousRepo)?previousRepo:'';
   repoFilter.value=selectedRepo;
+  const statuses=[...new Set(jobs.map(job=>job.runtimeStatus||'IDLE'))].sort();
+  const previousStatus=selectedRuntimeStatus;
+  quickStatus.replaceChildren(new Option('STATUS',''),...statuses.map(status=>new Option(status,status)));
+  selectedRuntimeStatus=statuses.includes(previousStatus)?previousStatus:'';
+  if(quickMode==='status'&&!selectedRuntimeStatus)quickMode='jobs';
+  quickStatus.value=quickMode==='status'?selectedRuntimeStatus:'';
+  quickJobs.setAttribute('aria-pressed',String(quickMode==='jobs'));
+  quickAutonomous.setAttribute('aria-pressed',String(quickMode==='autonomous'));
+  quickDraft.setAttribute('aria-pressed',String(quickMode==='draft'));
 }
 function actionEnabled(job,action){if(action==='start')return job.state==='DRAFT'&&job.githubState!=='CLOSED'&&job.githubState!=='MERGED';if(action==='reconcile')return job.state==='ACTIVE'&&job.githubState==='OPEN';if(action==='cancel')return job.state!=='COMPLETED'&&job.state!=='CANCELLED'&&job.githubState==='OPEN';return false;}
 function actionButton(job,action,label,icon){const button=document.createElement('button');button.type='button';button.className='job-action';button.textContent=icon;button.title=label;button.setAttribute('aria-label',label);button.disabled=!actionEnabled(job,action);button.addEventListener('click',event=>{event.stopPropagation();void runJobAction(job,action,button);});return button;}
 async function runJobAction(job,action,button){button.disabled=true;try{const response=await fetch('/api/job-action?id='+encodeURIComponent(job.id)+'&action='+encodeURIComponent(action),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);await refresh(true);}catch(error){button.title=labelForAction(action)+': '+error.message;}finally{renderAll();}}
 function labelForAction(action){return action==='start'?'Start':action==='reconcile'?'Reconcile':'Cancel';}
 function repoName(repository){if(typeof repository!=='string'||!repository)return 'unknown-repo';const parts=repository.split('/').filter(Boolean);return parts.at(-1)||repository;}
-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 row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(job.id===selectedJob));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(job.id===selectedJob));select.title=job.title||job.id;select.addEventListener('click',()=>selectJob(job.id));select.append(element('span','job-title',text(repoName(job.repository)+'/PR#'+value(job.prNumber)+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))),element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))),element('span','badge '+value(job.githubState||'UNKNOWN'),text(value(job.githubState||'UNKNOWN'))));const actions=element('span','job-actions');actions.append(actionButton(job,'start','Start','▶'),actionButton(job,'reconcile','Reconcile','↻'),actionButton(job,'cancel','Cancel','×'));const primary=element('div','job-primary');primary.append(states,actions);const meta=element('span','job-meta');meta.append(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')));const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,meta,lastLine);row.append(content);jobList.append(element('li','',row));}}
+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 row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(job.id===selectedJob));row.addEventListener('click',()=>selectJob(job.id));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(job.id===selectedJob));select.title=job.title||job.id;select.addEventListener('click',event=>{event.stopPropagation();selectJob(job.id);});select.append(element('span','job-title',text(repoName(job.repository)+'/PR#'+value(job.prNumber)+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))),element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))),element('span','badge '+value(job.githubState||'UNKNOWN'),text(value(job.githubState||'UNKNOWN'))));if(job.executionMode==='autonomous')states.append(element('span','badge flag-autonomous',text('AUTONOMOUS')));if(job.reviewEnabled!==false)states.append(element('span','badge flag-review',text('REVIEW REQUIRED')));if(isCompleteUnmerged(job))states.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));const actions=element('span','job-actions');actions.append(actionButton(job,'start','Start','▶'),actionButton(job,'reconcile','Reconcile','↻'),actionButton(job,'cancel','Cancel','×'));const primary=element('div','job-primary');primary.append(states,actions);const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,lastLine);row.append(content);jobList.append(element('li','',row));}}
 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;}
@@ -264,7 +282,8 @@ function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if
 function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();}
 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));}
+function jobGroup(job){if(isTerminalJob(job))return 3;if(job.executionMode==='autonomous')return 1;if(job.draft||job.state==='DRAFT')return 2;return 0;}
+function compareJobs(a,b){const groupDelta=jobGroup(a)-jobGroup(b);if(groupDelta)return groupDelta;const mergePendingDelta=Number(isCompleteUnmerged(b))-Number(isCompleteUnmerged(a));return mergePendingDelta||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();}
 function renderRateLimitStatus(status){
   if(!status?.limited){rateLimitWarning.hidden=true;rateLimitWarning.textContent='';return;}
@@ -288,6 +307,10 @@ jobsTab.addEventListener('click',()=>{location.hash=selectedJob?'#/jobs/'+encode
 jobsRefresh.addEventListener('click',()=>void refresh(true));
 eventsAllTasks.addEventListener('click',()=>{eventTaskId=null;clearEvents();renderEventScope();void loadEventHistory();});
 repoFilter.addEventListener('change',()=>{selectedRepo=repoFilter.value;sessionStorage.setItem('agents-relay:repo-filter',selectedRepo);renderJobList();});
+quickJobs.addEventListener('click',()=>setQuickMode('jobs'));
+quickAutonomous.addEventListener('click',()=>setQuickMode('autonomous'));
+quickDraft.addEventListener('click',()=>setQuickMode('draft'));
+quickStatus.addEventListener('change',()=>setQuickMode(quickStatus.value?'status':'jobs',quickStatus.value));
 selectedJobRefresh.addEventListener('click',()=>void refreshSelected());
 usageTab.addEventListener('click',()=>{location.hash='#/usage';showView('usage');});
 window.addEventListener('keydown',event=>{if(event.key==='Tab'&&event.altKey){event.preventDefault();showView(location.hash==='#/usage'?'jobs':'usage');}});

package/dist/markers.js

@@ -32,10 +32,18 @@ function contentBeforeDelimiter(body, heading, end) {
         return undefined;
     return body.slice(contentStart, endAt);
 }
+function jobMetadata(job) {
+    const { objective: _objective, description: _description, tasks: _tasks, ...metadata } = job;
+    return metadata;
+}
+export function renderJobBody(job) {
+    const objective = job.objective?.trim() || '_No objective recorded._';
+    return `${marker(JOB_MARKER, jobMetadata(job))}
+${objective}`;
+}
 export function renderJobComment(job) {
     const objective = job.objective?.trim() || '_No objective recorded._';
-    const { objective: _objective, description: _description, tasks: _tasks, ...metadata } = job;
-    return `${marker(JOB_MARKER, metadata)}
+    return `${marker(JOB_MARKER, jobMetadata(job))}
 # Agents Relay job: ${job.title}
 
 - **State:** ${job.state}
@@ -70,7 +78,9 @@ export function parseJob(body) {
     const job = parseMarker(body, JOB_MARKER);
     if (!job)
         return null;
-    const objective = job.objective ?? job.description ?? contentBeforeDelimiter(body, '\n## Objective\n\n', JOB_OBJECTIVE_END) ?? markdownSection(body, '\n## Objective\n');
+    const markerEnd = body.indexOf('-->');
+    const bodyObjective = markerEnd >= 0 ? body.slice(markerEnd + 3).trim() || undefined : undefined;
+    const objective = job.objective ?? job.description ?? contentBeforeDelimiter(body, '\n## Objective\n\n', JOB_OBJECTIVE_END) ?? markdownSection(body, '\n## Objective\n') ?? bodyObjective;
     const parsed = { ...job, objective };
     if (parsed.executionMode === undefined)
         return { ...parsed, executionMode: 'fixed' };

package/dist/store.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { createSign } from 'node:crypto';
-import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.js';
+import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobBody, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.js';
 export async function loadManagedGitHubPullRequestGraphql(client, repository, prNumber, trustedAuthors) {
     const [owner, name] = repository.split('/', 2);
     if (!owner || !name || !Number.isInteger(prNumber) || prNumber <= 0 || !client.graphql)
@@ -17,7 +17,9 @@ export async function loadManagedGitHubPullRequestGraphql(client, repository, pr
         const author = row.author;
         return typeof author?.login === 'string' && trustedAuthors.has(author.login);
     });
-    const jobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+    const bodyJob = parseJob(typeof pr.body === 'string' ? pr.body : '');
+    const commentJobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+    const jobs = bodyJob ? [bodyJob] : commentJobs;
     const tasks = trusted.map(item => parseTask(String(item.body ?? ''))).filter((item) => item !== null);
     const state = String(pr.state ?? '').toUpperCase();
     const githubState = pr.merged === true ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';
@@ -424,13 +426,17 @@ export class GitHubStore {
     }
     async prNode() {
         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){id state merged mergedAt closedAt}}}', { owner, name, number: this.prNumber });
+        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id state merged mergedAt closedAt body}}}', { owner, name, number: this.prNumber });
         const repository = data.repository;
         const pr = repository?.pullRequest;
         if (!pr)
             throw new Error(`Pull request #${this.prNumber} not found in ${this.repository}`);
         return pr;
     }
+    async pullRequestBody() {
+        const pr = await this.prNode();
+        return typeof pr.body === 'string' ? pr.body : '';
+    }
     async list() {
         const { owner, name } = this.repoParts();
         const all = [];
@@ -490,10 +496,16 @@ export class GitHubStore {
     }
     async load(jobId) {
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
-        const jobs = comments.map(x => parseJob(x.body)).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
+        const bodyJob = parseJob(await this.pullRequestBody());
+        const commentJobs = comments.map(x => parseJob(x.body)).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
+        const jobs = bodyJob ? [bodyJob] : commentJobs;
         const job = jobs.find(x => x.id === jobId);
-        if (!job)
+        if (!job) {
+            const conflicting = bodyJob ?? commentJobs[0];
+            if (conflicting)
+                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${conflicting.id}, not ${jobId}`);
             throw new Error(`JOB_MARKER_MISSING: Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}`);
+        }
         const soleTrustedJob = jobs.length === 1;
         job.tasks = comments.map(comment => {
             const task = parseTask(comment.body);
@@ -505,6 +517,16 @@ export class GitHubStore {
         return job;
     }
     async validateJobBinding(jobId) {
+        const body = await this.pullRequestBody();
+        const bodyHasMarker = body.includes(`<!-- ${JOB_MARKER} `);
+        const bodyJob = parseJob(body);
+        if (bodyHasMarker && !bodyJob)
+            throw new Error(`JOB_MARKER_MALFORMED: PR #${this.prNumber} body contains a ${JOB_MARKER} marker that cannot be parsed`);
+        if (bodyJob) {
+            if (bodyJob.id !== jobId)
+                throw new Error(`JOB_ID_MISMATCH: PR #${this.prNumber} is bound to ${bodyJob.id}, not ${jobId}`);
+            return;
+        }
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
         const markerComments = comments.filter(comment => comment.body.includes(JOB_MARKER));
         const parsed = markerComments.map(comment => parseJob(comment.body));
@@ -539,22 +561,21 @@ export class GitHubStore {
         await this.graphql('mutation($id:ID!){deleteIssueComment(input:{id:$id}){clientMutationId}}', { id: comment.nodeId });
     }
     async saveJob(job) {
+        const currentBody = await this.pullRequestBody();
+        const bodyJob = parseJob(currentBody);
+        if (bodyJob && bodyJob.id !== job.id)
+            throw new Error(`PR #${this.prNumber} body already has a different ${JOB_MARKER} marker`);
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
         const jobComments = comments.filter(comment => parseJob(comment.body) !== null);
         const conflicts = jobComments.filter(comment => parseJob(comment.body)?.id !== job.id);
         if (conflicts.length > 0)
             throw new Error(`PR #${this.prNumber} already has a different ${JOB_MARKER} marker`);
-        const matches = jobComments.filter(comment => parseJob(comment.body)?.id === job.id);
-        if (matches.length === 0)
-            await this.comment(renderJobComment(job));
-        else {
-            await this.updateComment(matches[0], renderJobComment(job));
-            for (const duplicate of matches.slice(1))
-                await this.deleteComment(duplicate);
-        }
-        const durable = (await this.list()).filter(comment => this.isTrusted(comment)).filter(comment => parseJob(comment.body)?.id === job.id);
-        if (durable.length !== 1)
-            throw new Error(`Failed to persist exactly one ${JOB_MARKER} marker for job ${job.id}`);
+        await this.updatePullRequestBody(renderJobBody(job));
+        const persisted = parseJob(await this.pullRequestBody());
+        if (!persisted || persisted.id !== job.id)
+            throw new Error(`Failed to persist ${JOB_MARKER} marker in PR #${this.prNumber} body for job ${job.id}`);
+        for (const legacy of jobComments.filter(comment => parseJob(comment.body)?.id === job.id))
+            await this.deleteComment(legacy);
     }
     async appendTask(task) {
         if (!task.jobId)
@@ -615,7 +636,9 @@ export async function listManagedGitHubJobs(client, repository, trustedAuthors)
                 const author = item.author;
                 return typeof author?.login === 'string' && trustedAuthors.has(author.login);
             });
-            const jobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+            const bodyJob = parseJob(typeof pr.body === 'string' ? pr.body : '');
+            const commentJobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
+            const jobs = bodyJob ? [bodyJob] : commentJobs;
             const tasks = trusted.map(item => parseTask(String(item.body ?? ''))).filter((item) => item !== null);
             const state = String(pr.state ?? '').toUpperCase();
             const githubState = pr.merged === true || state === 'MERGED' ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';

package/package.json

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

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

@@ -6,7 +6,7 @@ This contract is the shared protocol for every component that creates, schedules
 
 Job objectives and Task inputs are **Markdown** and are durable execution context, not short labels. Use Mermaid where a diagram materially explains a workflow, state model, architecture, dependency graph, relationship, or other visual structure. **Mermaid-first applies to that explanation/section, not to the entire Job objective or Task input.** Put the diagram before the prose that explains that visual model, but keep normal document structure: start with the goal/context when that is what the reader needs first. Do not force a Mermaid block at the top of every objective/input, and do not add decorative or redundant diagrams when Markdown is clearer.
 
-The trusted machine-readable Job/Task marker stores lifecycle and execution metadata only. Do **not** duplicate the Job objective or Task input inside the JSON marker; those long-form Markdown bodies remain the human-readable durable content rendered by the Job/Task comment (and, for a Job objective, the PR body). Readers reconstruct `objective` / `input` from that visible Markdown while remaining backward-compatible with legacy markers that embedded them.
+The trusted machine-readable Job/Task marker stores lifecycle and execution metadata only. Do **not** duplicate the Job objective or Task input inside marker JSON. The Job marker lives in the PR body immediately before the human-readable Job objective; Task markers live in their Task comments immediately before the human-readable Task input/result. Readers reconstruct `objective` / `input` from that visible Markdown while remaining backward-compatible with legacy markers that embedded long-form content or stored the Job marker in a separate comment.
 
 For long-form content, use files instead of shell-quoted arguments:
 
@@ -15,7 +15,7 @@ For long-form content, use files instead of shell-quoted arguments:
 
 When creating a new Job from an active discussion, the orchestrator must consolidate **all context needed to finish the Job without the originating thread** into the Job objective before creation. Include, as applicable: goal, relevant background, decisions already made, requirements, constraints, lifecycle/workflow semantics, non-goals, implementation boundaries, acceptance criteria, delivery/review instructions, and any important known issues. Do not create a Job whose objective is only a one-line summary when the discussion contains material implementation context.
 
-For a newly created PR (`job create --head`), standalone objective Markdown is required and becomes the default PR body. Updating the Job objective also updates the PR body. The trusted Job marker remains the machine-readable durable state, while the PR body and rendered Job comment expose the same objective to humans and agents.
+For a newly created PR (`job create --head`), standalone objective Markdown is required. The PR body is the single durable Job surface: one hidden `agents-relay:job:v1` marker followed by the objective Markdown. Updating Job metadata or objective updates that same body. New Jobs must not create a separate Job comment that repeats the objective. Readers must remain backward-compatible with legacy Job-comment markers, and a successful Job save may migrate such a legacy marker into the PR body only after validating the replacement before deleting the redundant legacy Job comment.
 
 ## Task producers