agents-relay 2.0.150 → 2.0.151

package/dist/local-git-merge.js

@@ -24,10 +24,21 @@ export function localSourceHead(repoPath, sourceRef) {
 export function requiresLocalGitMerge(job) {
     return Boolean(job.localMerge) || job.tasks.some(task => task.output?.kind === 'task_pr');
 }
-export function localMergeEligible(job) {
-    return job.state === 'ACTIVE' && job.autoMerge !== false && !job.schedule &&
-        implementationComplete(job) && completionGateSatisfied(job) &&
-        (job.reviewEnabled === false || job.review?.outcome === 'approved');
+export function localMergeFacts(job, headSha, now = Date.now) {
+    return {
+        jobActive: job.state === 'ACTIVE',
+        autoMergeEnabled: job.autoMerge !== false,
+        schedulePresent: Boolean(job.schedule),
+        implementationComplete: implementationComplete(job),
+        completionGateSatisfied: completionGateSatisfied(job),
+        reviewSatisfied: job.reviewEnabled === false || job.review?.outcome === 'approved',
+        localMergeRequired: requiresLocalGitMerge(job),
+        localMergeSucceeded: job.localMerge?.status === 'succeeded',
+        localMergePresent: Boolean(job.localMerge),
+        reviewHeadCurrent: job.reviewEnabled === false || job.review?.headSha === headSha,
+        mergeAttemptReady: Boolean(job.localMerge && job.localMerge.status !== 'succeeded'
+            && (!job.localMerge.nextAttemptAt || Date.parse(job.localMerge.nextAttemptAt) <= now())),
+    };
 }
 export function localMergeCommitMessage(request, sourceSha) {
     const lines = ['Agents Relay local merge', '', `Agents-Relay-Source-SHA: ${sourceSha}`];

package/dist/local-merge-delivery.js

@@ -1,22 +1,25 @@
 import { createHash } from 'node:crypto';
 import { eventFor } from './events.js';
 import { transitionJobEvent } from './scheduler.js';
-import { deliverLocalMerge, localMergeEligible, requiresLocalGitMerge } from './local-git-merge.js';
+import { deliverLocalMerge, localMergeFacts } from './local-git-merge.js';
 import { errorMessage } from './observability.js';
+import { decideJobLifecycle } from './workflow/lifecycle.js';
 /** Graph-selected durable local merge and completion; no checked-out worktree is ever changed. */
 export async function reconcileLocalGitCompletion(store, finalState, headSha, noGitHub, projectPathForJob, emit, mergeEffect = deliverLocalMerge, now = Date.now) {
-    if (localMergeEligible(finalState) && !requiresLocalGitMerge(finalState)) {
-        await transitionJobEvent(finalState, 'local.completed', { localCompletionAllowed: true });
+    const facts = localMergeFacts(finalState, headSha, now);
+    if (decideJobLifecycle(finalState, 'local.completed', facts).target === 'COMPLETED') {
+        await transitionJobEvent(finalState, 'local.completed', facts);
         await store.saveJob(finalState);
         return true;
     }
-    if (localMergeEligible(finalState) &&
-        finalState.localMerge && (!finalState.reviewEnabled || finalState.review?.headSha === headSha)) {
+    if (decideJobLifecycle(finalState, 'local.merge.requested', facts).actions.includes('effect.deliverLocalMerge')) {
         const receipt = finalState.localMerge;
+        if (!receipt)
+            return false;
         let activeReceipt = receipt;
         if (receipt.status !== 'succeeded' &&
             (!receipt.nextAttemptAt || Date.parse(receipt.nextAttemptAt) <= now())) {
-            await transitionJobEvent(finalState, 'local.merge.requested', { localMergeReady: true }, async (actionId) => {
+            await transitionJobEvent(finalState, 'local.merge.requested', facts, async (actionId) => {
                 if (actionId !== 'effect.deliverLocalMerge')
                     throw new Error('Unsupported local merge Graph effect ' + actionId);
                 try {
@@ -75,7 +78,8 @@ export async function reconcileLocalGitCompletion(store, finalState, headSha, no
             });
         }
         if (finalState.localMerge?.status === 'succeeded') {
-            await transitionJobEvent(finalState, 'local.completed', { localCompletionAllowed: true });
+            const completionFacts = localMergeFacts(finalState, headSha, now);
+            await transitionJobEvent(finalState, 'local.completed', completionFacts);
             await store.saveJob(finalState);
             return true;
         }

package/dist/managed-worker-input.js

@@ -4,6 +4,7 @@ import { agentGraphPrompt } from './agent-graph.js';
 import { createReviewChairExecutionPlan } from './review-chair.js';
 import { taskTagWorkerPrompt } from './task-tag.js';
 import { executionEventSource } from './reconciler-runtime.js';
+import { taskAgentHistoryContext } from './task-context.js';
 export async function managedWorkerInput(job, task, context, mode = 'production') {
     const isLocalJob = Boolean(job.localMerge?.sourceRef);
     const projectedReview = isLocalJob && task.agentName === 'reviewer' && job.prNumber > 0;
@@ -53,7 +54,7 @@ ${interactiveContext}Task attempt/execution: ${task.attempt}/${task.maxAttempts}
 Dependencies: ${task.dependencies.length ? task.dependencies.join(', ') : 'none'}
 ${task.attempt > 1 || task.error ? `Retry summary: prior error=${task.error ?? 'none'}; prior generations=${(task.executionHistory ?? []).map(item => `${item.id}@${item.attempt}`).join(', ') || 'none'}` : 'Retry summary: first attempt'}
 SQLite/RelayStore and the canonical Mermaid Graphs own lifecycle, merge, recovery, and completion decisions. Do not perform Relay-owned merge or completion actions from this worker.
-${chairPlan ? `[Review Chair execution plan]\n${JSON.stringify(chairPlan, null, 2)}\n\nUse this runtime-discovered panel to create sibling durable specialist Tasks. Preserve each specialistTasks entry as review metadata, keep the target immutable, and synthesize structured results with synthesizeReview semantics before returning the unified revision plan.\n\n` : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
+${taskAgentHistoryContext(job, task)}\n\n${chairPlan ? `[Review Chair execution plan]\n${JSON.stringify(chairPlan, null, 2)}\n\nUse this runtime-discovered panel to create sibling durable specialist Tasks. Preserve each specialistTasks entry as review metadata, keep the target immutable, and synthesize structured results with synthesizeReview semantics before returning the unified revision plan.\n\n` : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
 [Output contract]
 ${output}
 ${taskTag}${mode === 'evaluation' ? `[Isolated prompt evaluation mode]

package/dist/pool.js

@@ -8,7 +8,7 @@ import { jobHasActiveExecution } from './job-execution-slot.js';
 import { unblockNeedsNewPlan } from './unblock.js';
 const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareJobPriority(a, b) { return RANK[a.priority ?? 'P2'] - RANK[b.priority ?? 'P2'] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
-export function runnableManagedJobs(items) { return items.filter(item => item.job.state === 'ACTIVE').map(item => item.job).sort(compareJobPriority); }
+export function runnableManagedJobs(items) { return items.filter(item => item.job.state === 'ACTIVE' || item.job.projectionRecovery?.status === 'repairing').map(item => item.job).sort(compareJobPriority); }
 export function needsLifecycleReconciliation(job, now = Date.now()) {
     if (job.pause)
         return job.tasks.some(task => Boolean(task.pausedExecution)) || Boolean(job.plans?.some(plan => Boolean(plan.pausedExecutionId)));

package/dist/projected-store.js

@@ -95,7 +95,7 @@ export class GitHubProjectionWriter {
         let deferred = 0;
         for (const item of items) {
             try {
-                if (this.externalOnly && !['merge_pull_request', 'close_pull_request', 'update_pr_body', 'create_pull_request'].includes(item.operation)) {
+                if (this.externalOnly && !['merge_pull_request', 'close_pull_request', 'update_pr_body', 'create_pull_request', 'append_task_comment'].includes(item.operation)) {
                     // Drop legacy lifecycle projections; GitHub may not override SQLite truth.
                     await this.relay.completeProjection(item.id);
                     continue;
@@ -182,6 +182,11 @@ export class GitHubProjectionWriter {
             case 'save_task':
                 await this.github.saveTask(payload.value);
                 return;
+            case 'append_task_comment':
+                if (!this.github.appendTaskHistoryComment)
+                    throw new Error('GitHub projection target cannot append Task history comments');
+                await this.github.appendTaskHistoryComment(payload.value);
+                return;
             case 'save_agent':
                 await this.github.saveAgent(payload.value);
                 return;

package/dist/projection-failure-recovery.js

@@ -0,0 +1,52 @@
+import { eventFor } from './events.js';
+import { beginProjectionRecovery } from './projection-recovery.js';
+import { reconcileProjectionRecovery } from './projection-recovery-runtime.js';
+import { SQLiteRelayStore } from './relay-store.js';
+import { classifyFailure, errorMessage, observability } from './observability.js';
+import { resolveManagedProjectPath } from './workspace.js';
+export async function reconcileBindingProjectionRecovery(job, store, options) {
+    const recovery = await reconcileProjectionRecovery(job, store, options);
+    if (recovery && recovery.state === 'escalated')
+        return { skip: true };
+    if (recovery && !['retry', 'projected'].includes(recovery.state))
+        return { skip: true };
+    if (recovery?.state === 'retry' && !recovery.projectedMerge)
+        return { skip: true };
+    return { skip: false, projectedMerge: recovery?.projectedMerge };
+}
+export async function projectBindingLocalMerge(job, store, options) {
+    const recovery = await reconcileBindingProjectionRecovery(job, store, options);
+    if (recovery.skip)
+        return recovery;
+    return { skip: false, projectedMerge: recovery.projectedMerge ?? await options.project(job) };
+}
+export async function handleGitHubProjectionFailure(error, job, snapshotPath, options) {
+    const reason = errorMessage(error), classification = classifyFailure(error).classification;
+    if (job.state === 'COMPLETED' && job.localMerge?.status === 'succeeded') {
+        const recoveryStore = options.relayStores.get(`${snapshotPath}#${job.id}`)
+            ?? new SQLiteRelayStore(snapshotPath, job.id);
+        options.relayStores.set(`${snapshotPath}#${job.id}`, recoveryStore);
+        const recoveryPath = options.repositoryPaths.get(job.repository)
+            ?? await resolveManagedProjectPath(job.repository, options.explicitProjectPath, options.workspaceRoot);
+        const remoteSha = await options.gitText(recoveryPath, ['fetch', '--no-tags', 'origin', '+refs/heads/main:refs/remotes/origin/main'])
+            .then(() => options.gitText(recoveryPath, ['rev-parse', '--verify', 'refs/remotes/origin/main']))
+            .catch(() => '');
+        const recovery = await beginProjectionRecovery(recoveryStore, job.id, remoteSha, reason);
+        if (recovery === 'created') {
+            await options.reconcileLocalJob(job.id, 'projection.delivery_failed');
+            await options.eventBus?.publish(eventFor(job.id, 'projection', null, 'projection.recovery_requested', 'queued', `Projection recovery task created for origin/main ${remoteSha}`, 'orchestrator', { remoteSha, idempotencyKey: `${job.id}:${remoteSha}` }, { agent: 'relay', component: 'projection-conflict' })).catch(() => { });
+        }
+        else if (recovery === 'escalated') {
+            await options.eventBus?.publish(eventFor(job.id, 'projection', null, 'projection.recovery_escalated', 'failed', 'Projection recovery exhausted its bounded task retry budget', 'user', { idempotencyKey: `${job.id}:${remoteSha}` }, { agent: 'relay', component: 'projection-conflict' })).catch(() => { });
+        }
+    }
+    if (!options.deduplicator.shouldReport(job.id, job.updatedAt, reason, classification))
+        return;
+    await options.eventBus?.publish(eventFor(job.id, 'projection', null, 'projection.delivery_failed', 'failed', `GitHub projection failed: ${errorMessage(error)}`, 'orchestrator', { operation: 'github.projectLocalMerge', error: reason }, { agent: 'relay', component: 'github-projection' }))?.catch(() => { });
+    observability().record({
+        stage: 'projection', event: 'github.binding_job_failed', level: 'warn', outcome: 'failed',
+        message: `GitHub binding/projection failed for ${job.id}: ${reason}`,
+        correlation: { repository: job.repository, prNumber: job.prNumber, jobId: job.id },
+        data: { classification, reason },
+    });
+}

package/dist/projection-recovery-runtime.js

@@ -0,0 +1,121 @@
+import { eventFor } from './events.js';
+import { deliverLocalMerge, localSourceHead } from './local-git-merge.js';
+import { dispatchWorkflowGraph } from './workflow/dispatcher.js';
+import { projectionConflictV2 } from './workflow/projection-conflict-v2.js';
+/** Executes only the retry or escalation selected by the projection-conflict graph. */
+export async function reconcileProjectionRecovery(job, store, options) {
+    const recovery = job.projectionRecovery;
+    if (!recovery)
+        return null;
+    if (recovery.status === 'projected' || recovery.status === 'escalated')
+        return { state: recovery.status };
+    const repair = job.tasks.find(task => task.id === recovery.taskId);
+    const reviewTask = job.review?.taskId ? job.tasks.find(task => task.id === job.review?.taskId) : undefined;
+    const expectedReviewTaskId = job.review?.taskId;
+    const expectedReviewOutcome = job.review?.outcome;
+    const expectedReviewHeadSha = job.review?.headSha;
+    let projectedMerge;
+    let claimed = false;
+    let escalated = false;
+    let projectionCompleted = false;
+    const decision = await dispatchWorkflowGraph(projectionConflictV2, {
+        initialState: recovery.status, input: { transport: 'event', id: 'reconcile', payload: {} },
+        durableFacts: {
+            repairTaskState: repair?.state,
+            reviewTaskState: reviewTask?.state,
+            reviewOutcome: job.review?.outcome,
+            taskRetryAvailable: repair?.state !== 'FAILED',
+            attempts: recovery.attempts,
+            maxAttempts: recovery.maxAttempts,
+        }, graphName: 'projection-conflict', maxSteps: 1,
+        persistTransition: async (source, target) => {
+            if (target === 'retry') {
+                if (!store.mutateJob)
+                    throw new Error('Atomic SQLite mutation is required for projection recovery attempts');
+                await store.mutateJob(job.id, current => {
+                    const currentRecovery = current.projectionRecovery;
+                    const currentRepair = current.tasks.find(task => task.id === currentRecovery?.taskId);
+                    const currentReviewTask = current.review?.taskId
+                        ? current.tasks.find(task => task.id === current.review?.taskId) : undefined;
+                    if (current.state !== 'COMPLETED' || currentRecovery?.key !== recovery.key
+                        || currentRecovery.taskId !== recovery.taskId || currentRecovery.status !== source
+                        || currentRecovery.attempts !== recovery.attempts || currentRepair?.state !== repair?.state
+                        || currentReviewTask?.id !== expectedReviewTaskId || current.review?.outcome !== expectedReviewOutcome
+                        || current.review?.headSha !== expectedReviewHeadSha)
+                        return current;
+                    claimed = true;
+                    return { ...current, projectionRecovery: { ...currentRecovery, status: 'retry',
+                            attempts: currentRecovery.attempts + 1, updatedAt: new Date().toISOString() } };
+                });
+            }
+            else if (target === 'escalated') {
+                if (!store.mutateJob)
+                    throw new Error('Atomic SQLite mutation is required for projection recovery status');
+                await store.mutateJob(job.id, current => current.projectionRecovery?.key === recovery.key
+                    && current.projectionRecovery.taskId === recovery.taskId
+                    && current.projectionRecovery.status === source
+                    && current.projectionRecovery.attempts === recovery.attempts
+                    ? (escalated = true, { ...current, projectionRecovery: { ...current.projectionRecovery, status: 'escalated', updatedAt: new Date().toISOString() } })
+                    : current);
+            }
+            else if (source !== target)
+                throw new Error(`Unexpected projection recovery transition ${source} -> ${target}`);
+        },
+        executeAction: async (actionId) => {
+            if (actionId === 'effect.projectLocalMerge') {
+                if (!claimed)
+                    return {};
+                const localMerge = job.localMerge;
+                if (!localMerge)
+                    throw new Error('Projection recovery requires a durable local merge receipt');
+                const sourceSha = localSourceHead(options.projectPath, localMerge.sourceRef);
+                if (job.review?.headSha !== sourceSha)
+                    throw new Error('Projection recovery source changed after review');
+                const delivered = deliverLocalMerge(options.projectPath, { ...localMerge, sourceSha,
+                    correlationJobId: job.id, displayPrNumber: job.prNumber > 0 ? job.prNumber : undefined });
+                await options.verifyObservedRemote(recovery.remoteSha);
+                const projectedJob = { ...job, localMerge: { ...localMerge, sourceSha: delivered.sourceSha,
+                        mergedCommitSha: delivered.mergedCommitSha, status: 'succeeded', error: undefined,
+                        nextAttemptAt: undefined, updatedAt: new Date().toISOString() } };
+                projectedMerge = await options.project(projectedJob);
+                let finalized = false;
+                const deliveredDecision = await dispatchWorkflowGraph(projectionConflictV2, {
+                    initialState: 'retry', input: { transport: 'event', id: 'projection.delivered', payload: {} },
+                    durableFacts: {}, graphName: 'projection-conflict', maxSteps: 1,
+                    persistTransition: async (source, target) => {
+                        if (source !== 'retry' || target !== 'projected' || !store.mutateJob)
+                            return;
+                        await store.mutateJob(job.id, current => {
+                            const currentMerge = current.localMerge;
+                            if (current.projectionRecovery?.key !== recovery.key
+                                || current.projectionRecovery.taskId !== recovery.taskId
+                                || current.projectionRecovery.status !== 'retry'
+                                || current.projectionRecovery.attempts !== recovery.attempts + 1
+                                || currentMerge?.sourceRef !== localMerge.sourceRef || currentMerge.targetRef !== localMerge.targetRef
+                                || currentMerge.status !== localMerge.status || currentMerge.sourceSha !== localMerge.sourceSha
+                                || currentMerge.mergedCommitSha !== localMerge.mergedCommitSha)
+                                return current;
+                            finalized = true;
+                            return { ...current, localMerge: projectedJob.localMerge,
+                                projectionRecovery: { ...current.projectionRecovery, status: 'projected', updatedAt: new Date().toISOString() },
+                                updatedAt: new Date().toISOString() };
+                        });
+                    },
+                });
+                projectionCompleted = finalized;
+                if (!deliveredDecision.accepted || deliveredDecision.target !== 'projected' || !finalized)
+                    projectedMerge = undefined;
+                return {};
+            }
+            if (actionId === 'projection.escalate') {
+                if (escalated)
+                    await options.eventBus?.publish(eventFor(job.id, 'projection', null, 'projection.recovery_escalated', 'failed', 'Projection recovery exhausted its bounded retry path', 'user', { idempotencyKey: recovery.key, attempts: recovery.attempts }, { agent: 'relay', component: 'projection-conflict' })).catch(() => { });
+                return {};
+            }
+            if (actionId === 'projection.createRecoveryTask')
+                return {};
+            throw new Error(`Unexpected projection recovery action ${actionId}`);
+        },
+    });
+    return { state: projectionCompleted ? 'projected' : decision.accepted ? decision.target : '', projectedMerge };
+}

package/dist/projection-recovery.js

@@ -0,0 +1,101 @@
+import { createTaskEntity } from './workflow/entity-creation.js';
+import { dispatchWorkflowGraph } from './workflow/dispatcher.js';
+import { projectionConflictV2 } from './workflow/projection-conflict-v2.js';
+import { taskOverallTimeoutMs } from './types.js';
+const MAX_RECOVERY_ATTEMPTS = 2;
+function taskFor(job, remoteSha, now) {
+    const key = `${job.id}:${remoteSha}`;
+    const id = `projection-recovery-${remoteSha}`;
+    return createTaskEntity(job, {
+        jobId: job.id, id, title: `Reconcile main divergence for ${job.title}`, kind: 'work',
+        priority: job.priority ?? 'P1', storySize: 'M', projectName: job.title,
+        agentName: 'implementation', parentTaskId: null, dependencies: [],
+        capabilities: ['implementation'], workerRequirements: { capabilities: ['implementation'] },
+        adapter: 'codex', input: [
+            `Projection recovery key: ${key}`,
+            `Observed origin/main SHA: ${remoteSha}`,
+            `Job ${job.id} is already COMPLETED; preserve that Job state.`,
+            'Inspect local main and origin/main, reconcile their divergence with a normal merge or rebase that preserves both histories, and never force-push.',
+            'Do not publish or rewrite refs. Record the resulting local main SHA and verify it contains the completed Job merge and the observed remote main history.',
+            'If the histories cannot be reconciled safely, stop and explain the exact blocker.',
+        ].join('\n'), output: { kind: 'task_pr' }, continuation: null, continuationDeliveredAt: null,
+        attempt: 0, maxAttempts: 2, leaseOwner: null, leaseExpiresAt: null,
+        executionId: null, threadId: null, result: null, plannerResult: null, error: null,
+        timeoutMs: taskOverallTimeoutMs('M'), createdAt: now, updatedAt: now,
+    });
+}
+/** Select graph policy from SQLite facts, then atomically materialize its selected recovery action. */
+export async function beginProjectionRecovery(store, jobId, remoteSha, error) {
+    if (!store.mutateJob)
+        throw new Error('Projection recovery requires atomic SQLite Job mutation');
+    let created = false;
+    let escalated = false;
+    const snapshot = await store.loadJob(jobId);
+    if (!snapshot)
+        return false;
+    const sameKey = snapshot.projectionRecovery?.key === `${jobId}:${remoteSha}`;
+    const expectedRecoveryKey = snapshot.projectionRecovery?.key ?? null;
+    const expectedAttempts = snapshot.projectionRecovery?.attempts ?? 0;
+    const expectedRecoveryStatus = snapshot.projectionRecovery?.status ?? null;
+    const expectedRecoveryRemoteSha = snapshot.projectionRecovery?.remoteSha ?? null;
+    const recoveryInProgress = snapshot.projectionRecovery?.status === 'repairing'
+        || (snapshot.projectionRecovery?.status === 'retry' && snapshot.projectionRecovery.remoteSha === remoteSha);
+    const decision = await dispatchWorkflowGraph(projectionConflictV2, {
+        initialState: 'classify', input: { transport: 'event', id: 'projection.delivery_failed', payload: {} },
+        durableFacts: {
+            jobState: snapshot.state,
+            mergeSucceeded: snapshot.localMerge?.status === 'succeeded',
+            projectionStrategy: snapshot.localMerge?.projectionStrategy,
+            divergenceConfirmed: /non-fast-forward|fetch first|diverg|not a fast-forward|rejected/i.test(error),
+            remoteShaAvailable: /^[0-9a-f]{40,64}$/i.test(remoteSha),
+            sameIdempotencyKey: sameKey,
+            recoveryInProgress,
+            attempts: snapshot.projectionRecovery?.attempts ?? 0,
+            maxAttempts: MAX_RECOVERY_ATTEMPTS,
+        }, graphName: 'projection-conflict', maxSteps: 1,
+        executeAction: async (actionId) => {
+            if (actionId === 'projection.escalate') {
+                await store.mutateJob(jobId, current => {
+                    if (current.state === 'COMPLETED'
+                        && (current.projectionRecovery?.key ?? null) === expectedRecoveryKey
+                        && (current.projectionRecovery?.attempts ?? 0) === expectedAttempts
+                        && current.projectionRecovery?.status === snapshot.projectionRecovery?.status
+                        && current.projectionRecovery) {
+                        current.projectionRecovery = { ...current.projectionRecovery, key: `${jobId}:${remoteSha}`, remoteSha,
+                            status: 'escalated', error, updatedAt: new Date().toISOString() };
+                        escalated = true;
+                    }
+                    return current;
+                });
+                return {};
+            }
+            if (actionId !== 'projection.createRecoveryTask')
+                throw new Error(`Unexpected projection action ${actionId}`);
+            const now = new Date().toISOString();
+            await store.mutateJob(jobId, current => {
+                if (current.state !== 'COMPLETED' || current.localMerge?.status !== 'succeeded'
+                    || (current.projectionRecovery?.key ?? null) !== expectedRecoveryKey
+                    || (current.projectionRecovery?.attempts ?? 0) !== expectedAttempts
+                    || (current.projectionRecovery?.status ?? null) !== expectedRecoveryStatus
+                    || (current.projectionRecovery?.remoteSha ?? null) !== expectedRecoveryRemoteSha
+                    || current.projectionRecovery?.status === 'repairing'
+                    || current.projectionRecovery?.key === `${jobId}:${remoteSha}`)
+                    return current;
+                const task = taskFor(current, remoteSha, now);
+                if (!current.tasks.some(item => item.id === task.id))
+                    current.tasks.push(task);
+                const recovery = {
+                    key: `${jobId}:${remoteSha}`, remoteSha, status: 'repairing', taskId: task.id,
+                    attempts: current.projectionRecovery?.attempts ?? 0,
+                    maxAttempts: MAX_RECOVERY_ATTEMPTS, error, updatedAt: now,
+                };
+                current.projectionRecovery = recovery;
+                current.updatedAt = now;
+                created = true;
+                return current;
+            });
+            return {};
+        },
+    });
+    return decision.accepted ? (created ? 'created' : escalated ? 'escalated' : false) : false;
+}

package/dist/reconciler-review.js

@@ -18,6 +18,8 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         // immutable input SHA is already present in the authoritative Job.
         if (this.options.noGitHub && this.options.localMergeEffect)
             return job.headSha ?? job.review?.headSha ?? null;
+        if (this.options.headShaProvider)
+            return this.options.headShaProvider(job);
         // GitHub PR head facts are audit-only. Source identity is local Git.
         if (!this.options.projectPathForJob)
             return job.headSha ?? job.review?.headSha ?? null;
@@ -37,7 +39,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         return {
             unscheduled: !job.schedule,
             reviewEnabled: job.reviewEnabled !== false,
-            jobActive: job.state === 'ACTIVE',
+            jobActive: job.state === 'ACTIVE' || job.projectionRecovery?.status === 'repairing',
             implementationComplete: implementationComplete(job),
             headAvailable: Boolean(headSha),
             completionGateSatisfied: completionGateSatisfied(job),
@@ -141,7 +143,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         }, this.options.reviewer?.threadId);
         const input = [
             `Job ID: ${job.id}`,
-            `Review PR #${reviewPrNumber} at exactly head SHA ${headSha}.`,
+            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),
             'Use the selected reviewer agent contract as the authoritative review protocol.',
@@ -150,7 +152,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
             '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: `Final review: ${job.title}`, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer',
+            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'],
             workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter,
             input,
@@ -355,7 +357,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         if (task.reviewHeadSha !== headSha)
             return { applied: false, reconcile: false, reason: event.type + '.stale' };
         const currentHeadSha = await this.currentHeadSha(job);
-        if ((currentHeadSha && currentHeadSha !== headSha) || (job.headSha && job.headSha !== headSha))
+        if (currentHeadSha ? currentHeadSha !== headSha : Boolean(job.headSha && job.headSha !== headSha))
             return { applied: false, reconcile: false, reason: event.type + '.stale' };
         // Planner-created reviewer tasks predate the final-review Job gate. Bind
         // their first trustworthy review event to PENDING before dispatching it.
@@ -388,8 +390,10 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
                 const now = event.timestamp || new Date().toISOString();
                 const id = 'review-fix-' + headSha.slice(0, 8);
                 if (!job.tasks.some(item => item.id === id)) {
-                    const input = 'Address all reviewer findings for PR #' + this.externalReviewPrNumber(job) + ' at ' + headSha + ':\n\n' + issues.map((issue, index) => (index + 1) + '. ' + issue).join('\n');
-                    const fixTask = createTaskEntity(job, { jobId: job.id, id, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'implementation', parentTaskId: task.id, dependencies: [task.id], capabilities: ['implementation'], workerRequirements: { capabilities: [] }, adapter: 'codex', input, output: { kind: 'task_pr' }, continuation: null, continuationDeliveredAt: null, attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: 0, createdAt: now, updatedAt: now });
+                    const fixPrNumber = this.externalReviewPrNumber(job);
+                    const fixTarget = fixPrNumber > 0 ? `PR #${fixPrNumber}` : `Job ${job.id} artifact`;
+                    const input = 'Address all reviewer findings for ' + fixTarget + ' at ' + headSha + ':\n\n' + issues.map((issue, index) => (index + 1) + '. ' + issue).join('\n');
+                    const fixTask = createTaskEntity(job, { jobId: job.id, id, title: `Fix review ${headSha.slice(0, 8)}`, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'implementation', parentTaskId: task.id, dependencies: [task.id], capabilities: ['implementation'], workerRequirements: { capabilities: [] }, adapter: 'codex', input, output: { kind: 'task_pr' }, continuation: null, continuationDeliveredAt: null, attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: 0, createdAt: now, updatedAt: now });
                     pendingFixTask = fixTask;
                 }
                 return {};
@@ -435,6 +439,8 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
                 if ((!current.review || (current.review.outcome === 'stale' && current.review.headSha !== headSha)) && freshTask.planningDecisionId) {
                     current.review = { outcome: 'pending', headSha, taskId: freshTask.id, evidence: null, updatedAt: reviewUpdatedAt };
                 }
+                if (currentHeadSha === headSha)
+                    current.headSha = headSha;
                 freshTask.error = null;
                 if (freshDecision.target !== 'RUNNING')
                     freshTask.result = { summary: event.message || `Review ${event.type}`, data: event.data ?? {} };

package/dist/reconciler-runtime.js

@@ -224,7 +224,6 @@ export class ReconcilerRuntimeBase {
             const outcome = await this.store.verifyWorkflowLaunch(event.job_id, event.task_id, transition.task.executionId);
             if (outcome === 'Failed')
                 throw Error('worker start postcondition violated');
-            // Unknown remains durable and never authorizes repeating this generation.
         }
         if (live?.executionId === transition.task.executionId)
             live.workerStarted = true;

package/dist/reconciler.js

@@ -114,7 +114,7 @@ export class Reconciler extends ReconcilerReviewBase {
                 } });
                 return job;
             }
-            if (job.state !== 'ACTIVE')
+            if (job.state !== 'ACTIVE' && job.projectionRecovery?.status !== 'repairing')
                 return job;
             await recoverExpiredExecutions(job, now, this.executionRecoveryPorts(job));
             await repairLegacyOrchestrators(jobId, now, { store: this.store, owner: this.options.owner, emit: event => this.emit(event) });
@@ -202,7 +202,7 @@ export class Reconciler extends ReconcilerReviewBase {
             await this.ensureFinalReview(finalState, headSha);
             await this.dispatchExecutableTasks(jobId);
             finalState = await this.store.load(jobId);
-            const localMergeCompleted = await reconcileLocalGitCompletion(this.store, finalState, headSha, this.options.noGitHub === true, this.options.projectPathForJob, event => this.emit(event), this.options.localMergeEffect, () => (this.options.now ?? new Date()).getTime());
+            const localMergeCompleted = await reconcileLocalGitCompletion(this.store, finalState, headSha, this.options.noGitHub === true, this.options.projectPathForJob, event => this.emit(event), this.options.localMergeEffect ?? this.options.localMergeDelivery, () => (this.options.now ?? new Date()).getTime());
             await drainProductionWorkflowOutbox(this.store, this.options);
             if (localMergeCompleted)
                 return this.store.load(jobId);

package/dist/relay-store.js

@@ -163,7 +163,7 @@ export class SQLiteRelayStore {
         }
     }
     workflowOperations() {
-        return new SQLiteWorkflowOperations(this.db, (job, at) => this.writeJobSnapshot(job, at));
+        return new SQLiteWorkflowOperations(this.db, (job, at) => this.writeJobSnapshot(job, at), (request, now) => { this.enqueueProjectionInTransaction(request, now); });
     }
     async commitWorkflowMutationAndEvents(jobId, mutation, events) {
         this.assertScope(jobId);

package/dist/relay-workflow-operations.js

@@ -5,13 +5,45 @@ import { dispatchWorkflowGraphSync } from './workflow/dispatcher.js';
 import { WorkflowActionLedger } from './workflow/action-ledger.js';
 import { ConditionRegistry, booleanCondition } from './workflow/conditions.js';
 import { DurableWorkflowPublication } from './workflow/durable-publication.js';
+import { randomUUID } from 'node:crypto';
+import { appendTaskComment } from './task-comments.js';
 function monotonicJobTimestamp(previous, candidate = new Date().toISOString()) { const a = Date.parse(previous), b = Date.parse(candidate); return new Date(Math.max(Number.isFinite(a) ? a + 1 : Date.now(), Number.isFinite(b) ? b : Date.now())).toISOString(); }
+function recordTaskStateHistory(current, next) {
+    const appended = [];
+    for (const task of next.tasks) {
+        const before = current.tasks.find(item => item.id === task.id);
+        if (!before)
+            continue;
+        for (const field of ['resolution', 'escalation']) {
+            const prior = before[field] ?? null, value = task[field] ?? null;
+            if (JSON.stringify(prior) === JSON.stringify(value) || value === null)
+                continue;
+            const resolution = field === 'resolution' ? value : null;
+            const escalation = field === 'escalation' ? value : null;
+            const kind = resolution ? 'resolution.changed'
+                : escalation?.status === 'responded' ? 'escalation.responded' : 'escalation.requested';
+            const action = resolution ? `Authoritative resolution changed: ${JSON.stringify(resolution)}`
+                : escalation?.status === 'responded'
+                    ? `Human response to escalation ${escalation.id}: ${escalation.response ?? ''}. Re-evaluate the historical resolution condition against original execution evidence.`
+                    : `Authoritative escalation changed: ${JSON.stringify(escalation)}`;
+            appended.push(appendTaskComment(next, task.id, action, {
+                author: escalation?.status === 'responded' ? 'human' : 'relay', kind,
+                executionId: resolution ? before.executionId ?? task.executionId ?? undefined : escalation?.originalExecutionId ?? before.executionId ?? undefined,
+                transition: resolution ? `resolution.${resolution.state}` : `escalation.${escalation?.status}`,
+                idempotencyKey: `task-state/${next.id}/${task.id}/${field}/${randomUUID()}`,
+            }));
+        }
+    }
+    return appended;
+}
 export class SQLiteWorkflowOperations {
     db;
     write;
-    constructor(db, write) {
+    enqueue;
+    constructor(db, write, enqueue) {
         this.db = db;
         this.write = write;
+        this.enqueue = enqueue;
     }
     async commitWorkflowMutationAndEvents(jobId, mutation, events) {
         let committed;
@@ -21,15 +53,20 @@ export class SQLiteWorkflowOperations {
                 throw new Error(`Unknown Job ${jobId}`);
             const current = normalizeLegacyJobPrNumber(JSON.parse(row.json));
             current.tasks = current.tasks.map(task => normalizeLegacyTaskLifecycle(task, current.executionMode));
+            const previous = structuredClone(current);
             const next = mutation(current);
             if (next.id !== jobId)
                 throw new Error('Cannot change authoritative Job identity');
             if (next.state !== current.state && ['COMPLETED', 'CANCELLED'].includes(current.state))
                 throw new Error('Cannot overwrite terminal authoritative state');
+            const history = recordTaskStateHistory(previous, next);
             const beforeTime = Date.parse(current.updatedAt);
             if (Number.isFinite(beforeTime) && !(Date.parse(next.updatedAt) > beforeTime))
                 next.updatedAt = new Date(beforeTime + 1).toISOString();
             this.write(next, new Date().toISOString());
+            if (next.prNumber > 0)
+                for (const comment of history)
+                    this.enqueue?.({ idempotencyKey: `append_task_comment:${comment.idempotencyKey ?? comment.id}`, operation: 'append_task_comment', payload: { operation: 'append_task_comment', value: comment }, priority: 20 }, new Date().toISOString());
             committed = structuredClone(next);
         }, () => events.map(item => ({ key: item.key, eventId: item.event.type, payload: item.event })));
         return committed;
@@ -85,14 +122,19 @@ export class SQLiteWorkflowOperations {
                 throw new Error(`Local authoritative Job ${jobId} not found`);
             const current = normalizeLegacyJobPrNumber(JSON.parse(row.json));
             current.tasks = current.tasks.map(task => normalizeLegacyTaskLifecycle(task, current.executionMode));
+            const previous = structuredClone(current);
             const before = JSON.stringify(current);
             const next = mutation(current);
+            const history = recordTaskStateHistory(previous, next);
             if (next.id !== jobId)
                 throw new Error('Cannot change authoritative Job identity');
             if (JSON.stringify(next) !== before && next.updatedAt <= JSON.parse(before).updatedAt) {
                 next.updatedAt = monotonicJobTimestamp(JSON.parse(before).updatedAt);
             }
             this.write(next, new Date().toISOString());
+            if (next.prNumber > 0)
+                for (const comment of history)
+                    this.enqueue?.({ idempotencyKey: `append_task_comment:${comment.idempotencyKey ?? comment.id}`, operation: 'append_task_comment', payload: { operation: 'append_task_comment', value: comment }, priority: 20 }, new Date().toISOString());
             this.db.exec('COMMIT');
             return structuredClone(next);
         }

package/dist/relayd.js

@@ -20,6 +20,7 @@ import { projectAuthoritativeLocalMerge } from './local-merge-projection.js';
 import { archiveDisplayPullRequest } from './github-pr-archive.js';
 import { orderGitHubBindingCandidates } from './github-binding-order.js';
 import { ProjectionFailureDeduplicator } from './projection-failure-dedupe.js';
+import { handleGitHubProjectionFailure, projectBindingLocalMerge } from './projection-failure-recovery.js';
 import { authoritativeBranchPushArgs } from './github-branch-projection.js';
 import { githubAuthContext } from './github-auth.js';
 import { DisabledGitHubClient, noGitHubMode } from './no-github.js';
@@ -320,8 +321,23 @@ export async function runDaemon(argv) {
                 const github = new GitHubStore(client, job.repository, prNumber, trusted);
                 projectionWriters.set(`job:${job.id}`, new GitHubProjectionWriter(relay, github, undefined, true, effect));
                 if (job.state === 'COMPLETED' && job.localMerge?.status === 'succeeded' && job.localMerge.projectionStrategy === 'target_ref_push') {
-                    const injection = await consumeMethodInjection(relay, job.repository, job.id, 'github.projectLocalMerge');
-                    const projectedMerge = await withTestInjection('github.projectLocalMerge', injection, () => projectAuthoritativeLocalMerge(canonical, job));
+                    const projection = await projectBindingLocalMerge(job, relay, {
+                        projectPath: canonical,
+                        project: async (projectedJob) => withTestInjection('github.projectLocalMerge', await consumeMethodInjection(relay, job.repository, job.id, 'github.projectLocalMerge'), () => projectAuthoritativeLocalMerge(canonical, projectedJob)),
+                        verifyObservedRemote: async (sha) => {
+                            try {
+                                await gitText(canonical, ['merge-base', '--is-ancestor', sha, 'refs/heads/main']);
+                            }
+                            catch {
+                                throw new Error(`Projection recovery did not preserve observed origin/main ${sha} in local main`);
+                            }
+                        }, eventBus: bus,
+                    });
+                    if (projection.skip)
+                        continue;
+                    const projectedMerge = projection.projectedMerge;
+                    if (!projectedMerge)
+                        continue;
                     await bus?.publish(eventFor(job.id, 'projection', null, 'projection.delivered', 'succeeded', `GitHub local merge projection ${projectedMerge.status}`, 'orchestrator', { operation: 'github.projectLocalMerge', deliveryStatus: projectedMerge.status, mergedCommitSha: projectedMerge.localMergedCommitSha }, { agent: 'relay', component: 'github-projection' }));
                     // A review-only PR is never merged by GitHub. Close it after local main
                     // has been safely published, retaining the diff, comments and commit link.
@@ -339,16 +355,9 @@ export async function runDaemon(argv) {
                 }
             }
             catch (error) {
-                const reason = errorMessage(error), classification = classifyFailure(error).classification;
-                if (!projectionFailureDeduplicator.shouldReport(discovered.id, discovered.updatedAt, reason, classification))
-                    continue;
-                await bus?.publish(eventFor(discovered.id, 'projection', null, 'projection.delivery_failed', 'failed', `GitHub projection failed: ${errorMessage(error)}`, 'orchestrator', { operation: 'github.projectLocalMerge', error: reason }, { agent: 'relay', component: 'github-projection' }))?.catch(() => { });
-                observability().record({
-                    stage: 'projection', event: 'github.binding_job_failed', level: 'warn', outcome: 'failed',
-                    message: `GitHub binding/projection failed for ${discovered.id}: ${reason}`,
-                    correlation: { repository: discovered.repository, prNumber: discovered.prNumber, jobId: discovered.id },
-                    data: { classification, reason },
-                });
+                await handleGitHubProjectionFailure(error, discovered, snapshot.path, { relayStores, repositoryPaths,
+                    explicitProjectPath, workspaceRoot, gitText, reconcileLocalJob: (jobId, reason) => pool.reconcileLocalJob(jobId, reason),
+                    eventBus: bus, deduplicator: projectionFailureDeduplicator });
             }
         }
         cachedOverviews = await inventoryFromLocal();

package/dist/review-generation-fence.js

@@ -1,7 +1,8 @@
 /** Called inside SQLite mutateJob against the latest durable Job snapshot. */
 export function reviewGenerationMatches(current, original, task, headSha) {
     const fresh = current.tasks.find(item => item.id === task.id);
-    if (!fresh || fresh.reviewHeadSha !== headSha || current.state !== 'ACTIVE'
+    if (!fresh || fresh.reviewHeadSha !== headSha
+        || (current.state !== 'ACTIVE' && current.projectionRecovery?.status !== 'repairing')
         || (current.headSha && current.headSha !== headSha)
         || fresh.executionId !== task.executionId)
         return false;

package/dist/store-github.js

@@ -258,6 +258,22 @@ export class GitHubStore {
             throw new Error(`JOB_BINDING_CONFLICT: PR #${this.prNumber} contains trusted ${JOB_MARKER} markers for multiple job ids`);
     }
     async listAgents() { return (await this.list()).filter(comment => this.isTrusted(comment)).map(x => parseAgent(x.body)).filter((x) => x !== null); }
+    async appendTaskHistoryComment(comment) {
+        if (!comment.idempotencyKey || comment.jobId === undefined || comment.taskId === undefined)
+            throw new Error('Task history projection requires durable identity');
+        const marker = `<!-- agents-relay:task-comment:v1 key=${comment.idempotencyKey} -->`;
+        if ((await this.list()).some(existing => this.isTrusted(existing) && existing.body.includes(marker)))
+            return;
+        try {
+            await this.comment(`${marker}\n**Task ${comment.taskId} · ${comment.kind ?? 'history'}**\n\n${comment.text}`);
+        }
+        catch (error) {
+            // The server may have accepted the comment before the connection failed.
+            // Force a fresh read before the outbox retries this stable logical key.
+            this.clearReadSnapshot();
+            throw error;
+        }
+    }
     async comment(body) {
         const pr = await this.prNode();
         const data = await this.graphql('mutation($subjectId:ID!,$body:String!){addComment(input:{subjectId:$subjectId,body:$body}){commentEdge{node{id databaseId url body updatedAt author{login}}}}}', { subjectId: pr.id, body });

package/dist/task-comments.js

@@ -1,11 +1,21 @@
 import { randomUUID } from 'node:crypto';
-export function appendTaskComment(job, taskId, message, author = 'cli') {
+export function appendTaskComment(job, taskId, message, options = 'cli') {
     const task = job.tasks.find(item => item.id === taskId);
     if (!task)
         throw new Error(`Task ${taskId} not found`);
     if (!message.trim())
         throw new Error('task comment requires nonempty --message');
-    const comment = { id: randomUUID(), text: message.trim(), author, createdAt: new Date().toISOString() };
+    const config = typeof options === 'string' ? { author: options } : options;
+    const key = config.idempotencyKey;
+    const existing = key && task.comments?.find(comment => comment.idempotencyKey === key);
+    if (existing)
+        return existing;
+    const comment = {
+        id: key ?? randomUUID(), text: message.trim(), author: config.author ?? 'cli', createdAt: new Date().toISOString(),
+        jobId: job.id, taskId, ...(config.kind ? { kind: config.kind } : {}),
+        ...(config.executionId ? { executionId: config.executionId } : {}),
+        ...(config.transition ? { transition: config.transition } : {}), ...(key ? { idempotencyKey: key } : {}),
+    };
     task.comments = [...(task.comments ?? []), comment];
     return comment;
 }

package/dist/task-context.js

@@ -7,10 +7,27 @@ export function taskExecutionContext(job, taskId, executionId) {
         throw new Error(`Task ${taskId} not found`);
     if (task.executionId !== executionId || !['QUEUED', 'RUNNING'].includes(task.state))
         throw new Error(`Stale Task execution ${taskId}/${executionId}; current state ${task.state}`);
+    const relevant = task.agentName === 'troubleshooter'
+        ? job.tasks.filter(item => item.id === task.parentTaskId)
+        : task.agentName === 'reviewer' ? task.dependencies.map(id => job.tasks.find(item => item.id === id)).filter((item) => Boolean(item)) : [];
     return { job: { id: job.id, repository: job.repository, title: job.title, objective: job.objective,
-            projectPath: job.projectPath, state: job.state }, task, comments: task.comments ?? [], dependencies: task.dependencies.map(id => job.tasks.find(item => item.id === id) ?? { id, missing: true }),
+            projectPath: job.projectPath, state: job.state }, task, currentState: task.state, resolution: task.resolution ?? null, escalation: task.escalation ?? null,
+        comments: task.comments ?? [], relevantTasks: relevant.map(item => ({ id: item.id, title: item.title, state: item.state, attempt: item.attempt, executionId: item.executionId, resolution: item.resolution ?? null, escalation: item.escalation ?? null, comments: item.comments ?? [], result: item.result, error: item.error, failureReason: item.failureReason })),
+        dependencies: task.dependencies.map(id => job.tasks.find(item => item.id === id) ?? { id, missing: true }),
         plan: job.plans?.find(plan => plan.id === task.planningDecisionId) ?? null };
 }
+/** Runtime-only task history; durable task.input remains the stable objective. */
+export function taskAgentHistoryContext(job, task) {
+    if (task.agentName !== 'troubleshooter' && task.agentName !== 'reviewer')
+        return '';
+    const related = task.agentName === 'troubleshooter'
+        ? job.tasks.filter(item => item.id === task.parentTaskId)
+        : task.dependencies.map(id => job.tasks.find(item => item.id === id)).filter((item) => Boolean(item));
+    return `\n\n[Authoritative task state and append-only comments]\n${JSON.stringify({
+        currentTask: { id: task.id, state: task.state, attempt: task.attempt, executionId: task.executionId, resolution: task.resolution ?? null, escalation: task.escalation ?? null, comments: task.comments ?? [] },
+        relatedTasks: related.map(item => ({ id: item.id, title: item.title, state: item.state, attempt: item.attempt, executionId: item.executionId, resolution: item.resolution ?? null, escalation: item.escalation ?? null, comments: item.comments ?? [], result: item.result, error: item.error, failureReason: item.failureReason })),
+    }, null, 2)}\nTreat comments as supplementary history. Re-evaluate historical conditions using evidence from the original failing execution; a human response or prior condition alone does not prove recovery.`;
+}
 /** Browser new-turn envelope: the local Contract and durable Task Context are authoritative. */
 export function taskReferencePrompt(repository, jobId, taskId, executionId, managedInput) {
     if (managedInput !== undefined && !managedInput.includes('[Execution event contract — mandatory]'))

package/dist/task-recovery.js

@@ -1,4 +1,4 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { eventFor } from './events.js';
 import { tryTransitionTaskEvent } from './scheduler.js';
 import { dispatchTaskResolutionSync, materializeResolution } from './workflow/task-resolution.js';
@@ -20,6 +20,11 @@ function validateRequest(request) {
     if (!request.context.trim())
         throw new Error('Escalation requires diagnostic context');
 }
+function escalationFingerprint(request, executionId) {
+    return createHash('sha256').update(JSON.stringify([
+        request.requiredAction.trim(), request.resolutionCondition.trim(), request.context.trim(), executionId ?? null,
+    ])).digest('hex');
+}
 /** Relay-owned escalation: the recovery Task, never the failed original, becomes BLOCKED. */
 export async function requestTroubleshooterEscalation(store, jobId, recoveryTaskId, request, now = new Date().toISOString()) {
     validateRequest(request);
@@ -35,6 +40,11 @@ export async function requestTroubleshooterEscalation(store, jobId, recoveryTask
         const originalPlan = recovery.recoveryPlanId ? job.plans?.find(plan => plan.id === recovery.recoveryPlanId) : undefined;
         if ((!original || original.state !== 'FAILED') && (!originalPlan || originalPlan.status !== 'FAILED'))
             throw new Error(`Troubleshooter ${recoveryTaskId} has no current FAILED original Task or Plan`);
+        const fingerprint = escalationFingerprint(request, original?.executionId ?? originalPlan?.executionId);
+        if (recovery.escalation?.fingerprint === fingerprint) {
+            result = { task: structuredClone(recovery), escalation: structuredClone(recovery.escalation), duplicate: true };
+            return job;
+        }
         if (recovery.escalation?.status === 'pending' && recovery.state === 'BLOCKED') {
             result = { task: structuredClone(recovery), escalation: structuredClone(recovery.escalation), duplicate: true };
             return job;
@@ -56,6 +66,7 @@ export async function requestTroubleshooterEscalation(store, jobId, recoveryTask
             throw new Error(`Troubleshooter ${recoveryTaskId} cannot be blocked`);
         const escalation = {
             id: randomUUID(), originalTaskId: original?.id, originalPlanId: originalPlan?.id,
+            fingerprint,
             originalExecutionId: original?.executionId ?? undefined,
             recoveryExecutionId: recovery.executionId ?? undefined, requiredAction: request.requiredAction.trim(),
             resolutionCondition: request.resolutionCondition.trim(), context: request.context.trim(), status: 'pending',
@@ -84,6 +95,8 @@ export async function requestTroubleshooterEscalation(store, jobId, recoveryTask
                 await store.saveTask(task); await store.saveJob(current); return current; });
     if (!result)
         throw new Error('Escalation did not produce a durable result');
+    result.task = structuredClone(job.tasks.find(task => task.id === recoveryTaskId) ?? result.task);
+    result.escalation = structuredClone(result.task.escalation ?? result.escalation);
     return { job, ...result };
 }
 /** Authorized human response; only a blocked Troubleshooter may be resumed. */
@@ -102,7 +115,6 @@ export async function resumeTroubleshooter(store, jobId, recoveryTaskId, respons
         if (!tryTransitionTaskEvent(task, 'task.unblocked', { autonomousJob: false }).accepted)
             throw new Error(`Troubleshooter ${recoveryTaskId} cannot be resumed`);
         task.escalation = { ...task.escalation, status: 'responded', response: response.trim(), respondedAt: now };
-        task.input += `\n\n## Human response (${now})\n${response.trim()}\n\nRe-validate the original failure against this response. Required resolution condition: ${task.escalation.resolutionCondition}`;
         task.result = null;
         task.error = null;
         task.failureReason = undefined;
@@ -116,6 +128,7 @@ export async function resumeTroubleshooter(store, jobId, recoveryTaskId, respons
         await store.saveTask(task); await store.saveJob(current); return current; });
     if (!updated)
         throw new Error('Troubleshooter was not resumed');
+    updated = structuredClone(job.tasks.find(item => item.id === recoveryTaskId) ?? updated);
     return { job, task: updated };
 }
 export function hasPendingTroubleshooterEscalation(job, original) {

package/dist/troubleshooter.js

@@ -26,7 +26,7 @@ Retrieve this task's lifecycle event history before classifying the root cause o
 GET http://127.0.0.1:8787/api/events?job=${encodeURIComponent(job.id)}&task=${encodeURIComponent(task.id)}&limit=200
 Inspect event order, type/status, source, data/phase, duplicate events, missing expected lifecycle events, late events, and execution identifiers. If the event stream points to delivery/runtime failure, inspect the corresponding Relay/worker/tool logs too. Do not treat the final task.error string as the complete root cause.
 
-Follow the selected Troubleshooter agent contract. Diagnose root cause from durable task state + event history + relevant runtime logs before retry. The final task.error string alone is never sufficient. Classify the evidence as model/provider/runtime, worker/tool/infrastructure, semantic task failure, or timeout/unknown. Select exactly one graph-enabled resolution path: exact_original_retry, same_job_dependency, blocker_job_dependency (with merge or verified mode), escalation_gate, or cancel_supersede. For confirmed adapter/model/provider failure, include --failure-kind, --reason, --evidence and --reroute in task recover; use --exclude-current-route only if the exact failed route should not be selected again. For semantic task failure use --failure-kind task_failure without rerouting. For uncertain failures use --failure-kind unknown and preserve routing unless evidence justifies rerouting. The recovery transaction stores diagnosis, clears old routing only on request, and next execution automatically reroutes with the evidence and exclusions. Troubleshooter must then reactivate/retry this exact original task and verify progress. Use the dedicated agents-relay task recover path with --task-id ${task.id} and --recovery-task-id ${recoveryId}; never use ordinary task retry from a Troubleshooter because manual retry intentionally supersedes active recovery. Do not manually choose a provider/model or create a replacement task; no replacement_task action exists. If the blocker is a shared worker/runtime/tool defect, create and directly complete a P0/self-job in the owning repository, including required release/deploy verification. If diagnosis suggests a genuine human/external blocker, do not publish task.blocked directly and do not implement the result branch procedurally. Call agents-relay escalation with the original intent, blocker, and relevant context. Pass any caller-defined notification plan through --on-needs-user/--on-needs-user-file; do not hard-code a channel. The canonical escalation graph invokes Neo escalation and owns the resolved/failed/needs_user branch; follow its selected outcome. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
+Follow the selected Troubleshooter agent contract. Diagnose root cause from durable task state, append-only comments, task-scoped event history, and relevant runtime logs before retry. The final task.error string alone is never sufficient. Independently verify every human response against evidence from the exact original failing execution context; a response or historical resolution condition alone never proves recovery. Classify evidence as model/provider/runtime, worker/tool/infrastructure, semantic task failure, or timeout/unknown. Select one graph-enabled resolution path: exact_original_retry, same_job_dependency, blocker_job_dependency, escalation_gate, or cancel_supersede. For confirmed adapter/model/provider failure, include --failure-kind, --reason, --evidence and --reroute in task recover; use --exclude-current-route only if the exact failed route should not be selected again. For semantic task failure use --failure-kind task_failure without rerouting. For uncertain failures use --failure-kind unknown and preserve routing unless evidence justifies rerouting. Request the existing agents-relay task recover or agents-relay escalation operation; submission alone is not recovery. Reload authoritative SQLite state and verify the requested resolution and exact-original retry postconditions before reporting success. Bound self-healing retries to the durable Task retry budget. For a shared worker/runtime/tool defect, use its owning repository's P0/self-job workflow and verify the durable fix before requesting recovery. Never use ordinary task retry from a Troubleshooter because manual retry intentionally supersedes active recovery. Do not manually choose a provider/model or create a replacement task. If diagnosis suggests a genuine human/external blocker, invoke the escalation command; do not publish task.blocked or implement a workflow branch procedurally. The canonical escalation graph invokes Neo escalation and owns the resolved/failed/needs_user branch; Relay applies the selected outcome. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
 }
 function belongsToCurrentRun(job, task) {
     const slot = job.schedule?.currentRunSlot;
@@ -92,7 +92,7 @@ export function pendingTroubleshooterTasks(job) {
         recoveries.push(createTaskEntity(job, {
             jobId: job.id,
             id,
-            title: `Diagnose and recover failed task ${task.id}`,
+            title: `Recover task ${task.id}`,
             recoveryForAttempt: task.attempt,
             kind: 'work',
             priority: 'P0',

package/dist/workflow/definitions-v2.js

@@ -43,8 +43,20 @@ export const jobLifecycleV2 = load('job-lifecycle', JOB_STATES, {
     implementationComplete: boolGuard('implementationComplete'),
     headAvailable: boolGuard('headAvailable'),
     mergeCapable: boolGuard('mergeCapable'),
-    localCompletionAllowed: boolGuard('localCompletionAllowed'),
-    localMergeReady: boolGuard('localMergeReady'),
+    localCompletionAllowed: (facts) => {
+        const values = facts.durableFacts;
+        return values.jobActive === true && values.autoMergeEnabled === true && values.schedulePresent !== true
+            && values.implementationComplete === true && values.completionGateSatisfied === true
+            && values.reviewSatisfied === true
+            && (values.localMergeRequired !== true || values.localMergeSucceeded === true);
+    },
+    localMergeReady: (facts) => {
+        const values = facts.durableFacts;
+        return values.jobActive === true && values.autoMergeEnabled === true && values.schedulePresent !== true
+            && values.implementationComplete === true && values.completionGateSatisfied === true
+            && values.reviewSatisfied === true && values.localMergePresent === true
+            && values.reviewHeadCurrent === true && values.mergeAttemptReady === true;
+    },
 });
 function topologyTargets(graph, from) {
     const source = [...graph.nodes.values()].find(node => node.kind === 'state' && node.semanticId === from);

package/dist/workflow/graph-v2.js

@@ -25,7 +25,7 @@ function parseLabel(raw, line) {
 export function parseGraphV2(source) {
     const lines = source.split(/\r?\n/);
     // Mermaid YAML frontmatter is metadata only; never execute it as graph policy.
-    // Preserve original source line positions for diagnostics and coverage reports.
+    // Keep source line positions stable even when graph metadata grows.
     let graphStart = 0;
     if (lines[0]?.trim() === '---') {
         let closing = -1;
@@ -34,8 +34,6 @@ export function parseGraphV2(source) {
                 closing = i;
                 break;
             }
-            if (!/^(title|description):\s+[^\r\n]+$/.test(lines[i]))
-                fail(i + 1, 'unsupported graph frontmatter field');
         }
         if (closing < 0)
             fail(1, 'unterminated graph frontmatter');

package/dist/workflow/projection-conflict-v2.js

@@ -3,19 +3,36 @@ import { GraphRuntime } from './graph-v2.js';
 import { dispatchWorkflowGraphSync } from './dispatcher.js';
 const source = readFileSync(new URL('../../workflow/projection-conflict.mmd', import.meta.url), 'utf8');
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+const guards = {
+    deterministicDefinitionConflict: boolGuard('deterministicDefinitionConflict'),
+    'projection.recoveryInProgress': boolGuard('recoveryInProgress'),
+    'projection.recoveryEligible': (facts) => {
+        const values = facts.durableFacts;
+        return values.jobState === 'COMPLETED' && values.mergeSucceeded === true
+            && values.projectionStrategy === 'target_ref_push' && values.divergenceConfirmed === true
+            && values.remoteShaAvailable === true
+            && values.sameIdempotencyKey !== true && values.recoveryInProgress !== true
+            && Number(values.attempts ?? 0) < Number(values.maxAttempts ?? 0);
+    },
+    'projection.recoveryExhausted': (facts) => {
+        const values = facts.durableFacts;
+        return values.jobState === 'COMPLETED' && values.divergenceConfirmed === true && values.remoteShaAvailable === true
+            && values.sameIdempotencyKey !== true && values.recoveryInProgress !== true
+            && Number(values.attempts ?? 0) >= Number(values.maxAttempts ?? 0);
+    },
+    'projection.retryAvailable': (facts) => facts.durableFacts.taskRetryAvailable === true
+        && Number(facts.durableFacts.attempts ?? 0) < Number(facts.durableFacts.maxAttempts ?? 0),
+    'projection.repairReviewed': (facts) => facts.durableFacts.repairTaskState === 'SUCCEEDED' && facts.durableFacts.reviewOutcome === 'approved',
+    'projection.repairFailed': (facts) => facts.durableFacts.repairTaskState === 'FAILED' || facts.durableFacts.repairTaskState === 'BLOCKED'
+        || facts.durableFacts.reviewOutcome === 'blocked' || facts.durableFacts.reviewTaskState === 'FAILED',
+};
 export const projectionConflictV2 = new GraphRuntime(source, {
-    states: new Set(['classify', 'retry', 'conflict']),
-    guards: { deterministicDefinitionConflict: boolGuard('deterministicDefinitionConflict') },
-    actions: {},
-    events: { 'projection.failed': { id: 'projection.failed' } },
+    states: new Set(['classify', 'repairing', 'retry', 'conflict', 'escalated', 'projected']),
+    guards,
+    actions: Object.fromEntries(['projection.createRecoveryTask', 'effect.projectLocalMerge', 'projection.escalate'].map(id => [id, { id }])),
+    events: Object.fromEntries(['projection.failed', 'projection.delivery_failed', 'projection.delivered', 'reconcile'].map(id => [id, { id }])),
 });
-/**
- * Core projection-failure disposition policy.
- *
- * A deterministic same-id/different-definition conflict stops consuming retry budget;
- * any other failure keeps the normal backoff/retry path. This branch is owned by the
- * canonical Mermaid graph, not by a procedural `if` in the projection writer.
- */
+/** The decision is graph-owned; callers supply SQLite and inspected Git facts. */
 export function decideProjectionFailure(facts) {
     return dispatchWorkflowGraphSync(projectionConflictV2, {
         initialState: 'classify',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.150",
+  "version": "2.0.151",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     "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/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": "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": "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/SKILL.md

@@ -54,7 +54,7 @@ The event must carry the exact durable `job_id` and `task_id`. Progress events a
 Agents Relay maps those terminal events to durable state:
 - `task.completed` → `SUCCEEDED`
 - `task.failed` → `FAILED`
-Relay may authoritatively move a Task to `BLOCKED` for an external condition and may resume it only through an authorized unblock operation. A human response resumes the blocked Troubleshooter, not the failed original Task.
+Relay may authoritatively move a Task to `BLOCKED` for an external condition and may resume it only through an authorized unblock operation. A human response is an append-only Task Comment and resumes the blocked Troubleshooter, not the failed original Task. Task input remains stable; recovery agents receive current authoritative state and relevant comments as execution context.
 
 A model-backed task must not launch without an event bus. If no terminal event arrives before the task timeout, Relay records an explicit timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
 

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

@@ -17,7 +17,7 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
 
 ## Recovery loop
 
-1. Retrieve the durable original Job and failed/blocked Task from GitHub.
+1. Retrieve the durable original Job and Task from the authoritative Relay store with `agents-relay task context`; GitHub is only an optional projection and is never lifecycle authority.
 2. **Mandatory before diagnosis:** retrieve the failed Task's task-scoped lifecycle event history. When the local Relay dashboard is available, use `GET http://127.0.0.1:8787/api/events?job=<job_id>&task=<task_id>&limit=200`. Inspect event order, type/status, source, data/phase, execution IDs, duplicates, missing expected lifecycle events, and late events. Then inspect task error/failureReason, worker selection, routing, attempt count, task input/output contract, PR state, and relevant runtime/service logs.
 3. Classify the blocker:
    - transient execution/delivery/lease failure;
@@ -32,8 +32,8 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
    - 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.
-7. For an immediate repair, only after the blocker is removed run `agents-relay task recover` for the original Task with this Troubleshooter's recovery Task ID and reconcile its Job. An authorized human response resumes this same Troubleshooter with its diagnostic context; verify the action before requesting original-task recovery. For deferred repair, rely on the durable blocker relation: merge-mode blockers wake matching dependents after merge; release/deploy/runtime blockers use `--resolution verified` and `agents-relay blocker resolve` only after verification.
-8. Verify durable evidence that the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
+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.
 
 ## Rules

package/skills/agents-relay/contracts/event-contract.md

@@ -25,7 +25,7 @@ A Reviewer must **not** publish unstructured `task.completed`: missing verdict o
 
 Only a real user action merits escalation. Troubleshooter invokes the Relay escalation operation, specifying the required action, resolution condition, and diagnostic context. Relay durably records the human action and blocks **the Troubleshooter Task**, leaving the original failed Task `FAILED`. This is a Relay state transition, not a third agent terminal event.
 
-When the human responds, the **Troubleshooter Task** is authoritatively unblocked and resumed with its prior context plus the response. Troubleshooter independently verifies resolution, requests an authorized original Task recovery, and only then publishes its own `task.completed`. If unresolved, it continues diagnosis or escalates again; human assertion alone is not technical verification.
+When the human responds, Relay records the response as an append-only Task Comment and authoritatively unblocks the **Troubleshooter Task**. The stable Task input is unchanged. Troubleshooter receives current authoritative state and relevant comments, independently verifies the response against the original failing execution context, requests an authorized original Task recovery, and only then publishes its own `task.completed`. A repeated identical escalation without new evidence is idempotent. If unresolved, it continues diagnosis or escalates again; human assertion alone is not technical verification.
 
 See [task-recovery-flows.md](task-recovery-flows.md) for unified architecture, overall flow, failure recovery, and post-blocked resumption.
 

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

@@ -32,6 +32,13 @@ A later Planner round must inspect the existing semantic tree and attach review,
 
 A Task input records **what is known and what has already been decided before execution**. A Task result records **what execution discovered and what was actually done**.
 
+After creation, keep `Task.input` stable as the objective and initial evidence.
+Responses, resolution changes, and escalation history belong in append-only
+Task Comments. SQLite atomically records typed comments with authoritative
+resolution/escalation mutations; PR-bound Jobs project those comments through
+the durable idempotent projection outbox. Comments supplement current state and
+never replace `Task.resolution` or `Task.escalation`.
+
 Task input should include, as applicable:
 
 - goal and observed behavior;

package/skills/agents-relay/contracts/task-recovery-flows.md

@@ -1,6 +1,6 @@
 # Task Failure Recovery and Human Escalation — Agreed Target Design
 
-**Status:** Design agreement; not an assertion of current implementation. This document describes two flows. Existing runtime, workflow graphs, and agent instructions may need changes to conform.
+**Status:** Current recovery contract. SQLite Task snapshots retain append-only typed comments alongside authoritative state.
 
 ## Principles and ownership
 
@@ -133,3 +133,20 @@ flowchart TD
 - Align escalation graph, CLI, reconciler, and unblock commands so human intervention blocks **Troubleshooter**, not the original failed Task; preserve the original failure and correlated recovery context.
 - Ensure the blocked Troubleshooter can resume after an authorized human unblock rather than being treated as a finished terminal execution.
 - Add integrated checks: technical retry, blocker-Job handoff, human request/block, human unblock/resume, failed verification/re-escalation, stale/duplicate responses, and correct original-Task retry.
+
+## Durable recovery history
+
+`Task.input` remains the stable objective and original evidence. `Task.resolution` and
+`Task.escalation` remain the current authoritative states; comments are append-only
+history, not a second state authority. SQLite mutation transactions compare the
+before/after authoritative values and append typed comments with Job, Task,
+execution, transition, and idempotency identity in the same commit. Do not add a
+`resolutionHistory` field.
+
+Human responses are comments. Resuming a Troubleshooter must not rewrite its
+input or append a stale “Required resolution condition” as new objective text.
+The condition remains in escalation provenance. Reviewer and Troubleshooter
+prompts receive current authoritative state and relevant task comments as runtime
+context; Troubleshooters independently verify a response against evidence from
+the original failing execution. Repeating an identical escalation with unchanged
+evidence is idempotent.

package/workflow/projection-conflict.mmd

@@ -1,15 +1,66 @@
 ---
 title: Projection Conflict
-description: Detects and resolves conflicting workflow state projections against authoritative facts.
+description: Recover local-main and origin-main divergence after a completed Job's GitHub projection fails.
+name: projection-conflict
+authority: SQLite Relay Job snapshot
+trigger: projection.delivery_failed
+idempotency: job-id plus observed origin/main SHA
+actions:
+  - projection.createRecoveryTask
+  - projection.escalate
+effects:
+  - effect.projectLocalMerge
+guards:
+  - deterministicDefinitionConflict
+  - projection.recoveryEligible
+  - projection.recoveryExhausted
+  - projection.recoveryInProgress
+  - projection.retryAvailable
+  - projection.repairReviewed
+  - projection.repairFailed
 ---
 flowchart LR
 %% relay: initial classify
 classify["state: classify"]
-retry["state: retry"]
 conflict["state: conflict"]
+repairing["state: repairing"]
+retry["state: retry"]
+escalated["state: escalated"]
+projected["state: projected"]
 
+eligible["guard: projection.recoveryEligible"]
+inProgress["guard: projection.recoveryInProgress"]
 deterministic["guard: deterministicDefinitionConflict"]
+exhausted["guard: projection.recoveryExhausted"]
+retryAvailable["guard: projection.retryAvailable"]
+reviewed["guard: projection.repairReviewed"]
+repairFailed["guard: projection.repairFailed"]
+createTask["action: projection.createRecoveryTask"]
+retryProjection["action: effect.projectLocalMerge"]
+escalate["action: projection.escalate"]
 
+classify -->|on: projection.delivery_failed| inProgress
+inProgress -->|true| classify
+inProgress -->|false| eligible
 classify -->|on: projection.failed| deterministic
 deterministic -->|true| conflict
 deterministic -->|false| retry
+eligible -->|true| createTask
+eligible -->|false| exhausted
+exhausted -->|true| escalate
+exhausted -->|false| classify
+createTask --> repairing
+
+repairing -->|on: reconcile| reviewed
+retry -->|on: reconcile| retryAvailable
+reviewed -->|true| retryAvailable
+retryAvailable -->|true| retryProjection
+retryAvailable -->|false| escalate
+reviewed -->|false| repairFailed
+repairFailed -->|true| escalate
+repairFailed -->|false| repairing
+retryProjection --> retry
+escalate --> escalated
+
+retry -->|on: projection.delivered| projected
+retry -->|on: projection.delivery_failed| eligible