agents-relay 2.0.67 → 2.0.68

package/dist/dashboard.js

@@ -71,7 +71,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
     const discoveredJobs = async (forceRefresh = false) => {
         try {
             const jobs = overviewProvider
-                ? (await overviewProvider(forceRefresh, forceRefresh ? 'dashboard.jobs-refresh' : 'internal.unknown')).map(item => ({ ...item.job, githubState: item.githubState, runtimeStatus: deriveJobRuntimeStatus(item.job, item.githubState), mergedAt: item.mergedAt, closedAt: item.closedAt, draft: item.draft, publication: item.publication }))
+                ? (await overviewProvider(forceRefresh, forceRefresh ? 'dashboard.jobs-refresh' : 'internal.unknown')).map(item => ({ ...item.job, githubState: item.githubState, runtimeStatus: deriveJobRuntimeStatus(item.job, item.githubState), mergedAt: item.mergedAt, closedAt: item.closedAt, draft: item.draft, publication: item.publication, publicationFailure: item.publicationFailure }))
                 : jobId ? [await store.load(jobId)] : [];
             lastKnownJobs = jobs;
             return jobs;

package/dist/github-auth.js

@@ -15,17 +15,18 @@ export function githubAppConfig(args, env = process.env) {
         throw new Error('GitHub App auth requires app id, installation id, and private key file');
     return { appId, installationId, privateKeyFile };
 }
-export async function githubAuthContext(args, env = process.env) {
+export async function githubAuthContext(args, env = process.env, probeLogin = true) {
     const config = githubAppConfig(args, env);
     let options = null;
     if (config)
         options = { appId: config.appId, installationId: config.installationId, privateKey: await readFile(config.privateKeyFile, 'utf8') };
     const client = new GhApiClient(options);
     const trustedAuthors = new Set();
-    trustedAuthors.add(await client.currentLogin());
+    if (probeLogin)
+        trustedAuthors.add(await client.currentLogin());
     for (const author of (value(args, '--trusted-authors') || env.AGENTS_RELAY_TRUSTED_AUTHORS || '').split(',').map(item => item.trim()).filter(Boolean))
         trustedAuthors.add(author);
-    if (options) {
+    if (options && probeLogin) {
         const local = await client.localLogin();
         if (local)
             trustedAuthors.add(local);

package/dist/github-webhook.js

@@ -65,9 +65,11 @@ function pullRequestFacts(payload, action) {
     const sha = typeof head?.sha === 'string' ? head.sha : null;
     if (!ref || !sha)
         return null;
+    const updated = typeof pr.updated_at === 'string' && Number.isFinite(Date.parse(pr.updated_at))
+        ? { observedAt: new Date(pr.updated_at).toISOString() } : {};
     if (action === 'closed')
-        return { state: pr.merged === true ? 'MERGED' : 'CLOSED', head: { ref, sha } };
-    return { state: 'OPEN', head: { ref, sha } };
+        return { state: pr.merged === true ? 'MERGED' : 'CLOSED', head: { ref, sha }, ...updated };
+    return { state: 'OPEN', head: { ref, sha }, ...updated };
 }
 export function parseGitHubWebhook(headers, body) {
     const deliveryId = String(headers['x-github-delivery'] ?? '');
@@ -91,12 +93,18 @@ export function parseGitHubWebhook(headers, body) {
         return null;
     if (event === 'issue_comment') {
         const comment = payload.comment;
-        const publication = parsePackagePublicationMarker(comment?.body);
-        const publishFailure = comment?.user?.login === 'github-actions[bot]'
+        const trustedPublisher = comment?.user?.login === 'github-actions[bot]';
+        const publication = trustedPublisher ? parsePackagePublicationMarker(comment?.body) : null;
+        const publishFailure = trustedPublisher
             ? parsePackagePublishFailureMarker(comment?.body) : null;
         if (!publication && !publishFailure)
             return null;
-        return { deliveryId, event, action, repository: repositoryName, pullRequest: number, publication, ...(publishFailure ? { publishFailure } : {}), pullRequestFacts: 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,
+            ...(publicationObservedAt ? { publicationObservedAt } : {}),
+            ...(publishFailure ? { publishFailure } : {}), pullRequestFacts: null };
     }
     const facts = pullRequestFacts(payload, action);
     if (!facts)

package/dist/local-authority-store.js

@@ -0,0 +1,279 @@
+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;
+        });
+    }
+    async mutate(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);
+    }
+    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-git-merge.js

@@ -0,0 +1,113 @@
+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');
+}
+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) {
+    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=all')) {
+        throw new Error('Local merge target worktree is not clean');
+    }
+    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', 'Agents Relay local merge', 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 (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 */ }
+        if (checkedOutTarget(repoPath, targetRef)) {
+            return { sourceSha, mergedCommitSha: mergeCheckedOutTarget(repoPath, targetRef, sourceSha, targetSha) };
+        }
+        // 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');
+        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,23 @@
+import { 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) {
+    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);
+        }
+        // The GitHub adapter cannot enter the lifecycle execution store.
+        return { job, relay, store: new LocalAuthorityDurableStore(relay, new InMemoryStore(), undefined, true) };
+    };
+}

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,52 @@
+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 });
+                    finalState.localMerge = { ...activeReceipt, ...delivered, status: 'succeeded',
+                        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;
+}