agents-relay 2.0.68 → 2.0.70

package/dist/relayd.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
+import { consumeMethodInjection, withTestInjection } from './e2e-injection.js';
 import { once } from 'node:events';
+import { spawnOwnedProcess } from './owned-process.js';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -8,133 +10,45 @@ import { CodexThreadContinuation, CommandContinuation, WebhookContinuation } fro
 import { serveDashboard } from './dashboard.js';
 import { RepositoryWorkerPool } from './pool.js';
 import { Reconciler } from './reconciler.js';
-import { dashboardManagedJobs, GitHubStore, InMemoryStore } from './store.js';
+import { dashboardManagedJobs, GitHubStore, InMemoryStore, resolvePullRequest } from './store.js';
+import { GitHubProjectionWriter } from './projected-store.js';
 import { LocalAuthorityDurableStore } from './local-authority-store.js';
-import { discoverLocalRelayStoreSnapshots, relayStorePath, SQLiteRelayStore } from './relay-store.js';
+import { discoverLocalRelayStoreSnapshots, relayStoreDirectory, relayStorePath, SQLiteRelayStore } from './relay-store.js';
 import { createJobIdRegistryResolver } from './local-job-registry.js';
-import { GhApiClient } from './github-client.js';
+import { projectAuthoritativeLocalMerge } from './local-merge-projection.js';
+import { archiveDisplayPullRequest } from './github-pr-archive.js';
+import { orderGitHubBindingCandidates } from './github-binding-order.js';
+import { githubAuthContext } from './github-auth.js';
 import { DisabledGitHubClient, noGitHubMode } from './no-github.js';
 import { basename } from 'node:path';
 import { dashboardJobAction, isEntrypoint, runtimePlanner, runtimeReviewer, startService, SERVICE_DEFAULTS } from './cli.js';
