agents-relay 2.0.67 → 2.0.69

package/dist/local-authority-store.js

@@ -0,0 +1,288 @@
+import { GitHubProjectionWriter } from './projected-store.js';
+import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
+import { samePlanDefinition, sameTaskDefinition, DurableDefinitionConflictError, planDefinitionDivergence, taskDefinitionDivergence } from './store-task-definition.js';
+import { mergeInboundJobSnapshot } from './relay-store.js';
+import { publishLocalCommit } from './local-commit-events.js';
+import { decideScheduledRun } from './workflow/scheduled-run-v2.js';
+import { nextScheduleRun, scheduleBucket } from './scheduler.js';
+/**
+ * V2 authoritative lifecycle boundary.
+ *
+ * Job, Plan, Task and Agent reads/writes are SQLite-only. No GitHub marker,
+ * remote snapshot, or projection result can create, recover, or mutate them.
+ * Inherited PR merge/close/head interfaces are external collaboration adapters,
+ * not lifecycle storage. An explicit one-time import must use RelayStore directly.
+ */
+const TASK_STATE_ORDER = {
+    DRAFT: 0, QUEUED: 1, UNBLOCKED: 2, RUNNING: 3, BLOCKED: 4,
+    SUCCEEDED: 5, FAILED: 5, CANCELLED: 5,
+};
+export class LocalAuthorityDurableStore {
+    authority;
+    relatedStore;
+    noGitHub;
+    projection;
+    constructor(authority, github, relatedStore, noGitHub = false) {
+        this.authority = authority;
+        this.relatedStore = relatedStore;
+        this.noGitHub = noGitHub;
+        this.projection = new GitHubProjectionWriter(authority, github, undefined, true);
+    }
+    /** Queue one retryable PR merge; do not mutate Job lifecycle until external confirmation. */
+    async mergePullRequest(expectedHeadSha) {
+        if (this.noGitHub)
+            throw new Error('Remote merge unavailable with --no-github; local Graph completion is separate');
+        if (!expectedHeadSha)
+            throw new Error('External merge requires immutable expected head SHA');
+        const facts = await this.authority.loadPullRequestFacts();
+        if (facts?.state === 'MERGED')
+            return;
+        if (facts?.state === 'CLOSED')
+            throw new Error('Cannot merge a PR already known closed');
+        if (!this.authority.enqueueExternalActionOnce)
+            throw new Error('Atomic external action queue is required');
+        await this.authority.enqueueExternalActionOnce({
+            idempotencyKey: `merge_pull_request:${expectedHeadSha}`,
+            operation: 'merge_pull_request',
+            payload: { operation: 'merge_pull_request', expectedHeadSha },
+            priority: 200,
+        });
+    }
+    async closePullRequest() {
+        if (this.noGitHub)
+            return; // Local cancel is persisted by Graph; there is no remote PR.
+        const facts = await this.authority.loadPullRequestFacts();
+        if (facts?.state === 'MERGED')
+            throw new Error('Cannot close a PR already merged');
+        if (facts?.state === 'CLOSED')
+            return;
+        if (!this.authority.enqueueExternalActionOnce)
+            throw new Error('Atomic external action queue is required');
+        await this.authority.enqueueExternalActionOnce({
+            idempotencyKey: 'close_pull_request',
+            operation: 'close_pull_request',
+            payload: { operation: 'close_pull_request' },
+            priority: 200,
+        });
+    }
+    async recordExecutionProcess(record) {
+        await this.authority.recordExecutionProcess(record);
+    }
+    async loadExecutionProcess(jobId, taskId, executionId) {
+        return this.authority.loadExecutionProcess(jobId, taskId, executionId);
+    }
+    async finishExecutionProcess(jobId, taskId, executionId) {
+        await this.authority.finishExecutionProcess(jobId, taskId, executionId);
+    }
+    async applyPullRequestFacts(facts) {
+        await this.authority.savePullRequestFacts(structuredClone(facts));
+    }
+    async headSha() {
+        return (await this.pullRequestHead())?.sha ?? null;
+    }
+    async registerBlockerDependent(jobId, dependent) {
+        if (!this.relatedStore)
+            throw new Error('Related local store factory is required for blocker dependencies');
+        await registerBlockerDependency({
+            blockerStore: this,
+            blockerJobId: jobId,
+            dependentStore: this.relatedStore(dependent.repository, dependent.prNumber),
+            dependentJobId: dependent.jobId,
+            dependentTaskId: dependent.taskId,
+            resolutionMode: dependent.resolutionMode,
+        });
+    }
+    async resolveBlockerDependents(jobId, resolution) {
+        if (!this.relatedStore)
+            throw new Error('Related local store factory is required for blocker dependencies');
+        return resolveBlockerDependencies({
+            blockerStore: this,
+            blockerJobId: jobId,
+            resolution,
+            dependentStore: (repository, prNumber) => this.relatedStore(repository, prNumber),
+        });
+    }
+    async comments() { return []; }
+    async pullRequestState() {
+        return this.noGitHub ? 'UNKNOWN' : (await this.authority.loadPullRequestFacts())?.state ?? 'UNKNOWN';
+    }
+    async pullRequestHead() {
+        return this.noGitHub ? null : (await this.authority.loadPullRequestFacts())?.head ?? null;
+    }
+    async hydrate(_job) {
+        // GitHub snapshots cannot overwrite or create authoritative lifecycle state.
+    }
+    async load(jobId) {
+        const job = await this.authority.loadJob(jobId);
+        if (!job)
+            throw new Error(`Local authoritative Job ${jobId} not found`);
+        return structuredClone(job);
+    }
+    async saveJob(job) {
+        const incoming = structuredClone(job);
+        const existing = await this.authority.loadJob(job.id);
+        if (!existing) {
+            await this.authority.saveJob(incoming);
+            Object.assign(job, structuredClone(incoming));
+            publishLocalCommit(incoming);
+            return;
+        }
+        if (!this.authority.mutateJob)
+            throw new Error('Atomic SQLite mutation is required for local lifecycle authority');
+        const updated = await this.authority.mutateJob(job.id, current => {
+            const children = mergeInboundJobSnapshot(current, incoming);
+            const preserveTerminal = ['COMPLETED', 'CANCELLED'].includes(current.state)
+                && !['COMPLETED', 'CANCELLED'].includes(incoming.state);
+            const review = current.review && incoming.review
+                && current.review.updatedAt > incoming.review.updatedAt
+                ? current.review : incoming.review;
+            // Job-level scalar fields obey snapshot freshness. Graph transitions
+            // may commit review evidence after a preceding effect has already saved
+            // the Job; review itself is merged independently by review.updatedAt.
+            const scalarSource = incoming.updatedAt > current.updatedAt ? incoming : current;
+            return {
+                ...current, ...scalarSource,
+                state: preserveTerminal ? current.state : scalarSource.state,
+                updatedAt: current.updatedAt > incoming.updatedAt ? current.updatedAt : incoming.updatedAt,
+                tasks: children.tasks,
+                ...(children.plans ? { plans: children.plans } : {}),
+                ...(review !== undefined ? { review } : {}),
+            };
+        });
+        Object.assign(job, structuredClone(updated));
+        publishLocalCommit(updated);
+    }
+    /** Claim a schedule slot under one SQLite IMMEDIATE transaction, across all processes. */
+    async claimScheduledSlot(jobId, bucket, now) {
+        if (!this.authority.mutateJob)
+            throw new Error('Atomic SQLite schedule claim is required');
+        let status = 'skipped-idempotent';
+        const result = await this.authority.mutateJob(jobId, current => {
+            const schedule = current.schedule;
+            if (!schedule)
+                throw new Error('Scheduled Job ' + jobId + ' has no schedule metadata');
+            const slot = new Date(schedule.nextRunAt);
+            const decision = decideScheduledRun({
+                slotDue: scheduleBucket(slot) === bucket && slot.getTime() <= now.getTime(),
+                slotUnclaimed: !schedule.lastScheduledSlot || new Date(schedule.lastScheduledSlot).getTime() < slot.getTime(),
+                jobActive: current.state === 'ACTIVE',
+                hasActiveTasks: current.tasks.some(task => ['QUEUED', 'RUNNING'].includes(task.state)),
+                concurrencySkip: schedule.concurrencyPolicy === 'skip',
+                concurrencyQueue: schedule.concurrencyPolicy === 'queue',
+                runMissed: schedule.missedRunPolicy === 'run',
+            });
+            const action = decision.accepted ? decision.actions[0]?.id : undefined;
+            if (action === 'schedule.skipActiveAdvance') {
+                schedule.lastScheduledSlot = slot.toISOString();
+                schedule.nextRunAt = nextScheduleRun(schedule, now).toISOString();
+                status = 'skipped-active';
+            }
+            else if (action === 'schedule.claimFromSlot' || action === 'schedule.claimFromNow') {
+                schedule.lastScheduledSlot = slot.toISOString();
+                schedule.currentRunSlot = slot.toISOString();
+                schedule.nextRunAt = nextScheduleRun(schedule, action === 'schedule.claimFromSlot' ? slot : now).toISOString();
+                status = 'completed';
+            }
+            if (status !== 'skipped-idempotent')
+                current.updatedAt = now.toISOString();
+            return current;
+        });
+        if (status !== 'skipped-idempotent')
+            publishLocalCommit(result);
+        return { job: result, status };
+    }
+    /** Persist completion only if this is still the authoritative claimed slot. */
+    async finishScheduledSlot(jobId, slot, now) {
+        if (!this.authority.mutateJob)
+            throw new Error('Atomic SQLite schedule completion is required');
+        const result = await this.authority.mutateJob(jobId, current => {
+            if (current.schedule?.currentRunSlot !== slot)
+                return current;
+            if (!current.schedule.lastRunAt || Date.parse(current.schedule.lastRunAt) < now.getTime()) {
+                current.schedule.lastRunAt = now.toISOString();
+                current.updatedAt = now.toISOString();
+            }
+            return current;
+        });
+        publishLocalCommit(result);
+        return result;
+    }
+    async appendPlan(plan) {
+        await this.mutate(plan.jobId, job => {
+            const existing = (job.plans ?? []).find(item => item.id === plan.id);
+            if (existing) {
+                if (samePlanDefinition(existing, plan))
+                    return job;
+                throw new DurableDefinitionConflictError('plan', 'append_plan', plan.jobId, plan.id, plan, existing, planDefinitionDivergence(existing, plan));
+            }
+            job.plans = [...(job.plans ?? []), structuredClone(plan)].sort((a, b) => a.round - b.round);
+            return job;
+        });
+    }
+    async savePlan(plan) {
+        await this.mutate(plan.jobId, job => {
+            const plans = [...(job.plans ?? [])];
+            const index = plans.findIndex(item => item.id === plan.id);
+            if (index < 0)
+                plans.push(structuredClone(plan));
+            else if (plans[index].updatedAt <= plan.updatedAt)
+                plans[index] = structuredClone(plan);
+            job.plans = plans.sort((a, b) => a.round - b.round);
+            return job;
+        });
+    }
+    async appendTask(task) {
+        if (!task.jobId)
+            throw new Error('Local authoritative task requires jobId');
+        await this.mutate(task.jobId, job => {
+            const existing = job.tasks.find(item => item.id === task.id);
+            if (existing) {
+                if (sameTaskDefinition(existing, task))
+                    return job;
+                throw new DurableDefinitionConflictError('task', 'append_task', task.jobId, task.id, task, existing, taskDefinitionDivergence(existing, task));
+            }
+            job.tasks.push(structuredClone(task));
+            return job;
+        });
+    }
+    async saveTask(task) {
+        if (!task.jobId)
+            throw new Error('Local authoritative task requires jobId');
+        await this.mutate(task.jobId, job => {
+            const index = job.tasks.findIndex(item => item.id === task.id);
+            if (index < 0)
+                throw new Error(`Local authoritative Task ${task.id} not found`);
+            const current = job.tasks[index];
+            if (current.attempt > task.attempt || current.updatedAt > task.updatedAt)
+                return job;
+            if (current.attempt === task.attempt && current.updatedAt === task.updatedAt
+                && TASK_STATE_ORDER[current.state] >= TASK_STATE_ORDER[task.state])
+                return job;
+            job.tasks[index] = structuredClone(task);
+            return job;
+        });
+    }
+    /**
+     * 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() ?? []);
+    }
+    async saveAgent(agent) {
+        if (!this.authority.upsertAgent)
+            throw new Error('Atomic SQLite agent upsert is required');
+        await this.authority.upsertAgent(structuredClone(agent));
+    }
+}

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

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import { withLocalMergeLock } from './local-merge-lock.js';
+import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { implementationComplete } from './runtime-status.js';
+import { completionGateSatisfied } from './scheduler.js';
+function git(cwd, ...args) {
+    return execFileSync('git', ['-C', cwd, ...args], {
+        encoding: 'utf8', timeout: 30000, maxBuffer: 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    }).trim();
+}
+function ref(name) {
+    if (!/^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name) || name.includes('..') || name.endsWith('.lock'))
+        throw new Error('Local merge requires explicit refs/heads/ branch references');
+    return name;
+}
+export function localWorkingHead(repoPath) {
+    return git(repoPath, 'rev-parse', '--verify', 'HEAD');
+}
+export function localSourceHead(repoPath, sourceRef) {
+    return git(repoPath, 'rev-parse', '--verify', ref(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 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))
+        .map(record => record.split('\n').find(line => line.startsWith('worktree '))?.slice(9))
+        .filter((path) => Boolean(path));
+    if (paths.length > 1)
+        throw new Error('Local merge target has multiple checked-out worktrees');
+    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, message) {
+    const worktree = checkedOutTarget(repoPath, targetRef);
+    if (!worktree)
+        throw new Error('Target worktree disappeared before local merge');
+    if (git(worktree, 'symbolic-ref', 'HEAD') !== targetRef
+        || git(worktree, 'rev-parse', 'HEAD') !== targetSha) {
+        throw new Error('Local merge target moved before delivery');
+    }
+    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');
+    }
+    // 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', message, sourceSha);
+    }
+    catch (error) {
+        // Only a MERGE_HEAD matching our exact source SHA can be attributed to
+        // this delivery. Never abort a concurrent user's unrelated merge.
+        const mergeHead = resolve(worktree, git(worktree, 'rev-parse', '--git-path', 'MERGE_HEAD'));
+        if (existsSync(mergeHead)) {
+            try {
+                const mergeMessage = resolve(worktree, git(worktree, 'rev-parse', '--git-path', 'MERGE_MSG'));
+                if (readFileSync(mergeHead, 'utf8').trim() === sourceSha
+                    && existsSync(mergeMessage)
+                    && readFileSync(mergeMessage, 'utf8').startsWith('Agents Relay local merge')
+                    && git(worktree, 'rev-parse', 'HEAD') === targetSha) {
+                    git(worktree, 'merge', '--abort');
+                }
+            }
+            catch { /* Leave unidentified merge state for manual resolution. */ }
+        }
+        throw error;
+    }
+    const result = git(worktree, 'rev-parse', 'HEAD');
+    const parents = git(worktree, 'rev-list', '--parents', '-n', '1', result).split(' ');
+    if (parents[1] !== targetSha || parents[2] !== sourceSha) {
+        throw new Error('Unexpected local merge commit parentage; manual verification required');
+    }
+    return result;
+}
+/** 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'));
+    return withLocalMergeLock(commonDir, targetRef, () => {
+        const sourceSha = localSourceHead(repoPath, sourceRef);
+        if (request.sourceSha && sourceSha !== request.sourceSha)
+            throw new Error('Local merge source SHA changed after review');
+        const targetSha = git(repoPath, 'rev-parse', '--verify', targetRef);
+        try {
+            git(repoPath, 'merge-base', '--is-ancestor', sourceSha, targetSha);
+            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, 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', message);
+        git(repoPath, 'update-ref', targetRef, mergedCommitSha, targetSha);
+        return { sourceSha, mergedCommitSha };
+    });
+}

package/dist/local-job-path.js

@@ -0,0 +1,7 @@
+import { createHash } from 'node:crypto';
+/** Primary local store key is immutable Job ID, independent of a PR number. */
+export function relayJobStorePath(directory, jobId) {
+    if (!jobId.trim() || jobId.length > 1024)
+        throw new Error('Invalid immutable Job ID');
+    return directory + '/job-' + createHash('sha256').update(jobId).digest('hex') + '.db';
+}

