agents-relay 1.0.162 → 1.0.164

package/README.md

@@ -201,6 +201,13 @@ For work that was completed outside the relay but must be represented truthfully
 
 ### Automatic task troubleshooting
 
-When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
+When an ACTIVE Job contains a current-run `FAILED` task, reconciliation may create one P0-priority `troubleshooter` recovery task for that exact failed attempt. `BLOCKED` work is not troubleshooter-owned: it remains blocked until authoritative unblock transitions it to `UNBLOCKED`. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
 
-The Troubleshooter diagnoses before retrying. A task-local or transient blocker is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the blocker is removed does it retry the original task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.
+The Troubleshooter diagnoses before retrying. A task-local or transient execution cause is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the failure cause is repaired does it retry the original FAILED task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.
+
+
+### Authoritative unblock and Planner history
+
+Dependency release and runtime unblock are separate concepts. Dependency completion simply releases DAG work. A runtime/external blocker remains `BLOCKED` until `task unblock`, `job unblock`, or blocker-Job resolution records the blocked baseline/current evidence and emits `task.unblocked`, transitioning the Task to `UNBLOCKED`.
+
+For autonomous Jobs, `UNBLOCKED` is historical: Relay does not retry that old Task. The unblock evidence becomes the trigger/context of the next Planner round. Every Planner round is a first-class `agents-relay:plan:v1` PR comment. Relay creates that Plan comment before generated Task comments, then updates the same comment with the Planner assessment and generated Task IDs, preserving causal order in the PR timeline. Fixed Jobs may transition `UNBLOCKED -> QUEUED` through retry after the authoritative unblock record exists. Legacy Job `changeCycle` data is accepted only as compatibility input and is not written by the current model.

package/dist/blockers.js

@@ -1,5 +1,5 @@
 import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
-import { isEffectivelyBlocked, unblockAutonomousTasks } from './unblock.js';
+import { isEffectivelyBlocked, unblockAutonomousTasks, unblockTask } from './unblock.js';
 function dependentKey(value) {
     return `${value.repository}#${value.prNumber}:${value.jobId}:${value.taskId}:a${value.blockedAttempt}`;
 }
