agents-relay 2.0.157 → 2.0.159

package/dist/cli-help.js

@@ -9,7 +9,7 @@ Usage:
 
 Commands:
   job create|update|show|list|merge|unblock|cancel|pause|resume  Manage SQLite-authoritative jobs with optional GitHub PRs
-  task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
+  task create|update|show|list|classify|complete|retry|unblock|cancel  Manage durable tasks
   review request           Request graph-owned review (optional thread override)
   plan                     Invoke the Planner for an existing managed Job
   plan apply               Submit a validated Task Tree within one active Plan
@@ -166,15 +166,14 @@ Optional: --failure-kind adapter_failure|model_failure|provider_failure|task_fai
     'task cancel': `Cancel one durable Task.
 
 Required: --task-id ID and the normal Job storage options.`,
-    'task supersede': `Mark an already-CANCELLED durable Task as superseded by later corrected work through the Task Resolution Graph.
-
-Required: --task-id ID, --reason TEXT, and the normal managed Job storage options. This does not change Task state and cannot supersede FAILED/BLOCKED/runnable work.`,
+    'task supersede': `Mark an already-CANCELLED durable Task as superseded by later corrected work through the Task Resolution Graph.\n\nRequired: --task-id ID, --reason TEXT, and the normal managed Job storage options. This does not change Task state and cannot supersede FAILED/BLOCKED/runnable work.`,
+    'task classify': `Classify a FAILED work Task as superseded or invalid without changing its Task lifecycle.\n\nRequired: --task-id ID --classification superseded|invalid --target-task-id ID --evidence TEXT --reason TEXT and the normal Job storage options. Unknown or active execution outcomes are rejected.`,
     plan: `Invoke the Planner against the current durable Job state.
 
 Agent submit: agents-relay plan apply --repo OWNER/REPO --pr PR_NUMBER --id JOB_ID --plan-id PLAN_ID --execution-id EXECUTION_ID --file plan.json. Validation errors reject without partial task writes and can be corrected inside the same Planner execution.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
-Optional: --prompt TEXT or --prompt-file PATH|- (mutually exclusive). The prompt is additional guidance for this planning round and never replaces the durable Job objective.
+Optional: --prompt TEXT or --prompt-file PATH|- (mutually exclusive). The prompt is additional guidance for this planning round and never replaces the durable Job objective. --force-clean-history asks Planner to inspect authoritative failed Tasks, decide whether evidence supports superseded/invalid classification or cancellation of a failed review, and apply selected changes through guarded task commands before submitting the Plan. Tasks without sufficient evidence remain unresolved. The durable Plan records the cleanup assessment, and plan apply remains the required receipt. Text responses are never applied as a Plan; unknown execution outcomes are not classified without proof.
 
 The command persists one real plan-N round, materializes validated next_tasks with planner provenance, and wakes normal reconciliation. It works for zero-task DRAFT Jobs. Historical planner-N rounds remain readable, but new rounds use plan-N.
 

package/dist/cli-worker-task.js

@@ -2,6 +2,17 @@ import { taskOverallTimeoutMs } from './types.js';
 import { arg, hasArg, textOption, integerArg, chatGptTabClosePolicy, storySize, priority, continuation } from './cli-support.js';
 import { parseAgentGraph } from './agent-graph.js';
 import { createTaskEntity } from './workflow/entity-creation.js';
+export function recoveryDiagnosisFromArgs(args) {
+    const failureKind = arg(args, '--failure-kind');
+    if (!failureKind)
+        return undefined;
+    const reason = arg(args, '--reason');
+    if (!reason.trim())
+        throw new Error('--failure-kind requires --reason');
+    if (!['adapter_failure', 'model_failure', 'provider_failure', 'task_failure', 'unknown'].includes(failureKind))
+        throw new Error('Invalid --failure-kind');
+    return { failureKind, reason, evidence: arg(args, '--evidence') || undefined, reroute: hasArg(args, '--reroute'), excludeCurrentRoute: hasArg(args, '--exclude-current-route') };
+}
 export async function workerTaskFromArgs(job, args, now) {
     const model = arg(args, '--model');
     const adapterValue = arg(args, '--adapter');

package/dist/cli.js

@@ -23,6 +23,7 @@ import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
 import { applyTaskHoldAction, applyTaskQueueAction, dispatchTaskAction } from './task-actions.js';
 import { applyJobActivateAction, applyJobCancelAction } from './job-actions.js';
+import { classifyFailedTask } from './task-actions.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { startServiceExternalActionFlusher } from './service-external-actions.js';
 import { handleServicePublication } from './service-publication.js';
@@ -42,7 +43,7 @@ import { normalizeThreadId, runtimeReviewer } from './reviewer-thread.js';
 export { runtimeReviewer } from './reviewer-thread.js';
 import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, eventBus, publishWake, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, jobTagFromArgs, requestManagedReconciliation, relayControlJob, relayControlCommand, relayJobList, relayJobStateCommand, relayTaskCommand, withEventBus } from './cli-support.js';
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
-import { workerTaskFromArgs } from './cli-worker-task.js';
+import { recoveryDiagnosisFromArgs, workerTaskFromArgs } from './cli-worker-task.js';
 import { taskExecutionContext } from './task-context.js';
 import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
 import { pauseJob, resumeJob } from './job-pause.js';
@@ -72,20 +73,8 @@ async function runManagedTaskCommand(action, args) {
         throw new Error(`Task ${id} missing after ${action}`);
     console.log(JSON.stringify(task, null, 2));
 }
-function recoveryDiagnosisFromArgs(args) {
-    const failureKind = arg(args, '--failure-kind');
-    if (!failureKind)
-        return undefined;
-    const reason = arg(args, '--reason');
-    if (!reason.trim())
-        throw new Error('--failure-kind requires --reason');
-    if (!['adapter_failure', 'model_failure', 'provider_failure', 'task_failure', 'unknown'].includes(failureKind))
-        throw new Error('Invalid --failure-kind');
-    const reroute = args.includes('--reroute');
-    return { failureKind, reason, evidence: arg(args, '--evidence') || undefined, reroute, excludeCurrentRoute: args.includes('--exclude-current-route') };
-}
 async function runTaskCommand(action, args) {
-    if (!['create', 'update', 'show', 'context', 'comment', 'comments', 'list', 'retry', 'recover', 'unblock', 'escalate', 'resume-troubleshooter', 'cancel', 'supersede'].includes(action))
+    if (!['create', 'update', 'show', 'context', 'comment', 'comments', 'list', 'retry', 'recover', 'unblock', 'escalate', 'resume-troubleshooter', 'cancel', 'supersede', 'classify'].includes(action))
         throw new Error(usage);
     const managed = !arg(args, '--file') && Boolean(arg(args, '--repo') && arg(args, '--id'));
     if (managed) {
@@ -130,6 +119,16 @@ async function runTaskCommand(action, args) {
             console.log(JSON.stringify(task, null, 2));
             return;
         }
+        if (action === 'classify') {
+            if (!taskId)
+                throw new Error('task classify requires --task-id');
+            const kind = arg(args, '--classification');
+            if (kind !== 'superseded' && kind !== 'invalid')
+                throw new Error('--classification must be superseded or invalid');
+            const result = await relayControlCommand(args, { command: 'task.classify', jobId, taskId, classification: { kind, targetTaskId: arg(args, '--target-task-id'), evidence: await textOption(args, '--evidence', '--evidence-file'), reason: await textOption(args, '--reason', '--reason-file') } });
+            console.log(JSON.stringify(result.tasks.find(item => item.id === taskId), null, 2));
+            return;
+        }
         if (['create', 'retry', 'cancel'].includes(action)) {
             await runManagedTaskCommand(action, args);
             return;
@@ -262,6 +261,15 @@ async function runTaskCommand(action, args) {
         console.log(JSON.stringify(task, null, 2));
         return;
     }
+    if (action === 'classify') {
+        const kind = arg(args, '--classification');
+        if (kind !== 'superseded' && kind !== 'invalid')
+            throw new Error('--classification must be superseded or invalid');
+        const result = await classifyFailedTask(store, job.id, id, { kind, targetTaskId: arg(args, '--target-task-id'), evidence: await textOption(args, '--evidence', '--evidence-file'), reason: await textOption(args, '--reason', '--reason-file') });
+        await saveLocal(localFile, result.job);
+        console.log(JSON.stringify(result.task, null, 2));
+        return;
+    }
     if (action === 'unblock') {
         await runTaskUnblockCommand(args, store, job, task, localFile);
         return;
@@ -798,7 +806,7 @@ async function main() {
             throw new Error(`${command} requires --repo and --id`);
         if (command === 'plan') {
             const guidance = hasArg(args, '--prompt') || hasArg(args, '--prompt-file') ? await textOption(args, '--prompt', '--prompt-file') : undefined;
-            console.log(JSON.stringify(await relayControlCommand(args, { command: 'job.plan', jobId, ...(guidance?.trim() ? { guidance: guidance.trim() } : {}) }), null, 2));
+            console.log(JSON.stringify(await relayControlCommand(args, { command: 'job.plan', jobId, ...(guidance?.trim() ? { guidance: guidance.trim() } : {}), forceCleanHistory: hasArg(args, '--force-clean-history') }), null, 2));
             return;
         }
         if (command === 'reconcile') {
@@ -827,7 +835,7 @@ async function main() {
         await withEventBus(args, async (bus) => {
             const reconciler = runtime(store, args, bus);
             try {
-                const result = await reconciler.planJob(job.id, guidance?.trim() || undefined);
+                const result = await reconciler.planJob(job.id, guidance?.trim() || undefined, hasArg(args, '--force-clean-history'));
                 await saveLocal(localFile, result.job);
                 await publishWake(bus, result.job, result.round.id, `Planning round ${result.round.id} completed`);
                 console.log(JSON.stringify(result.round, null, 2));

package/dist/dashboard-html.js

@@ -263,7 +263,7 @@ const TASK_STATES=['DRAFT','QUEUED','RUNNING','BLOCKED','SUCCEEDED','FAILED','CA
 async function setTaskState(task,state,select){const job=selected();if(!job||state===task.state)return;select.disabled=true;try{const params=new URLSearchParams({id:job.id,task:task.id,state,repo:job.repository,pr:String(job.prNumber)});const response=await fetch('/api/task-state?'+params.toString(),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);const updated=await response.json();const index=jobs.findIndex(candidate=>jobSelectionKey(candidate)===jobSelectionKey(job));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 showDetailsDialog(title,sections){const dialog=element('dialog','details-dialog');dialog.setAttribute('aria-label',title);const head=element('div','details-dialog-head');const name=element('strong','',text(title));const close=element('button','refresh-button',text('Close'));close.type='button';close.addEventListener('click',()=>dialog.close());head.append(name,close);dialog.append(head);for(const [label,value] of sections){if(value===undefined||value===null||value==='')continue;dialog.append(element('h3','',text(label)));const content=element('pre');content.textContent=typeof value==='string'?value:JSON.stringify(value,null,2);dialog.append(content);}dialog.addEventListener('close',()=>dialog.remove());document.body.append(dialog);dialog.showModal();}function openJobDetails(){const job=selected();if(!job)return;showDetailsDialog('Job '+job.id+' · '+value(job.title),[['Objective',job.objective],['Description',job.description],['State',job.state],['Plans',job.plans?.map(p=>({id:p.id,status:p.status,assessment:p.assessment,error:p.error,generatedTaskIds:p.generatedTaskIds}))],['Review',job.review],['Outcome',job.result],['Publication',job.publication],['Failure',job.error]]);}function openTaskDetails(task){const result=task.result?.data??task.result;showDetailsDialog('Task '+task.id+' · '+value(task.title),[['Input / task objective',task.input],['State',task.state],['Conclusion',result],['Result summary',task.result?.summary],['Planner assessment',task.plannerResult?.assessment],['Resolution',task.resolution],['Failure',task.failureReason||task.error],['Dependencies',task.dependencies]]);}document.querySelector('#job-content-open').addEventListener('click',openJobDetails);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('Title',task.title||'—'),field('Task ID',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));const result=task.result?.data??task.result;if(result){groups.append(field('Conclusion',result.verdict||result.outcome?.verdict||task.result?.summary||'Available'));}taskDetailRoot.append(groups);const details=element('button','refresh-button',text('Task details / conclusion'));details.type='button';details.addEventListener('click',()=>openTaskDetails(task));taskDetailRoot.append(details);}
+function showDetailsDialog(title,sections){const dialog=element('dialog','details-dialog');dialog.setAttribute('aria-label',title);const head=element('div','details-dialog-head');const name=element('strong','',text(title));const close=element('button','refresh-button',text('Close'));close.type='button';close.addEventListener('click',()=>dialog.close());head.append(name,close);dialog.append(head);for(const [label,value] of sections){if(value===undefined||value===null||value==='')continue;dialog.append(element('h3','',text(label)));const content=element('pre');content.textContent=typeof value==='string'?value:JSON.stringify(value,null,2);dialog.append(content);}dialog.addEventListener('close',()=>dialog.remove());document.body.append(dialog);dialog.showModal();}function openJobDetails(){const job=selected();if(!job)return;showDetailsDialog('Job '+job.id+' · '+value(job.title),[['Objective',job.objective],['Description',job.description],['State',job.state],['Plans',job.plans?.map(p=>({id:p.id,status:p.status,assessment:p.assessment,error:p.error,generatedTaskIds:p.generatedTaskIds}))],['Review',job.review],['Outcome',job.result],['Publication',job.publication],['Failure',job.error]]);}function openTaskDetails(task){const result=task.result?.data??task.result;showDetailsDialog('Task '+task.id+' · '+value(task.title),[['Input / task objective',task.input],['State',task.state],['Conclusion',result],['Result summary',task.result?.summary],['Planner assessment',task.plannerResult?.assessment],['Resolution',task.resolution],['Resolution classification',task.resolutionClassification],['Failure',task.failureReason||task.error],['Dependencies',task.dependencies]]);}document.querySelector('#job-content-open').addEventListener('click',openJobDetails);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('Title',task.title||'—'),field('Task ID',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'),...(task.resolutionClassification?[field('Resolution classification',task.resolutionClassification.kind),field('Resolution target',task.resolutionClassification.targetTaskId),field('Resolution evidence',task.resolutionClassification.evidence),field('Resolution reason',task.resolutionClassification.reason)]:[]),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));const result=task.result?.data??task.result;if(result){groups.append(field('Conclusion',result.verdict||result.outcome?.verdict||task.result?.summary||'Available'));}taskDetailRoot.append(groups);const details=element('button','refresh-button',text('Task details / conclusion'));details.type='button';details.addEventListener('click',()=>openTaskDetails(task));taskDetailRoot.append(details);}
 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(jobSelectionKey(job)!==selectedJob){selectedJob=jobSelectionKey(job);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)),field('Creator thread',job.creatorThreadId||'—'),threadField('Implementation thread',job.implementationThreadId),threadField('Reviewer thread',job.reviewerThreadId),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)),chatShortcutField(job));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/manual-plan.js

@@ -1,7 +1,9 @@
 import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
 import { createPlanRound, pendingPlan } from './planner.js';
 import { applyJobActivateAction } from './job-actions.js';
-export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner) {
+export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner, forceCleanHistory = false) {
+    if (forceCleanHistory && !store.mutateJob)
+        throw new Error('--force-clean-history requires atomic durable SQLite mutations');
     let job = await store.load(jobId);
     if (['COMPLETED', 'CANCELLED'].includes(job.state))
         throw new Error(`Cannot plan terminal job ${job.id} (${job.state})`);
@@ -18,6 +20,8 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
             if (current.pause)
                 throw new Error(`Cannot plan paused Job ${current.id}; resume it first`);
             const concurrent = pendingPlan(current);
+            if (forceCleanHistory && concurrent)
+                throw new Error(`--force-clean-history requires no pending Plan (${concurrent.id})`);
             if (concurrent) {
                 if (concurrent.executionId)
                     throw new Error(`Planning round ${concurrent.id} is already PLANNING`);
@@ -25,6 +29,10 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
             }
             else {
                 round = createPlanRound(current, { guidance, manual: true, timeoutMs });
+                if (forceCleanHistory) {
+                    round.forceCleanHistory = true;
+                    round.cleanHistoryTaskIds = current.tasks.filter(task => task.kind !== 'planner' && task.state === 'FAILED' && !task.resolutionClassification).map(task => task.id);
+                }
                 current.plans = [...(current.plans ?? []), structuredClone(round)].sort((a, b) => a.round - b.round);
             }
             if (current.state === 'DRAFT') {

package/dist/planner-history-cleanup.js

@@ -0,0 +1,33 @@
+function record(value, field) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Planner ${field} must be an object`);
+    return value;
+}
+function requiredText(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error(`Planner ${field} must be a non-empty string`);
+    return value;
+}
+export function parsePlannerHistoryCleanup(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error('Planner history_cleanup must be an array when provided');
+    const ids = new Set();
+    return value.map((item, index) => {
+        const row = record(item, `history_cleanup[${index}]`);
+        const taskId = requiredText(row.taskId, `history_cleanup[${index}].taskId`);
+        const outcome = row.outcome;
+        const evidence = requiredText(row.evidence, `history_cleanup[${index}].evidence`);
+        const reason = requiredText(row.reason, `history_cleanup[${index}].reason`);
+        if (!['superseded', 'invalid', 'cancelled_review', 'unresolved'].includes(String(outcome)))
+            throw new Error(`Planner history_cleanup[${index}].outcome is invalid`);
+        if (ids.has(taskId))
+            throw new Error(`Planner history_cleanup contains duplicate Task ${taskId}`);
+        ids.add(taskId);
+        const targetTaskId = row.targetTaskId === undefined ? undefined : requiredText(row.targetTaskId, `history_cleanup[${index}].targetTaskId`);
+        if ((outcome === 'superseded' || outcome === 'invalid') && !targetTaskId)
+            throw new Error(`Planner history_cleanup[${index}].targetTaskId is required for ${String(outcome)}`);
+        return { taskId, outcome: outcome, evidence, reason, ...(targetTaskId ? { targetTaskId } : {}) };
+    });
+}