package/dist/local-job-registry.js

@@ -0,0 +1,29 @@
+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, 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 })));
+        // Retain historical terminal snapshots without shadowing a uniquely live Job.
+        const live = matches.filter(item => !['COMPLETED', 'CANCELLED'].includes(item.job.state));
+        const selected = live.length === 1 ? live[0] : live.length === 0 && matches.length === 1 ? matches[0] : null;
+        if (!selected)
+            return null;
+        const { snapshot, job } = selected;
+        let relay = openStores.get(snapshot.path);
+        if (!relay) {
+            relay = new SQLiteRelayStore(snapshot.path);
+            openStores.set(snapshot.path, relay);
+        }
+        // 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-managed-store.js

@@ -0,0 +1,21 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { GhApiClient } from './github-client.js';
+import { DisabledGitHubClient, noGitHubMode } from './no-github.js';
+import { GitHubStore } from './store.js';
+import { LocalAuthorityDurableStore } from './local-authority-store.js';
+import { relayStorePath, relayJobStorePath, SQLiteRelayStore } from './relay-store.js';
+/** Open the canonical V2 SQLite authority without making any GitHub request. */
+export function openLocalManagedStore(repository, prNumber, options = {}) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || repository.includes('..') || !Number.isInteger(prNumber) || prNumber < 0 || (prNumber === 0 && !options.jobId)) {
+        throw new Error('Local managed store requires a repository and either a positive PR number or immutable jobId');
+    }
+    const directory = options.directory ?? join(homedir(), '.agents-relay', 'stores');
+    const relay = new SQLiteRelayStore(prNumber === 0 ? relayJobStorePath(directory, options.jobId) : relayStorePath(directory, repository, prNumber));
+    const client = prNumber === 0 || options.noGitHub || noGitHubMode() ? new DisabledGitHubClient() : options.client ?? new GhApiClient();
+    const github = new GitHubStore(client, repository, prNumber, options.trustedAuthors ?? new Set());
+    return {
+        relay,
+        store: new LocalAuthorityDurableStore(relay, github, (relatedRepository, relatedPr) => openLocalManagedStore(relatedRepository, relatedPr, options).store, options.noGitHub || noGitHubMode()),
+    };
+}

