agents-relay 2.0.68 → 2.0.69

package/dist/e2e-injection.js

@@ -0,0 +1,76 @@
+const legacy = {
+    quota_exceeded: { method: 'worker.codex.launch', action: 'return', execution: 'skip', mock: 'worker_quota' },
+    model_not_found: { method: 'worker.codex.launch', action: 'return', execution: 'skip', mock: 'worker_model_not_found' },
+    provider_unavailable: { method: 'worker.codex.launch', action: 'return', execution: 'skip', mock: 'worker_provider_unavailable' },
+    github_projection_failure: { method: 'github.projectLocalMerge', action: 'throw', execution: 'skip', error: { code: 'SERVICE_UNAVAILABLE', message: 'E2E transient GitHub projection transport failure', status: 503 } },
+};
+export function parseTestInjection(value) {
+    if (typeof value === 'string')
+        return legacy[value];
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const v = value;
+    if (v.method !== 'worker.codex.launch' && v.method !== 'github.projectLocalMerge' && v.method !== 'browserWorkspace.command')
+        return undefined;
+    if (v.action !== 'throw' && v.action !== 'return' && v.action !== 'pass')
+        return undefined;
+    if (v.execution !== 'skip' && v.execution !== 'after' && v.execution !== 'run')
+        return undefined;
+    const error = v.error;
+    if (v.action === 'throw' && (!error || typeof error !== 'object' || typeof error.message !== 'string' || typeof error.code !== 'string'))
+        return undefined;
+    const mock = v.mock;
+    if (v.action === 'return' && (v.method !== 'worker.codex.launch' || !['worker_quota', 'worker_model_not_found', 'worker_provider_unavailable'].includes(String(mock))))
+        return undefined;
+    if (v.method === 'worker.codex.launch' && v.action !== 'pass' && (v.action !== 'return' || v.execution !== 'skip'))
+        return undefined;
+    if (v.action === 'pass' && v.execution !== 'run')
+        return undefined;
+    if (v.action !== 'pass' && v.execution === 'run')
+        return undefined;
+    return { method: v.method, action: v.action, execution: v.execution, error: error, mock: mock };
+}
+export function authorizedInjection(repository, raw, env = process.env) {
+    return env.E2E_REPO && repository === env.E2E_REPO ? parseTestInjection(raw) : undefined;
+}
+function mockWorker(name) {
+    const message = name === 'worker_quota' ? 'rate_limit_exceeded: usage limit reached' : name === 'worker_model_not_found' ? 'model_not_found: model is unavailable' : 'provider_unavailable: provider refused the request';
+    const promise = Promise.reject(new Error(message));
+    promise.catch(() => { });
+    return { id: 'e2e-injected', launched: Promise.resolve(), promise, cancel: () => { }, processExit: { exitCode: 1, signal: null, stderr: message, terminationReason: null } };
+}
+/** Caller must supply a configuration already consumed durably before this invocation. */
+export function withTestInjection(method, config, execute) {
+    if (!config || config.method !== method || config.action === 'pass')
+        return execute();
+    const apply = (original) => {
+        if (config.action === 'throw') {
+            const error = Object.assign(new Error(config.error.message), { code: config.error.code, status: config.error.status });
+            throw error;
+        }
+        if (method === 'worker.codex.launch' && config.mock)
+            return mockWorker(config.mock);
+        return original;
+    };
+    return config.execution === 'after' ? Promise.resolve(execute()).then(apply) : apply();
+}
+/** Shared atomic consumer, scoped solely by E2E_REPO and exact method. */
+export async function consumeMethodInjection(relay, repository, jobId, method) {
+    if (!process.env.E2E_REPO || process.env.E2E_REPO !== repository || !relay.mutateJob)
+        return undefined;
+    let config;
+    await relay.mutateJob(jobId, job => {
+        if (job.repository !== repository)
+            return job;
+        const task = job.tasks.find(t => authorizedInjection(job.repository, t.testInjection)?.method === method);
+        if (!task)
+            return job;
+        config = authorizedInjection(job.repository, task.testInjection);
+        delete task.testInjection;
+        task.updatedAt = new Date(Math.max(Date.now(), Date.parse(task.updatedAt) + 1)).toISOString();
+        return job;
+    });
+    if (config && (await relay.loadJob(jobId))?.tasks.some(t => authorizedInjection(repository, t.testInjection)?.method === method))
+        throw Error(`E2E injection consumption not committed: ${jobId}`);
+    return config;
+}

