agents-relay 1.0.159 → 1.0.161

package/dist/blockers.js

@@ -1,4 +1,5 @@
 import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
+import { isEffectivelyBlocked, unblockAutonomousTasks } from './unblock.js';
 function dependentKey(value) {
     return `${value.repository}#${value.prNumber}:${value.jobId}:${value.taskId}:a${value.blockedAttempt}`;
 }
@@ -91,6 +92,31 @@ export async function resolveBlockerDependencies(options) {
             obsolete += 1;
             continue;
         }
+        if (targetJob.executionMode === 'autonomous') {
+            if (isEffectivelyBlocked(task)) {
+                await unblockAutonomousTasks({
+                    store,
+                    job: targetJob,
+                    tasks: [task],
+                    trigger: { source: 'blocker_job', reason: `Blocker Job ${blocker.id} resolved (${options.resolution})`, blockerJobId: blocker.id, resolution: options.resolution },
+                    now,
+                });
+                relation.state = 'resumed';
+                relation.resolvedAt = now;
+                relation.resolution = options.resolution;
+                relation.note = 'dependent task unblocked for replanning';
+                resumed += 1;
+                continue;
+            }
+            if (task.state === 'BLOCKED' && task.unblock) {
+                relation.state = 'resumed';
+                relation.resolvedAt = now;
+                relation.resolution = options.resolution;
+                relation.note = 'dependent Job already unblocked for replanning';
+                resumed += 1;
+                continue;
+            }
+        }
         if (task.state === 'DRAFT') {
             await transitionTaskEvent(task, 'release');
         }

package/dist/cli-help.js

@@ -6,8 +6,8 @@ Usage:
   npx agents-relay <command> [options]
 
 Commands:
-  job create|update|show|list|merge|cancel  Manage durable GitHub-backed jobs
-  task create|update|show|list|complete|retry|cancel  Manage durable tasks
+  job create|update|show|list|merge|unblock|cancel  Manage durable GitHub-backed jobs
+  task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
   plan                     Invoke the Planner for an existing managed Job
   blocker add|resolve|show  Manage cross-Job blocker dependencies
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
@@ -25,7 +25,7 @@ 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|merge|cancel> [options]
+  npx agents-relay job <create|update|show|list|merge|unblock|cancel> [options]
 
 Actions:
   create  Create a durable Job, optionally binding an existing unmanaged PR
@@ -33,6 +33,7 @@ Actions:
   show    Show one durable Job
   list    List managed Jobs in a repository
   merge   Merge the backing PR and complete the Job
+  unblock Authoritatively invalidate current BLOCKED decisions and trigger replanning/resume
   cancel  Close the backing PR and cancel the Job
 
 Common options:
@@ -74,6 +75,7 @@ Example:
     '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 unblock': `Authoritatively unblock the effective BLOCKED work Tasks in one Job.\n\nRequired: --repo OWNER/REPO --pr NUMBER --id JOB_ID --reason TEXT. Autonomous Jobs persist a Change Cycle and wake Planner; fixed Jobs resume the blocked Tasks directly.`,
     '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.`,