package/dist/local-merge-delivery.js

@@ -0,0 +1,53 @@
+import { transitionJobEvent } from './scheduler.js';
+import { deliverLocalMerge, localMergeEligible, requiresLocalGitMerge } from './local-git-merge.js';
+import { errorMessage } from './observability.js';
+/** Graph-selected durable local merge and completion; no checked-out worktree is ever changed. */
+export async function reconcileLocalGitCompletion(store, finalState, headSha, noGitHub, projectPathForJob) {
+    if (localMergeEligible(finalState) && !requiresLocalGitMerge(finalState)) {
+        await transitionJobEvent(finalState, 'local.completed', { localCompletionAllowed: true });
+        await store.saveJob(finalState);
+        return true;
+    }
+    if (localMergeEligible(finalState) &&
+        finalState.localMerge && (!finalState.reviewEnabled || finalState.review?.headSha === headSha)) {
+        const receipt = finalState.localMerge;
+        let activeReceipt = receipt;
+        if (receipt.status !== 'succeeded' &&
+            (!receipt.nextAttemptAt || Date.parse(receipt.nextAttemptAt) <= Date.now())) {
+            await transitionJobEvent(finalState, 'local.merge.requested', { localMergeReady: true }, async (actionId) => {
+                if (actionId !== 'effect.deliverLocalMerge')
+                    throw new Error('Unsupported local merge Graph effect ' + actionId);
+                try {
+                    if (receipt.sourceSha !== headSha && headSha) {
+                        activeReceipt = { ...receipt, sourceSha: headSha, status: 'pending' };
+                        finalState.localMerge = activeReceipt;
+                        finalState.updatedAt = new Date().toISOString();
+                        await store.saveJob(finalState);
+                    }
+                    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,
+                        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) {
+                    const attempts = (activeReceipt.attempts ?? 0) + 1;
+                    finalState.localMerge = { ...activeReceipt, status: 'failed', attempts,
+                        error: errorMessage(error),
+                        nextAttemptAt: new Date(Date.now() + Math.min(300_000, 1000 * (2 ** Math.min(attempts, 8)))).toISOString(),
+                        updatedAt: new Date().toISOString() };
+                }
+                finalState.updatedAt = new Date().toISOString();
+                await store.saveJob(finalState);
+            });
+        }
+        if (finalState.localMerge?.status === 'succeeded') {
+            await transitionJobEvent(finalState, 'local.completed', { localCompletionAllowed: true });
+            await store.saveJob(finalState);
+            return true;
+        }
+    }
+    return false;
+}

