agents-relay 2.0.156 → 2.0.158

package/dist/workflow/contracts.js

@@ -12,6 +12,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'hold',
     'lease.expired',
     'implementation.completed',
+    'interactive.waiting',
     'local.completed',
     'local.merge.requested',
     'effect.deliverLocalMerge.failed',
@@ -38,6 +39,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'task.progress',
     'task.started',
     'task.unblocked',
+    'interactive.waiting',
     'watchdog.failed',
     'worker.delivery_failed',
     'worker.start_ack_failed',
@@ -70,6 +72,7 @@ export const WORKFLOW_MUTATION_NAMES = [
     'mutation.clearExecution',
     'mutation.markLeaseExpired',
     'mutation.markStartupOrphanedExhausted',
+    'mutation.markUnknownOutcome',
     'mutation.markPlannerUnavailable',
     'mutation.preparePlatformFallback',
     'mutation.quarantinePlatformFailure',

package/dist/workflow/definitions-v2.js

@@ -5,7 +5,7 @@ import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES, }
 const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
 const JOB_STATES = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'];
 const conditionRegistry = new ConditionRegistry([
-    ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'retryAvailable', 'autonomousJob', 'platformFallbackSafe', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady'])
+    ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'troubleshooterTask', 'awaitingInteractiveDecision', 'retryAvailable', 'autonomousJob', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady'])
 ].map(booleanCondition));
 const boolGuard = (name) => conditionRegistry.guard(name);
 export const lifecycleConditions = conditionRegistry;