@@ -60,12 +60,13 @@ export async function resolveBlockerDependencies(options) {
     const mode = blocker.blockerResolutionMode ?? 'merge';
     if (mode === 'verified' && options.resolution !== 'verified') {
         const waiting = (blocker.unblocks ?? []).filter(item => item.state === 'waiting').length;
-        return { resumed: 0, obsolete: 0, waiting };
+        return { resumed: 0, obsolete: 0, waiting, unblocked: [] };
     }
     const now = options.now ?? new Date().toISOString();
     const relations = blocker.unblocks ?? [];
     let resumed = 0;
     let obsolete = 0;
+    const unblocked = [];
     for (const relation of relations) {
         if (relation.state !== 'waiting')
             continue;
@@ -83,7 +84,7 @@ export async function resolveBlockerDependencies(options) {
             continue;
         }
         const task = targetJob.tasks.find(item => item.id === relation.taskId);
-        const matches = !!task && ['DRAFT', 'FAILED', 'BLOCKED'].includes(task.state) && task.attempt === relation.blockedAttempt;
+        const matches = !!task && ['DRAFT', 'FAILED', 'BLOCKED', 'UNBLOCKED'].includes(task.state) && task.attempt === relation.blockedAttempt;
         if (!matches) {
             relation.state = 'obsolete';
             relation.resolvedAt = now;
@@ -101,6 +102,7 @@ export async function resolveBlockerDependencies(options) {
                     trigger: { source: 'blocker_job', reason: `Blocker Job ${blocker.id} resolved (${options.resolution})`, blockerJobId: blocker.id, resolution: options.resolution },
                     now,
                 });
+                unblocked.push({ repository: relation.repository, prNumber: relation.prNumber, jobId: relation.jobId, taskId: relation.taskId });
                 relation.state = 'resumed';
                 relation.resolvedAt = now;
                 relation.resolution = options.resolution;
@@ -108,7 +110,7 @@ export async function resolveBlockerDependencies(options) {
                 resumed += 1;
                 continue;
             }
-            if (task.state === 'BLOCKED' && task.unblock) {
+            if (task.state === 'UNBLOCKED' && task.unblock) {
                 relation.state = 'resumed';
                 relation.resolvedAt = now;
                 relation.resolution = options.resolution;
@@ -119,18 +121,26 @@ export async function resolveBlockerDependencies(options) {
         }
         if (task.state === 'DRAFT') {
             await transitionTaskEvent(task, 'release');
+            task.error = null;
+            task.updatedAt = now;
+            delete task.blockedBy;
+            await store.saveTask(task);
+        }
+        else if (task.state === 'BLOCKED') {
+            await unblockTask({ store, job: targetJob, task, trigger: { source: 'blocker_job', reason: `Blocker Job ${blocker.id} resolved (${options.resolution})`, blockerJobId: blocker.id, resolution: options.resolution }, now });
+            unblocked.push({ repository: relation.repository, prNumber: relation.prNumber, jobId: relation.jobId, taskId: relation.taskId });
         }
         else {
             task.maxAttempts = extendRetryBudget(task);
             await transitionTaskEvent(task, 'retry');
+            task.error = null;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            task.executionId = null;
+            delete task.blockedBy;
+            task.updatedAt = now;
+            await store.saveTask(task);
         }
-        task.error = null;
-        task.leaseOwner = null;
-        task.leaseExpiresAt = null;
-        task.executionId = null;
-        delete task.blockedBy;
-        task.updatedAt = now;
-        await store.saveTask(task);
         relation.state = 'resumed';
         relation.resolvedAt = now;
         relation.resolution = options.resolution;
@@ -140,7 +150,7 @@ export async function resolveBlockerDependencies(options) {
     const remaining = relations.filter(relation => relation.state === 'waiting');
     const consumed = remaining.length !== relations.length;
     if (!consumed)
-        return { resumed, obsolete, waiting: remaining.length };
+        return { resumed, obsolete, waiting: remaining.length, unblocked };
     if (remaining.length > 0)
         blocker.unblocks = remaining;
     else
@@ -148,5 +158,5 @@ export async function resolveBlockerDependencies(options) {
     blocker.blockerResolvedAt = now;
     blocker.updatedAt = now;
     await options.blockerStore.saveJob(blocker);
-    return { resumed, obsolete, waiting: remaining.length };
+    return { resumed, obsolete, waiting: remaining.length, unblocked };
 }

package/dist/cli-blocker.js

@@ -1,7 +1,7 @@
 import { GitHubStore } from './store.js';
 import { githubAuthContext } from './github-auth.js';
 import { registerBlockerDependency } from './blockers.js';
-import { arg, repository } from './cli-support.js';
+import { arg, eventBus, publishDependentUnblocked, repository } from './cli-support.js';
 import { usage } from './cli-help.js';
 export async function runBlockerCommand(action, args) {
     if (!['add', 'resolve', 'show'].includes(action))
@@ -19,6 +19,7 @@ export async function runBlockerCommand(action, args) {
     }
     if (action === 'resolve') {
         const summary = await blockerStore.resolveBlockerDependents(id, 'verified');
+        await publishDependentUnblocked(eventBus(args), summary.unblocked, `Blocker Job ${id} resolved (verified)`);
         console.log(JSON.stringify({ blocker: id, resolution: 'verified', ...summary }, null, 2));
         return;
     }

package/dist/cli-help.js

@@ -75,7 +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 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 transition blocked work to historical UNBLOCKED state and wake Planner with unblock facts as Plan trigger/context; fixed Jobs record UNBLOCKED first and then resume according to fixed-job retry semantics.`,
     '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.`,

package/dist/cli-support.js

@@ -75,6 +75,22 @@ export async function publishWake(bus, job, taskId, message) { if (!bus)
 catch (error) {
     process.stderr.write(`warning: event wake unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
 } }
+export async function publishTaskUnblocked(bus, job, taskId, reason) { if (!bus)
+    return; try {
+    await bus.publish(eventFor(job.id, taskId, null, 'task.unblocked', 'unblocked', `Task ${taskId} unblocked: ${reason}`, 'orchestrator', { repository: job.repository, prNumber: job.prNumber, reason }));
+}
+catch (error) {
+    process.stderr.write(`warning: unblock event unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+} }
+export async function publishDependentUnblocked(bus, targets, reason) { if (!bus)
+    return; for (const target of targets) {
+    try {
+        await bus.publish(eventFor(target.jobId, target.taskId, null, 'task.unblocked', 'unblocked', `Task ${target.taskId} unblocked: ${reason}`, 'orchestrator', { repository: target.repository, prNumber: target.prNumber, reason }));
+    }
+    catch (error) {
+        process.stderr.write(`warning: dependent unblock event unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+} }
 export async function requestManagedReconciliation(bus, job) {
     if (!bus)
         throw new Error('Managed GitHub reconciliation requires --events nats so agents-relayd can execute the job');

package/dist/cli-unblock.js

@@ -1,4 +1,4 @@
-import { arg, eventBus, publishWake, saveLocal } from './cli-support.js';
+import { arg, eventBus, publishTaskUnblocked, 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');
@@ -7,7 +7,9 @@ export async function runTaskUnblockCommand(args, store, job, task, localFile) {
     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' : ''}`);
+    const bus = eventBus(args);
+    await publishTaskUnblocked(bus, refreshed, task.id, reason);
+    await publishWake(bus, 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) {
@@ -18,15 +20,21 @@ export async function runJobUnblockCommand(args, store, job) {
     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 planTrigger = 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));
+        const bus = eventBus(args);
+        for (const task of blocked)
+            await publishTaskUnblocked(bus, refreshed, task.id, reason);
+        await publishWake(bus, refreshed, 'job', `Job ${job.id} unblocked for replanning`);
+        console.log(JSON.stringify({ jobId: job.id, replanning: true, planTrigger }, 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`);
+    const bus = eventBus(args);
+    for (const task of blocked)
+        await publishTaskUnblocked(bus, refreshed, task.id, reason);
+    await publishWake(bus, 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

@@ -26,7 +26,7 @@ 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';
+import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, publishDependentUnblocked, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, jobTagFromArgs, requestManagedReconciliation, } from './cli-support.js';
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
 export async function ensureManagedGitHubJob(client, repositoryName, trustedAuthors, options) {
     if (!options.id)
@@ -196,10 +196,14 @@ async function runTaskCommand(action, args) {
         if (action === 'retry') {
             if (task.state === 'BLOCKED')
                 throw new Error(`Task ${id} is BLOCKED; use task unblock --reason instead of retry`);
+            if (task.state === 'UNBLOCKED')
+                throw new Error(`Task ${id} is historical UNBLOCKED work; only fixed-job authoritative unblock may requeue it`);
             task.maxAttempts = extendRetryBudget(task);
             if (task.kind === 'planner' && task.error)
                 task.plannerRetryFeedback = task.error;
         }
+        if (action === 'cancel' && task.state === 'UNBLOCKED')
+            throw new Error(`Task ${id} is historical UNBLOCKED work and is immutable`);
         await transitionTaskEvent(task, action === 'retry' ? 'retry' : task.state === 'RUNNING' ? 'task.cancelled' : 'cancel');
         task.error = action === 'retry' ? null : 'Cancelled by user';
         task.leaseOwner = null;
@@ -215,7 +219,7 @@ async function runTaskCommand(action, args) {
         console.log(JSON.stringify(task, null, 2));
         return;
     }
-    if (['RUNNING', 'SUCCEEDED', 'CANCELLED'].includes(task.state))
+    if (['RUNNING', 'UNBLOCKED', 'SUCCEEDED', 'CANCELLED'].includes(task.state))
         throw new Error(`Task ${id} is ${task.state}; durable execution fields are immutable in this state`);
     if (hasArg(args, '--adapter')) {
         const adapter = arg(args, '--adapter');
@@ -266,6 +270,8 @@ async function runTaskCommand(action, args) {
             await transitionTaskEvent(task, 'retry');
         else if (task.state === 'BLOCKED')
             throw new Error(`Task ${id} is BLOCKED; use task unblock --reason instead of --queue`);
+        else if (task.state === 'UNBLOCKED')
+            throw new Error(`Task ${id} is historical UNBLOCKED work and cannot be queued`);
     }
     if (hasArg(args, '--max-attempts') && task.maxAttempts < task.attempt)
         throw new Error('--max-attempts cannot be less than the current attempt count');
@@ -384,14 +390,15 @@ async function runJobCommand(action, args) {
         await store.mergePullRequest(headSha ?? undefined);
         await transitionJobEvent(job, 'pr.merged');
         await store.saveJob(job);
-        await store.resolveBlockerDependents(id, 'merge');
+        const resolved = await store.resolveBlockerDependents(id, 'merge');
+        await publishDependentUnblocked(eventBus(args), resolved.unblocked, `Blocker Job ${id} resolved (merge)`);
         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))) {
+        for (const task of job.tasks.filter(item => !['SUCCEEDED', 'UNBLOCKED', 'CANCELLED'].includes(item.state))) {
             await transitionTaskEvent(task, 'cancel');
             task.error = 'Job cancelled';
             task.leaseOwner = null;

package/dist/dashboard-actions.js

@@ -55,7 +55,11 @@ export function dashboardTaskSetState(store) {
         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`);
+            throw new Error(`Task ${task.id} is BLOCKED; only authoritative unblock may transition it to UNBLOCKED`);
+        if (state === 'UNBLOCKED')
+            throw new Error(`Task ${task.id} may enter UNBLOCKED only through authoritative unblock`);
+        if (task.state === 'UNBLOCKED')
+            throw new Error(`Task ${task.id} is historical UNBLOCKED work and cannot be changed by dashboard state override`);
         const now = new Date().toISOString();
         const from = task.state;
         applyTaskWorkflowDecision(task, {

package/dist/dashboard-html.js

@@ -62,7 +62,7 @@ export const dashboardHtml = `<!doctype html>
     .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.IDLE,.badge.CANCELLED { background:#edf0f4; color:var(--muted); }
+    .status-pill.neutral,.badge.IDLE,.badge.UNBLOCKED,.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; }
@@ -282,7 +282,7 @@ function rememberSelection(){if(selectedJob)sessionStorage.setItem('agents-relay
 function syncMobileJobsView(){const detail=mobileJobs.matches&&Boolean(selectedJob)&&location.hash.startsWith('#/jobs/');document.body.dataset.mobileJobsView=detail?'detail':'list';}
 function selected(){return jobs.find(job=>job.id===selectedJob)||jobs[0]||null;}
 function counts(tasks){const out={};for(const task of Array.isArray(tasks)?tasks:[])out[task.state]=(out[task.state]||0)+1;return out;}
-function compactCounts(input){const order=['RUNNING','BLOCKED','FAILED','QUEUED','DRAFT','SUCCEEDED','CANCELLED'];return order.filter(state=>input[state]).map(state=>input[state]+' '+state).join(', ')||'No tasks';}
+function compactCounts(input){const order=['RUNNING','BLOCKED','UNBLOCKED','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 cadence(job){const schedule=job?.schedule;if(!schedule?.cron)return '—';const cron=String(schedule.cron).trim();const timezone=value(schedule.timezone||'UTC');const fields=cron.split(/\\s+/);let label=cron;if(fields.length===5){const [minute,hour,day,month,weekday]=fields;if(day==='*'&&month==='*'&&weekday==='*'){const everyMinute=minute.match(/^\\*\\/(\\d+)$/);if(everyMinute&&hour==='*')label='Every '+everyMinute[1]+' min';else if(minute==='0'&&hour==='*')label='Hourly';else if(/^\\d+$/.test(minute)&&/^\\d+$/.test(hour)){const hh=String(Number(hour)).padStart(2,'0');const mm=String(Number(minute)).padStart(2,'0');label='Daily '+hh+':'+mm;}}}return label+' · '+cron+' · '+timezone;}
 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;}
@@ -327,9 +327,9 @@ function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Nu
 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'];
+const TASK_STATES=['DRAFT','QUEUED','RUNNING','BLOCKED','UNBLOCKED','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 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){const option=new Option(state,state);if(state==='UNBLOCKED'&&task.state!=='UNBLOCKED')option.disabled=true;select.append(option);}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();}

package/dist/manual-plan.js

@@ -1,4 +1,4 @@
-import { createPlannerRoundTask } from './planner.js';
+import { createPlannerRoundTask, pendingPlanForPlannerTask, recoverPendingPlannerTask } from './planner.js';
 import { transitionJobEvent } from './scheduler.js';
 export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner) {
     let job = await store.load(jobId);
@@ -7,7 +7,10 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
     const active = job.tasks.find(task => task.kind === 'planner' && ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state));
     if (active)
         throw new Error(`Planning round ${active.id} is already ${active.state}`);
-    const round = createPlannerRoundTask(job, { guidance, manual: true, timeoutMs });
+    const recovered = recoverPendingPlannerTask(job, timeoutMs);
+    const round = recovered ?? createPlannerRoundTask(job, { guidance, manual: true, timeoutMs });
+    if (!recovered)
+        await store.appendPlan(pendingPlanForPlannerTask(job, round));
     await store.appendTask(round);
     job = await store.load(jobId);
     if (job.state === 'DRAFT') {

package/dist/markers.js

@@ -1,5 +1,6 @@
 export const JOB_MARKER = 'agents-relay:job:v1';
 export const TASK_MARKER = 'agents-relay:task:v1';
+export const PLAN_MARKER = 'agents-relay:plan:v1';
 export const AGENT_MARKER = 'agents-relay:agent:v1';
 export function marker(label, value) { return `<!-- ${label} ${JSON.stringify(value).replace(/>/g, '\\u003e')} -->`; }
 export function parseMarker(body, label) {
@@ -33,7 +34,7 @@ function contentBeforeDelimiter(body, heading, end) {
     return body.slice(contentStart, endAt);
 }
 function jobMetadata(job) {
-    const { objective: _objective, description: _description, tasks: _tasks, ...metadata } = job;
+    const { objective: _objective, description: _description, tasks: _tasks, plans: _plans, ...metadata } = job;
     return metadata;
 }
 export function renderJobBody(job) {
@@ -104,5 +105,25 @@ export function parseTask(body) {
         return null;
     return { ...task, input, kind: task.kind === 'planner' ? 'planner' : 'work' };
 }
+export function renderPlanComment(plan) {
+    const { planUrl: _planUrl, ...metadata } = plan;
+    const triggerLines = [
+        `- **State:** ${plan.status}`,
+        `- **Source:** ${plan.trigger.source}`,
+        plan.trigger.taskIds?.length ? `- **Triggered tasks:** ${plan.trigger.taskIds.join(', ')}` : '',
+        plan.trigger.reason ? `- **Reason:** ${plan.trigger.reason}` : '',
+        plan.trigger.blockedHeadShas?.length ? `- **Blocked head(s):** ${plan.trigger.blockedHeadShas.join(', ')}` : '',
+        plan.trigger.currentHeadSha ? `- **Current head:** ${plan.trigger.currentHeadSha}` : '',
+    ].filter(Boolean).join('\n');
+    const generated = plan.generatedTaskIds.length ? plan.generatedTaskIds.map(id => `- ${id}`).join('\n') : '- _No tasks generated._';
+    const facts = plan.trigger.facts?.length ? `\n\n### Change facts\n\n${plan.trigger.facts.map(fact => `- ${fact}`).join('\n')}` : '';
+    return `${marker(PLAN_MARKER, metadata)}\n## Plan ${plan.round}: ${plan.id}\n\n${triggerLines}${facts}\n\n### Assessment\n\n${plan.assessment}\n\n### Generated tasks\n\n${generated}`;
+}
+export function parsePlan(body) {
+    const plan = parseMarker(body, PLAN_MARKER);
+    if (!plan || typeof plan.jobId !== 'string' || typeof plan.id !== 'string' || !Number.isInteger(plan.round))
+        return null;
+    return plan;
+}
 export function renderAgentComment(agent) { return `${marker(AGENT_MARKER, agent)}\n## Registered agent ${agent.name}\nRole: ${agent.role}\nAvailability: ${agent.availability}`; }
 export function parseAgent(body) { return parseMarker(body, AGENT_MARKER); }

package/dist/planner.js

@@ -5,6 +5,29 @@ import { dirname, join } from 'node:path';
 import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
 import { executionContextPrompt } from './execution-context.js';
 import { parseAgentGraph } from './agent-graph.js';
+function plannerTrigger(job, manual = false) {
+    if (manual)
+        return { source: 'manual' };
+    const consumed = new Set((job.plans ?? []).flatMap(plan => plan.trigger.source === 'unblock' ? plan.trigger.taskIds ?? [] : []));
+    const unblocked = job.tasks.filter(task => task.state === 'UNBLOCKED' && task.unblock && !consumed.has(task.id));
+    if (unblocked.length > 0) {
+        const records = unblocked.map(task => task.unblock);
+        const blockedHeadShas = [...new Set(records.map(record => record.baseline.headSha).filter((value) => Boolean(value)))];
+        return {
+            source: 'unblock', taskIds: unblocked.map(task => task.id),
+            reason: [...new Set(records.map(record => record.reason))].join('; '),
+            blockedHeadShas,
+            currentHeadSha: records.map(record => record.currentHeadSha).find((value) => Boolean(value)),
+            unblockSource: records[0].source,
+            facts: [...new Set(records.flatMap(record => record.facts ?? [`unblock: ${record.reason}`]))],
+        };
+    }
+    if (job.changeCycle && !job.changeCycle.consumedByPlannerTaskId)
+        return { source: 'unblock', taskIds: job.changeCycle.taskIds, reason: job.changeCycle.reason, facts: job.changeCycle.facts, blockedHeadShas: job.changeCycle.baselineHeadShas, currentHeadSha: job.changeCycle.currentHeadSha, unblockSource: job.changeCycle.source };
+    if (job.schedule?.currentRunSlot)
+        return { source: 'schedule' };
+    return (job.plans?.length ?? 0) === 0 && !job.tasks.some(task => task.kind === 'planner') ? { source: 'initial' } : { source: 'continuation' };
+}
 export function plannerRoundNumber(task) {
     if (task.kind !== 'planner')
         return null;
@@ -30,6 +53,7 @@ export function createPlannerRoundTask(job, options = {}) {
         tasks: job.tasks,
         objective: job.objective ?? job.description ?? job.title,
         previousPlannerTaskId: previousPlanner?.id ?? null,
+        trigger: plannerTrigger(job, options.manual === true),
         guidance: options.guidance,
     };
     return {
@@ -39,9 +63,31 @@ export function createPlannerRoundTask(job, options = {}) {
         maxAttempts: options.manual ? 1 : 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null,
         result: null, plannerResult: null, error: null, timeoutMs: options.timeoutMs ?? storySizeTimeoutMs('M'),
         createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: round, previousPlannerTaskId: previousPlanner?.id ?? null,
-        plannerGuidance: options.guidance, manualPlanning: options.manual === true,
+        plannerGuidance: options.guidance, manualPlanning: options.manual === true, planTrigger: context.trigger,
     };
 }
+export function pendingPlanForPlannerTask(job, task) {
+    return {
+        jobId: job.id, id: task.id, round: task.planningRound ?? 1, source: task.planningSource ?? 'model-planner',
+        previousPlanId: task.previousPlannerTaskId ?? null, trigger: task.planTrigger ?? { source: task.manualPlanning ? 'manual' : 'continuation' },
+        status: 'PLANNING', guidance: task.plannerGuidance, assessment: 'Planning in progress.', generatedTaskIds: [],
+        headSha: task.planTrigger?.currentHeadSha ?? job.headSha, createdAt: task.createdAt, updatedAt: task.updatedAt,
+    };
+}
+export function recoverPendingPlannerTask(job, timeoutMs) {
+    const pending = (job.plans ?? []).filter(plan => plan.status === 'PLANNING' && !job.tasks.some(task => task.kind === 'planner' && task.id === plan.id)).sort((a, b) => a.round - b.round)[0];
+    if (!pending)
+        return null;
+    const task = createPlannerRoundTask(job, { guidance: pending.guidance, manual: pending.trigger.source === 'manual', timeoutMs, now: pending.createdAt });
+    if (task.id !== pending.id || task.planningRound !== pending.round)
+        throw new Error(`Pending Plan ${pending.id} cannot be recovered as planner round ${task.id}`);
+    task.previousPlannerTaskId = pending.previousPlanId;
+    task.planTrigger = pending.trigger;
+    task.planningSource = pending.source;
+    task.planningDecisionId = pending.id;
+    task.input = plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: pending.previousPlanId, trigger: pending.trigger, guidance: pending.guidance });
+    return task;
+}
 export function planningSpec(task) {
     if (!task.output && task.adapter !== 'orchestrator')
         throw new Error(`Initial task ${task.id} requires an output contract`);
@@ -281,7 +327,8 @@ export function plannerInput(context) {
         retry_feedback: context.retryFeedback,
         caller_prompt: context.guidance,
         previous_planner_task_id: context.previousPlannerTaskId,
-        change_cycle: context.job.changeCycle,
+        plan_trigger: context.trigger,
+        legacy_change_cycle: context.job.changeCycle,
         project: project ? { name: project.name, path: project.path } : undefined,
         visible_agents: visibleAgents ?? [],
         tasks: context.tasks.map(task => ({

package/dist/pool.js

@@ -226,7 +226,7 @@ export class RepositoryWorkerPool {
             }
             if (routedWebhook)
                 return;
-            const lifecycle = ['task.started', 'task.completed', 'task.failed', 'task.blocked', 'task.cancelled', 'review.started', 'review.approved', 'review.changes_required', 'review.blocked'].includes(event.type);
+            const lifecycle = ['task.started', 'task.completed', 'task.failed', 'task.blocked', 'task.unblocked', 'task.cancelled', 'review.started', 'review.approved', 'review.changes_required', 'review.blocked'].includes(event.type);
             const wake = event.type === 'job.wake' || event.type === 'github.webhook';
             if (!lifecycle && !wake)
                 return;

package/dist/reconciler.js

@@ -4,7 +4,7 @@ import { dependencyReady, schedule, transitionJobEvent, transitionTaskEvent } fr
 import { implementationComplete } from './runtime-status.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
-import { createPlannerRoundTask, parsePlannerResult, plannerInput, validatePlannerHierarchy } from './planner.js';
+import { createPlannerRoundTask, pendingPlanForPlannerTask, recoverPendingPlannerTask, parsePlannerResult, plannerInput, validatePlannerHierarchy } from './planner.js';
 import { agentContractPrompt, executionContextPrompt, resolveExecutionContext } from './execution-context.js';
 import { agentGraphPrompt, validateAgentSelection } from './agent-graph.js';
 import { ReconcilerReviewBase } from './reconciler-review.js';
@@ -17,7 +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 { 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); }
@@ -46,14 +46,10 @@ Job ID: ${job.id}
 Task URL: ${taskUrl}
 Task ID: ${task.id}
 Project: ${task.projectName ?? context?.project.name ?? 'unspecified'}
-
 Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.
-
 ${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? selectedAgent + '\n\n' : ''}${selectedGraph ? selectedGraph + '\n\n' : ''}${chairPlan ? `[Review Chair execution plan]\n${JSON.stringify(chairPlan, null, 2)}\n\nUse this runtime-discovered panel to create sibling durable specialist Tasks. Preserve each specialistTasks entry as review metadata, keep the target immutable, and synthesize structured results with synthesizeReview semantics before returning the unified revision plan.\n\n` : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
-
 [Output contract]
 ${output}
-
 ${taskTag}[Execution event contract — mandatory]
 Use the canonical Neo events-bus with exactly Job ${job.id} and Task ${task.id}.
 Your exact event source identity is: ${sourceId}
@@ -61,7 +57,6 @@ Every lifecycle event for this execution MUST set source.id to that exact string
 Follow the events-bus skill/protocol. For sandboxed Codex or hosted ChatGPT,
 publish through the federated MCP tool events__publish; do not open NATS directly.
 For a direct non-sandbox local worker, use NEO_EVENTS_EMIT when the caller provides it.
-
 As your FIRST execution action, before reading files, editing code, running commands, or doing other work,
 you MUST publish exactly one canonical task.started event for this exact Job/Task.
 
@@ -136,8 +131,11 @@ export class Reconciler extends ReconcilerReviewBase {
                         await this.applyJobEffectOutcomes(job, outcomes);
                     }
                 }
-                if (prState === 'MERGED' && this.store.resolveBlockerDependents)
-                    await this.store.resolveBlockerDependents(job.id, 'merge');
+                if (prState === 'MERGED' && this.store.resolveBlockerDependents) {
+                    const resolved = await this.store.resolveBlockerDependents(job.id, 'merge');
+                    for (const target of resolved.unblocked)
+                        await this.emit(eventFor(target.jobId, target.taskId, null, 'task.unblocked', 'unblocked', `Blocker Job ${job.id} resolved (merge)`, 'orchestrator', { repository: target.repository, prNumber: target.prNumber, blockerJobId: job.id }));
+                }
                 return this.store.load(jobId);
             }
             if (job.state !== 'ACTIVE')
@@ -266,6 +264,12 @@ export class Reconciler extends ReconcilerReviewBase {
             return job;
         if (job.initialPlanning?.status === 'pending')
             return job;
+        const recovered = recoverPendingPlannerTask(job, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'));
+        if (recovered) {
+            await this.store.appendTask(recovered);
+            await this.emit(eventFor(job.id, recovered.id, null, 'planner.created', 'queued', `Recovered pending Plan ${recovered.id}`, 'orchestrator'));
+            return this.store.load(job.id);
+        }
         const allPlanners = job.tasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
         if (allPlanners.length === 0 && job.tasks.length === 0)
             return job;
@@ -284,9 +288,8 @@ export class Reconciler extends ReconcilerReviewBase {
         if (latest?.plannerResult?.objective_status === 'satisfied')
             return job;
         const task = createPlannerRoundTask(job, { timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M') });
+        await this.store.appendPlan(pendingPlanForPlannerTask(job, task));
         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);
     }
@@ -296,7 +299,15 @@ export class Reconciler extends ReconcilerReviewBase {
             return;
         const executionContext = await this.plannerContext(job, contextTask);
         for (const planner of job.tasks.filter(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && task.plannerResult)) {
-            const children = planner.plannerResult?.next_tasks.map(spec => this.plannerChild(job, planner, spec, executionContext)) ?? [];
+            const result = planner.plannerResult;
+            const plan = { jobId: job.id, id: planner.id, round: planner.planningRound ?? 1, source: planner.planningSource ?? 'model-planner', previousPlanId: planner.previousPlannerTaskId ?? null, trigger: planner.planTrigger ?? { source: 'continuation' }, status: 'SUCCEEDED', guidance: planner.plannerGuidance, objectiveStatus: result.objective_status, assessment: result.assessment, generatedTaskIds: result.next_tasks.map(item => item.id), headSha: planner.planTrigger?.currentHeadSha ?? job.headSha, createdAt: planner.createdAt, updatedAt: planner.updatedAt };
+            if (!(job.plans ?? []).some(item => item.id === plan.id)) {
+                await this.store.appendPlan(plan);
+                (job.plans ??= []).push(plan);
+            }
+            else
+                await this.store.savePlan(plan);
+            const children = result.next_tasks.map(spec => this.plannerChild(job, planner, spec, executionContext));
             for (const child of children) {
                 const existing = job.tasks.find(item => item.id === child.id);
                 if (existing) {
@@ -458,7 +469,7 @@ export class Reconciler extends ReconcilerReviewBase {
         let promise;
         try {
             const executionContext = await this.plannerContext(job, task);
-            const context = { job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.previousPlannerTaskId ?? null, executionContext, retryFeedback: task.plannerRetryFeedback, guidance: task.plannerGuidance };
+            const context = { job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.previousPlannerTaskId ?? null, trigger: task.planTrigger, executionContext, retryFeedback: task.plannerRetryFeedback, guidance: task.plannerGuidance };
             task.input = plannerInput(context);
             await this.store.saveTask(task);
             promise = planner.plan(context, controller.signal);
@@ -491,6 +502,8 @@ export class Reconciler extends ReconcilerReviewBase {
             if (task.attempt < task.maxAttempts)
                 await transitionTaskEvent(task, 'retry');
             await this.store.saveTask(task);
+            const pending = (job.plans ?? []).find(plan => plan.id === task.id) ?? pendingPlanForPlannerTask(job, task);
+            await this.store.savePlan({ ...pending, status: task.state === 'FAILED' ? 'FAILED' : 'PLANNING', error: error.message, assessment: task.state === 'FAILED' ? `Planning failed: ${error.message}` : `Planning retry: ${error.message}`, updatedAt: new Date().toISOString() });
             await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'planner.failed' : 'planner.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Planner ${task.id}: ${error.message}`, 'user'));
             this.detach(this.reconcile(jobId), jobId, task.id, 'planner retry reconciliation');
             return;
@@ -509,7 +522,15 @@ export class Reconciler extends ReconcilerReviewBase {
                 if (existing && !samePlannerChildDefinition(existing, child))
                     throw new Error(`Planner child ${child.id} already exists with a different definition`);
             }
-            // Persist the completed decision before exposing executable children.
+            // Persist the first-class Plan decision before exposing executable child Task comments.
+            const now = new Date().toISOString();
+            const plan = { jobId: job.id, id: task.id, round: task.planningRound ?? 1, source: task.planningSource ?? 'model-planner', previousPlanId: task.previousPlannerTaskId ?? null, trigger: task.planTrigger ?? { source: task.manualPlanning ? 'manual' : 'continuation' }, status: 'SUCCEEDED', guidance: task.plannerGuidance, objectiveStatus: result.objective_status, assessment: result.assessment, generatedTaskIds: result.next_tasks.map(item => item.id), headSha: task.planTrigger?.currentHeadSha ?? await this.store.headSha?.() ?? job.headSha, createdAt: task.createdAt, updatedAt: now };
+            await this.store.savePlan(plan);
+            if (job.changeCycle && !job.changeCycle.consumedByPlannerTaskId && plan.trigger.source === 'unblock') {
+                job.changeCycle.consumedByPlannerTaskId = task.id;
+                job.updatedAt = now;
+                await this.store.saveJob(job);
+            }
             task.plannerResult = result;
             task.result = { summary: result.assessment, data: { objective_status: result.objective_status, next_tasks: result.next_tasks, unblocks: result.unblocks } };
             task.error = null;
@@ -543,6 +564,8 @@ export class Reconciler extends ReconcilerReviewBase {
                 await this.store.saveTask(task);
                 await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'planner.failed' : 'planner.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Planner ${task.id}: ${message}`, 'user'));
             }
+            const pending = (await this.store.load(job.id)).plans?.find(plan => plan.id === task.id) ?? pendingPlanForPlannerTask(job, task);
+            await this.store.savePlan({ ...pending, status: task.state === 'QUEUED' ? 'PLANNING' : 'FAILED', error: message, assessment: task.state === 'QUEUED' ? `Planning retry: ${message}` : `Planning failed: ${message}`, updatedAt: new Date().toISOString() });
         }
         if (!task.manualPlanning)
             this.detach(this.reconcile(jobId), jobId, task.id, 'planner follow-up reconciliation');

package/dist/runtime-status.js

@@ -5,7 +5,7 @@ export function implementationTasks(job) {
     return job.tasks.filter(task => task.agentName !== 'reviewer'
         && task.agentName !== 'troubleshooter'
         && !isSuperseded(task)
-        && !(task.state === 'BLOCKED' && task.unblock));
+        && task.state !== 'UNBLOCKED');
 }
 export function implementationComplete(job) {
     const tasks = implementationTasks(job);
@@ -23,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' && !task.unblock))
+        if (job.tasks.some(task => task.state === 'BLOCKED'))
             return 'BLOCKED';
         if (job.tasks.some(task => task.state === 'FAILED'))
             return 'FAILED';
@@ -43,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' && !task.unblock))
+    if (job.tasks.some(task => task.state === 'BLOCKED'))
         return 'BLOCKED';
     if (job.tasks.some(task => task.state === 'FAILED'))
         return 'FAILED';

package/dist/store-github.js

@@ -1,7 +1,8 @@
-import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobBody, renderTaskComment, JOB_MARKER } from './markers.js';
+import { parseAgent, parseJob, parsePlan, parseTask, renderAgentComment, renderJobBody, renderPlanComment, renderTaskComment, JOB_MARKER } from './markers.js';
 import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
 import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
 const TASK_WRITE_OVERLAY = new Map();
+const PLAN_WRITE_OVERLAY = new Map();
 export class GitHubStore {
     client;
     repository;
@@ -24,7 +25,9 @@ export class GitHubStore {
         }
     }
     taskKey(task) { return `${this.repository}#${this.prNumber}:${task.jobId ?? ''}/${task.id}`; }
+    planKey(plan) { return `${this.repository}#${this.prNumber}:${plan.jobId}/${plan.id}`; }
     taskKeyFromBody(body) { const task = parseTask(body); return task ? this.taskKey(task) : null; }
+    planKeyFromBody(body) { const plan = parsePlan(body); return plan ? this.planKey(plan) : null; }
     overlayTaskWrites(comments) {
         if (TASK_WRITE_OVERLAY.size === 0)
             return comments;
@@ -46,6 +49,27 @@ export class GitHubStore {
         return result;
     }
     rememberTaskWrite(task, comment, body) { TASK_WRITE_OVERLAY.set(this.taskKey(task), { ...comment, body }); }
+    overlayPlanWrites(comments) {
+        if (PLAN_WRITE_OVERLAY.size === 0)
+            return comments;
+        const result = [...comments];
+        for (const [key, overlay] of [...PLAN_WRITE_OVERLAY]) {
+            const index = result.findIndex(comment => this.planKeyFromBody(comment.body) === key);
+            if (index >= 0) {
+                const remote = result[index];
+                if (remote.updatedAt && overlay.updatedAt && remote.updatedAt >= overlay.updatedAt) {
+                    PLAN_WRITE_OVERLAY.delete(key);
+                    continue;
+                }
+                result[index] = { ...remote, ...overlay, id: remote.id || overlay.id, nodeId: remote.nodeId ?? overlay.nodeId, url: remote.url ?? overlay.url, authorLogin: remote.authorLogin ?? overlay.authorLogin };
+            }
+            else {
+                PLAN_WRITE_OVERLAY.delete(key);
+            }
+        }
+        return result;
+    }
+    rememberPlanWrite(plan, comment, body) { PLAN_WRITE_OVERLAY.set(this.planKey(plan), { ...comment, body }); }
     isTrusted(comment) { return comment.authorLogin !== null && this.trustedAuthors.has(comment.authorLogin); }
     repoParts() {
         const [owner, name] = this.repository.split('/', 2);
@@ -86,9 +110,9 @@ export class GitHubStore {
     }
     async list() {
         if (this.commentsCache)
-            return this.overlayTaskWrites(this.commentsCache);
+            return this.overlayPlanWrites(this.overlayTaskWrites(this.commentsCache));
         if (this.commentsFlight)
-            return this.overlayTaskWrites(await this.commentsFlight);
+            return this.overlayPlanWrites(this.overlayTaskWrites(await this.commentsFlight));
         const flight = (async () => {
             const { owner, name } = this.repoParts();
             const all = [];
@@ -111,7 +135,7 @@ export class GitHubStore {
         this.commentsFlight = flight;
         try {
             this.commentsCache = await flight;
-            return this.overlayTaskWrites(this.commentsCache);
+            return this.overlayPlanWrites(this.overlayTaskWrites(this.commentsCache));
         }
         finally {
             if (this.commentsFlight === flight)
@@ -182,6 +206,8 @@ export class GitHubStore {
             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.plans = comments.map(comment => { const plan = parsePlan(comment.body); if (!plan || plan.jobId !== jobId)
+            return null; const planUrl = comment.url ?? (comment.id > 0 ? `https://github.com/${this.repository}/pull/${this.prNumber}#issuecomment-${comment.id}` : undefined); return planUrl ? { ...plan, planUrl } : plan; }).filter((x) => x !== null).sort((a, b) => a.round - b.round);
         job.tasks = comments.map(comment => {
             const task = parseTask(comment.body);
             if (!task)
@@ -285,6 +311,36 @@ export class GitHubStore {
         for (const legacy of jobComments.filter(comment => parseJob(comment.body)?.id === job.id))
             await this.deleteComment(legacy);
     }
+    async appendPlan(plan) {
+        await this.load(plan.jobId);
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const matches = comments.filter(comment => { const existing = parsePlan(comment.body); return existing !== null && existing.jobId === plan.jobId && existing.id === plan.id; });
+        if (matches.length === 0) {
+            const body = renderPlanComment(plan);
+            const persisted = await this.comment(body);
+            this.rememberPlanWrite(plan, persisted, body);
+            return;
+        }
+        const existing = parsePlan(matches[0].body);
+        if (!existing || JSON.stringify({ ...existing, planUrl: undefined }) !== JSON.stringify({ ...plan, planUrl: undefined }))
+            throw new Error(`Plan ${plan.id} already exists with a different definition`);
+        for (const duplicate of matches.slice(1))
+            await this.deleteComment(duplicate);
+    }
+    async savePlan(plan) {
+        await this.load(plan.jobId);
+        const comments = (await this.list()).filter(comment => this.isTrusted(comment));
+        const existing = comments.filter(comment => { const markerPlan = parsePlan(comment.body); return markerPlan !== null && markerPlan.jobId === plan.jobId && markerPlan.id === plan.id; });
+        if (existing.length > 0) {
+            const body = renderPlanComment(plan);
+            const persisted = await this.updateComment(existing[0], body);
+            this.rememberPlanWrite(plan, persisted, body);
+            for (const duplicate of existing.slice(1))
+                await this.deleteComment(duplicate);
+        }
+        else
+            await this.appendPlan(plan);
+    }
     async appendTask(task) {
         if (!task.jobId)
             throw new Error('GitHub task requires jobId');

package/dist/store.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { createSign } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { parseAgent, parseJob, parseTask, renderAgentComment, renderJobComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, TASK_MARKER } from './markers.js';
+import { parseAgent, parseJob, parsePlan, parseTask, renderAgentComment, renderJobComment, renderPlanComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, PLAN_MARKER, TASK_MARKER } from './markers.js';
 import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
 import { parsePackagePublicationMarker } from './github-webhook.js';
 function publicationFromComments(rows, trustedAuthors) {
@@ -44,6 +44,8 @@ export async function loadManagedGitHubPullRequestSnapshotGraphql(client, reposi
     const commentJobs = trusted.map(item => parseJob(String(item.body ?? ''))).filter((item) => item !== null);
     const jobs = bodyJob ? [bodyJob] : commentJobs;
     const publication = publicationFromComments(commentRows, trustedAuthors);
+    const plans = trusted.map(row => { const plan = parsePlan(String(row.body ?? '')); if (!plan)
+        return null; const planUrl = typeof row.url === 'string' ? row.url : Number.isInteger(row.databaseId) ? `https://github.com/${repository}/pull/${prNumber}#issuecomment-${row.databaseId}` : undefined; return planUrl ? { ...plan, planUrl } : plan; }).filter((item) => item !== null);
     const tasks = trusted.map(row => {
         const task = parseTask(String(row.body ?? ''));
         if (!task)
@@ -54,6 +56,7 @@ export async function loadManagedGitHubPullRequestSnapshotGraphql(client, reposi
     const state = String(pr.state ?? '').toUpperCase();
     const githubState = pr.merged === true ? 'MERGED' : state === 'CLOSED' ? 'CLOSED' : 'OPEN';
     const overviews = jobs.map(job => {
+        job.plans = plans.filter(plan => plan.jobId === job.id).sort((a, b) => a.round - b.round);
         job.tasks = tasks.filter(task => task.jobId === job.id || (!task.jobId && jobs.length === 1));
         if (!job.description && typeof pr.body === 'string' && pr.body)
             job.description = pr.body;
@@ -84,13 +87,22 @@ export class InMemoryStore {
     constructor(job) {
         if (job) {
             this.values.set(`${JOB_MARKER}:${job.id}`, renderJobComment(job));
+            for (const plan of job.plans ?? [])
+                this.values.set(`${PLAN_MARKER}:${plan.jobId}:${plan.id}`, renderPlanComment(plan));
             for (const task of job.tasks)
                 this.values.set(`${TASK_MARKER}:${task.jobId ?? ''}:${task.id}`, renderTaskComment(task));
         }
     }
     async load(jobId) { const job = await this.findJob(jobId); if (!job)
-        throw new Error(`Job ${jobId} not found`); job.tasks = this.tasksForJob(jobId); return job; }
+        throw new Error(`Job ${jobId} not found`); job.plans = this.plansForJob(jobId); job.tasks = this.tasksForJob(jobId); return job; }
     async saveJob(job) { this.values.set(`${JOB_MARKER}:${job.id}`, renderJobComment(job)); }
+    async appendPlan(plan) { const key = `${PLAN_MARKER}:${plan.jobId}:${plan.id}`; const existing = this.values.get(key); if (existing) {
+        const current = parsePlan(existing);
+        if (current && JSON.stringify(current) === JSON.stringify(plan))
+            return;
+        throw new Error(`Plan ${plan.id} already exists with a different definition`);
+    } this.values.set(key, renderPlanComment(plan)); }
+    async savePlan(plan) { this.values.set(`${PLAN_MARKER}:${plan.jobId}:${plan.id}`, renderPlanComment(plan)); }
     async appendTask(task) {
         const key = `${TASK_MARKER}:${task.jobId ?? ''}:${task.id}`;
         const existing = this.values.get(key);
@@ -110,6 +122,7 @@ export class InMemoryStore {
     async saveAgent(agent) { this.values.set(`${AGENT_MARKER}:${agent.id}`, renderAgentComment(agent)); }
     async comments() { return [...this.values.values()].map((body, i) => ({ id: i + 1, body, updatedAt: new Date().toISOString(), authorLogin: 'local' })); }
     findJob(jobId) { return [...this.values.values()].map(parseJob).find((x) => x !== null && x.id === jobId) ?? null; }
+    plansForJob(jobId) { return [...this.values.values()].map(parsePlan).filter((x) => x !== null && x.jobId === jobId).sort((a, b) => a.round - b.round); }
     tasksForJob(jobId) {
         const jobs = [...this.values.values()].map(parseJob).filter((x) => x !== null && typeof x.id === 'string' && x.id.length > 0);
         return [...this.values.values()].map(parseTask).filter((x) => x !== null).filter(task => isTaskForJob(task, jobId, jobs.length === 1));

package/dist/unblock.js

@@ -1,9 +1,9 @@
 import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
-export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.state === 'BLOCKED' && !task.unblock; }
+export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.state === 'BLOCKED'; }
 function baselineFor(task) {
     return task.blockedBaseline ?? { blockedAt: task.updatedAt, reason: task.error ?? undefined };
 }
-function cycleFacts(job, tasks, currentHeadSha, reason) {
+function unblockFacts(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)))];
@@ -11,7 +11,7 @@ function cycleFacts(job, tasks, currentHeadSha, reason) {
         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) {
+    if (earliest !== undefined)
         for (const task of job.tasks) {
             if (tasks.some(item => item.id === task.id))
                 continue;
@@ -21,9 +21,28 @@ function cycleFacts(job, tasks, currentHeadSha, reason) {
             const detail = task.result?.summary ?? task.error ?? task.state;
             facts.push(`task ${task.id} -> ${task.state}: ${detail}`);
         }
-    }
     return [...new Set(facts)];
 }
+export function unconsumedUnblockTrigger(job) {
+    const consumed = new Set((job.plans ?? []).flatMap(plan => plan.trigger.source === 'unblock' ? plan.trigger.taskIds ?? [] : []));
+    const tasks = job.tasks.filter(task => task.state === 'UNBLOCKED' && task.unblock && !consumed.has(task.id));
+    if (tasks.length === 0) {
+        const legacy = job.changeCycle;
+        if (!legacy || legacy.consumedByPlannerTaskId)
+            return undefined;
+        return { source: 'unblock', taskIds: legacy.taskIds, reason: legacy.reason, facts: legacy.facts, blockedHeadShas: legacy.baselineHeadShas, currentHeadSha: legacy.currentHeadSha, unblockSource: legacy.source };
+    }
+    const records = tasks.map(task => task.unblock);
+    return {
+        source: 'unblock',
+        taskIds: tasks.map(task => task.id),
+        reason: [...new Set(records.map(item => item.reason))].join('; '),
+        facts: [...new Set(records.flatMap(item => item.facts ?? [`unblock: ${item.reason}`]))],
+        blockedHeadShas: [...new Set(records.map(item => item.baseline.headSha).filter((item) => Boolean(item)))],
+        currentHeadSha: records.map(item => item.currentHeadSha).find((item) => Boolean(item)),
+        unblockSource: records[0].source,
+    };
+}
 export async function unblockAutonomousTasks(options) {
     const { store, job, trigger } = options;
     const tasks = options.tasks.filter(isEffectivelyBlocked);
@@ -31,44 +50,43 @@ export async function unblockAutonomousTasks(options) {
         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;
+    const facts = unblockFacts(job, tasks, currentHeadSha, trigger.reason);
     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.unblock = { at: now, source: trigger.source, reason: trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: trigger.blockerJobId, resolution: trigger.resolution };
+        await transitionTaskEvent(task, 'task.unblocked');
         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;
+    const planTrigger = unconsumedUnblockTrigger(job) ?? {
+        source: 'unblock', taskIds: tasks.map(task => task.id), reason: trigger.reason,
+        facts, currentHeadSha: currentHeadSha ?? undefined, unblockSource: trigger.source,
+    };
+    return planTrigger;
 }
 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 };
-    }
+    if (options.job.executionMode === 'autonomous')
+        return { replanning: true, planTrigger: await unblockAutonomousTasks({ store: options.store, job: options.job, tasks: [options.task], trigger: options.trigger, now: options.now }) };
+    const now = options.now ?? new Date().toISOString();
+    const currentHeadSha = await options.store.headSha?.() ?? options.job.headSha ?? null;
+    const baseline = baselineFor(options.task);
+    options.task.blockedBaseline = baseline;
+    const facts = unblockFacts(options.job, [options.task], currentHeadSha, options.trigger.reason);
+    options.task.unblock = { at: now, source: options.trigger.source, reason: options.trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: options.trigger.blockerJobId, resolution: options.trigger.resolution };
+    await transitionTaskEvent(options.task, 'task.unblocked');
+    await options.store.saveTask(options.task);
     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();
+    options.task.updatedAt = now;
     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/dist/workflow/contracts.js

@@ -23,6 +23,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'task.completed',
     'task.failed',
     'task.started',
+    'task.unblocked',
     'watchdog.failed',
     'worker.delivery_failed',
     'worker.start_ack_failed',

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -115,6 +115,6 @@ Keep secrets, credentials, private prompts, and large private payloads out of du
 
 ### Automatic task troubleshooting
 
-When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
+When an ACTIVE Job contains a current-run `FAILED` task, reconciliation may create one P0-priority `troubleshooter` recovery task for that exact failed attempt. `BLOCKED` is resolved only through authoritative unblock, which records evidence and transitions the Task to `UNBLOCKED`. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Autonomous `UNBLOCKED` Tasks are historical and feed the next Planner round instead of being retried or sent through Troubleshooter. Each Planner round is durably represented by an `agents-relay:plan:v1` PR comment created before generated Task comments and updated in place with its assessment and generated Task IDs. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
 
 The Troubleshooter diagnoses before retrying. A task-local or transient blocker is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the blocker is removed does it retry the original task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.

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

@@ -6,7 +6,7 @@ Before producing tasks, read and follow `../contracts/task-job-contract.md`.
 
 You are a pure planning agent. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. You return one structured planning result. You do not call the Agents Relay CLI, persist state, create Jobs, or mutate Tasks yourself.
 
-Relay persists each successful planner invocation as one planner-history round. Returned work Tasks are not automatically children of that round; use `parentTaskId` only when the business Task graph needs hierarchy.
+Relay persists each planning round as a first-class Plan PR comment/marker before generated Task comments. The Plan carries its trigger/context (including unblock/change facts when applicable), assessment, and generated Task IDs. Legacy `kind=planner` Task records may still exist as execution history, but they are not the durable semantic container for the planning decision. Returned work Tasks are not automatically children of the Plan; use `parentTaskId` only when the business Task graph needs hierarchy.
 
 ## Planning contract
 

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

@@ -1,6 +1,6 @@
 ---
 name: troubleshooter
-description: Recover failed or blocked Agents Relay tasks by diagnosing the root cause, repairing recoverable blockers, and retrying the original task only after the blocker is removed.
+description: Recover FAILED Agents Relay tasks by diagnosing runtime/execution faults and repairing recoverable causes. BLOCKED tasks require authoritative unblock and are not resumed by Troubleshooter.
 capabilities: [troubleshoot, recovery, orchestration, local_repo, iterative_tools]
 runtime: codex
 delegation: [p0-self-job, relay-task-retry]
@@ -9,7 +9,7 @@ restrictions: [preserve-failure-evidence, no-blind-retry, no-human-blocker-bypas
 
 # Troubleshooter Agent
 
-You are the recovery orchestrator for a failed or blocked Agents Relay task.
+You are the recovery orchestrator for a FAILED Agents Relay task. Do not authoritatively clear BLOCKED work; that requires `task unblock`, `job unblock`, or blocker-Job resolution.
 
 Your goal is not to explain the failure. Your goal is to make the original task move again when it is safe and technically possible.
 

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

@@ -122,10 +122,14 @@ This does not weaken immutable review semantics: final review and specialist rev
 
 ## 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.
+`dependencies` describe normal DAG ordering. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; 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 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 ...`. Authoritative unblock records the blocked baseline and current evidence, then transitions `BLOCKED -> UNBLOCKED` through the durable `task.unblocked` lifecycle event. `BLOCKED` therefore always means the blocker is still effective; `UNBLOCKED` means the old blocked attempt is historical and its blocker was explicitly cleared.
 
-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.
+For autonomous Jobs, an UNBLOCKED Task is never silently retried. Its unblock metadata becomes the trigger/change context for the next Planner round, which decides whether to replace, split, wait, or otherwise re-plan the objective. For fixed Jobs, authoritative unblock records the UNBLOCKED transition first and may then requeue the same Task according to fixed-job retry semantics.
 
-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.
+Each Planner round is also a first-class durable Plan entity stored in its own `agents-relay:plan:v1` PR comment. Relay creates the Plan comment before the internal planner execution record and before any generated Task comments, then updates that same Plan comment with the final assessment and generated Task IDs. Unblock/change facts belong to the Plan trigger/context, not to new Job-level Change Cycle state. Historical `kind=planner` Task records and legacy Job `changeCycle` fields remain readable for compatibility only.
+
+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 authoritative `BLOCKED -> UNBLOCKED -> Planner` path. 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 a Task whose lifecycle state is exactly `BLOCKED` as a block gate. `UNBLOCKED` and FAILED history do not themselves gate a new Planner round; active DRAFT/QUEUED/RUNNING work still prevents a competing planning round.

package/workflow/task-lifecycle.mmd

@@ -32,9 +32,11 @@ stateDiagram-v2
     RUNNING --> FAILED: watchdog.failed
     RUNNING --> CANCELLED: task.cancelled
 
-    BLOCKED --> QUEUED: retry / mutation.clearError,mutation.clearFailureReason
+    BLOCKED --> UNBLOCKED: task.unblocked
     BLOCKED --> CANCELLED: cancel
 
+    UNBLOCKED --> QUEUED: retry / mutation.clearError,mutation.clearFailureReason
+
     FAILED --> QUEUED: retry / mutation.clearError,mutation.clearFailureReason
     FAILED --> RUNNING: task.started [recoverableExecution] / mutation.clearError,mutation.clearFailureReason
     FAILED --> SUCCEEDED: task.completed [recoverableExecution] / mutation.clearError,mutation.clearFailureReason