package/dist/local-merge-lock.js

@@ -0,0 +1,103 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync, statSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+const sleep = (ms) => {
+    // Synchronous delivery API; Atomics.wait only blocks this worker's thread.
+    const wait = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(wait, 0, 0, ms);
+};
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+/** Cross-process atomic directory lock in the shared Git common directory. */
+export function withLocalMergeLock(commonDir, targetRef, action, timeoutMs = 15000) {
+    const digest = createHash('sha256').update(targetRef).digest('hex').slice(0, 24);
+    const path = join(commonDir, 'agents-relay-merge-' + digest + '.lockdir');
+    const ownerPath = join(path, 'owner.json');
+    const recoveryGuard = path + '.recovery';
+    const guardOwnerPath = join(recoveryGuard, 'owner.json');
+    const incompleteGraceMs = 3000;
+    const deadline = Date.now() + timeoutMs;
+    const owner = { pid: process.pid, host: hostname(), startedAt: new Date().toISOString(), targetRef };
+    while (true) {
+        try {
+            mkdirSync(path);
+            writeFileSync(ownerPath, JSON.stringify(owner), { flag: 'wx', mode: 0o600 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            // Reap a crashed recovery owner, or a crash between mkdir and owner write.
+            // Renaming the orphan into a private quarantine keeps cleanup out of the
+            // active path. A grace period protects slow owner-file initialization.
+            const orphaned = (directory, metadata) => {
+                try {
+                    const age = Date.now() - statSync(directory).mtimeMs;
+                    if (age < incompleteGraceMs)
+                        return false;
+                    try {
+                        const previous = JSON.parse(readFileSync(metadata, 'utf8'));
+                        return previous.host === hostname() && Number.isInteger(previous.pid)
+                            && !processAlive(previous.pid);
+                    }
+                    catch {
+                        return true;
+                    }
+                }
+                catch {
+                    return false;
+                }
+            };
+            if (orphaned(recoveryGuard, guardOwnerPath)) {
+                const quarantine = recoveryGuard + '.orphan-' + process.pid + '-' + createHash('sha256').update(owner.startedAt).digest('hex').slice(0, 10);
+                try {
+                    renameSync(recoveryGuard, quarantine);
+                    rmSync(quarantine, { recursive: true, force: true });
+                }
+                catch { /* another recovery contender may already have moved it */ }
+            }
+            let guarded = false;
+            try {
+                mkdirSync(recoveryGuard);
+                guarded = true;
+                writeFileSync(guardOwnerPath, JSON.stringify(owner), { flag: 'wx', mode: 0o600 });
+                if (orphaned(path, ownerPath))
+                    rmSync(path, { recursive: true, force: true });
+            }
+            catch { /* A live lock or incomplete initialization must be preserved. */ }
+            finally {
+                if (guarded) {
+                    try {
+                        const current = JSON.parse(readFileSync(guardOwnerPath, 'utf8'));
+                        if (current.pid === owner.pid && current.startedAt === owner.startedAt && current.host === owner.host)
+                            rmSync(recoveryGuard, { recursive: true, force: true });
+                    }
+                    catch { /* keep unknown guard */ }
+                }
+            }
+            if (Date.now() >= deadline)
+                throw new Error('Local merge target locked: ' + targetRef);
+            sleep(50);
+        }
+    }
+    try {
+        return action();
+    }
+    finally {
+        // Never release a lock now owned by a different process.
+        try {
+            const current = JSON.parse(readFileSync(ownerPath, 'utf8'));
+            if (current.pid === owner.pid && current.host === owner.host && current.startedAt === owner.startedAt)
+                rmSync(path, { recursive: true, force: true });
+        }
+        catch { /* preserve any unknown lock */ }
+    }
+}