package/dist/github-binding-order.js

@@ -0,0 +1,15 @@
+/** Fresh unbound ACTIVE jobs are highest priority; terminal projection debt is last. */
+export function orderGitHubBindingCandidates(items) {
+    return [...items].sort((a, b) => score(a.job) - score(b.job) || a.job.createdAt.localeCompare(b.job.createdAt));
+}
+function score(job) {
+    const bound = (job.externalPrNumber ?? (job.prNumber > 0 ? job.prNumber : 0)) > 0;
+    const terminal = ['COMPLETED', 'CANCELLED'].includes(job.state);
+    if (!terminal && !bound)
+        return 0;
+    if (!terminal && bound)
+        return 1;
+    if (terminal && bound)
+        return 2;
+    return 3;
+}

package/dist/github-client.js

@@ -241,13 +241,18 @@ export class GhApiClient {
             let stdout = '';
             child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
             child.on('error', () => resolve(null));
-            child.on('close', () => {
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    resolve(null);
+                    return;
+                }
                 try {
                     const value = JSON.parse(stdout);
                     const hosts = value.hosts;
                     const github = hosts?.['github.com'];
                     const active = Array.isArray(github) ? github.find(item => item.active === true) : undefined;
-                    resolve(typeof active?.login === 'string' && active.login.length > 0 ? active.login : null);
+                    const healthy = active && active.state !== 'error' && typeof active.error !== 'string';
+                    resolve(healthy && typeof active?.login === 'string' && active.login.length > 0 ? active.login : null);
                 }
                 catch {
                     resolve(null);

package/dist/github-pr-archive.js

@@ -0,0 +1,22 @@
+/** A PR is a read-only collaboration record after authoritative local completion. */
+export async function archiveDisplayPullRequest(client, repository, number, jobId, publishedSha, state) {
+    if (state !== 'OPEN')
+        return 'already_closed';
+    const marker = `Agents Relay local completion: ${jobId}`;
+    const path = `repos/${repository}/issues/${number}/comments?per_page=100`;
+    const comments = await client.request(path);
+    if (!Array.isArray(comments))
+        throw new Error('Cannot verify PR archive comment idempotency');
+    const alreadyCommented = comments.some(item => item && typeof item === 'object'
+        && 'body' in item && typeof item.body === 'string' && item.body.includes(marker));
+    if (!alreadyCommented) {
+        await client.request(`repos/${repository}/issues/${number}/comments`, {
+            method: 'POST',
+            body: JSON.stringify({ body: `${marker}\nPublished local main commit: ${publishedSha}.\nThis PR is closed as a review record; GitHub did not perform a merge.` }),
+        });
+    }
+    await client.request(`repos/${repository}/pulls/${number}`, {
+        method: 'PATCH', body: JSON.stringify({ state: 'closed' }),
+    });
+    return 'archived';
+}

package/dist/github-webhook.js

@@ -14,7 +14,7 @@ export function parsePackagePublishFailureMarker(body) {
         const data = JSON.parse(body.slice(start + prefix.length, end));
         if (typeof data.runId !== 'string' || !/^\d+$/.test(data.runId) || !Number.isInteger(data.attempt) || Number(data.attempt) < 1 || typeof data.sha !== 'string' || !/^[a-f0-9]{7,40}$/i.test(data.sha) || typeof data.stage !== 'string' || !data.stage)
             return null;
-        return { runId: data.runId, attempt: Number(data.attempt), sha: data.sha, stage: data.stage };
+        return { runId: data.runId, attempt: Number(data.attempt), sha: data.sha, stage: data.stage, ...(typeof data.jobId === 'string' && data.jobId ? { jobId: data.jobId } : {}) };
     }
     catch {
         return null;
@@ -45,6 +45,7 @@ export function parsePackagePublicationMarker(body) {
         version: value.version,
         registry: typeof value.registry === 'string' ? value.registry : null,
         sha: typeof value.sha === 'string' ? value.sha : null,
+        ...(typeof value.jobId === 'string' && value.jobId ? { jobId: value.jobId } : {}),
     };
 }
 export function verifyGitHubWebhook(secret, body, signature) {
@@ -74,7 +75,7 @@ function pullRequestFacts(payload, action) {
 export function parseGitHubWebhook(headers, body) {
     const deliveryId = String(headers['x-github-delivery'] ?? '');
     const event = String(headers['x-github-event'] ?? '');
-    if (!deliveryId || (event !== 'pull_request' && event !== 'issue_comment'))
+    if (!deliveryId || (event !== 'pull_request' && event !== 'issue_comment' && event !== 'commit_comment'))
         return null;
     let payload;
     try {
@@ -86,26 +87,50 @@ export function parseGitHubWebhook(headers, body) {
     const repository = payload.repository;
     const repositoryName = typeof repository?.full_name === 'string' ? repository.full_name : null;
     const action = typeof payload.action === 'string' ? payload.action : null;
+    if (!repositoryName)
+        return null;
+    if (event === 'commit_comment') {
+        const comment = payload.comment;
+        const trustedPublisher = comment?.user?.login === 'github-actions[bot]';
+        const publication = trustedPublisher ? parsePackagePublicationMarker(comment?.body) : null;
+        const publishFailure = trustedPublisher ? parsePackagePublishFailureMarker(comment?.body) : null;
+        const jobId = publication?.jobId ?? publishFailure?.jobId;
+        if ((!publication && !publishFailure) || !jobId)
+            return null;
+        const commentTime = comment?.created_at;
+        const publicationObservedAt = typeof commentTime === 'string' && Number.isFinite(Date.parse(commentTime))
+            ? new Date(commentTime).toISOString() : undefined;
+        return { deliveryId, event, action, repository: repositoryName, pullRequest: null, jobId, publication,
+            ...(publicationObservedAt ? { publicationObservedAt } : {}),
+            ...(publishFailure ? { publishFailure } : {}), pullRequestFacts: null };
+    }
     const pr = payload.pull_request;
     const issue = payload.issue;
-    const number = Number(pr?.number ?? (issue?.pull_request ? issue.number : 0));
-    if (!repositoryName || !Number.isInteger(number) || number <= 0)
-        return null;
     if (event === 'issue_comment') {
+        const issueNumber = Number(issue?.number ?? 0);
+        if (!Number.isInteger(issueNumber) || issueNumber <= 0)
+            return null;
         const comment = payload.comment;
         const trustedPublisher = comment?.user?.login === 'github-actions[bot]';
         const publication = trustedPublisher ? parsePackagePublicationMarker(comment?.body) : null;
         const publishFailure = trustedPublisher
             ? parsePackagePublishFailureMarker(comment?.body) : null;
+        const jobId = publication?.jobId ?? publishFailure?.jobId;
         if (!publication && !publishFailure)
             return null;
+        if (!issue?.pull_request && !jobId)
+            return null;
         const commentTime = comment?.created_at;
         const publicationObservedAt = typeof commentTime === 'string' && Number.isFinite(Date.parse(commentTime))
             ? new Date(commentTime).toISOString() : undefined;
-        return { deliveryId, event, action, repository: repositoryName, pullRequest: number, publication,
+        return { deliveryId, event, action, repository: repositoryName,
+            pullRequest: issue?.pull_request ? issueNumber : null, ...(jobId ? { jobId } : {}), publication,
             ...(publicationObservedAt ? { publicationObservedAt } : {}),
             ...(publishFailure ? { publishFailure } : {}), pullRequestFacts: null };
     }
+    const number = Number(pr?.number ?? 0);
+    if (!Number.isInteger(number) || number <= 0)
+        return null;
     const facts = pullRequestFacts(payload, action);
     if (!facts)
         return null;

package/dist/job-actions.js

@@ -1,5 +1,6 @@
 import { transitionJobEvent } from './scheduler.js';
 import { tryApplyTaskCancelAction } from './task-actions.js';
+import { decideJobLifecycle, dispatchJobLifecycleSync } from './workflow/lifecycle.js';
 export const JOB_ACTIVATE_ACTION = 'job.activate';
 export const JOB_CANCEL_ACTION = 'job.cancel';
 async function transitionJobAction(job, event, action) {
@@ -34,8 +35,36 @@ async function cancelActiveWork(store, job, reason) {
         await store.saveTask(task);
     }
 }
+function cancelActiveWorkSnapshot(job, reason) {
+    for (const plan of (job.plans ?? []).filter(item => item.status === 'PLANNING')) {
+        plan.status = 'FAILED';
+        plan.error = reason;
+        plan.assessment = `Planning failed: ${reason}`;
+        plan.leaseOwner = null;
+        plan.leaseExpiresAt = null;
+        plan.executionId = null;
+        plan.updatedAt = new Date().toISOString();
+    }
+    for (const task of job.tasks)
+        tryApplyTaskCancelAction(task, reason);
+}
 export async function applyJobCancelAction(store, job, reason = 'Job cancelled') {
     const from = job.state;
+    if (store.mutateJob) {
+        const updated = await store.mutateJob(job.id, current => {
+            const decision = decideJobLifecycle(current, 'cancel');
+            if (!decision.accepted)
+                throw new Error(`Job ${current.id} is not cancellable (${current.state})`);
+            dispatchJobLifecycleSync(current, 'cancel');
+            if (!decision.actions.includes('effect.cancelActiveTasks'))
+                throw new Error('Unsupported job.cancel effect');
+            cancelActiveWorkSnapshot(current, reason);
+            current.updatedAt = new Date().toISOString();
+            return current;
+        });
+        Object.assign(job, structuredClone(updated));
+        return job;
+    }
     try {
         await transitionJobEvent(job, 'cancel', {}, async (actionId) => {
             if (actionId !== 'effect.cancelActiveTasks')

package/dist/local-authority-store.js

@@ -262,11 +262,20 @@ export class LocalAuthorityDurableStore {
             return job;
         });
     }
-    async mutate(jobId, mutation) {
+    /**
+     * Apply all related lifecycle changes to one freshly loaded Job snapshot.
+     * RelayStore owns the SQLite transaction; callers must not call saveJob,
+     * savePlan, or saveTask from inside this callback.
+     */
+    async mutateJob(jobId, mutation) {
         if (!this.authority.mutateJob)
             throw new Error('Atomic SQLite mutation is required for local lifecycle authority');
         const changed = await this.authority.mutateJob(jobId, mutation);
         publishLocalCommit(changed);
+        return structuredClone(changed);
+    }
+    async mutate(jobId, mutation) {
+        await this.mutateJob(jobId, mutation);
     }
     async listAgents() {
         return structuredClone(await this.authority.loadAgents() ?? []);

package/dist/local-commit-events.js

@@ -1,6 +1,8 @@
 const listeners = new Set();
 /** Notify dashboard listeners only after authoritative SQLite state is committed. */
 export function publishLocalCommit(job) {
+    // Notify after commit. A listener failure may be surfaced to the caller,
+    // but it can never roll back the already-committed SQLite snapshot.
     for (const listener of listeners)
         listener(structuredClone(job));
 }

package/dist/local-git-merge.js

@@ -29,6 +29,14 @@ export function localMergeEligible(job) {
         implementationComplete(job) && completionGateSatisfied(job) &&
         (job.reviewEnabled === false || job.review?.outcome === 'approved');
 }
+export function localMergeCommitMessage(request, sourceSha) {
+    const lines = ['Agents Relay local merge', '', `Agents-Relay-Source-SHA: ${sourceSha}`];
+    if (request.correlationJobId)
+        lines.push(`Agents-Relay-Job: ${request.correlationJobId}`);
+    if (Number.isInteger(request.displayPrNumber) && Number(request.displayPrNumber) > 0)
+        lines.push(`Agents-Relay-Display-PR: ${request.displayPrNumber}`);
+    return lines.join('\n');
+}
 function checkedOutTarget(repoPath, targetRef) {
     const records = git(repoPath, 'worktree', 'list', '--porcelain').split(/\n\n/);
     const paths = records.filter(record => record.split('\n').includes('branch ' + targetRef))
@@ -39,7 +47,7 @@ function checkedOutTarget(repoPath, targetRef) {
     return paths[0] ?? null;
 }
 /** Merge a checked-out branch using Git porcelain so its worktree and index stay coherent. */
-function mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha) {
+function mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha, message) {
     const worktree = checkedOutTarget(repoPath, targetRef);
     if (!worktree)
         throw new Error('Target worktree disappeared before local merge');
@@ -47,8 +55,8 @@ function mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha) {
         || git(worktree, 'rev-parse', 'HEAD') !== targetSha) {
         throw new Error('Local merge target moved before delivery');
     }
-    if (git(worktree, 'status', '--porcelain', '--untracked-files=all')) {
-        throw new Error('Local merge target worktree is not clean');
+    if (git(worktree, 'status', '--porcelain', '--untracked-files=no')) {
+        throw new Error('Local merge target worktree has tracked or index changes');
     }
     if (existsSync(resolve(worktree, git(worktree, 'rev-parse', '--git-path', 'MERGE_HEAD')))) {
         throw new Error('Existing MERGE_HEAD is not owned by Relay; manual resolution required');
@@ -56,7 +64,7 @@ function mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha) {
     // No checkout, reset or force update. Git controls index and working tree,
     // reports conflicts and leaves a recoverable merge state when interrupted.
     try {
-        git(worktree, 'merge', '--no-ff', '--no-edit', '-m', 'Agents Relay local merge', sourceSha);
+        git(worktree, 'merge', '--no-ff', '--no-edit', '-m', message, sourceSha);
     }
     catch (error) {
         // Only a MERGE_HEAD matching our exact source SHA can be attributed to
@@ -86,6 +94,8 @@ function mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha) {
 /** Deliver to a Git ref without ever updating a checked-out ref behind Git's back. */
 export function deliverLocalMerge(repoPath, request) {
     const sourceRef = ref(request.sourceRef), targetRef = ref(request.targetRef);
+    if (targetRef !== 'refs/heads/main')
+        throw new Error('Local Git merge target must always be refs/heads/main');
     if (sourceRef === targetRef)
         throw new Error('Local merge source and target must differ');
     const commonDir = resolve(repoPath, git(repoPath, 'rev-parse', '--git-common-dir'));
@@ -99,14 +109,15 @@ export function deliverLocalMerge(repoPath, request) {
             return { sourceSha, mergedCommitSha: targetSha }; // Idempotent after acknowledged or crashed delivery.
         }
         catch { /* merge required */ }
+        const message = localMergeCommitMessage(request, sourceSha);
         if (checkedOutTarget(repoPath, targetRef)) {
-            return { sourceSha, mergedCommitSha: mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha) };
+            return { sourceSha, mergedCommitSha: mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha, message) };
         }
         // Unchecked-out refs can be updated atomically without touching any worktree.
         const tree = git(repoPath, 'merge-tree', '--write-tree', targetSha, sourceSha).split('\n')[0];
         if (!/^[0-9a-f]{40,64}$/.test(tree))
             throw new Error('Local merge-tree returned no valid tree');
-        const mergedCommitSha = git(repoPath, 'commit-tree', tree, '-p', targetSha, '-p', sourceSha, '-m', 'Agents Relay local merge');
+        const mergedCommitSha = git(repoPath, 'commit-tree', tree, '-p', targetSha, '-p', sourceSha, '-m', message);
         git(repoPath, 'update-ref', targetRef, mergedCommitSha, targetSha);
         return { sourceSha, mergedCommitSha };
     });

package/dist/local-job-registry.js

@@ -1,8 +1,8 @@
-import { InMemoryStore } from './store.js';
+import { GitHubStore, InMemoryStore } from './store.js';
 import { LocalAuthorityDurableStore } from './local-authority-store.js';
 import { discoverLocalRelayStoreSnapshots, SQLiteRelayStore } from './relay-store.js';
 /** Resolve exactly one SQLite-backed Job from its immutable ID, independent of PR binding. */
-export function createJobIdRegistryResolver(directory, openStores) {
+export function createJobIdRegistryResolver(directory, openStores, options = {}) {
     return async (jobId) => {
         const snapshots = await discoverLocalRelayStoreSnapshots(directory);
         const matches = snapshots.flatMap(snapshot => snapshot.jobs.filter(job => job.id === jobId).map(job => ({ snapshot, job })));
@@ -17,7 +17,13 @@ export function createJobIdRegistryResolver(directory, openStores) {
             relay = new SQLiteRelayStore(snapshot.path);
             openStores.set(snapshot.path, relay);
         }
-        // The GitHub adapter cannot enter the lifecycle execution store.
-        return { job, relay, store: new LocalAuthorityDurableStore(relay, new InMemoryStore(), undefined, true) };
+        // SQLite remains lifecycle authority. A positive PR binding only enables
+        // the external collaboration adapter for projection/merge side effects.
+        const externalPrNumber = job.externalPrNumber ?? (job.prNumber > 0 ? job.prNumber : 0);
+        const githubEnabled = !options.noGitHub && externalPrNumber > 0 && options.client;
+        const github = githubEnabled
+            ? new GitHubStore(options.client, job.repository, externalPrNumber, options.trustedAuthors ?? new Set())
+            : new InMemoryStore();
+        return { job, relay, store: new LocalAuthorityDurableStore(relay, github, undefined, !githubEnabled) };
     };
 }

package/dist/local-merge-delivery.js

@@ -27,8 +27,9 @@ export async function reconcileLocalGitCompletion(store, finalState, headSha, no
                     if (!projectPathForJob)
                         throw new Error('Local Git merge requires an explicit project path');
                     const repoPath = await projectPathForJob(finalState);
-                    const delivered = deliverLocalMerge(repoPath, { ...activeReceipt, sourceSha: activeReceipt.sourceSha ?? headSha ?? undefined });
-                    finalState.localMerge = { ...activeReceipt, ...delivered, status: 'succeeded',
+                    const delivered = deliverLocalMerge(repoPath, { ...activeReceipt, sourceSha: activeReceipt.sourceSha ?? headSha ?? undefined,
+                        correlationJobId: finalState.id, displayPrNumber: finalState.externalPrNumber ?? (finalState.prNumber > 0 ? finalState.prNumber : undefined) });
+                    finalState.localMerge = { ...activeReceipt, ...delivered, status: 'succeeded', projectionStrategy: 'target_ref_push',
                         error: undefined, nextAttemptAt: undefined, updatedAt: new Date().toISOString() };
                 }
                 catch (error) {

package/dist/local-merge-projection.js

@@ -0,0 +1,60 @@
+import { execFileSync } from 'node:child_process';
+function git(cwd, ...args) {
+    return execFileSync('git', ['-C', cwd, ...args], {
+        encoding: 'utf8', timeout: 120000, maxBuffer: 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    }).trim();
+}
+function branchRef(name) {
+    if (!/^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name) || name.includes('..') || name.endsWith('.lock'))
+        throw new Error('Local merge projection requires explicit refs/heads/ target');
+    return name;
+}
+function validSha(value, label) {
+    if (!value || !/^[0-9a-f]{40,64}$/.test(value))
+        throw new Error(`Local merge projection requires valid ${label} SHA`);
+    return value;
+}
+/**
+ * Publish SQLite-authoritative local main using a normal fast-forward push.
+ * GitHub never performs a second merge. Divergence is retried only after
+ * an operator or a separate Git synchronization workflow resolves it.
+ */
+export function projectAuthoritativeLocalMerge(repoPath, job) {
+    const receipt = job.localMerge;
+    if (job.state !== 'COMPLETED' || receipt?.status !== 'succeeded')
+        throw new Error('Authoritative local merge projection requires COMPLETED Job with succeeded merge receipt');
+    const targetRef = branchRef(receipt.targetRef);
+    if (targetRef !== 'refs/heads/main')
+        throw new Error('Local Git target must always be refs/heads/main');
+    const sourceSha = validSha(receipt.sourceSha, 'source');
+    const mergedCommitSha = validSha(receipt.mergedCommitSha, 'merged commit');
+    const localTargetSha = git(repoPath, 'rev-parse', '--verify', targetRef);
+    if (localTargetSha !== mergedCommitSha) {
+        try {
+            git(repoPath, 'merge-base', '--is-ancestor', mergedCommitSha, localTargetSha);
+        }
+        catch {
+            throw new Error(`Local merge target ${targetRef} diverged after authoritative delivery for ${job.id}`);
+        }
+    }
+    const branch = targetRef.slice('refs/heads/'.length);
+    const remoteTracking = `refs/remotes/origin/${branch}`;
+    git(repoPath, 'fetch', '--no-tags', 'origin', `+${targetRef}:${remoteTracking}`);
+    const remoteTargetSha = git(repoPath, 'rev-parse', '--verify', remoteTracking);
+    try {
+        git(repoPath, 'merge-base', '--is-ancestor', localTargetSha, remoteTargetSha);
+        return { targetRef, localMergedCommitSha: mergedCommitSha, remoteTargetSha, projectedCommitSha: remoteTargetSha, status: 'already_projected' };
+    }
+    catch { /* remote projection required */ }
+    // GitHub mirrors the SQLite-authoritative local main; it must never synthesize
+    // a second merge or rewrite the tree when the remote has diverged.
+    try {
+        git(repoPath, 'merge-base', '--is-ancestor', remoteTargetSha, localTargetSha);
+    }
+    catch {
+        throw new Error(`GitHub sync deferred: origin/${branch} diverged from authoritative local main; resolve the remote conflict without force push`);
+    }
+    git(repoPath, 'push', 'origin', `${targetRef}:${targetRef}`);
+    return { targetRef, localMergedCommitSha: mergedCommitSha, remoteTargetSha, projectedCommitSha: localTargetSha, status: 'projected' };
+}

package/dist/managed-worker-input.js

@@ -4,7 +4,10 @@ import { createReviewChairExecutionPlan } from './review-chair.js';
 import { taskTagWorkerPrompt } from './task-tag.js';
 import { executionEventSource } from './reconciler-runtime.js';
 export async function managedWorkerInput(job, task, context) {
-    if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository || job.prNumber <= 0)
+    const isLocalJob = job.prNumber === 0;
+    const externalPrNumber = job.externalPrNumber && job.externalPrNumber > 0 ? job.externalPrNumber : (job.prNumber > 0 ? job.prNumber : 0);
+    const projectedReview = isLocalJob && task.agentName === 'reviewer' && externalPrNumber > 0;
+    if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository)
         return task.input;
     const selectedAgent = task.agentName && context ? await agentContractPrompt(context, task.agentName) : '';
     const selectedGraph = task.agentGraph && context ? await agentGraphPrompt(context, task.agentGraph) : '';
@@ -16,19 +19,23 @@ export async function managedWorkerInput(job, task, context) {
     if (!task.executionId)
         throw new Error(`Task ${task.id} requires an executionId before worker input is built`);
     const sourceId = executionEventSource(job.id, task.id, task.executionId);
-    const prUrl = `https://github.com/${job.repository}/pull/${job.prNumber}`;
-    const taskUrl = task.taskUrl ?? `${prUrl}#issuecomment-${task.id}`;
+    const prUrl = externalPrNumber > 0 ? `https://github.com/${job.repository}/pull/${externalPrNumber}` : null;
+    const taskUrl = task.taskUrl ?? (isLocalJob ? `local:${job.id}/task/${task.id}` : `${prUrl}#issuecomment-${task.id}`);
     const output = task.output.kind === 'file'
         ? `file\nPath: ${task.output.path}`
-        : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`;
+        : (projectedReview ? `task/PR\nProjected PR: ${prUrl}\nTask: ${task.id}` : isLocalJob ? `task/PR\nTask: ${task.id}` : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`);
     const taskTag = taskTagWorkerPrompt(job);
     return `[Agents Relay managed task]
-Job URL: ${prUrl}
+${projectedReview ? `Job: local ${job.id} (lifecycle authority)\nProjected GitHub PR: ${prUrl}` : isLocalJob ? `Job: local ${job.id}` : `Job URL: ${prUrl}`}
 Job ID: ${job.id}
 Task URL: ${taskUrl}
 Task ID: ${task.id}
 Project: ${task.projectName ?? context?.project.name ?? 'unspecified'}
-Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.
+${projectedReview
+        ? `The local SQLite Job is the lifecycle authority. The projected GitHub PR exists only for artifact/head verification. Review the projected PR at ${prUrl} and verify its exact immutable head against the durable review task input below. Do not use GitHub comments or PR metadata as lifecycle authority.\n\n${task.input}`
+        : isLocalJob
+            ? `Treat the following durable task input as the authoritative work contract; do not query GitHub.\n\n${task.input}`
+            : `Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.`}
 ${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? selectedAgent + '\n\n' : ''}${selectedGraph ? selectedGraph + '\n\n' : ''}${chairPlan ? `[Review Chair execution plan]\n${JSON.stringify(chairPlan, null, 2)}\n\nUse this runtime-discovered panel to create sibling durable specialist Tasks. Preserve each specialistTasks entry as review metadata, keep the target immutable, and synthesize structured results with synthesizeReview semantics before returning the unified revision plan.\n\n` : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
 [Output contract]
 ${output}

package/dist/manual-plan.js

@@ -7,14 +7,36 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
     const active = pendingPlan(job);
     if (active && active.executionId)
         throw new Error(`Planning round ${active.id} is already PLANNING`);
-    const round = active ?? createPlanRound(job, { guidance, manual: true, timeoutMs });
-    if (!active)
-        await store.appendPlan(round);
-    job = await store.load(jobId);
-    if (job.state === 'DRAFT') {
-        await applyJobActivateAction(job);
-        await store.saveJob(job);
+    let round = active ?? createPlanRound(job, { guidance, manual: true, timeoutMs });
+    if (store.mutateJob) {
+        const committed = await store.mutateJob(jobId, current => {
+            if (['COMPLETED', 'CANCELLED'].includes(current.state))
+                throw new Error(`Cannot plan terminal job ${current.id} (${current.state})`);
+            const concurrent = pendingPlan(current);
+            if (concurrent) {
+                if (concurrent.executionId)
+                    throw new Error(`Planning round ${concurrent.id} is already PLANNING`);
+                round = structuredClone(concurrent);
+            }
+            else {
+                round = createPlanRound(current, { guidance, manual: true, timeoutMs });
+                current.plans = [...(current.plans ?? []), structuredClone(round)].sort((a, b) => a.round - b.round);
+            }
+            if (current.state === 'DRAFT')
+                applyJobActivateAction(current);
+            return current;
+        });
+        job = structuredClone(committed);
+    }
+    else {
+        if (!active)
+            await store.appendPlan(round);
         job = await store.load(jobId);
+        if (job.state === 'DRAFT') {
+            await applyJobActivateAction(job);
+            await store.saveJob(job);
+            job = await store.load(jobId);
+        }
     }
     const durableRound = (job.plans ?? []).find(plan => plan.id === round.id);
     if (!durableRound)