package/dist/planner-recovery.js

@@ -9,7 +9,7 @@ export function createFailedPlanRecovery(job, plan) {
         throw Error('Plan recovery identity already exists');
     const now = new Date().toISOString();
     return createTaskEntity(job, {
-        jobId: job.id, id, title: 'Diagnose and recover failed Planner round',
+        jobId: job.id, id, title: 'Troubleshoot',
         recoveryPlanId: plan.id,
         kind: 'work', priority: 'P0', storySize: 'M', projectName: job.title,
         agentName: 'troubleshooter', parentTaskId: null, dependencies: [],

package/dist/planner-runtime.js

@@ -71,7 +71,7 @@ export async function finishPlanner(ports, jobId, planId, executionId, error, ra
         ports.live.delete(planId); };
     const job = await ports.store.load(jobId);
     const plan = (job.plans ?? []).find(item => item.id === planId);
-    if (!plan || plan.status !== "PLANNING" || plan.executionId !== executionId) {
+    if (!plan || (plan.executionId !== executionId && !(raw?.cliApplied && plan.status === 'SUCCEEDED'))) {
         releaseLive();
         if (cliApply)
             throw new Error(`Plan ${planId} is not owned by this active execution`);
@@ -118,6 +118,14 @@ export async function finishPlanner(ports, jobId, planId, executionId, error, ra
         if (retry && !plan.manualPlanning)
             ports.detach(ports.reconcile(jobId), jobId, planId, 'planner retry reconciliation');
     };
+    if (raw?.cliApplied) {
+        if (plan.status !== 'SUCCEEDED') {
+            releaseLive();
+            throw new Error(`Planner reported CLI application, but Plan ${planId} is ${plan.status}`);
+        }
+        releaseLive();
+        return;
+    }
     if (error) {
         if (cliApply)
             throw error;
@@ -128,6 +136,25 @@ export async function finishPlanner(ports, jobId, planId, executionId, error, ra
     let planCommitted = false;
     try {
         const parsed = parsePlannerResult(raw);
+        if (plan.forceCleanHistory) {
+            const cleanup = parsed.history_cleanup ?? [];
+            const expected = new Set(plan.cleanHistoryTaskIds ?? []);
+            if (cleanup.length !== expected.size || cleanup.some(item => !expected.delete(item.taskId)) || expected.size)
+                throw new Error('--force-clean-history requires exactly one Planner disposition for each failed Task in its durable snapshot');
+            for (const item of cleanup) {
+                const task = job.tasks.find(candidate => candidate.id === item.taskId);
+                if (!task)
+                    throw new Error(`Clean history Task ${item.taskId} disappeared`);
+                if (task.failureReason === 'worker_outcome_unknown' && item.outcome !== 'unresolved')
+                    throw new Error(`Unknown execution outcome for ${item.taskId} must remain unresolved without graph-verified proof`);
+                if ((item.outcome === 'superseded' || item.outcome === 'invalid') && (task.resolutionClassification?.kind !== item.outcome || task.resolutionClassification.targetTaskId !== item.targetTaskId || task.resolutionClassification.evidence !== item.evidence || task.resolutionClassification.reason !== item.reason))
+                    throw new Error(`Clean history classification for ${item.taskId} was not applied through task classify with matching evidence`);
+                if (item.outcome === 'cancelled_review' && (task.agentName !== 'reviewer' || task.state !== 'CANCELLED'))
+                    throw new Error(`Failed review ${item.taskId} must be cancelled through task cancel before Plan apply`);
+                if (item.outcome === 'unresolved' && (task.state !== 'FAILED' || task.resolutionClassification))
+                    throw new Error(`Unresolved history item ${item.taskId} changed after Planner assessment`);
+            }
+        }
         const result = assignPlannerTaskIds(parsed, job.repository, job.id, plan.id);
         const executionContext = await ports.plannerContext(job, plan);
         validatePlannerHierarchy(job.tasks, result.next_tasks);
@@ -326,7 +353,7 @@ export async function launchPlanExecution(ports, job, plan) {
     let promise;
     try {
         const executionContext = await ports.plannerContext(job, plan);
-        const context = { planExecution: { planId: plan.id, executionId }, job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
+        const context = { planExecution: { planId: plan.id, executionId }, forceCleanHistory: plan.forceCleanHistory, cleanHistoryTaskIds: plan.cleanHistoryTaskIds, job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
         promise = planner.plan(context, controller.signal);
     }
     catch (error) {

package/dist/planner-task-context.js

@@ -0,0 +1,26 @@
+function boundedText(value, max = 4000) {
+    if (value === null || value === undefined || value.length <= max)
+        return value;
+    return value.slice(0, max) + `\n...[truncated ${value.length - max} chars]`;
+}
+export function plannerTaskContext(task) {
+    return {
+        id: task.id,
+        title: task.title,
+        kind: task.kind ?? 'work',
+        parent_task_id: task.parentTaskId,
+        dependencies: task.dependencies,
+        state: task.state,
+        failure_reason: task.failureReason,
+        input: task.kind === 'planner' ? undefined : boundedText(task.input),
+        result_summary: boundedText(task.result?.summary),
+        result_evidence: task.result?.data ? boundedText(JSON.stringify(task.result.data), 2000) : undefined,
+        execution_history: task.executionHistory?.map(item => ({ id: item.id, attempt: item.attempt, started_at: item.startedAt })),
+        platform_failure: task.platformFailure ? { classification: task.platformFailure.classification, evidence: boundedText(task.platformFailure.evidence), safe_to_reroute: task.platformFailure.safeToReroute } : undefined,
+        comments: task.comments?.slice(-10).map(comment => ({ author: comment.author, text: boundedText(comment.text, 1000), created_at: comment.createdAt })),
+        resolution_classification: task.resolutionClassification,
+        error: boundedText(task.error, 2000),
+        blocked_baseline: task.blockedBaseline,
+        unblock: task.unblock,
+    };
+}

package/dist/planner.js

@@ -13,12 +13,14 @@ import { createTaskEntity } from './workflow/entity-creation.js';
 import { prepareReviewerThreadDelivery, chatgptThreadRequirements } from './reviewer-thread.js';
 import { spawnOwnedProcess } from './owned-process.js';
 import { requiredPlannerTaskTitle } from './planner-task-title.js';
+import { parsePlannerHistoryCleanup } from './planner-history-cleanup.js';
+import { plannerTaskContext } from './planner-task-context.js';
 export function semanticTaskTree(tasks) {
     const work = tasks.filter(task => task.kind !== 'planner');
     const ids = new Set(work.map(task => task.id));
     return {
         roots: work.filter(task => !task.parentTaskId || !ids.has(task.parentTaskId)).map(task => task.id),
-        tasks: work.map(task => ({ id: task.id, title: task.title, parent_task_id: task.parentTaskId, state: task.state, dependencies: [...task.dependencies], planning_decision_id: task.planningDecisionId, planning_round: task.planningRound, review: task.review })),
+        tasks: work.map(task => ({ id: task.id, title: task.title, parent_task_id: task.parentTaskId, state: task.state, dependencies: [...task.dependencies], planning_decision_id: task.planningDecisionId, planning_round: task.planningRound, review: task.review, resolution_classification: task.resolutionClassification })),
     };
 }
 function plannerTrigger(job, manual = false) {
@@ -107,6 +109,7 @@ export function materializePlannerChild(job, planner, spec, executionContext) {
     const round = 'round' in planner ? planner.round : planner.planningRound ?? 1;
     const plannerHeadSha = 'round' in planner ? planner.headSha : undefined;
     const reviewHeadSha = spec.agentName === 'reviewer' && !(spec.dependencies?.length) ? plannerHeadSha ?? job.headSha : undefined;
+    const objectiveRoot = spec.agentName === 'reviewer' ? job.tasks.find(task => task.kind !== 'planner' && task.agentName !== 'reviewer' && task.agentName !== 'troubleshooter' && !task.parentTaskId) : undefined;
     const resolution = spec.resolution;
     if (resolution) {
         const target = resolution.targetTaskId ? job.tasks.find(task => task.id === resolution.targetTaskId) : undefined;
@@ -115,7 +118,7 @@ export function materializePlannerChild(job, planner, spec, executionContext) {
         validateResolutionProposal(job, target, resolution);
     }
     const reviewerThread = spec.agentName === 'reviewer' ? prepareReviewerThreadDelivery(job, { id: spec.id, agentName: spec.agentName, reviewHeadSha }) : undefined, implementationThread = (spec.agentName === 'implementation' || spec.agentName == null) && job.implementationThreadId ? job.implementationThreadId : undefined, threadOwned = Boolean(reviewerThread || implementationThread);
-    return createTaskEntity(job, { jobId: job.id, id: spec.id, title: spec.title, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, agentGraph: spec.agentGraph, review: spec.review, parentTaskId: spec.parentTaskId ?? null, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: threadOwned ? chatgptThreadRequirements(spec.workerRequirements) : spec.workerRequirements, testInjection: spec.testInjection, adapter: threadOwned ? 'chatgpt' : (spec.adapter ?? 'codex'), chatgptThreadDelivery: reviewerThread, input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: decisionId, planningSource: source, planningRound: round, reviewHeadSha, resolution: resolution ? { ...resolution, state: 'proposed', owner: 'planner', updatedAt: now } : undefined });
+    return createTaskEntity(job, { jobId: job.id, id: spec.id, title: spec.agentName === 'reviewer' ? 'Review' : spec.title, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, agentGraph: spec.agentGraph, review: spec.review, parentTaskId: objectiveRoot?.id ?? spec.parentTaskId ?? null, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: threadOwned ? chatgptThreadRequirements(spec.workerRequirements) : spec.workerRequirements, testInjection: spec.testInjection, adapter: threadOwned ? 'chatgpt' : (spec.adapter ?? 'codex'), chatgptThreadDelivery: reviewerThread, input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: decisionId, planningSource: source, planningRound: round, reviewHeadSha, resolution: resolution ? { ...resolution, state: 'proposed', owner: 'planner', updatedAt: now } : undefined });
 }
 export function planningSpec(task) {
     if (!task.output)
@@ -267,6 +270,7 @@ export function parsePlannerResult(value) {
         unblockKeys.add(key);
         return { repository, prNumber: Number(prNumber), jobId, taskId, resolutionMode: resolutionMode };
     });
+    const history_cleanup = parsePlannerHistoryCleanup(root.history_cleanup);
     const ids = new Set();
     const next_tasks = root.next_tasks.map((item, index) => {
         const task = record(item, `next_tasks[${index}]`);
@@ -319,7 +323,7 @@ export function parsePlannerResult(value) {
             continuation: task.continuation, maxAttempts, timeoutMs, resolution: resolutionProposal(task.resolution, `next_tasks[${index}].resolution`)
         };
     });
-    return { objective_status: status, assessment: root.assessment, next_tasks, unblocks };
+    return { objective_status: status, assessment: root.assessment, next_tasks, unblocks, ...(history_cleanup ? { history_cleanup } : {}) };
 }
 export function validatePlannerProgress(job, result) {
     if (result.objective_status !== 'in_progress' || result.next_tasks.length > 0 || result.unblocks.length > 0)
@@ -386,7 +390,7 @@ export function validatePlannerHierarchy(existing, specs) {
 /** Planner may only materialize a new business Task while unresolved work is either
  * explicitly resolved in this round or already owned by an active resolution path. */
 export function validatePlannerResolutionMaterialization(existing, specs) {
-    const unresolved = existing.filter(task => unresolvedTask(task) && ['FAILED', 'BLOCKED'].includes(task.state));
+    const unresolved = existing.filter(task => unresolvedTask(task) && ['FAILED', 'BLOCKED'].includes(task.state) && !task.resolutionClassification);
     if (unresolved.length === 0)
         return;
     const resolvedIds = new Set(specs.map(spec => spec.resolution?.targetTaskId).filter((id) => Boolean(id)));
@@ -416,8 +420,11 @@ export function plannerInput(context) {
     const project = context.executionContext?.project;
     return JSON.stringify({
         objective: context.objective,
+        apply_cli: context.planExecution ? `agents-relay plan apply --repo ${context.job.repository} --pr ${context.job.prNumber} --id ${context.job.id} --plan-id ${context.planExecution.planId} --execution-id ${context.planExecution.executionId} --file PATH` : undefined,
         plan_execution: context.planExecution, retry_feedback: context.retryFeedback,
         caller_prompt: context.guidance,
+        force_clean_history: context.forceCleanHistory === true,
+        clean_history_task_ids: context.cleanHistoryTaskIds ?? [],
         previous_planner_task_id: context.previousPlannerTaskId,
         plan_trigger: context.trigger,
         legacy_change_cycle: context.job.changeCycle,
@@ -436,23 +443,11 @@ export function plannerInput(context) {
         })),
         project: project ? { name: project.name, path: project.path } : undefined,
         visible_agents: visibleAgents ?? [],
-        tasks: context.tasks.map(task => ({
-            id: task.id,
-            title: task.title,
-            kind: task.kind ?? 'work',
-            parent_task_id: task.parentTaskId,
-            state: task.state,
-            input: task.kind === 'planner' ? undefined : boundedText(task.input),
-            result_summary: boundedText(task.result?.summary),
-            planner_result: task.plannerResult ? {
+        tasks: context.tasks.map(task => ({ ...plannerTaskContext(task), planner_result: task.plannerResult ? {
                 objective_status: task.plannerResult.objective_status,
                 assessment: boundedText(task.plannerResult.assessment),
                 next_task_ids: task.plannerResult.next_tasks.map(item => item.id),
-            } : undefined,
-            error: boundedText(task.error, 2000),
-            blocked_baseline: task.blockedBaseline,
-            unblock: task.unblock,
-        })),
+            } : undefined })),
     });
 }
 export class CommandObjectivePlanner {
@@ -470,12 +465,10 @@ export class CommandObjectivePlanner {
             child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
             child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
             child.on('error', reject);
-            child.on('close', code => code === 0 ? (() => { try {
-                resolve(parsePlannerOutput(stdout));
-            }
-            catch (error) {
-                reject(error);
-            } })() : reject(new Error(stderr.trim() || `Planner exited ${code}`)));
+            child.on('close', code => code === 0 ? (() => { const expected = context.planExecution ? `PLAN_APPLIED:${context.planExecution.planId}:${context.planExecution.executionId}` : ''; if (stdout.trim() !== expected || !expected) {
+                reject(new Error('Planner command must commit its proposal through agents-relay plan apply and return the matching PLAN_APPLIED receipt'));
+                return;
+            } resolve({ objective_status: 'satisfied', assessment: 'Plan committed through the authorized CLI action.', next_tasks: [], unblocks: [], cliApplied: true }); })() : reject(new Error(stderr.trim() || `Planner exited ${code}`)));
             child.stdin?.end(plannerInput(context));
         });
     }
@@ -539,18 +532,12 @@ export class AgentObjectivePlanner {
                 resolve(finalMessage);
             });
         });
-        const parseAndCheck = (raw) => { const result = parsePlannerOutput(raw); validatePlannerResolutionMaterialization(context.tasks, result.next_tasks); return result; };
-        let response = await runAgent(prompt);
-        for (let retry = 0; retry <= 3; retry++) {
-            try {
-                return parseAndCheck(response);
-            }
-            catch (error) {
-                if (signal.aborted || retry === 3)
-                    throw new Error(`Planner validation failed after ${retry} corrections: ${error instanceof Error ? error.message : String(error)}`);
-                response = await runAgent(`${prompt}\n\n## Fix validation error (correction ${retry + 1} of 3)\n${error instanceof Error ? error.message : String(error)}\nPrevious JSON:\n${response.slice(0, 12000)}\nReturn exactly one complete Planner JSON object. Correct all schema, title, resolution, and dependency requirements; do not remove valid work or bypass safeguards.`);
-            }
-        }
-        throw new Error('Planner correction exhausted');
+        if (!context.planExecution)
+            throw new Error('Planner execution is missing its durable Plan and execution identity');
+        const response = await runAgent(prompt);
+        const expected = `PLAN_APPLIED:${context.planExecution.planId}:${context.planExecution.executionId}`;
+        if (response !== expected)
+            throw new Error('Planner must commit its proposal with the authorized `agents-relay plan apply` CLI action and return only the matching PLAN_APPLIED receipt');
+        return { objective_status: 'satisfied', assessment: 'Plan committed through the authorized CLI action.', next_tasks: [], unblocks: [], cliApplied: true };
     }
 }

package/dist/reconciler-review.js

@@ -146,14 +146,15 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
             reviewPrNumber > 0 ? `Review PR #${reviewPrNumber} at exactly head SHA ${headSha}.` : `Review the local Job artifact at exactly head SHA ${headSha}.`,
             `Review head SHA: ${headSha}`,
             'Job objective: ' + (job.objective ?? job.description ?? job.title),
+            'Review the complete PR diff at this exact immutable head SHA, not only the dependency Tasks.',
             'Use the selected reviewer agent contract as the authoritative review protocol.',
             'This is a PRE-MERGE artifact approval gate: inspect exact PR head, requirements, tests and genuine blocking defects.',
             'Do not block approval because automatic merge, Job COMPLETED, or post-merge E2E evidence has not occurred yet.',
             'Do not treat historical failed attempts as current artifact defects; distinguish preserved baseline files from implementation.',
         ].join('\n\n');
         const task = createTaskEntity(job, {
-            jobId: job.id, id, title: `Review ${headSha.slice(0, 8)}`, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer',
-            parentTaskId: null, dependencies: reviewGateTasks.map(item => item.id), capabilities: ['review'],
+            jobId: job.id, id, title: 'Review', kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer',
+            parentTaskId: reviewGateTasks.find(item => !item.parentTaskId)?.id ?? null, dependencies: reviewGateTasks.map(item => item.id), capabilities: ['review'],
             workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter,
             input,
             output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.routing, continuation: null, continuationDeliveredAt: null,
@@ -163,7 +164,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
             error: null, timeoutMs: this.options.reviewer?.timeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now
         });
         await this.store.appendTask(task);
-        await this.emit(eventFor(job.id, id, null, 'review.created', 'queued', 'Final review task ' + id + ' created for ' + headSha + ' using ' + reviewerRouting.reason, 'orchestrator', { headSha, agentName: 'reviewer', reviewerRouting: { workerId: reviewerRouting.selection.workerId, reason: reviewerRouting.reason, selectedBy: reviewerRouting.selection.selectedBy } }));
+        await this.emit(eventFor(job.id, id, task.parentTaskId, 'review.created', 'queued', 'Final review task ' + id + ' created for ' + headSha + ' using ' + reviewerRouting.reason, 'orchestrator', { headSha, agentName: 'reviewer', reviewerRouting: { workerId: reviewerRouting.selection.workerId, reason: reviewerRouting.reason, selectedBy: reviewerRouting.selection.selectedBy } }));
         return id;
     }
     async projectedReviewHeadReady(job, headSha) {

package/dist/reconciler.js

@@ -137,7 +137,7 @@ export class Reconciler extends ReconcilerReviewBase {
             }
             for (const recovery of pendingTroubleshooterTasks(await this.store.load(jobId))) {
                 await this.store.appendTask(recovery);
-                await this.emit(eventFor(job.id, recovery.id, null, "troubleshooter.created", "queued", "Troubleshooter task " + recovery.id + " created for failed/blocked work", "orchestrator", { agentName: "troubleshooter" }));
+                await this.emit(eventFor(job.id, recovery.id, recovery.parentTaskId, "troubleshooter.created", "queued", "Troubleshooter task " + recovery.id + " created for failed/blocked work", "orchestrator", { agentName: "troubleshooter", originalTaskId: recovery.parentTaskId }));
             }
             {
                 const recoveryJob = await this.store.load(jobId);
@@ -273,8 +273,8 @@ export class Reconciler extends ReconcilerReviewBase {
         }
         return this.store.load(jobId);
     }
-    async planJob(jobId, guidance) {
-        return executeManualPlan(this.store, jobId, guidance, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), (job, plan) => this.launchPlanner(job, plan));
+    async planJob(jobId, guidance, forceCleanHistory = false) {
+        return executeManualPlan(this.store, jobId, guidance, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), (job, plan) => this.launchPlanner(job, plan), forceCleanHistory);
     }
     async maybeCreatePlanner(job) {
         const pending = pendingPlan(job);

package/dist/relayd-control.js

@@ -4,7 +4,7 @@ import { openLocalManagedStore } from './local-managed-store.js';
 import { relayStoreDirectory } from './relay-store.js';
 import { normalizeThreadId } from './reviewer-thread.js';
 import { publishTaskBlocked } from './cli-support.js';
-import { supersedeCancelledTask } from './task-actions.js';
+import { classifyFailedTask, supersedeCancelledTask } from './task-actions.js';
 import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
 import { adoptExistingPullRequestJob } from './cli-job-create.js';
 export function createWorkspaceControl(deps) {
@@ -109,7 +109,7 @@ export function createWorkspaceControl(deps) {
         if (command === 'job.plan') {
             const reconciler = makeReconciler(store, concurrency);
             try {
-                const planned = await reconciler.planJob(jobId, typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance : undefined);
+                const planned = await reconciler.planJob(jobId, typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance : undefined, body.forceCleanHistory === true);
                 await pool.reconcileLocalJob(jobId, 'control.job.plan');
                 return planned.round;
             }
@@ -150,6 +150,15 @@ export function createWorkspaceControl(deps) {
             await pool.reconcileLocalJob(jobId, 'control.task.supersede');
             return await store.load(jobId);
         }
+        if (command === 'task.classify') {
+            const taskId = typeof body.taskId === 'string' ? body.taskId : '';
+            const raw = body.classification;
+            if (!taskId || !raw || (raw.kind !== 'superseded' && raw.kind !== 'invalid') || typeof raw.targetTaskId !== 'string' || typeof raw.evidence !== 'string' || typeof raw.reason !== 'string')
+                throw new Error('task classify requires taskId, classification, targetTaskId, evidence, and reason');
+            await classifyFailedTask(store, jobId, taskId, { kind: raw.kind, targetTaskId: raw.targetTaskId, evidence: raw.evidence, reason: raw.reason });
+            await pool.reconcileLocalJob(jobId, 'control.task.classify');
+            return await store.load(jobId);
+        }
         if (command === 'task.recover') {
             const taskId = typeof body.taskId === 'string' ? body.taskId : '';
             const recoveryTaskId = typeof body.recoveryTaskId === 'string' ? body.recoveryTaskId : '';

package/dist/single-job-task-control.js

@@ -17,7 +17,7 @@ export async function createSingleJobTaskControl(jobId, store, reconciler, bus)
         unblockAutonomousTasks: unblock.unblockAutonomousTasks, unblockTask: unblock.unblockTask,
         publishTaskUnblocked, dispatchTaskAction,
     });
-    const allowed = new Set(['task.unblock', 'task.recover', 'task.escalate', 'task.resume-troubleshooter']);
+    const allowed = new Set(['task.unblock', 'task.recover', 'task.escalate', 'task.resume-troubleshooter', 'task.classify']);
     return async (body) => {
         if (!allowed.has(String(body.command ?? '')))
             throw new Error('Single-Job control command not supported');

package/dist/task-actions.js

@@ -1,6 +1,7 @@
 import { extendRetryBudget, transitionTaskEvent, tryTransitionTaskEvent } from './scheduler.js';
 import { selectRelatedTaskMutations } from './workflow/task-action-policy.js';
 import { dispatchTaskResolutionSync, materializeResolution } from './workflow/task-resolution.js';
+import { classifyTaskResolution } from './workflow/task-resolution.js';
 export const TASK_RETRY_ACTION = 'task.retry';
 export const TASK_RECOVER_ACTION = 'task.recover';
 export const TASK_UNBLOCK_RETRY_ACTION = 'task.unblock.retry';
@@ -8,6 +9,24 @@ export const TASK_CANCEL_ACTION = 'task.cancel';
 export const TASK_RELEASE_ACTION = 'task.release';
 export const TASK_HOLD_ACTION = 'task.hold';
 export const TASK_QUEUE_ACTION = 'task.queue';
+export async function classifyFailedTask(store, jobId, taskId, classification) {
+    if (!store.mutateJob)
+        throw new Error('Task resolution classification requires atomic SQLite mutation');
+    let changed;
+    const job = await store.mutateJob(jobId, current => {
+        const task = current.tasks.find(item => item.id === taskId);
+        if (!task)
+            throw new Error(`Task ${taskId} not found`);
+        if (classification.targetTaskId === task.id || !current.tasks.some(item => item.id === classification.targetTaskId))
+            throw new Error('Task classification targetTaskId must identify a different durable Task in this Job');
+        classifyTaskResolution(task, classification);
+        changed = structuredClone(task);
+        return current;
+    });
+    if (!changed)
+        throw new Error(`Task ${taskId} classification was not committed`);
+    return { job, task: changed };
+}
 function lifecycleRejection(task, action) {
     return new Error(`Task ${task.id} is not ${action} (${task.state})`);
 }

package/dist/troubleshooter.js

@@ -92,7 +92,7 @@ export function pendingTroubleshooterTasks(job) {
         recoveries.push(createTaskEntity(job, {
             jobId: job.id,
             id,
-            title: `Recover task ${task.id}`,
+            title: 'Troubleshoot',
             recoveryForAttempt: task.attempt,
             kind: 'work',
             priority: 'P0',

package/dist/workflow/task-resolution.js

@@ -7,16 +7,45 @@ export const TASK_RESOLUTION_PATHS = [
 const source = readFileSync(new URL('../../workflow/task-resolution.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const taskResolutionV2 = new GraphRuntime(source, {
-    states: new Set(['unresolved', 'check_owner', 'check_path', 'check_fresh_execution', 'resolved', 'rejected']),
+    states: new Set(['unresolved', 'check_owner', 'check_path', 'check_fresh_execution', 'check_classification', 'classificationKind', 'resolved', 'rejected']),
     guards: {
         recoveryOwnerAvailable: boolGuard('recoveryOwnerAvailable'), plannerOwnerAvailable: boolGuard('plannerOwnerAvailable'),
         exactOriginalRetry: boolGuard('exactOriginalRetry'), sameJobDependency: boolGuard('sameJobDependency'),
         blockerJobDependency: boolGuard('blockerJobDependency'), escalationGate: boolGuard('escalationGate'), genuinelyObsolete: boolGuard('genuinelyObsolete'),
         freshRecoveryExecution: boolGuard('freshRecoveryExecution'),
+        classifiableFailure: boolGuard('classifiableFailure'),
+        classificationSuperseded: boolGuard('classificationSuperseded'),
+        supersededEvidenceComplete: boolGuard('supersededEvidenceComplete'),
+        invalidEvidenceComplete: boolGuard('invalidEvidenceComplete'),
     },
-    actions: Object.fromEntries(['resolution.activateRecovery', 'resolution.attachSameJobDependency', 'resolution.registerBlockerDependency', 'resolution.createEscalationGate', 'resolution.cancelSupersede'].map(id => [id, { id }])),
-    events: { 'resolution.propose': { id: 'resolution.propose' } },
+    actions: Object.fromEntries(['resolution.activateRecovery', 'resolution.attachSameJobDependency', 'resolution.registerBlockerDependency', 'resolution.createEscalationGate', 'resolution.cancelSupersede', 'resolution.classifySuperseded', 'resolution.classifyInvalid'].map(id => [id, { id }])),
+    events: { 'resolution.propose': { id: 'resolution.propose' }, 'resolution.classify': { id: 'resolution.classify' } },
 });
+export function classifyTaskResolution(task, classification, now = new Date().toISOString()) {
+    const complete = Boolean(classification.targetTaskId.trim() && classification.evidence.trim() && classification.reason.trim());
+    let applied;
+    const decision = dispatchWorkflowGraphSync(taskResolutionV2, {
+        initialState: 'unresolved', input: { transport: 'event', id: 'resolution.classify', payload: classification },
+        durableFacts: {
+            classifiableFailure: task.kind !== 'planner' && task.state === 'FAILED' && task.failureReason !== 'worker_outcome_unknown' && !task.executionId && !task.leaseOwner && !task.leaseExpiresAt && !task.resolutionClassification && !['active', 'waiting'].includes(task.resolution?.state ?? ''),
+            classificationSuperseded: classification.kind === 'superseded',
+            supersededEvidenceComplete: classification.kind === 'superseded' && complete,
+            invalidEvidenceComplete: classification.kind === 'invalid' && complete,
+        }, graphName: 'task-resolution', isTransientState: state => state === 'check_classification' || state === 'classificationKind', maxSteps: 6,
+        executeAction: actionId => {
+            const expectedAction = classification.kind === 'superseded' ? 'resolution.classifySuperseded' : 'resolution.classifyInvalid';
+            if (actionId !== expectedAction)
+                throw new Error(`Unexpected Task Resolution action ${actionId}`);
+            applied = { ...classification, updatedAt: now };
+            task.resolutionClassification = applied;
+            task.updatedAt = now;
+            return {};
+        },
+    });
+    if (!decision.accepted || decision.target !== 'resolved' || !applied)
+        throw new Error(`Task resolution graph rejected ${classification.kind} classification for ${task.id}`);
+    return applied;
+}
 export function unresolvedTask(task) { return task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state); }
 export function validateResolutionProposal(job, original, proposal) {
     if (!TASK_RESOLUTION_PATHS.includes(proposal.path))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.157",
+  "version": "2.0.159",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",
@@ -19,8 +19,8 @@
     "test:publish": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 --test-force-exit test/*.test.js",
     "test:fast": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=2 test/workflow-lifecycle.test.js test/workflow-v2-lifecycle-parity.test.js test/workflow-effects.test.js test/relay-store.test.js test/local-authority.test.js test/local-jobid-routing.test.js test/local-sqlite-jobid.test.js test/no-github.test.js test/scheduled-jobs.test.js test/reconcile-coordinator.test.js test/service-publication.test.js test/github-webhook.test.js",
     "test:full": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/*.test.js && npm run test:verification:l3",
-    "test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs",
-    "test:verification:l3": "npm run build && node --test --test-concurrency=1 test/verification/harness.test.mjs test/verification/l3-sqlite.test.mjs test/verification/l3-ingress.test.mjs test/verification/l3-replay.test.mjs test/verification/objective-authority.test.mjs test/verification/l3-convergence.test.mjs test/verification/l3-review-convergence.test.mjs test/verification/l3-human-escalation.test.mjs test/verification/l3-escalation-notifier.test.mjs test/verification/l3-unknown-effect.test.mjs test/verification/l3-cli-actions.test.mjs test/verification/l3-planner-round.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.test.mjs test/verification/l3-full-path.test.mjs test/verification/l3-projection-recovery.test.mjs",
+    "test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs test/verification/task-resolution-classification.test.mjs",
+    "test:verification:l3": "npm run build && node --test --test-concurrency=1 test/verification/harness.test.mjs test/verification/l3-sqlite.test.mjs test/verification/l3-ingress.test.mjs test/verification/l3-replay.test.mjs test/verification/objective-authority.test.mjs test/verification/l3-convergence.test.mjs test/verification/l3-review-convergence.test.mjs test/verification/l3-human-escalation.test.mjs test/verification/l3-escalation-notifier.test.mjs test/verification/l3-unknown-effect.test.mjs test/verification/l3-cli-actions.test.mjs test/verification/l3-planner-round.test.mjs test/verification/l3-task-resolution.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.test.mjs test/verification/l3-full-path.test.mjs test/verification/l3-projection-recovery.test.mjs",
     "test:verification": "npm run test:verification:l1 && npm run test:verification:l2 && npm run test:verification:l3 && npm run test:verification:cross-a && node --test test/workflow-production-outbox.test.js && npm run test:verification:matrix",
     "e2e": "node e2e/runner/run.mjs",
     "test:verification:cross-a": "npm run build && RELAY_A_DIST=$PWD/dist node --test test/verification/action-ledger-cross-branch.test.mjs test/verification/outbox-cross-a.test.mjs",

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

@@ -4,7 +4,7 @@ You are the default objective planner for Agents Relay autonomous jobs.
 
 Before producing tasks, read and follow `../contracts/task-job-contract.md`.
 
-You are a planning agent. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. Your sole responsibility is to decompose the objective and create a valid Plan/Task Tree. When the invocation provides a live Plan ID and execution ID, write the proposed JSON to a temporary file and submit it with `agents-relay plan apply --repo OWNER/REPO --pr PR_NUMBER --id JOB_ID --plan-id PLAN_ID --execution-id EXECUTION_ID --file PATH`. If the CLI rejects it, correct the reported error and re-submit within the SAME Plan, up to three corrections. Do not create new Jobs, run Tasks, change statuses, or perform scheduling/recovery. On successful apply, return the same JSON as your final answer for compatibility; Relay detects the committed round and does not create duplicate Tasks. If no live execution identity is provided, return JSON and let Relay materialize it as before.
+You are a planning agent. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. Your sole responsibility is to decompose the objective and create a valid Plan/Task Tree. Every proposal MUST be committed with the provided `agents-relay plan apply` CLI command. Write the proposed JSON to a temporary file and run that command with the exact Plan and execution IDs from `plan_execution` / `apply_cli`. If the CLI rejects it, correct the reported error and resubmit within the SAME Plan, up to three corrections. Do not edit SQLite or other durable storage directly. Do not treat a JSON/text response as a plan submission and do not return the proposal as your final answer. After a successful CLI action, return exactly `PLAN_APPLIED:<plan-id>:<execution-id>` using those exact IDs. Never invent that receipt. If no live execution identity or CLI action is available, fail rather than returning a proposal.
 
 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.
 
@@ -96,9 +96,15 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - If satisfied, return `objective_status: "satisfied"` and `next_tasks: []`.
 - Otherwise return only the next useful executable batch from the graph-derived Task boundaries.
 - Do not repeat completed work or recreate an existing Task unless replacement work is explicitly needed.
-- **Resolution is mandatory for replacement work:** before returning any `next_tasks`, inspect every existing `FAILED` or `BLOCKED` work Task. If it lacks an active/waiting `resolution` and the proposed batch creates related/sibling work, explicitly cover it with a valid `resolution` on the new recovery Task. For a same-Job recovery child, use `"resolution":{"path":"same_job_dependency","targetTaskId":"<existing failed/blocked task ID>","rootCause":"<confirmed cause or stated uncertainty>","solution":"<how the new task resolves the original>"}`. `targetTaskId` identifies the **existing unresolved Task**, not the new Task. Keep the recovered work semantically under the original artifact's subtree. Do not invent a resolution or silently cancel unrelated failed work.
+- **Resolution is mandatory for replacement work:** before returning any `next_tasks`, inspect every existing `FAILED` or `BLOCKED` work Task. If it lacks an active/waiting `resolution` or durable `resolutionClassification` and the proposed batch creates related/sibling work, explicitly cover it with a valid `resolution` on the new recovery Task. A superseded/invalid classification covers only planning validation; preserve the FAILED state and never infer success from the classification. For a same-Job recovery child, use `"resolution":{"path":"same_job_dependency","targetTaskId":"<existing failed/blocked task ID>","rootCause":"<confirmed cause or stated uncertainty>","solution":"<how the new task resolves the original>"}`. `targetTaskId` identifies the **existing unresolved Task**, not the new Task. Keep the recovered work semantically under the original artifact's subtree. Do not invent a resolution or silently cancel unrelated failed work.
 - **On `retry_feedback`:** treat the feedback as Relay's authoritative validation error for the previous output in this **same Plan**. Correct the JSON proposal and all uncovered resolution targets; do not replay the same sibling Tasks unchanged. Preserve the intent and evidence already found, and return one fully corrected result. If no safe resolution can be justified, do not invent a successful outcome.
 
+### Forced failed-history cleanup
+
+When `force_clean_history` is true, inspect every ID in `clean_history_task_ids` against the authoritative Task records and dependency/evidence context before planning. Do not infer a result from text alone. For a failed review that is demonstrably stale, run the existing guarded `agents-relay task cancel` command. For a failed work Task with evidence that replacement work covers it, run the existing guarded `agents-relay task classify --classification superseded`; for proven invalid work, use `--classification invalid`. Supply a different durable `--target-task-id`, and the same concrete `--evidence` and `--reason` in your report. Use the normal repository, PR, and Job options from this invocation. Never change task state directly or claim an action succeeded unless the CLI command succeeds and a fresh `task show` confirms it.
+
+If evidence is absent or execution outcome is unknown, leave the Task unresolved and do not classify it, cancel ordinary failed work, or claim success. Do not create related replacement work for an unresolved failure. After all selected guarded commands succeed, refresh authoritative Task state and submit the Plan through the standard `plan apply` command. Include exactly one `history_cleanup` entry for each `clean_history_task_ids` item: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. For unresolved items, state what evidence is missing. Relay validates that reported mutations match durable SQLite state; an ordinary text response is never a Plan receipt.
+
 - Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.
 - When a Task depends on mutable repository or product state, distinguish a frozen evidence target from the current execution head. A SHA may freeze that Task's own review/source evidence, but do not copy an upstream SHA into a dependent release, deploy, publication, or other follow-on Task unless the objective explicitly requires that same frozen target. After dependencies complete, downstream Tasks must resolve and verify the current durable Job/PR head before acting.
 - When fresh UI, browser, store, runtime, or visual evidence is material to the Task outcome, say so explicitly in the Task input and require evidence from the real current state. Existing screenshots, prepared assets, or prior observations are not substitutes for fresh evidence unless the objective explicitly allows reuse.
@@ -117,7 +123,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 
 ## Output
 
-Return exactly one JSON object with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`.
+Return exactly one JSON object with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`. In forced cleanup mode, also return required `history_cleanup` as specified above.
 
 For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
 

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

@@ -114,6 +114,18 @@ A tag must describe something specific to the Job contract, not Relay lifecycle.
 For the ChatGPT Browser Worker guardian, for example, the Job defines `pass -> ✅` and `fail -> ❌`; each hourly E2E child Task reports `data.tag` after running the fixed deterministic E2E, while the Task lifecycle independently records whether Relay execution itself completed, failed, or became blocked.
 
 
+### Task resolution classifications
+
+`Task.resolutionClassification` is durable diagnostic metadata, separate from
+`Task.state` and the recovery `Task.resolution` path. The canonical Task
+Resolution Graph and `task classify` CLI action may classify a known FAILED
+work Task as `superseded` or `invalid`; each record requires a different
+durable target Task, evidence, and reason. Classification never changes the
+FAILED lifecycle state, execution history, or result and never proves success.
+Unknown outcomes, active executions, and Tasks with active recovery ownership
+cannot be classified. Planners must preserve these fields in their assessment
+and may treat classified history as covered when validating a fresh Plan.
+
 ### Optional Review Chair Tasks
 
 Projects may use the shared `review-chair` agent as a normal Task or Agent

package/workflow/task-resolution.mmd

@@ -23,6 +23,12 @@ fresh["guard: freshRecoveryExecution"]
 blocker["guard: blockerJobDependency"]
 gate["guard: escalationGate"]
 obsoleteGuard["guard: genuinelyObsolete"]
+classifiable["guard: classifiableFailure"]
+classificationKind["guard: classificationSuperseded"]
+classifySuperseded["action: resolution.classifySuperseded"]
+classifyInvalid["action: resolution.classifyInvalid"]
+supersededEvidence["guard: supersededEvidenceComplete"]
+invalidEvidence["guard: invalidEvidenceComplete"]
 
 unresolved -->|on: resolution.propose| checkOwner
 checkOwner -->|on: resolution.propose| recoveryOwner
@@ -49,3 +55,12 @@ sameJob -->|to: resolved| resolved
 blockerJob -->|to: resolved| resolved
 escalate -->|to: resolved| resolved
 obsolete -->|to: resolved| resolved
+unresolved -->|on: resolution.classify| classifiable
+classifiable -->|true| classificationKind
+classifiable -->|false| rejected
+classificationKind -->|true| supersededEvidence
+classificationKind -->|false| invalidEvidence
+supersededEvidence -->|true| classifySuperseded
+invalidEvidence -->|true| classifyInvalid
+classifySuperseded --> resolved
+classifyInvalid --> resolved