agents-relay 2.0.149 → 2.0.151

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');