-import { eventBusResolutionMessage, publishOrchestratorTaskStarted, publishOrchestratorTaskCompletion, resolveEventBus } from './cli-support.js';
+import { eventBusResolutionMessage, publishOrchestratorTaskStarted, publishOrchestratorTaskCompletion, publishTaskUnblocked, resolveEventBus } from './cli-support.js';
+import { eventFor } from './events.js';
+import { dispatchTaskAction } from './task-actions.js';
+import { isEffectivelyBlocked, unblockAutonomousTasks, unblockTask } from './unblock.js';
+import { registerBlockerDependency } from './blockers.js';
+import { ensureManagedGitHubJob } from './cli-job-create.js';
 import { applyJobActivateAction } from './job-actions.js';
 import { applyOrchestratorStartAction, applyOrchestratorCompleteAction } from './task-actions.js';
 import { managedTaskUpdateHandler } from './task-update.js';
 import { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
-import { defaultWorkspaceRoot, discoverWorkspaceRepositories, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
+import { defaultWorkspaceRoot, discoverWorkspaceRepositories, ensureLocalJobSourceBranch, prepareLocalJobExecutionWorktree, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { deriveJobRuntimeStatus } from './runtime-status.js';
+import { createRuntimeStatusPublisher } from './runtime-status-events.js';
+import { subscribeLocalCommits } from './local-commit-events.js';
 import { decisionMode, executionDecisionEngine } from './decision.js';
 import { JsonlDecisionAuditStore } from './decision-audit.js';
 import { summarizeRuntime } from './runtime-summary.js';
-import { executionRouterRulesPath } from './routing-policy.js';
 import { workerCandidates } from './worker-routing.js';
+import { discoverAgents } from './registry.js';
 import { shutdownOwnedProcesses } from './owned-process.js';
 import { routeExecution } from './execution-routing.js';
-import { RelayObservability, classifyFailure, errorMessage, observability, setObservability } from './observability.js';
-/** Initialize the process-wide structured observability sink once, from environment. */
-export function configureDaemonObservability(env = process.env) {
-    const configured = RelayObservability.fromEnvironment(env);
-    setObservability(configured);
-    return configured;
-}
-export async function overlayOperationalOverviews(overviews, storeFor) {
-    return await Promise.all(overviews.map(async (item) => {
-        const store = storeFor(item.job.repository, item.job.prNumber);
-        await store.hydrate?.(item.job);
-        const job = await store.load(item.job.id);
-        return { ...item, job };
-    }));
-}
-function managedOverviewKey(item) {
-    return item.job.repository + '#' + item.job.prNumber + ':' + item.job.id;
-}
-export function mergeOperationalInventory(current, discovered) {
-    const merged = new Map(current.map(item => [managedOverviewKey(item), item]));
-    for (const item of discovered)
-        merged.set(managedOverviewKey(item), item);
-    return [...merged.values()];
-}
-const PR_REFRESH_COALESCE_MS = 1000;
-export const SCHEDULE_HEARTBEAT_MS = 600_000;
-export function dueScheduledOverviews(overviews, now = new Date()) {
-    return overviews.filter(item => item.job.state === 'ACTIVE' && item.job.executionMode === 'autonomous' && item.job.schedule && Date.parse(item.job.schedule.nextRunAt) <= now.getTime());
-}
-export function shouldCoalescePullRequestRefresh(completedAt, now = Date.now(), force = false) {
-    return !force && completedAt !== null && now >= completedAt && now - completedAt < PR_REFRESH_COALESCE_MS;
-}
-export const daemonHelp = `Agents Relay daemon runs the dashboard and worker pool.
-
-Usage:
-  npx agents-relayd [options]
-
-Options:
-  --no-github             Local-only mode: no GitHub auth, transport, PR, merge, or fetch
-  --repo OWNER/REPO       Watch one repository
-  --workspace PATH        Discover repositories below PATH (default: ~/Workspace)
-  --port PORT             Dashboard port (default: 8787)
-  --concurrency N         Maximum concurrent workers (default: 4)
-  --interval MS           Recovery interval
-  --projection-ms MS      GitHub projection flush interval (default: 1000)
-  --execution-router-rules PATH
-                         Router Rules file (default: ~/.agents-relay/execution-router-rules.md)
-  --events nats            Require NATS event wakeups (otherwise auto-detect reachable NATS)
-
-Legacy single-job mode also accepts --repo OWNER/REPO --pr NUMBER --id JOB_ID.
-
-Examples:
-  npx agents-relayd --repo OWNER/REPO
-  npx agents-relayd --workspace ~/Workspace`;
-function firstStageChoices(decisionInput) {
-    const stages = decisionInput?.stages;
-    if (!Array.isArray(stages) || stages.length === 0)
-        return [];
-    const contract = stages[0].contract;
-    return Array.isArray(contract?.choices) ? contract.choices.filter((item) => typeof item === 'string') : [];
-}
-function value(args, name, fallback = '') { const index = args.indexOf(name); return index >= 0 ? args[index + 1] ?? fallback : fallback; }
-export function normalizeDaemonArguments(argv) {
-    const repository = value(argv, '--repo') || null;
-    const workspaceRoot = value(argv, '--workspace', defaultWorkspaceRoot()) || null;
-    const prValue = value(argv, '--pr');
-    const id = value(argv, '--id');
-    if ((prValue && !id) || (!prValue && id))
-        throw new Error('--pr and --id must be supplied together for legacy single-job mode');
-    if ((prValue || id) && !repository)
-        throw new Error('--repo is required for legacy single-job mode');
-    if (repository && argv.includes('--workspace'))
-        throw new Error('--repo and --workspace are mutually exclusive');
-    const pullRequest = prValue ? Number(prValue) : null;
-    if (pullRequest !== null && (!Number.isInteger(pullRequest) || pullRequest <= 0))
-        throw new Error('--pr must be positive');
-    return { repository, workspaceRoot: repository ? null : workspaceRoot, pullRequest, jobId: id || null, serviceArguments: [...argv] };
-}
-export function recoveryScanRepositories(repositories, cached, dormantProbeIndex = 0) {
-    const byRepository = new Map();
-    for (const item of cached) {
-        const values = byRepository.get(item.job.repository) ?? [];
-        values.push(item);
-        byRepository.set(item.job.repository, values);
-    }
-    const activeOrUnknown = [];
-    const dormant = [];
-    for (const repository of repositories) {
-        const values = byRepository.get(repository);
-        if (!values || values.length === 0 || values.some(item => !['COMPLETED', 'CANCELLED'].includes(item.job.state)))
-            activeOrUnknown.push(repository);
-        else
-            dormant.push(repository);
-    }
-    if (dormant.length === 0)
-        return activeOrUnknown;
-    return [...activeOrUnknown, dormant[Math.abs(dormantProbeIndex) % dormant.length]];
-}
-export function configureExecutionRouterRulesPath(argv) {
-    const explicitRulesPath = value(argv, '--execution-router-rules') || undefined;
-    if (explicitRulesPath)
-        process.env.AGENTS_RELAY_EXECUTION_ROUTER_RULES = executionRouterRulesPath(explicitRulesPath);
-    return executionRouterRulesPath();
-}
+import { classifyFailure, errorMessage, observability } from './observability.js';
+import { createWorkspaceControl } from './relayd-control.js';
+import { createDashboardActions } from './relayd-dashboard-actions.js';
+export { daemonHelp, normalizeDaemonArguments, overlayOperationalOverviews, mergeOperationalInventory, recoveryScanRepositories, shouldCoalescePullRequestRefresh, SCHEDULE_HEARTBEAT_MS, dueScheduledOverviews, configureExecutionRouterRulesPath } from './relayd-utilities.js';
+import { configureDaemonObservability, firstStageChoices, value, daemonHelp, normalizeDaemonArguments, SCHEDULE_HEARTBEAT_MS, dueScheduledOverviews, configureExecutionRouterRulesPath } from './relayd-utilities.js';
 export async function runDaemon(argv) {
     if (argv.includes('--help') || argv.includes('-h')) {
         console.log(daemonHelp);
@@ -156,13 +70,31 @@ export async function runDaemon(argv) {
         await startService([...argv]);
         return;
     }
-    // Local authority starts without GitHub authentication. External audit transport
-    // is optional and may initialize independently after the daemon is online.
-    const client = noGitHub ? new DisabledGitHubClient() : new GhApiClient();
-    const trusted = new Set();
+    // Local authority never depends on GitHub availability, but every enabled
+    // GitHub transport must use the same authenticated context as the CLI. Probe
+    // identity separately so an auth outage is observable without blocking startup.
+    const auth = noGitHub ? null : await githubAuthContext(argv, undefined, false);
+    const client = noGitHub ? new DisabledGitHubClient() : auth.client;
+    const trusted = noGitHub ? new Set() : auth.trustedAuthors;
+    let githubAuthenticated = noGitHub ? false : null;
+    let githubAuthError = null;
+    if (!noGitHub) {
+        try {
+            const login = auth?.appAuth ? await client.currentLogin() : await client.localLogin();
+            if (!login)
+                throw new Error('gh authentication did not return a healthy login');
+            trusted.add(login);
+            githubAuthenticated = true;
+        }
+        catch (error) {
+            githubAuthenticated = false;
+            githubAuthError = errorMessage(error);
+        }
+    }
     const concurrency = Number(value(argv, '--concurrency', '4'));
     const eventResolution = await resolveEventBus([...argv]);
     const bus = eventResolution.bus;
+    const stopRuntimeStatusEvents = bus ? subscribeLocalCommits(createRuntimeStatusPublisher(bus)) : () => { };
     process.stderr.write(`${eventBusResolutionMessage(eventResolution)}\n`);
     const workspaceRoot = noGitHub ? (value(argv, '--project-path') || value(argv, '--workspace') || process.cwd())
         : normalized.workspaceRoot ?? defaultWorkspaceRoot();
@@ -184,7 +116,7 @@ export async function runDaemon(argv) {
         const key = `${repository}#${prNumber}`;
         let relay = relayStores.get(key);
         if (!relay) {
-            relay = new SQLiteRelayStore(relayStorePath(join(homedir(), '.agents-relay', 'stores'), repository, prNumber));
+            relay = new SQLiteRelayStore(relayStorePath(relayStoreDirectory(), repository, prNumber));
             relayStores.set(key, relay);
         }
         const github = new GitHubStore(client, repository, prNumber, trusted, seed);
@@ -195,7 +127,7 @@ export async function runDaemon(argv) {
         return projected;
     };
     // SQLite inventory, not GitHub discovery, defines which repositories exist.
-    const existingInventory = await discoverLocalRelayStoreSnapshots(join(homedir(), '.agents-relay', 'stores'));
+    const existingInventory = await discoverLocalRelayStoreSnapshots(relayStoreDirectory());
     for (const snapshot of existingInventory)
         for (const job of snapshot.jobs) {
             if (!repositories.includes(job.repository))
@@ -204,7 +136,7 @@ export async function runDaemon(argv) {
     if (repositories.length === 0)
         repositories.push('local/' + basename(workspaceRoot));
     const inventoryFromLocal = async () => {
-        const snapshots = await discoverLocalRelayStoreSnapshots(join(homedir(), '.agents-relay', 'stores'));
+        const snapshots = await discoverLocalRelayStoreSnapshots(relayStoreDirectory());
         const known = new Set(repositories);
         const entries = snapshots.flatMap(snapshot => snapshot.jobs.filter(job => known.has(job.repository)).map(job => ({
             job, githubState: snapshot.facts?.state ?? 'UNKNOWN',
@@ -219,7 +151,16 @@ export async function runDaemon(argv) {
         return dashboardManagedJobs(entries.filter(item => !['COMPLETED', 'CANCELLED'].includes(item.job.state) || counts.get(item.job.id) !== 1));
     };
     cachedOverviews = await inventoryFromLocal();
-    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { noGitHub, owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), usageSnapshotProvider: () => usageRegistry.snapshot(), runtimeSummaryProvider: () => ({ chatgptRunning: summarizeRuntime(cachedOverviews.map(item => item.job)).workers.chatgpt }), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), decisionAuditStore, eventBus: bus, reviewer: runtimeReviewer(argv), projectPathForJob: async (job) => resolveRepositoryProjectPath(repositoryPaths.get(job.repository) ?? await resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot), job.projectPath) });
+    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { noGitHub, owner: `relayd-${process.pid}`, maxConcurrent, leaseMs: Number(value(argv, '--lease-ms', '300000')), adapters: [new CodexAdapter(value(argv, '--codex', 'codex')), new ChatGptAdapter()], continuations: [new CodexThreadContinuation(value(argv, '--codex', 'codex')), new CommandContinuation(), new WebhookContinuation()], planner: runtimePlanner(argv), usageSnapshotProvider: () => usageRegistry.snapshot(), runtimeSummaryProvider: () => ({ chatgptRunning: summarizeRuntime(cachedOverviews.map(item => item.job)).workers.chatgpt }), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), decisionAuditStore, eventBus: bus, reviewer: runtimeReviewer(argv), projectPathForJob: async (job) => {
+            const canonical = repositoryPaths.get(job.repository) ?? await resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot);
+            if (job.prNumber !== 0 || job.schedule)
+                return resolveRepositoryProjectPath(canonical, job.projectPath);
+            const sourceRef = await ensureLocalJobSourceBranch(canonical, job);
+            if (!store.mutateJob)
+                throw new Error('Local Job branch binding requires atomic SQLite mutation');
+            const bound = await store.mutateJob(job.id, current => current.localMerge ? current : ({ ...current, localMerge: { sourceRef, targetRef: 'refs/heads/main', status: 'pending' }, updatedAt: new Date().toISOString() }));
+            return prepareLocalJobExecutionWorktree(canonical, bound, workspaceRoot);
+        } });
     const refreshAll = async (_full = false) => {
         cachedOverviews = await inventoryFromLocal();
         return cachedOverviews;
@@ -233,112 +174,179 @@ export async function runDaemon(argv) {
         };
     };
     const refreshPullRequest = async (repository, prNumber, trigger, options) => (await refreshPullRequestSnapshot(repository, prNumber, trigger, options)).overviews;
-    const localJobBinding = createJobIdRegistryResolver(join(homedir(), '.agents-relay', 'stores'), relayStores);
+    const localJobBinding = createJobIdRegistryResolver(relayStoreDirectory(), relayStores, { client, trustedAuthors: trusted, noGitHub });
     const requireLocalJobBinding = async (jobId) => {
         const binding = await localJobBinding(jobId);
         if (!binding)
             throw new Error('Local Job ' + jobId + ' not found or ambiguous in SQLite registry');
         return binding;
     };
-    const pool = new RepositoryWorkerPool(concurrency, makeReconciler, inventoryFromLocal, localJobBinding);
-    const initial = cachedOverviews;
-    const fallback = initial[0]?.job;
-    const dashboardStore = fallback ? (await requireLocalJobBinding(fallback.id)).store : new InMemoryStore();
-    const dashboardOverview = (jobId, target) => cachedOverviews.find(item => item.job.id === jobId
-        && (!target?.repository || item.job.repository === target.repository)
-        && (!target?.prNumber || item.job.prNumber === target.prNumber));
-    const workspaceJobAction = (action) => async (jobId) => {
-        const overview = cachedOverviews.find(item => item.job.id === jobId);
-        if (!overview)
-            throw new Error(`Managed job ${jobId} not found`);
-        const store = (await requireLocalJobBinding(jobId)).store;
-        if (action === 'reconcile') {
-            await pool.reconcileLocalJob(jobId, 'control.job.reconcile');
-            return await store.load(jobId);
+    const gitText = async (cwd, args) => await new Promise((resolve, reject) => {
+        const child = spawnOwnedProcess('git', ['-C', cwd, ...args], { invocation: 'workspace.git', timeoutMs: 120000, spawn: { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } } });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', chunk => { stdout += chunk.toString(); });
+        child.stderr?.on('data', chunk => { stderr += chunk.toString(); });
+        child.once('error', reject);
+        child.once('close', code => code === 0 ? resolve(stdout.trim()) : reject(new Error(stderr.trim() || `git exited ${code}`)));
+    });
+    const refreshGitHubAuthentication = async () => {
+        if (noGitHub)
+            return;
+        try {
+            const login = auth?.appAuth ? await client.currentLogin() : await client.localLogin();
+            if (!login)
+                throw new Error('gh authentication did not return a healthy login');
+            trusted.add(login);
+            githubAuthenticated = true;
+            githubAuthError = null;
         }
-        return await dashboardJobAction(store, makeReconciler(store, concurrency), action)(jobId);
-    };
-    const workspaceJobSetState = async (jobId, state, target) => {
-        const overview = dashboardOverview(jobId, target);
-        if (!overview)
-            throw new Error(`Managed job ${jobId} not found`);
-        const store = (await requireLocalJobBinding(jobId)).store;
-        const result = await dashboardJobSetState(store)(jobId, state);
-        await refreshAll();
-        return result;
-    };
-    const workspaceTaskCreate = async (jobId, task) => {
-        const overview = cachedOverviews.find(item => item.job.id === jobId);
-        if (!overview)
-            throw new Error(`Managed job ${jobId} not found`);
-        if (task.jobId !== jobId)
-            throw new Error(`Task ${task.id} belongs to ${task.jobId}, not ${jobId}`);
-        const store = (await requireLocalJobBinding(jobId)).store;
-        const job = await store.load(jobId);
-        if (['COMPLETED', 'CANCELLED'].includes(job.state))
-            throw new Error(`Cannot create task on terminal job ${job.id} (${job.state})`);
-        await store.appendTask(task);
-        const refreshed = await store.load(jobId);
-        if (refreshed.state === 'DRAFT') {
-            await applyJobActivateAction(refreshed);
-            await store.saveJob(refreshed);
+        catch (error) {
+            githubAuthenticated = false;
+            githubAuthError = errorMessage(error);
         }
-        await pool.reconcileLocalJob(jobId, 'control.task.create');
-        return await store.load(jobId);
     };
-    const workspaceTaskStart = async (jobId, taskId) => {
-        const overview = cachedOverviews.find(item => item.job.id === jobId);
-        if (!overview)
-            throw new Error(`Managed job ${jobId} not found`);
-        const store = (await requireLocalJobBinding(jobId)).store;
-        const job = await store.load(jobId);
-        const task = job.tasks.find(item => item.id === taskId);
-        if (!task)
-            throw new Error(`Task ${taskId} not found`);
-        await applyOrchestratorStartAction(task);
-        await store.saveTask(task);
-        await publishOrchestratorTaskStarted(bus, job, task);
-        await pool.reconcileLocalJob(jobId, 'control.task.start');
-        return await store.load(jobId);
-    };
-    const workspaceTaskComplete = async (jobId, taskId, summary) => {
-        const overview = cachedOverviews.find(item => item.job.id === jobId);
-        if (!overview)
-            throw new Error(`Managed job ${jobId} not found`);
-        const store = (await requireLocalJobBinding(jobId)).store;
-        const job = await store.load(jobId);
-        const task = job.tasks.find(item => item.id === taskId);
-        if (!task)
-            throw new Error(`Task ${taskId} not found`);
-        await applyOrchestratorCompleteAction(task, summary);
-        await store.saveTask(task);
-        await publishOrchestratorTaskCompletion(bus, job, task, summary);
-        await pool.reconcileLocalJob(jobId, 'control.task.complete');
-        return await store.load(jobId);
-    };
-    const workspaceTaskAction = (action) => async (jobId, taskId) => {
-        const overview = cachedOverviews.find(item => item.job.id === jobId);
-        if (!overview)
-            throw new Error(`Managed job ${jobId} not found`);
-        const store = (await requireLocalJobBinding(jobId)).store;
-        return await dashboardTaskAction(store, makeReconciler(store, concurrency), action)(jobId, taskId);
+    const syncGitHubBindings = async () => {
+        if (noGitHub)
+            return;
+        await refreshGitHubAuthentication();
+        if (githubAuthenticated !== true)
+            return;
+        if (client.rateLimitStatus().limited)
+            return;
+        const snapshots = await discoverLocalRelayStoreSnapshots(relayStoreDirectory());
+        const bindingCandidates = orderGitHubBindingCandidates(snapshots.flatMap(snapshot => snapshot.jobs.map(job => ({ snapshotPath: snapshot.path, job }))));
+        for (const candidate of bindingCandidates) {
+            const snapshot = { path: candidate.snapshotPath };
+            const discovered = candidate.job;
+            try {
+                if (!repositoryPaths.has(discovered.repository) || !discovered.localMerge?.sourceRef || !discovered.localMerge?.targetRef)
+                    continue;
+                const sourceRef = discovered.localMerge.sourceRef;
+                const targetRef = discovered.localMerge.targetRef;
+                if (!sourceRef.startsWith('refs/heads/') || !targetRef.startsWith('refs/heads/'))
+                    continue;
+                if (targetRef !== 'refs/heads/main')
+                    throw new Error('GitHub sync only supports local main as merge target');
+                const branch = sourceRef.slice('refs/heads/'.length), base = targetRef.slice('refs/heads/'.length);
+                let relay = relayStores.get(snapshot.path);
+                if (!relay) {
+                    relay = new SQLiteRelayStore(snapshot.path);
+                    relayStores.set(snapshot.path, relay);
+                }
+                const canonical = repositoryPaths.get(discovered.repository) ?? await resolveManagedProjectPath(discovered.repository, explicitProjectPath, workspaceRoot);
+                // A completed local Job may never have had a display PR. Publish main
+                // regardless: GitHub availability cannot determine SQLite completion.
+                if (discovered.state === 'COMPLETED' && discovered.localMerge?.status === 'succeeded'
+                    && (discovered.externalPrNumber ?? discovered.prNumber) <= 0) {
+                    const published = projectAuthoritativeLocalMerge(canonical, discovered);
+                    if (published.status === 'projected')
+                        await bus?.publish(eventFor(discovered.id, 'projection', null, 'projection.delivered', 'succeeded', `GitHub main synchronization ${published.status}`, 'orchestrator', { operation: 'github.syncMain', deliveryStatus: published.status, mergedCommitSha: published.localMergedCommitSha }, { agent: 'relay', component: 'github-projection' }));
+                    continue;
+                }
+                const existingExternalPr = discovered.externalPrNumber ?? (discovered.prNumber > 0 ? discovered.prNumber : 0);
+                const terminal = ['COMPLETED', 'CANCELLED'].includes(discovered.state);
+                if (terminal && existingExternalPr <= 0)
+                    continue;
+                const sourceSha = await gitText(canonical, ['rev-parse', '--verify', sourceRef]);
+                const facts = await relay.loadPullRequestFacts();
+                if (facts?.head?.sha !== sourceSha) {
+                    await gitText(canonical, ['push', 'origin', `${branch}:${branch}`]);
+                }
+                let job = (await relay.loadJob(discovered.id)) ?? discovered;
+                let externalPrNumber = job.externalPrNumber ?? (job.prNumber > 0 ? job.prNumber : 0);
+                if (externalPrNumber === 0 && ['COMPLETED', 'CANCELLED'].includes(job.state))
+                    continue;
+                if (externalPrNumber === 0) {
+                    // Do not bootstrap an empty remote-only PR commit: it would diverge from
+                    // the real local Job branch before its first Worker commit. Publish the
+                    // review-only PR when there is an actual diff against main.
+                    const ahead = Number(await gitText(canonical, ['rev-list', '--count', `${targetRef}..${sourceRef}`]));
+                    if (!Number.isFinite(ahead) || ahead <= 0)
+                        continue;
+                    // GitHub compares origin/main, not local main. Do not invoke the legacy
+                    // empty-PR bootstrap path when the published base already contains the
+                    // source head (for example when main was pushed by another Job).
+                    await gitText(canonical, ['fetch', '--no-tags', 'origin', `+refs/heads/main:refs/remotes/origin/main`]);
+                    const remoteAhead = Number(await gitText(canonical, ['rev-list', '--count', `refs/remotes/origin/main..${sourceRef}`]));
+                    if (!Number.isFinite(remoteAhead) || remoteAhead <= 0)
+                        continue;
+                    const pr = await resolvePullRequest(client, job.repository, { head: branch, base, title: job.title, body: job.objective ?? job.description ?? '' });
+                    if (!relay.mutateJob)
+                        throw new Error('Atomic SQLite mutation is required for GitHub PR binding');
+                    job = await relay.mutateJob(job.id, current => ({ ...current, externalPrNumber: pr.number, updatedAt: new Date().toISOString() }));
+                    externalPrNumber = pr.number;
+                    observability().record({ stage: 'projection', event: 'github.pr_bound', outcome: 'succeeded', message: `Bound local Job ${job.id} to GitHub PR #${pr.number}`, correlation: { repository: job.repository, prNumber: pr.number, jobId: job.id }, data: { head: branch, base } });
+                }
+                if (externalPrNumber <= 0)
+                    continue;
+                const latestFacts = await relay.loadPullRequestFacts();
+                if (latestFacts?.state !== 'MERGED' && (latestFacts?.head?.sha !== sourceSha || latestFacts?.head?.ref !== branch)) {
+                    await relay.savePullRequestFacts({ state: latestFacts?.state === 'CLOSED' ? 'CLOSED' : 'OPEN', head: { ref: branch, sha: sourceSha }, observedAt: new Date().toISOString() });
+                }
+                const github = new GitHubStore(client, job.repository, externalPrNumber, trusted);
+                projectionWriters.set(`job:${job.id}`, new GitHubProjectionWriter(relay, github, undefined, true));
+                if (job.state === 'COMPLETED' && job.localMerge?.status === 'succeeded' && job.localMerge.projectionStrategy === 'target_ref_push') {
+                    const injection = await consumeMethodInjection(relay, job.repository, job.id, 'github.projectLocalMerge');
+                    const projectedMerge = await withTestInjection('github.projectLocalMerge', injection, () => projectAuthoritativeLocalMerge(canonical, job));
+                    await bus?.publish(eventFor(job.id, 'projection', null, 'projection.delivered', 'succeeded', `GitHub local merge projection ${projectedMerge.status}`, 'orchestrator', { operation: 'github.projectLocalMerge', deliveryStatus: projectedMerge.status, mergedCommitSha: projectedMerge.localMergedCommitSha }, { agent: 'relay', component: 'github-projection' }));
+                    // A review-only PR is never merged by GitHub. Close it after local main
+                    // has been safely published, retaining the diff, comments and commit link.
+                    const remotePr = await github.pullRequestState();
+                    await archiveDisplayPullRequest(client, job.repository, externalPrNumber, job.id, projectedMerge.projectedCommitSha, remotePr);
+                    const projectedState = await github.pullRequestState();
+                    const projectedHead = await github.pullRequestHead();
+                    await relay.savePullRequestFacts({ state: projectedState, head: projectedHead, observedAt: new Date().toISOString() });
+                    observability().record({
+                        stage: 'projection', event: 'github.local_merge_projected', outcome: 'succeeded',
+                        message: `Projected authoritative local merge ${projectedMerge.localMergedCommitSha} to ${projectedMerge.targetRef}`,
+                        correlation: { repository: job.repository, prNumber: externalPrNumber, jobId: job.id },
+                        data: { ...projectedMerge, githubState: projectedState },
+                    });
+                }
+            }
+            catch (error) {
+                await bus?.publish(eventFor(discovered.id, 'projection', null, 'projection.delivery_failed', 'failed', `GitHub projection failed: ${errorMessage(error)}`, 'orchestrator', { operation: 'github.projectLocalMerge', error: errorMessage(error) }, { agent: 'relay', component: 'github-projection' }))?.catch(() => { });
+                observability().record({
+                    stage: 'projection', event: 'github.binding_job_failed', level: 'warn', outcome: 'failed',
+                    message: `GitHub binding/projection failed for ${discovered.id}: ${errorMessage(error)}`,
+                    correlation: { repository: discovered.repository, prNumber: discovered.externalPrNumber ?? discovered.prNumber, jobId: discovered.id },
+                    data: { classification: classifyFailure(error).classification, reason: errorMessage(error) },
+                });
+            }
+        }
+        cachedOverviews = await inventoryFromLocal();
     };
-    const workspaceTaskSetState = async (jobId, taskId, state, target) => {
-        const overview = dashboardOverview(jobId, target);
-        if (!overview)
-            throw new Error(`Managed job ${jobId} not found`);
-        const store = (await requireLocalJobBinding(jobId)).store;
-        const result = await dashboardTaskSetState(store)(jobId, taskId, state);
-        await refreshAll();
-        return result;
+    let githubBindingSyncInFlight = null;
+    const syncGitHubBindingsSafely = async () => {
+        if (githubBindingSyncInFlight)
+            return githubBindingSyncInFlight;
+        githubBindingSyncInFlight = (async () => {
+            try {
+                await syncGitHubBindings();
+            }
+            catch (error) {
+                observability().record({ stage: 'projection', event: 'github.binding_sync_failed', level: 'warn', outcome: 'failed', message: `GitHub Job binding sync failed: ${errorMessage(error)}`, data: { classification: classifyFailure(error).classification, reason: errorMessage(error) } });
+            }
+            finally {
+                githubBindingSyncInFlight = null;
+            }
+        })();
+        return githubBindingSyncInFlight;
     };
+    const pool = new RepositoryWorkerPool(concurrency, makeReconciler, inventoryFromLocal, localJobBinding);
+    const initial = cachedOverviews;
+    const fallback = initial[0]?.job;
+    const dashboardStore = fallback ? (await requireLocalJobBinding(fallback.id)).store : new InMemoryStore();
+    const { dashboardOverview, workspaceJobAction, workspaceJobSetState, workspaceTaskCreate, workspaceTaskStart, workspaceTaskComplete, workspaceTaskAction, workspaceTaskSetState } = createDashboardActions({ cachedOverviews, requireLocalJobBinding, pool, dashboardJobAction, makeReconciler, concurrency, dashboardJobSetState, refreshAll, applyJobActivateAction, applyOrchestratorStartAction, applyOrchestratorCompleteAction, publishOrchestratorTaskStarted, publishOrchestratorTaskCompletion, bus, dashboardTaskAction, dashboardTaskSetState });
+    const workspaceControl = createWorkspaceControl({ client, trusted, noGitHub, repositories, refreshAll, requireLocalJobBinding, makeReconciler, concurrency, pool, bus, isEffectivelyBlocked, unblockAutonomousTasks, unblockTask, publishTaskUnblocked, dispatchTaskAction, registerBlockerDependency, discoverAgents, ensureManagedGitHubJob });
     const secretFile = value(argv, '--github-webhook-secret-file');
     const secret = noGitHub ? '' : value(argv, '--github-webhook-secret') || process.env.AGENTS_RELAY_GITHUB_WEBHOOK_SECRET || (secretFile ? (await readFile(secretFile, 'utf8')).trim() : '');
     const webhook = secret ? {
         secret,
         repositories: new Set(repositories),
         wake: async (event) => {
-            const targets = cachedOverviews.filter(item => item.job.repository === event.repository && item.job.prNumber === event.pullRequest);
+            const targets = cachedOverviews.filter(item => item.job.repository === event.repository && (event.jobId ? item.job.id === event.jobId : (item.job.externalPrNumber ?? item.job.prNumber) === event.pullRequest));
             if (targets.length === 0)
                 return;
             for (const target of targets) {
@@ -386,7 +394,8 @@ export async function runDaemon(argv) {
         }
     };
     const stopWatch = bus ? await pool.watch(bus) : async () => { };
-    const server = serveDashboard(dashboardStore, Number(value(argv, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(value(argv, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), fallback?.id, usageRegistry, overviews, webhook, () => ({ ...client.rateLimitStatus(), readPaths: { ...githubReadPaths } }), noGitHub ? undefined : () => client.rateLimitSnapshot(), exactJob, {
+    const server = serveDashboard(dashboardStore, Number(value(argv, '--port', String(SERVICE_DEFAULTS.port))), bus, Number(value(argv, '--refresh-ms', String(SERVICE_DEFAULTS.dashboardRefreshMs))), fallback?.id, usageRegistry, overviews, webhook, () => ({ githubEnabled: !noGitHub, githubAuthenticated, githubAuthError, ...client.rateLimitStatus(), readPaths: { ...githubReadPaths } }), noGitHub ? undefined : () => client.rateLimitSnapshot(), exactJob, {
+        control: workspaceControl,
         start: workspaceJobAction('start'),
         reconcile: workspaceJobAction('reconcile'),
         cancel: workspaceJobAction('cancel'),
@@ -502,20 +511,21 @@ export async function runDaemon(argv) {
     let interval;
     let scheduleInterval;
     let projectionInterval;
-    const stop = () => { if (interval)
+    const stop = () => { stopRuntimeStatusEvents(); if (interval)
         clearInterval(interval); if (scheduleInterval)
         clearInterval(scheduleInterval); if (projectionInterval)
         clearInterval(projectionInterval); void Promise.allSettled([stopWatch(), shutdownOwnedProcesses('parent-shutdown')]).finally(() => { for (const store of relayStores.values())
         store.close(); server.close(() => process.exit(0)); }); };
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
+    await syncGitHubBindingsSafely();
     await pool.reconcileKnown(cachedOverviews);
     await scheduleHeartbeatSafely();
     await flushProjectionsSafely();
     interval = setInterval(() => void reconcileSafely().finally(flushProjectionsSafely), Number(value(argv, '--interval', String(watchdogDefault))));
     interval.unref();
     if (!noGitHub) {
-        projectionInterval = setInterval(() => void flushProjectionsSafely(), Number(value(argv, '--projection-ms', String(SERVICE_DEFAULTS.projectionFlushMs))));
+        projectionInterval = setInterval(() => void syncGitHubBindingsSafely().then(flushProjectionsSafely), Number(value(argv, '--projection-ms', String(SERVICE_DEFAULTS.projectionFlushMs))));
         projectionInterval.unref();
     }
     scheduleInterval = setInterval(() => void scheduleHeartbeatSafely(), SCHEDULE_HEARTBEAT_MS);

package/dist/review-generation-fence.js

@@ -0,0 +1,12 @@
+/** Called inside SQLite mutateJob against the latest durable Job snapshot. */
+export function reviewGenerationMatches(current, original, task, headSha) {
+    const fresh = current.tasks.find(item => item.id === task.id);
+    if (!fresh || fresh.reviewHeadSha !== headSha || current.state !== 'ACTIVE'
+        || (current.headSha && current.headSha !== headSha)
+        || fresh.executionId !== task.executionId)
+        return false;
+    if (current.review)
+        return current.review.taskId === task.id && current.review.headSha === headSha
+            && current.review.outcome === (original.review?.outcome ?? 'pending');
+    return Boolean(task.planningDecisionId && !original.review?.taskId);
+}

package/dist/runtime-status-events.js

@@ -0,0 +1,21 @@
+import { deriveJobRuntimeStatus } from './runtime-status.js';
+import { eventFor } from './events.js';
+/** Process-local change detector. No extra durable status field or polling required. */
+export function createRuntimeStatusPublisher(bus) {
+    const last = new Map();
+    return (job) => {
+        const key = `${job.repository}\0${job.id}`;
+        const to = deriveJobRuntimeStatus(job);
+        const from = last.get(key);
+        if (from === to)
+            return;
+        last.set(key, to);
+        // First observation establishes a baseline rather than fabricating a transition.
+        if (from === undefined)
+            return;
+        const event = eventFor(job.id, '', null, 'job.runtime_status.changed', 'info', `${from} → ${to}`, 'orchestrator', { from, to, repository: job.repository, jobState: job.state, updatedAt: job.updatedAt }, { agent: 'relay', component: 'runtime-status' });
+        void bus.publish(event).catch(error => {
+            process.stderr.write(`runtime status change publish failed ${job.id}: ${String(error)}\n`);
+        });
+    };
+}

package/dist/runtime-status.js

@@ -20,6 +20,11 @@ export function deriveJobRuntimeStatus(job, _prState = 'OPEN') {
         return 'COMPLETED';
     if (job.state === 'DRAFT')
         return 'IDLE';
+    const currentPlan = job.plans?.at(-1);
+    // An unresolved planner failure is a Job failure, not an idle Job.
+    // Active task execution still takes precedence below.
+    const plannerFailed = currentPlan?.status === 'FAILED' && !job.tasks.some(task => ['QUEUED', 'RUNNING'].includes(task.state));
+    const plannerRunning = currentPlan?.status === 'PLANNING';
     if (job.schedule) {
         if (job.tasks.some(task => task.state === 'RUNNING'))
             return 'RUNNING';
@@ -31,6 +36,10 @@ export function deriveJobRuntimeStatus(job, _prState = 'OPEN') {
             return 'FAILED';
         if (job.tasks.some(task => task.state === 'DRAFT'))
             return 'WAITING';
+        if (plannerFailed)
+            return 'FAILED';
+        if (plannerRunning)
+            return 'RUNNING';
         return 'WAITING';
     }
     // Draft or queued reviewers must not mask implementation that is still active.
@@ -54,6 +63,10 @@ export function deriveJobRuntimeStatus(job, _prState = 'OPEN') {
         return 'FAILED';
     if (job.tasks.some(task => task.state === 'DRAFT'))
         return 'WAITING';
+    if (plannerFailed)
+        return 'FAILED';
+    if (plannerRunning)
+        return 'RUNNING';
     if (job.executionMode === 'autonomous' && job.autoMerge === false && job.reviewEnabled === false && implementationComplete(job))
         return 'WAITING';
     if (job.reviewEnabled === false && implementationComplete(job))