@@ -31,9 +31,10 @@ export const taskLifecycleV2 = load('task-lifecycle', TASK_STATES, {
     dispatchable: boolGuard('dispatchable'),
     recoverableExecution: boolGuard('recoverableExecution'),
     troubleshooterRecovery: boolGuard('troubleshooterRecovery'),
+    troubleshooterTask: boolGuard('troubleshooterTask'),
+    awaitingInteractiveDecision: facts => facts.durableFacts.awaitingInteractiveDecision === true,
     retryAvailable: boolGuard('retryAvailable'),
     autonomousJob: boolGuard('autonomousJob'),
-    platformFallbackSafe: boolGuard('platformFallbackSafe'),
 });
 export const jobLifecycleV2 = load('job-lifecycle', JOB_STATES, {
     notMerged: boolGuard('notMerged'),

package/dist/workflow/lifecycle.js

@@ -26,7 +26,7 @@ function v2WorkflowDecision(runtime, from, event, facts = {}) {
     };
 }
 export function decideTaskLifecycle(task, event, facts = {}) {
-    return v2WorkflowDecision(taskLifecycleV2, task.state, event, facts);
+    return v2WorkflowDecision(taskLifecycleV2, task.state, event, { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' });
 }
 export function decideJobLifecycle(job, event, facts = {}) {
     return v2WorkflowDecision(jobLifecycleV2, job.state, event, facts);
@@ -36,9 +36,9 @@ export function dispatchTaskLifecycleSync(task, event, facts = {}) {
     const result = dispatchWorkflowGraphSync(taskLifecycleV2, {
         initialState: task.state,
         input: { transport: 'event', id: event, payload: {} },
-        durableFacts: facts,
+        durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' },
         graphName: 'task-lifecycle',
-        persistTransition: (_source, target) => applyTaskGraphTarget(task, target),
+        persistTransition: (_source, target) => applyTaskGraphTarget(task, target, new Date().toISOString(), event === 'task.unblocked' && task.agentName === 'troubleshooter'),
         executeAction: actionId => { actions.push(actionId); if (actionId.startsWith('mutation.'))
             applyTaskMutation(task, actionId); return {}; },
     });
@@ -49,9 +49,9 @@ export function dispatchTaskLifecycleSync(task, event, facts = {}) {
 export async function dispatchTaskLifecycle(task, event, facts = {}, executeEffect, persist) {
     const actions = [];
     const result = await dispatchWorkflowGraph(taskLifecycleV2, {
-        initialState: task.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: facts,
+        initialState: task.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' },
         graphName: 'task-lifecycle',
-        persistTransition: async (_source, target) => { applyTaskGraphTarget(task, target); await persist?.(); },
+        persistTransition: async (_source, target) => { applyTaskGraphTarget(task, target, new Date().toISOString(), event === 'task.unblocked' && task.agentName === 'troubleshooter'); await persist?.(); },
         executeAction: async (actionId) => {
             actions.push(actionId);
             if (actionId.startsWith('mutation.'))

package/dist/workflow/orchestrator-rescue.js

@@ -7,7 +7,7 @@ export const STALE_ORCHESTRATOR_TASK_MS = 30 * 60 * 1000;
 const source = readFileSync(new URL('../../workflow/orchestrator-rescue.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const orchestratorRescueV2 = new GraphRuntime(source, {
-    states: new Set(['idle', 'check', 'external_completed', 'blocked', 'skip', 'rescued']),
+    states: new Set(['idle', 'check', 'external_completed', 'failed', 'skip', 'rescued']),
     guards: {
         legacyActive: boolGuard('legacyActive'),
         verifiedExternalCompletion: boolGuard('verifiedExternalCompletion'),
@@ -16,7 +16,7 @@ export const orchestratorRescueV2 = new GraphRuntime(source, {
     },
     actions: {
         'task.applyExternalCompletion': { id: 'task.applyExternalCompletion' },
-        'task.blockLegacyOrchestrator': { id: 'task.blockLegacyOrchestrator' },
+        'task.failLegacyOrchestrator': { id: 'task.failLegacyOrchestrator' },
         'task.rescueOrchestrator': { id: 'task.rescueOrchestrator' },
     },
     events: { 'orchestrator.rescue.reconcile': { id: 'orchestrator.rescue.reconcile' } },
@@ -46,9 +46,9 @@ export function prepareOrchestratorRepair(task, now) {
     const decision = decideOrchestratorRescue(task, now);
     const externallyCompleted = decision.accepted
         && decision.actions.some(action => action.id === 'task.applyExternalCompletion');
-    const blocked = decision.accepted
-        && decision.actions.some(action => action.id === 'task.blockLegacyOrchestrator');
-    const rescued = externallyCompleted || blocked
+    const failed = decision.accepted
+        && decision.actions.some(action => action.id === 'task.failLegacyOrchestrator');
+    const rescued = externallyCompleted || failed
         || (decision.accepted && decision.actions.some(action => action.id === 'task.rescueOrchestrator'));
     const ageMs = now - Date.parse(task.createdAt);
     if (decision.accepted && externallyCompleted) {
@@ -58,19 +58,20 @@ export function prepareOrchestratorRepair(task, now) {
         task.executionId = null;
         task.threadId = null;
         task.updatedAt = new Date(now).toISOString();
-        return { repaired: true, externallyCompleted: true, blocked: false, ageMs };
+        return { repaired: true, externallyCompleted: true, failed: false, ageMs };
     }
     if (!rescued)
-        return { repaired: false, externallyCompleted: false, blocked: false, ageMs };
-    if (blocked) {
-        tryTransitionTaskEvent(task, 'task.blocked');
-        task.error = 'Legacy orchestrator execution outcome is unknown; automatic replay is unsafe. Verify external effects and create replacement validation/recovery work before unblocking.';
+        return { repaired: false, externallyCompleted: false, failed: false, ageMs };
+    if (failed) {
+        tryTransitionTaskEvent(task, 'task.failed');
+        task.error = 'Legacy orchestrator execution outcome is unknown; Troubleshooter diagnosis is required before retry.';
+        task.failureReason = 'worker_outcome_unknown';
         task.leaseOwner = null;
         task.leaseExpiresAt = null;
         task.executionId = null;
         task.threadId = null;
         task.updatedAt = new Date(now).toISOString();
-        return { repaired: true, externallyCompleted: false, blocked: true, ageMs };
+        return { repaired: true, externallyCompleted: false, failed: true, ageMs };
     }
     task.adapter = 'codex';
     task.workerRequirements = { capabilities: [...task.capabilities] };
@@ -82,5 +83,5 @@ export function prepareOrchestratorRepair(task, now) {
     task.threadId = null;
     task.timeoutMs = taskOverallTimeoutMs(task.storySize ?? 'M');
     task.updatedAt = new Date(now).toISOString();
-    return { repaired: true, externallyCompleted: false, blocked: false, ageMs };
+    return { repaired: true, externallyCompleted: false, failed: false, ageMs };
 }

package/dist/workflow/runtime.js

@@ -32,6 +32,10 @@ export function applyTaskMutation(task, mutation) {
         task.error = 'Lease expired after maximum attempts';
     if (mutation === 'mutation.markStartupOrphanedExhausted')
         task.error = 'Orphaned after relayd restart after maximum attempts';
+    if (mutation === 'mutation.markUnknownOutcome') {
+        task.error = 'Worker execution outcome is unknown; Troubleshooter diagnosis is required before retry.';
+        task.failureReason = 'worker_outcome_unknown';
+    }
     if (mutation === 'mutation.markPlannerUnavailable')
         task.error = 'No objective planner configured';
     if (mutation === 'mutation.preparePlatformFallback') {
@@ -49,10 +53,17 @@ export function applyTaskMutation(task, mutation) {
         task.leaseOwner = null;
         task.leaseExpiresAt = null;
         task.executionId = null;
-        task.failureReason = task.platformFailure?.safeToReroute ? 'worker_platform_fallback_unavailable' : 'worker_outcome_unknown';
+        task.failureReason = ['outcome_unknown', 'start_ack_timeout'].includes(task.platformFailure?.classification ?? '')
+            ? 'worker_outcome_unknown' : 'worker_platform_failure';
     }
 }
-export function applyTaskGraphTarget(task, target, timestamp = new Date().toISOString()) {
+export function applyTaskGraphTarget(task, target, timestamp = new Date().toISOString(), authoritativeUnblock = false) {
+    if (target === 'BLOCKED' && task.agentName !== 'troubleshooter')
+        throw new Error(`Only a Troubleshooter Task may become BLOCKED (${task.id})`);
+    if (task.state === 'BLOCKED' && target === 'QUEUED' && (!authoritativeUnblock || task.agentName !== 'troubleshooter'))
+        throw new Error(`Blocked Task ${task.id} requires an authoritative Troubleshooter unblock before transition`);
+    if (task.state === 'BLOCKED' && target !== 'QUEUED' && target !== 'CANCELLED' && target !== 'BLOCKED')
+        throw new Error(`Blocked Task ${task.id} requires an authoritative Troubleshooter unblock before transition`);
     const previous = Date.parse(task.updatedAt), candidate = Date.parse(timestamp);
     task.state = target;
     task.updatedAt = Number.isFinite(previous)

package/dist/workflow/task-resolution.js

@@ -7,23 +7,53 @@ 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', 'resolved']),
+    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))
         throw new Error(`Unknown task resolution path ${proposal.path}`);
     if (proposal.path === 'exact_original_retry' && original.state !== 'FAILED')
         throw new Error('Exact-original retry requires a FAILED original Task');
-    if (proposal.path === 'same_job_dependency' && (!proposal.targetTaskId || !job.tasks.some(task => task.id === proposal.targetTaskId && task.jobId === job.id)))
-        throw new Error('Same-Job dependency resolution requires an existing target Task in the same Job');
+    if (proposal.path === 'same_job_dependency' && (!proposal.targetTaskId || proposal.targetTaskId === original.id || !job.tasks.some(task => task.id === proposal.targetTaskId && task.jobId === job.id && !['SUCCEEDED', 'CANCELLED'].includes(task.state))))
+        throw new Error('Same-Job dependency resolution requires an existing unresolved target Task in the same Job');
     if (proposal.path === 'blocker_job_dependency' && (!proposal.targetJobId || !proposal.mode))
         throw new Error('Blocker-Job dependency resolution requires targetJobId and merge or verified mode');
     if (proposal.path === 'escalation_gate' && (!proposal.rootCause || !proposal.solution))
@@ -32,10 +62,15 @@ export function validateResolutionProposal(job, original, proposal) {
         throw new Error('Cancellation/supersession requires an explicit obsolescence rootCause');
 }
 export function resolutionFacts(task, proposal, owner) {
-    return { recoveryOwnerAvailable: owner === 'troubleshooter', plannerOwnerAvailable: owner !== null && owner !== 'troubleshooter', exactOriginalRetry: proposal.path === 'exact_original_retry', sameJobDependency: proposal.path === 'same_job_dependency', blockerJobDependency: proposal.path === 'blocker_job_dependency', escalationGate: proposal.path === 'escalation_gate', genuinelyObsolete: proposal.path === 'cancel_supersede', unresolved: unresolvedTask(task) };
+    const freshRecoveryExecution = owner !== 'troubleshooter' || proposal.path !== 'exact_original_retry' || (Boolean(proposal.recoveryExecutionId)
+        && proposal.recoveryExecutionId !== task.resolution?.recoveryExecutionId);
+    return { recoveryOwnerAvailable: owner === 'troubleshooter', plannerOwnerAvailable: owner !== null && owner !== 'troubleshooter', exactOriginalRetry: proposal.path === 'exact_original_retry' && task.state === 'FAILED', sameJobDependency: proposal.path === 'same_job_dependency' && owner !== null && proposal.targetTaskId !== task.id, blockerJobDependency: proposal.path === 'blocker_job_dependency' && owner !== null && Boolean(proposal.targetJobId && proposal.mode), escalationGate: proposal.path === 'escalation_gate' && owner === 'troubleshooter' && Boolean(proposal.rootCause && proposal.solution), genuinelyObsolete: proposal.path === 'cancel_supersede' && Boolean(proposal.rootCause), freshRecoveryExecution, unresolved: unresolvedTask(task) };
 }
 export function decideTaskResolution(task, proposal, owner) {
-    return dispatchWorkflowGraphSync(taskResolutionV2, { initialState: 'unresolved', input: { transport: 'event', id: 'resolution.propose', payload: proposal }, durableFacts: resolutionFacts(task, proposal, owner), graphName: 'task-resolution', isTransientState: state => state === 'check_owner' || state === 'check_path', maxSteps: 4 });
+    return checkedResolutionDecision(dispatchWorkflowGraphSync(taskResolutionV2, { initialState: 'unresolved', input: { transport: 'event', id: 'resolution.propose', payload: proposal }, durableFacts: resolutionFacts(task, proposal, owner), graphName: 'task-resolution', isTransientState: state => ['check_owner', 'check_path', 'check_fresh_execution'].includes(state), maxSteps: 8 }));
+}
+function checkedResolutionDecision(decision) {
+    return decision.accepted && decision.target === 'rejected' ? { ...decision, accepted: false, reason: 'no_transition' } : decision;
 }
 export function dispatchTaskResolutionSync(task, proposal, owner, effects) {
     const handlers = {
@@ -45,13 +80,13 @@ export function dispatchTaskResolutionSync(task, proposal, owner, effects) {
         'resolution.createEscalationGate': effects.createEscalationGate,
         'resolution.cancelSupersede': effects.cancelSupersede,
     };
-    return dispatchWorkflowGraphSync(taskResolutionV2, {
+    return checkedResolutionDecision(dispatchWorkflowGraphSync(taskResolutionV2, {
         initialState: 'unresolved', input: { transport: 'event', id: 'resolution.propose', payload: proposal },
         durableFacts: resolutionFacts(task, proposal, owner), graphName: 'task-resolution',
-        isTransientState: state => state === 'check_owner' || state === 'check_path', maxSteps: 6,
+        isTransientState: state => ['check_owner', 'check_path', 'check_fresh_execution'].includes(state), maxSteps: 8,
         executeAction: actionId => { const handler = handlers[actionId]; if (!handler)
             throw new Error(`Task resolution effect ${actionId} is unavailable`); handler(); return {}; },
-    });
+    }));
 }
 export async function dispatchTaskResolution(task, proposal, owner, effects) {
     const handlers = {
@@ -61,13 +96,13 @@ export async function dispatchTaskResolution(task, proposal, owner, effects) {
         'resolution.createEscalationGate': effects.createEscalationGate,
         'resolution.cancelSupersede': effects.cancelSupersede,
     };
-    return dispatchWorkflowGraph(taskResolutionV2, {
+    return checkedResolutionDecision(await dispatchWorkflowGraph(taskResolutionV2, {
         initialState: 'unresolved',
         input: { transport: 'event', id: 'resolution.propose', payload: proposal },
         durableFacts: resolutionFacts(task, proposal, owner),
         graphName: 'task-resolution',
-        isTransientState: state => state === 'check_owner' || state === 'check_path',
-        maxSteps: 6,
+        isTransientState: state => ['check_owner', 'check_path', 'check_fresh_execution'].includes(state),
+        maxSteps: 8,
         executeAction: async (actionId) => {
             const handler = handlers[actionId];
             if (!handler)
@@ -75,7 +110,7 @@ export async function dispatchTaskResolution(task, proposal, owner, effects) {
             await handler();
             return {};
         },
-    });
+    }));
 }
 export function materializeResolution(task, proposal, owner, now = new Date().toISOString()) {
     return { ...proposal, state: proposal.path === 'escalation_gate' || proposal.path === 'blocker_job_dependency' ? 'waiting' : 'active', owner, updatedAt: now };
@@ -100,5 +135,7 @@ export function attachResolutionOwnership(job, child, proposal, owner) {
     return original;
 }
 export function claimExactOriginalRecovery(original, recovery) {
-    original.resolution = materializeResolution(original, { path: 'exact_original_retry', targetTaskId: original.id, rootCause: original.failureReason ?? original.error ?? 'durable failure', solution: `Troubleshooter ${recovery.id} diagnosis and exact-original recovery` }, 'troubleshooter');
+    if (!recovery.executionId)
+        throw new Error(`Troubleshooter ${recovery.id} has no current execution for a fresh resolution`);
+    original.resolution = materializeResolution(original, { path: 'exact_original_retry', targetTaskId: original.id, recoveryExecutionId: recovery.executionId, rootCause: original.failureReason ?? original.error ?? 'durable failure', solution: `Troubleshooter ${recovery.id} diagnosis and exact-original recovery` }, 'troubleshooter');
 }

package/dist/workflow/troubleshooter-v2.js

@@ -4,7 +4,7 @@ import { dispatchWorkflowGraphSync } from './dispatcher.js';
 const source = readFileSync(new URL('../../workflow/troubleshooter.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const troubleshooterV2 = new GraphRuntime(source, {
-    states: new Set(['idle', 'check_ordinary', 'check_run', 'check_needs', 'check_id', 'check_barrier', 'skip', 'create']),
+    states: new Set(['idle', 'check_ordinary', 'check_run', 'check_needs', 'check_id', 'check_barrier', 'skip', 'create', 'resumed_after_authoritative_unblock', 'fresh_resolution_proposed', 'remain_failed_without_original_mutation']),
     guards: {
         failedWork: boolGuard('failedWork'),
         ordinaryWork: boolGuard('ordinaryWork'),
@@ -12,9 +12,11 @@ export const troubleshooterV2 = new GraphRuntime(source, {
         needsRecovery: boolGuard('needsRecovery'),
         idUnused: boolGuard('idUnused'),
         noRecoveryBarrier: boolGuard('noRecoveryBarrier'),
+        freshConditionVerification: boolGuard('freshConditionVerification'),
+        resolutionForCurrentExecution: boolGuard('resolutionForCurrentExecution'),
     },
-    actions: { 'troubleshooter.create': { id: 'troubleshooter.create' } },
-    events: { 'troubleshooter.reconcile': { id: 'troubleshooter.reconcile' } },
+    actions: { 'troubleshooter.create': { id: 'troubleshooter.create' }, 'troubleshooter.proposeFreshResolution': { id: 'troubleshooter.proposeFreshResolution' }, 'troubleshooter.applyAuthorizedResolution': { id: 'troubleshooter.applyAuthorizedResolution' } },
+    events: { 'troubleshooter.reconcile': { id: 'troubleshooter.reconcile' }, 'troubleshooter.resumed': { id: 'troubleshooter.resumed' }, 'task.started': { id: 'task.started' }, 'resolution.propose': { id: 'resolution.propose' } },
 });
 export function dispatchTroubleshooter(facts, onCreate) {
     return dispatchWorkflowGraphSync(troubleshooterV2, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.156",
+  "version": "2.0.158",
   "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,7 +96,7 @@ 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.
 
 - Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.

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

@@ -1,6 +1,6 @@
 ---
 name: troubleshooter
-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.
+description: Recover failed Agents Relay tasks by diagnosing execution faults and repairing recoverable causes. Only a Troubleshooter can wait in BLOCKED; after authoritative unblock, the same Troubleshooter reruns and re-verifies before issuing a fresh resolution.
 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 Agents Relay task. Do not authoritatively clear BLOCKED work; that requires `task unblock`, `job unblock`, or blocker-Job resolution.
+You are the recovery orchestrator for a FAILED Agents Relay task. Ordinary Tasks never enter BLOCKED or UNBLOCKED. Only a Troubleshooter can become BLOCKED, and only an authoritative unblock can resume that same Troubleshooter.
 
 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.
 
@@ -33,7 +33,9 @@ Read `skills/agents-relay/troubleshooter-qa.md` for user-editable best practices
    - For a transient failure, verify the transient condition is gone.
    - For task-local failure, make the smallest durable repair in the original Job/PR when that is within scope.
    - For a shared platform/runtime defect, first create or reuse the owning blocker P0/self-job. If it can be completed inside this recovery execution, fix/verify it and retry the original Task. If it cannot be completed now, register the original Task with `agents-relay blocker add` on that blocker Job and finish this Troubleshooter task; do not stay running while waiting for another Job.
-   - For a suspected genuine human/external blocker, do not publish `task.blocked` and do not branch on Neo's result yourself. Invoke `agents-relay escalation` with the original intent, blocker, and relevant context. The canonical graph owns the `resolved`, `failed`, and `needs_user` outcomes. When it returns `needs_user`, call Relay's `task escalate` operation with the concrete required action, resolution condition, and diagnostic context. Relay records the escalation and blocks this Troubleshooter; no worker remains running while waiting.
+   - For a suspected genuine human/external blocker, invoke `agents-relay escalation` with the original intent, blocker, and relevant context. The canonical graph owns the `resolved`, `failed`, and `needs_user` outcomes. When it returns `needs_user`, call Relay's `task escalate` operation with the concrete required action, resolution condition, and diagnostic context. Relay records the escalation and blocks this Troubleshooter; no worker remains running while waiting.
+   - After unblock, this same Troubleshooter must run with a new execution ID, re-check the blocking condition, and produce a fresh resolution bound to that execution. A previously resolved resolution record never authorizes retrying a new attempt.
+   - Unknown worker execution outcomes fail closed. Do not automatically reroute or retry the original task, and do not block the original task; diagnose it through the Troubleshooter.
 7. For an immediate repair, only after the blocker is removed request `agents-relay task recover` with this Troubleshooter's recovery Task ID, then reconcile the original Job. Verify the SQLite postcondition: original Task state QUEUED, expected resolution and recovery correlation. An authorized human response is a Task Comment, not a rewrite of Task input. Retain historical conditions as provenance, independently verify the original failing execution context, and do not submit an identical escalation with no new evidence. Deferred repair uses the durable blocker relation: merge-mode blockers wake dependents after merge; release/deploy/runtime blockers require `--resolution verified` and `agents-relay blocker resolve` only after verification.
 8. Verify durable evidence the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
 9. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.

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

@@ -70,7 +70,7 @@ Keep these concepts distinct: observation is not root cause; hypothesis is not r
 
 ### Job-defined Task tag
 
-`Task.state` is reserved for Relay lifecycle only: `DRAFT`, `QUEUED`, `RUNNING`, `BLOCKED`, `SUCCEEDED`, `FAILED`, and `CANCELLED`. A Job may additionally define one optional `tag` contract for a Job-specific result or classification that should be visible on each Task without changing its lifecycle state.
+`Task.state` is reserved for Relay lifecycle only: `DRAFT`, `QUEUED`, `RUNNING`, `BLOCKED`, `SUCCEEDED`, `FAILED`, and `CANCELLED`. `BLOCKED` is exclusive to Tasks whose `agentName` is exactly `troubleshooter`; ordinary Tasks never enter `BLOCKED` or an `UNBLOCKED` lifecycle state. A Job may additionally define one optional `tag` contract for a Job-specific result or classification that should be visible on each Task without changing its lifecycle state.
 
 The Job owns the meaning of the tag. Its trusted Job marker declares a human-readable `description` explaining what the tag means and when workers should set it, plus the allowed durable values and their dashboard display strings:
 
@@ -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
@@ -164,14 +176,14 @@ forbids it.
 
 ## Dependency vs block and authoritative unblock
 
-`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.
+`dependencies` describe normal DAG ordering. An unmet dependency keeps ordinary work in `DRAFT`; dispatchable work is `QUEUED`. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; Relay releases dependent work when its prerequisites succeed. Worker, platform, semantic, and unknown-outcome failures are `FAILED`. Unknown worker outcome fails closed and never justifies rerouting. Only a Troubleshooter waiting for an authoritative human response may become `BLOCKED`.
 
-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 BLOCKED Troubleshooter cannot be resumed through retry, queue, dashboard state editing, PR push, webhook, ordinary task update, or Troubleshooter inference. The authoritative entry point records the response and transitions that same Troubleshooter `BLOCKED -> QUEUED` through `task.unblocked`. The queued Troubleshooter must execute again, verify the condition from fresh evidence, and issue a fresh resolution before Relay may retry or replan the original FAILED Task. Prior `resolved` metadata never authorizes another attempt. Historical ordinary BLOCKED snapshots migrate to FAILED while their append-only event history remains unchanged; they are never silently converted to success.
 
-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.
+The old `UNBLOCKED` state is compatibility-only input. It normalizes to QUEUED only for Troubleshooter Tasks and to FAILED for ordinary Tasks, pending diagnosis.
 
 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.
+A blocker Job owns reverse `unblocks` references. When it resolves, Relay releases matching dependency-waiting Tasks through their ordinary DRAFT/QUEUED path. It cannot unblock ordinary work or resume a Troubleshooter without the authoritative response flow.
 
-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.
+Automatic Planner creation treats a currently BLOCKED Troubleshooter as a recovery gate. FAILED history alone does not authorize resolution or success; active DRAFT/QUEUED/RUNNING work still prevents a competing planning round.

package/workflow/authoritative-unblock.mmd

@@ -5,15 +5,12 @@ description: Validates authoritative unblock requests and safely resumes blocked
 flowchart LR
 %% relay: initial blocked
 blocked["state: blocked"]
-autonomous["state: autonomous_replan"]
-fixed["state: fixed_retry"]
+queued["state: troubleshooter_queued"]
 
-autonomousJob["guard: autonomousJob"]
-replan["action: unblock.replan"]
+eligible["guard: blockedTroubleshooter"]
 retry["action: unblock.retry"]
 
-blocked -->|on: task.authoritative_unblock| autonomousJob
-autonomousJob -->|true| replan
-replan --> autonomous
-autonomousJob -->|false| retry
-retry --> fixed
+blocked -->|on: task.authoritative_unblock| eligible
+eligible -->|true| retry
+eligible -->|false| blocked
+retry --> queued

package/workflow/blocker-resolution.mmd

@@ -1,6 +1,6 @@
 ---
 title: Blocker Resolution
-description: Resolves blockers through verified recovery evidence and graph-authorized decisions.
+description: Releases dependency-waiting work; failed work and blocked Troubleshooters require their own fresh recovery flow.
 ---
 flowchart LR
 %% relay: initial waiting
@@ -27,12 +27,7 @@ isBlocked["guard: isBlocked"]
 isFailed["guard: isFailed"]
 isUnblocked["guard: isUnblocked"]
 
-autonomousUnblock["action: blocker.autonomousUnblock"]
-acceptExisting["action: blocker.acceptExistingUnblock"]
 releaseDraft["action: blocker.releaseDraft"]
-unblockTask["action: blocker.unblockTask"]
-retryFailed["action: blocker.retryFailed"]
-retryUnblocked["action: blocker.retryUnblocked"]
 
 waiting -->|on: blocker.resolved| resolutionAllowed
 resolutionAllowed -->|false| wait
@@ -47,13 +42,11 @@ autonomousJob -->|true| checkEffective
 autonomousJob -->|false| checkDraft
 
 checkEffective -->|on: blocker.resolved| effectivelyBlocked
-effectivelyBlocked -->|true| autonomousUnblock
-autonomousUnblock --> resumed
+effectivelyBlocked -->|true| wait
 effectivelyBlocked -->|false| checkAlreadyUnblocked
 
 checkAlreadyUnblocked -->|on: blocker.resolved| alreadyUnblocked
-alreadyUnblocked -->|true| acceptExisting
-acceptExisting --> resumed
+alreadyUnblocked -->|true| resumed
 alreadyUnblocked -->|false| checkDraft
 
 checkDraft -->|on: blocker.resolved| isDraft
@@ -62,16 +55,13 @@ releaseDraft --> resumed
 isDraft -->|false| checkBlocked
 
 checkBlocked -->|on: blocker.resolved| isBlocked
-isBlocked -->|true| unblockTask
-unblockTask --> resumed
+isBlocked -->|true| wait
 isBlocked -->|false| checkFailed
 
 checkFailed -->|on: blocker.resolved| isFailed
-isFailed -->|true| retryFailed
-retryFailed --> resumed
+isFailed -->|true| wait
 isFailed -->|false| checkUnblocked
 
 checkUnblocked -->|on: blocker.resolved| isUnblocked
-isUnblocked -->|true| retryUnblocked
-retryUnblocked --> resumed
+isUnblocked -->|true| wait
 isUnblocked -->|false| obsolete

package/workflow/orchestrator-rescue.mmd

@@ -7,7 +7,7 @@ flowchart LR
 idle["state: idle"]
 check["state: check"]
 external["state: external_completed"]
-blocked["state: blocked"]
+failed["state: failed"]
 skip["state: skip"]
 rescued["state: rescued"]
 legacyActive["guard: legacyActive"]
@@ -16,7 +16,7 @@ unknownStartedOutcome["guard: unknownStartedOutcome"]
 rescuable["guard: rescuable"]
 rescue["action: task.rescueOrchestrator"]
 externalCompletion["action: task.applyExternalCompletion"]
-quarantine["action: task.blockLegacyOrchestrator"]
+quarantine["action: task.failLegacyOrchestrator"]
 idle -->|on: orchestrator.rescue.reconcile| check
 check -->|on: orchestrator.rescue.reconcile| legacyActive
 legacyActive -->|false| skip
@@ -25,7 +25,7 @@ verifiedExternalCompletion -->|true| externalCompletion
 externalCompletion -->|to: external_completed| external
 verifiedExternalCompletion -->|false| unknownStartedOutcome
 unknownStartedOutcome -->|true| quarantine
-quarantine -->|to: blocked| blocked
+quarantine -->|to: failed| failed
 unknownStartedOutcome -->|false| rescuable
 rescuable -->|false| skip
 rescuable -->|true| rescue