@@ -86,14 +88,15 @@ Returns the same summary used by the dashboard header plus a running array with
     task: `Manage durable tasks.
 
 Usage:
-  npx agents-relay task <create|update|show|list|retry|cancel> [options]
+  npx agents-relay task <create|update|show|list|retry|unblock|cancel> [options]
 
 Actions:
   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
+  retry   Retry a FAILED Task
+  unblock Authoritatively invalidate a BLOCKED decision
   complete Complete an orchestrator-owned Task
   cancel  Cancel a Task`,
     'task create': `Create one durable Task under an existing Job.

package/dist/cli-unblock.js

@@ -0,0 +1,32 @@
+import { arg, eventBus, publishWake, saveLocal } from './cli-support.js';
+import { isEffectivelyBlocked, unblockAutonomousTasks, unblockTask } from './unblock.js';
+export async function runTaskUnblockCommand(args, store, job, task, localFile) {
+    const reason = arg(args, '--reason');
+    if (!reason.trim())
+        throw new Error('task unblock requires --reason');
+    const result = await unblockTask({ store, job, task, trigger: { source: 'cli', reason } });
+    const refreshed = await store.load(job.id);
+    await saveLocal(localFile, refreshed);
+    await publishWake(eventBus(args), refreshed, task.id, `Task ${task.id} unblocked${result.replanning ? ' for replanning' : ''}`);
+    console.log(JSON.stringify({ taskId: task.id, ...result, task: refreshed.tasks.find(item => item.id === task.id) }, null, 2));
+}
+export async function runJobUnblockCommand(args, store, job) {
+    const reason = arg(args, '--reason');
+    if (!reason.trim())
+        throw new Error('job unblock requires --reason');
+    const blocked = job.tasks.filter(isEffectivelyBlocked);
+    if (blocked.length === 0)
+        throw new Error(`Job ${job.id} has no effective BLOCKED work task`);
+    if (job.executionMode === 'autonomous') {
+        const changeCycle = await unblockAutonomousTasks({ store, job, tasks: blocked, trigger: { source: 'cli', reason } });
+        const refreshed = await store.load(job.id);
+        await publishWake(eventBus(args), refreshed, 'job', `Job ${job.id} unblocked for replanning`);
+        console.log(JSON.stringify({ jobId: job.id, replanning: true, changeCycle }, null, 2));
+        return;
+    }
+    for (const task of blocked)
+        await unblockTask({ store, job, task, trigger: { source: 'cli', reason } });
+    const refreshed = await store.load(job.id);
+    await publishWake(eventBus(args), refreshed, 'job', `Job ${job.id} unblocked`);
+    console.log(JSON.stringify({ jobId: job.id, replanning: false, resumedTasks: blocked.map(task => task.id) }, null, 2));
+}

package/dist/cli.js

@@ -7,8 +7,8 @@ import { dashboardManagedJobs, InMemoryStore, GitHubStore, resolvePullRequest, l
 import { githubAuthContext } from './github-auth.js';
 import { taskOverallTimeoutMs } from './types.js';
 import { Reconciler } from './reconciler.js';
-import { dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
-export { dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
+import { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
+export { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
 import { CodexAdapter, ChatGptAdapter } from './adapters.js';
 import { CodexThreadContinuation, CommandContinuation, WebhookContinuation } from './continuation.js';
 import { eventFor } from './events.js';
@@ -24,6 +24,7 @@ import { defaultWorkspaceRoot, resolveManagedProjectPath, resolveRepositoryProje
 import { runBlockerCommand } from './cli-blocker.js';
 import { helpText, usage } from './cli-help.js';
 import { parseAgentGraph } from './agent-graph.js';
+import { runJobUnblockCommand, runTaskUnblockCommand } from './cli-unblock.js';
 export { helpText } from './cli-help.js';
 import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, jobTagFromArgs, requestManagedReconciliation, } from './cli-support.js';
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
@@ -130,7 +131,7 @@ async function workerTaskFromArgs(job, args, now) {
     };
 }
 async function runTaskCommand(action, args) {
-    if (!['create', 'update', 'show', 'list', 'complete', 'retry', 'cancel'].includes(action))
+    if (!['create', 'update', 'show', 'list', 'complete', 'retry', 'unblock', 'cancel'].includes(action))
         throw new Error(usage);
     const { store, job, localFile } = await storeFor(args);
     if (action === 'list') {
@@ -165,6 +166,10 @@ async function runTaskCommand(action, args) {
         console.log(JSON.stringify(task, null, 2));
         return;
     }
+    if (action === 'unblock') {
+        await runTaskUnblockCommand(args, store, job, task, localFile);
+        return;
+    }
     if (action === 'complete') {
         if (task.adapter !== 'orchestrator')
             throw new Error('task complete is only valid for adapter=orchestrator self-tasks');
@@ -189,6 +194,8 @@ async function runTaskCommand(action, args) {
     }
     if (action === 'retry' || action === 'cancel') {
         if (action === 'retry') {
+            if (task.state === 'BLOCKED')
+                throw new Error(`Task ${id} is BLOCKED; use task unblock --reason instead of retry`);
             task.maxAttempts = extendRetryBudget(task);
             if (task.kind === 'planner' && task.error)
                 task.plannerRetryFeedback = task.error;
@@ -255,8 +262,10 @@ async function runTaskCommand(action, args) {
             throw new Error('Task dependencies must succeed before queueing');
         if (task.state === 'DRAFT')
             await transitionTaskEvent(task, 'release');
-        else if (task.state === 'FAILED' || task.state === 'BLOCKED')
+        else if (task.state === 'FAILED')
             await transitionTaskEvent(task, 'retry');
+        else if (task.state === 'BLOCKED')
+            throw new Error(`Task ${id} is BLOCKED; use task unblock --reason instead of --queue`);
     }
     if (hasArg(args, '--max-attempts') && task.maxAttempts < task.attempt)
         throw new Error('--max-attempts cannot be less than the current attempt count');
@@ -306,7 +315,7 @@ async function runContextCommand(action, args) {
     console.log(JSON.stringify(context, null, 2));
 }
 async function runJobCommand(action, args) {
-    if (!['create', 'update', 'show', 'list', 'merge', 'cancel'].includes(action))
+    if (!['create', 'update', 'show', 'list', 'merge', 'unblock', 'cancel'].includes(action))
         throw new Error(usage);
     const repo = repository(args);
     let createObjective;
@@ -359,6 +368,10 @@ async function runJobCommand(action, args) {
         throw new Error(`job ${action} requires --pr`);
     const store = new GitHubStore(auth.client, repo, prNumber, auth.trustedAuthors);
     const job = await store.load(id);
+    if (action === 'unblock') {
+        await runJobUnblockCommand(args, store, job);
+        return;
+    }
     if (action === 'show') {
         console.log(JSON.stringify(job, null, 2));
         return;
@@ -488,6 +501,7 @@ export async function createService(args) {
         start: dashboardJobAction(loaded.store, reconciler, 'start'),
         reconcile: dashboardJobAction(loaded.store, reconciler, 'reconcile'),
         cancel: dashboardJobAction(loaded.store, reconciler, 'cancel'),
+        jobSetState: dashboardJobSetState(loaded.store),
         taskRetry: dashboardTaskAction(loaded.store, reconciler, 'retry'),
         taskCancel: dashboardTaskAction(loaded.store, reconciler, 'cancel'),
         taskSetState: dashboardTaskSetState(loaded.store),

package/dist/dashboard-actions.js

@@ -1,5 +1,5 @@
 import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
-import { applyTaskWorkflowDecision } from './workflow/runtime.js';
+import { applyJobWorkflowDecision, applyTaskWorkflowDecision } from './workflow/runtime.js';
 export function dashboardTaskAction(store, reconciler, action) {
     return async (jobId, taskId) => {
         const job = await store.load(jobId);
@@ -7,7 +7,9 @@ export function dashboardTaskAction(store, reconciler, action) {
         if (!task)
             throw new Error(`Task ${taskId} not found`);
         if (action === 'retry') {
-            if (!['FAILED', 'BLOCKED'].includes(task.state))
+            if (task.state === 'BLOCKED')
+                throw new Error(`Task ${task.id} is BLOCKED; use the unblock CLI with a reason`);
+            if (task.state !== 'FAILED')
                 throw new Error(`Task ${task.id} is not restartable (${task.state})`);
             task.maxAttempts = extendRetryBudget(task);
             await transitionTaskEvent(task, 'retry');
@@ -26,6 +28,24 @@ export function dashboardTaskAction(store, reconciler, action) {
         return await reconciler.wake(job.id);
     };
 }
+export function dashboardJobSetState(store) {
+    return async (jobId, state) => {
+        const job = await store.load(jobId);
+        if (job.state === state)
+            return job;
+        applyJobWorkflowDecision(job, {
+            accepted: true,
+            target: state,
+            guard: null,
+            actions: [],
+            mutations: [],
+            effects: [],
+            reason: 'accepted',
+        });
+        await store.saveJob(job);
+        return await store.load(job.id);
+    };
+}
 export function dashboardTaskSetState(store) {
     return async (jobId, taskId, state) => {
         const job = await store.load(jobId);
@@ -34,6 +54,8 @@ export function dashboardTaskSetState(store) {
             throw new Error(`Task ${taskId} not found`);
         if (task.state === state)
             return job;
+        if (task.state === 'BLOCKED' && state !== 'CANCELLED')
+            throw new Error(`Task ${task.id} is BLOCKED; only the unblock CLI may resume or replan it`);
         const now = new Date().toISOString();
         const from = task.state;
         applyTaskWorkflowDecision(task, {

package/dist/dashboard-html.js

@@ -324,13 +324,16 @@ function taskTagDisplay(job,task){const display=task.tag&&job?.tag?.values?.[tas
 function taskNode(task,children,depth){const li=element('li');const nested=children.get(task.id)||[];const line=element('div','task-line');if(nested.length){const key=(selectedJob||'')+':'+task.id;const collapsed=collapsedTasks.has(key);const fold=document.createElement('button');fold.type='button';fold.className='task-fold';fold.setAttribute('aria-expanded',String(!collapsed));fold.setAttribute('aria-label',(collapsed?'Expand ':'Collapse ')+task.id);fold.textContent=collapsed?'▸':'▾';line.append(fold);const ul=element('ul','tree');ul.hidden=collapsed;for(const child of nested)ul.append(taskNode(child,children,depth+1));fold.addEventListener('click',()=>{const next=!ul.hidden;ul.hidden=next;fold.setAttribute('aria-expanded',String(!next));fold.setAttribute('aria-label',(next?'Expand ':'Collapse ')+task.id);fold.textContent=next?'▸':'▾';if(next)collapsedTasks.add(key);else collapsedTasks.delete(key);});li.append(line,ul);}else li.append(line);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',()=>{const deselect=selectedTaskId===task.id;selectedTaskId=deselect?null:task.id;eventTaskId=deselect?null: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)));const tag=taskTagDisplay(selected(),task);if(tag){const badge=element('span','task-tag',text(tag));badge.title=(selected()?.tag?.description||'Task tag')+': '+task.tag;row.append(badge);}line.append(row);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 work=tasks.filter(task=>task.kind!=='planner');if(!work.length){taskTree.append(element('li','empty',text('No work tasks in durable state.')));return;}const known=new Set(work.map(task=>task.id));const children=new Map();const roots=[];for(const task of work){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;}
+const JOB_STATES=['DRAFT','ACTIVE','COMPLETED','CANCELLED'];
+async function setJobState(job,state,select){if(!job||state===job.state)return;select.disabled=true;try{const response=await fetch('/api/job-state?id='+encodeURIComponent(job.id)+'&state='+encodeURIComponent(state),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);const updated=await response.json();const index=jobs.findIndex(candidate=>candidate.id===job.id);if(index>=0)jobs[index]=updated;else jobs.push(updated);renderAll();void loadEventHistory();}catch(error){select.title='Set job lifecycle state: '+error.message;select.value=job.state;}finally{select.disabled=false;}}
+function jobStateField(job){const box=element('div','detail-group');box.append(element('p','detail-label',text('Lifecycle state')));const select=document.createElement('select');select.className='job-filter job-state-select';select.setAttribute('aria-label','Job lifecycle state');for(const state of JOB_STATES)select.append(new Option(state,state));select.value=job.state;select.addEventListener('change',()=>void setJobState(job,select.value,select));box.append(select);return box;}
 const TASK_STATES=['DRAFT','QUEUED','RUNNING','BLOCKED','SUCCEEDED','FAILED','CANCELLED'];
 async function setTaskState(task,state,select){const job=selected();if(!job||state===task.state)return;select.disabled=true;try{const response=await fetch('/api/task-state?id='+encodeURIComponent(job.id)+'&task='+encodeURIComponent(task.id)+'&state='+encodeURIComponent(state),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);const updated=await response.json();const index=jobs.findIndex(candidate=>candidate.id===job.id);if(index>=0)jobs[index]=updated;else jobs.push(updated);renderAll();void loadEventHistory();}catch(error){select.title='Set task state: '+error.message;select.value=task.state;}finally{select.disabled=false;}}
 function taskStateField(task){const box=element('div','detail-group');box.append(element('p','detail-label',text('State')));const select=document.createElement('select');select.className='job-filter task-state-select';select.setAttribute('aria-label','Task state');for(const state of TASK_STATES)select.append(new Option(state,state));select.value=task.state;select.addEventListener('change',()=>void setTaskState(task,select.value,select));box.append(select);return box;}
 function manualOverrideField(task){const rows=Array.isArray(task.manualStateOverrides)?task.manualStateOverrides:[];const last=rows.at(-1);return field('Manual override',last?last.from+' → '+last.to+' · '+relativeTime(last.at):'—');}
 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'),taskStateField(task),manualOverrideField(task),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'),taskCommentField(task),chatField(task));const job=selected();if(task.reviewHeadSha&&job)groups.append(commitField('HEAD commit',job,task.reviewHeadSha));const graph=agentGraphField(task);if(graph)groups.append(graph);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('PR state',job.githubState||'UNKNOWN'),field('Lifecycle state',job.state),field('Runtime status',job.runtimeStatus||'IDLE'),field('Execution mode',job.executionMode||'fixed'),field('Cadence',cadence(job)),field('Review',reviewStatus(job)),commitField('Review head SHA',job,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'),jobStateField(job),field('Runtime status',job.runtimeStatus||'IDLE'),field('Execution mode',job.executionMode||'fixed'),field('Cadence',cadence(job)),field('Review',reviewStatus(job)),commitField('Review head SHA',job,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();syncMobileJobsView();}
 function isCompleteUnmerged(job){return job.runtimeStatus==='MERGE_PENDING';}
 function isTerminalJob(job){return ['COMPLETED','CANCELLED'].includes(job.state)||['MERGED','CLOSED'].includes(job.githubState);}

package/dist/dashboard.js

@@ -269,6 +269,31 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             }
             return;
         }
+        if (new URL(req.url ?? '/', 'http://127.0.0.1').pathname === '/api/job-state') {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            const requestedJobId = url.searchParams.get('id') ?? '';
+            const requestedState = url.searchParams.get('state') ?? '';
+            const validState = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'].includes(requestedState);
+            if (req.method !== 'POST' || !/^[A-Za-z0-9_-]+$/.test(requestedJobId) || !validState || !resolvedActions?.jobSetState) {
+                res.writeHead(404);
+                res.end('Job state override unavailable');
+                return;
+            }
+            try {
+                const result = await resolvedActions.jobSetState(requestedJobId, requestedState);
+                if (!res.headersSent)
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                if (!res.writableEnded)
+                    res.end(JSON.stringify(result));
+            }
+            catch (error) {
+                if (!res.headersSent)
+                    res.writeHead(409);
+                if (!res.writableEnded)
+                    res.end(error instanceof Error ? error.message : String(error));
+            }
+            return;
+        }
         if (new URL(req.url ?? '/', 'http://127.0.0.1').pathname === '/api/task-state') {
             const url = new URL(req.url ?? '/', 'http://127.0.0.1');
             const requestedJobId = url.searchParams.get('id') ?? '';

package/dist/planner.js

@@ -281,6 +281,7 @@ export function plannerInput(context) {
         retry_feedback: context.retryFeedback,
         caller_prompt: context.guidance,
         previous_planner_task_id: context.previousPlannerTaskId,
+        change_cycle: context.job.changeCycle,
         project: project ? { name: project.name, path: project.path } : undefined,
         visible_agents: visibleAgents ?? [],
         tasks: context.tasks.map(task => ({
@@ -296,6 +297,8 @@ export function plannerInput(context) {
                 next_task_ids: task.plannerResult.next_tasks.map(item => item.id),
             } : undefined,
             error: boundedText(task.error, 2000),
+            blocked_baseline: task.blockedBaseline,
+            unblock: task.unblock,
         })),
     });
 }

package/dist/reconciler-runtime.js

@@ -353,6 +353,16 @@ export class ReconcilerRuntimeBase {
                 }
                 else if (event.type === 'task.blocked') {
                     task.error = event.message || `Task ${task.id} blocked`;
+                    const data = event.data ?? {};
+                    const head = ['candidate_head', 'candidate_head_sha', 'pr_head', 'head_sha']
+                        .map(key => data[key])
+                        .find(value => typeof value === 'string' && value.length > 0);
+                    task.blockedBaseline = {
+                        blockedAt: event.timestamp || task.updatedAt,
+                        headSha: typeof head === 'string' ? head : job.headSha,
+                        reason: task.error,
+                    };
+                    task.unblock = undefined;
                 }
                 else if (event.type === 'task.cancelled') {
                     task.error = event.message || `Task ${task.id} cancelled`;

package/dist/reconciler.js

@@ -17,6 +17,7 @@ import { pendingTroubleshooterTasks } from './troubleshooter.js';
 import { prepareManagedExecutionWorktree } from './workspace.js';
 import { createReviewChairExecutionPlan } from './review-chair.js';
 import { samePlannerChildDefinition } from './planner-child.js';
+import { consumeChangeCycle, isEffectivelyBlocked } from './unblock.js';
 import { taskTagWorkerPrompt } from './task-tag.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
@@ -271,13 +272,11 @@ export class Reconciler extends ReconcilerReviewBase {
         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 => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
+        if (planners.some(task => ['DRAFT', 'QUEUED', 'RUNNING', 'FAILED'].includes(task.state)))
             return job;
-        if (scopedTasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
+        if (scopedTasks.some(isEffectivelyBlocked))
             return job;
-        if (planners.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
-            return job;
-        if (scopedTasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
+        if (scopedTasks.some(task => task.kind !== 'planner' && ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
             return job;
         if (planners.length > 0 && planners.at(-1)?.plannerResult?.objective_status === 'in_progress' && !job.tasks.some(task => task.planningDecisionId === planners.at(-1)?.id))
             return job;
@@ -286,6 +285,8 @@ export class Reconciler extends ReconcilerReviewBase {
             return job;
         const task = createPlannerRoundTask(job, { timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M') });
         await this.store.appendTask(task);
+        if (consumeChangeCycle(job, task.id))
+            await this.store.saveJob(job);
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
         return this.store.load(job.id);
     }

package/dist/relayd.js

@@ -12,7 +12,7 @@ import { Reconciler } from './reconciler.js';
 import { dashboardManagedJobs, GitHubStore, InMemoryStore, loadManagedGitHubPullRequestSnapshotGraphql, withGitHubRequestContext } from './store.js';
 import { githubAuthContext } from './github-auth.js';
 import { dashboardJobAction, isEntrypoint, runtimePlanner, runtimeReviewer, startService, SERVICE_DEFAULTS } from './cli.js';
-import { dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
+import { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { defaultWorkspaceRoot, discoverWorkspaceRepositories, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { deriveJobRuntimeStatus } from './runtime-status.js';
@@ -200,6 +200,15 @@ export async function runDaemon(argv) {
         }
         return await dashboardJobAction(store, makeReconciler(store, concurrency), action)(jobId);
     };
+    const workspaceJobSetState = async (jobId, state) => {
+        const overview = cachedOverviews.find(item => item.job.id === jobId);
+        if (!overview)
+            throw new Error(`Managed job ${jobId} not found`);
+        const store = new GitHubStore(client, overview.job.repository, overview.job.prNumber, trusted);
+        const result = await dashboardJobSetState(store)(jobId, state);
+        await refreshPullRequest(overview.job.repository, overview.job.prNumber, 'dashboard.job-state', { force: true });
+        return result;
+    };
     const workspaceTaskAction = (action) => async (jobId, taskId) => {
         const overview = cachedOverviews.find(item => item.job.id === jobId);
         if (!overview)
@@ -255,6 +264,7 @@ export async function runDaemon(argv) {
         start: workspaceJobAction('start'),
         reconcile: workspaceJobAction('reconcile'),
         cancel: workspaceJobAction('cancel'),
+        jobSetState: workspaceJobSetState,
         taskRetry: workspaceTaskAction('retry'),
         taskCancel: workspaceTaskAction('cancel'),
         taskSetState: workspaceTaskSetState,

package/dist/runtime-status.js

@@ -2,7 +2,10 @@ 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' && task.agentName !== 'troubleshooter' && !isSuperseded(task));
+    return job.tasks.filter(task => task.agentName !== 'reviewer'
+        && task.agentName !== 'troubleshooter'
+        && !isSuperseded(task)
+        && !(task.state === 'BLOCKED' && task.unblock));
 }
 export function implementationComplete(job) {
     const tasks = implementationTasks(job);
@@ -20,7 +23,7 @@ export function deriveJobRuntimeStatus(job, prState = 'OPEN') {
             return 'RUNNING';
         if (job.tasks.some(task => task.state === 'QUEUED'))
             return 'QUEUED';
-        if (job.tasks.some(task => task.state === 'BLOCKED'))
+        if (job.tasks.some(task => task.state === 'BLOCKED' && !task.unblock))
             return 'BLOCKED';
         if (job.tasks.some(task => task.state === 'FAILED'))
             return 'FAILED';
@@ -40,7 +43,7 @@ export function deriveJobRuntimeStatus(job, prState = 'OPEN') {
         return 'RUNNING';
     if (job.tasks.some(task => task.state === 'QUEUED'))
         return 'QUEUED';
-    if (job.tasks.some(task => task.state === 'BLOCKED'))
+    if (job.tasks.some(task => task.state === 'BLOCKED' && !task.unblock))
         return 'BLOCKED';
     if (job.tasks.some(task => task.state === 'FAILED'))
         return 'FAILED';

package/dist/troubleshooter.js

@@ -48,6 +48,8 @@ export function pendingTroubleshooterTasks(job) {
     for (const task of job.tasks) {
         if (!['FAILED', 'BLOCKED'].includes(task.state) || task.kind === 'planner' || task.agentName === 'troubleshooter' || !belongsToCurrentRun(job, task))
             continue;
+        if (task.state === 'BLOCKED' && task.unblock)
+            continue;
         const id = troubleshooterTaskId(task);
         if (existing.has(id) || hasRecoveryBarrier(job, task))
             continue;

package/dist/unblock.js

@@ -0,0 +1,74 @@
+import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
+export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.state === 'BLOCKED' && !task.unblock; }
+function baselineFor(task) {
+    return task.blockedBaseline ?? { blockedAt: task.updatedAt, reason: task.error ?? undefined };
+}
+function cycleFacts(job, tasks, currentHeadSha, reason) {
+    const facts = [`unblock: ${reason}`];
+    const baselines = tasks.map(task => baselineFor(task));
+    const heads = [...new Set(baselines.map(item => item.headSha).filter((item) => Boolean(item)))];
+    if (currentHeadSha && heads.some(head => head !== currentHeadSha))
+        facts.push(`PR head advanced from ${heads.join(', ')} to ${currentHeadSha}`);
+    const times = baselines.map(item => Date.parse(item.blockedAt)).filter(Number.isFinite).sort((a, b) => a - b);
+    const earliest = times[0];
+    if (earliest !== undefined) {
+        for (const task of job.tasks) {
+            if (tasks.some(item => item.id === task.id))
+                continue;
+            const changedAt = Date.parse(task.updatedAt);
+            if (!Number.isFinite(changedAt) || changedAt < earliest)
+                continue;
+            const detail = task.result?.summary ?? task.error ?? task.state;
+            facts.push(`task ${task.id} -> ${task.state}: ${detail}`);
+        }
+    }
+    return [...new Set(facts)];
+}
+export async function unblockAutonomousTasks(options) {
+    const { store, job, trigger } = options;
+    const tasks = options.tasks.filter(isEffectivelyBlocked);
+    if (tasks.length === 0)
+        throw new Error('No effective BLOCKED work task is available to unblock');
+    const now = options.now ?? new Date().toISOString();
+    const currentHeadSha = await store.headSha?.() ?? job.headSha ?? null;
+    for (const task of tasks) {
+        const baseline = baselineFor(task);
+        const record = { at: now, source: trigger.source, reason: trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, blockerJobId: trigger.blockerJobId, resolution: trigger.resolution };
+        task.blockedBaseline = baseline;
+        task.unblock = record;
+        task.updatedAt = now;
+        delete task.blockedBy;
+        await store.saveTask(task);
+    }
+    const baselineHeadShas = [...new Set(tasks.map(task => baselineFor(task).headSha).filter((item) => Boolean(item)))];
+    const cycle = { triggeredAt: now, source: trigger.source, reason: trigger.reason, taskIds: tasks.map(task => task.id), baselineHeadShas, currentHeadSha: currentHeadSha ?? undefined, facts: cycleFacts(job, tasks, currentHeadSha, trigger.reason) };
+    job.changeCycle = cycle;
+    job.updatedAt = now;
+    await store.saveJob(job);
+    return cycle;
+}
+export async function unblockTask(options) {
+    if (!isEffectivelyBlocked(options.task))
+        throw new Error(`Task ${options.task.id} is not an effective BLOCKED work task`);
+    if (options.job.executionMode === 'autonomous') {
+        const changeCycle = await unblockAutonomousTasks({ store: options.store, job: options.job, tasks: [options.task], trigger: options.trigger, now: options.now });
+        return { replanning: true, changeCycle };
+    }
+    options.task.maxAttempts = extendRetryBudget(options.task);
+    await transitionTaskEvent(options.task, 'retry');
+    options.task.error = null;
+    options.task.leaseOwner = null;
+    options.task.leaseExpiresAt = null;
+    options.task.executionId = null;
+    options.task.updatedAt = options.now ?? new Date().toISOString();
+    delete options.task.blockedBy;
+    await options.store.saveTask(options.task);
+    return { replanning: false };
+}
+export function consumeChangeCycle(job, plannerTaskId, now = new Date().toISOString()) {
+    if (!job.changeCycle || job.changeCycle.consumedByPlannerTaskId)
+        return false;
+    job.changeCycle.consumedByPlannerTaskId = plannerTaskId;
+    job.updatedAt = now;
+    return true;
+}

package/package.json

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

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

@@ -110,3 +110,14 @@ review-chair -> unified revision plan` is a project pattern, not a hard-coded
 Relay reviewer list.
 
 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.
+
+
+## Dependency vs block and authoritative unblock
+
+`dependencies` describe normal DAG ordering. Dependency completion does not create an unblock event or a planning change cycle; Relay simply releases dependent work when its prerequisites succeed. `BLOCKED` is different: it records that execution reached a runtime/external condition that invalidates normal progress.
+
+A BLOCKED Task cannot be resumed through retry, queue, dashboard state editing, PR push, webhook, ordinary task update, or troubleshooter inference. Except for blocker-Job resolution, the authoritative entry points are `task unblock --reason ...` and `job unblock --reason ...`. For autonomous Jobs, unblock does not retry the old Task. Relay preserves its blocked baseline, records current head/change facts in a durable Job Change Cycle, marks that blocked decision as unblocked-for-planning, and wakes the next Planner round. The Planner then decides whether to retry, replace, split, wait, or otherwise re-plan the objective.
+
+A blocker Job owns reverse `unblocks` references. When it resolves, Relay checks the dependent Job. If that autonomous Job has an effective BLOCKED work Task, resolution uses the same Change Cycle/replanning primitive. If it does not have BLOCKED work (for example the registered Task is DRAFT or FAILED), existing release/retry behavior remains unchanged.
+
+Automatic Planner creation treats only an effective BLOCKED work Task as a block gate. FAILED history is not itself a Planner gate; active DRAFT/QUEUED/RUNNING work still prevents a competing planning round.