agents-relay 2.0.63 → 2.0.65

package/dist/adapters.js

@@ -2,7 +2,7 @@ import { readFile, writeFile, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { randomUUID } from 'node:crypto';
-import { spawnOwnedProcess, terminateOwnedProcess } from './owned-process.js';
+import { spawnOwnedProcess, terminateOwnedProcess, ownedProcessTerminationReason } from './owned-process.js';
 export function buildCodexArgs(route, input) {
     const args = ['exec', '--json'];
     if (route.profile)
@@ -82,7 +82,7 @@ export class CodexAdapter {
             child.on('error', error => { launchedReject(error); reject(error); });
             child.once('spawn', launchedResolve);
             child.on('close', (code, signal) => {
-                execution.processExit = { exitCode: code, signal, stderr: stderrTail };
+                execution.processExit = { exitCode: code, signal, stderr: stderrTail, terminationReason: ownedProcessTerminationReason(child) };
                 if (stdoutBuffer)
                     consumeLine(stdoutBuffer);
                 if (code === 0) {
@@ -110,14 +110,34 @@ export class LaunchFailure extends Error {
 }
 export class StartAckTimeout extends LaunchFailure {
 }
-function parseDriverJson(output) {
+function findSubmittedReceipt(value) {
+    if (typeof value === 'string') {
+        try {
+            return findSubmittedReceipt(JSON.parse(value));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    if (record.operation === 'submit' && record.status === 'submitted')
+        return record;
+    for (const key of ['result', 'output', 'data', 'stdout']) {
+        const nested = findSubmittedReceipt(record[key]);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
+export function parseDriverJson(output) {
     const lines = output.trim().split(/\r?\n/).filter(Boolean);
     for (let index = lines.length - 1; index >= 0; index -= 1) {
         try {
-            const value = JSON.parse(lines[index]);
-            if (value.operation !== 'submit' || value.status !== 'submitted')
-                continue;
-            return value;
+            const receipt = findSubmittedReceipt(JSON.parse(lines[index]));
+            if (receipt)
+                return receipt;
         }
         catch {
             // Browser-harness diagnostics may precede the final JSON observation.
@@ -180,7 +200,19 @@ export async function ensureChatGptBrowserWorkspace(command = process.env.AGENTS
     }
     await admin.ensureWorkspace(CHATGPT_BROWSER_WORKSPACE, CHATGPT_BROWSER_WORKSPACE_POOL_SIZE);
 }
-function autoSessionBrowserWorkerRunner() {
+async function runBrowserWorker(cli, configFile, signal) {
+    const session = parseWorkspaceJson(await browserWorkspaceCommand(cli, ['session', 'start'], undefined, signal));
+    const sessionId = session.session_id;
+    if (typeof sessionId !== 'string' || !sessionId)
+        throw new Error('browser-workspace session start returned no session_id');
+    try {
+        return await browserWorkspaceCommand(cli, ['platform', 'run', 'chatgpt', 'temporary-submit', '--session-id', sessionId, '--config', configFile], undefined, signal);
+    }
+    finally {
+        await browserWorkspaceCommand(cli, ['session', 'stop', sessionId]).catch(() => { });
+    }
+}
+function browserWorkerRunner() {
     const cli = browserWorkspaceCli();
     return (_definition, request, _route, signal) => {
         const promise = (async () => {
@@ -192,7 +224,7 @@ function autoSessionBrowserWorkerRunner() {
                 }));
                 if (signal.aborted)
                     throw new Error('browser-worker execution aborted');
-                const output = await browserWorkspaceCommand(cli, ['platform', 'run', 'chatgpt', 'temporary-submit', '--auto-session', '--config', configFile], undefined, signal);
+                const output = await runBrowserWorker(cli, configFile, signal);
                 return JSON.stringify(parseDriverJson(output));
             }
             finally {
@@ -255,7 +287,7 @@ export class ChatGptAdapter {
             if (controller.signal.aborted)
                 throw new Error('browser-worker execution aborted');
             const policy = chatGptTabClosePolicy(task.chatgptTabClosePolicy, this.tabClosePolicy);
-            const run = (this.runner ?? autoSessionBrowserWorkerRunner())(definition, { prompt: task.input, ...(task.attachments?.length ? { files: task.attachments } : {}), tabClosePolicy: policy }, route, controller.signal);
+            const run = (this.runner ?? browserWorkerRunner())(definition, { prompt: task.input, ...(task.attachments?.length ? { files: task.attachments } : {}), tabClosePolicy: policy }, route, controller.signal);
             try {
                 const output = await (run.submitted ?? run.promise);
                 const response = parseBrowserWorkerResponse(output);

package/dist/dashboard-html.js

@@ -486,9 +486,8 @@ const stream=new EventSource('/events');
 stream.onopen=()=>{connection.textContent='';connection.setAttribute('aria-label','Event stream connected');connection.className='status-pill ok';};
 stream.onerror=()=>{connection.textContent='';connection.setAttribute('aria-label','Event stream reconnecting');connection.className='status-pill warn';};
 stream.onmessage=message=>{const payload=parseMessage(message);if(payload?.job){const index=jobs.findIndex(job=>jobSelectionKey(job)===jobSelectionKey(payload.job));if(index>=0)jobs[index]=payload.job;else jobs.push(payload.job);renderAll();void drawRuntimeSummary();}};
-stream.addEventListener('relay',message=>{const payload=parseMessage(message);if(payload?.statePatch)applyStatePatch(payload.statePatch);if(payload?.event)addEvent(payload.event);renderAll();void drawRuntimeSummary();});
+stream.addEventListener('relay',message=>{const payload=parseMessage(message);if(payload?.job){const index=jobs.findIndex(job=>jobSelectionKey(job)===jobSelectionKey(payload.job));if(index>=0)jobs[index]=payload.job;else jobs.push(payload.job);}else if(payload?.statePatch)applyStatePatch(payload.statePatch);if(payload?.event)addEvent(payload.event);renderAll();void drawRuntimeSummary();});
 if(location.hash==='#/usage')showView('usage');else if(location.hash==='#/graphs')showView('graphs');else if(location.hash==='#/execution-router-rules')showView('rules');else if(location.hash==='#/shortcuts')showView('shortcuts');else showView('jobs');
-setInterval(()=>{if(location.hash!=='#/usage'&&location.hash!=='#/graphs'&&location.hash!=='#/execution-router-rules'&&location.hash!=='#/shortcuts')void refresh();},300000);
 setInterval(()=>{if(location.hash==='#/usage')void drawUsage();},30000);
 setInterval(()=>void refreshVersion(),30000);
 async function refreshSelected(){const job=selected();if(!job){await refresh();return;}selectedJobRefresh.disabled=true;selectedJobRefresh.textContent='Refreshing…';try{const params=new URLSearchParams({id:job.id,repo:job.repository,pr:String(job.prNumber)});const updated=await loadJSON('/api/job?'+params.toString());const index=jobs.findIndex(candidate=>jobSelectionKey(candidate)===jobSelectionKey(job));if(index>=0)jobs[index]=updated;else jobs.push(updated);selectedJob=jobSelectionKey(updated);rememberSelection();renderAll();connection.textContent='';connection.setAttribute('aria-label','Live durable state connected');connection.className='status-pill ok';}catch(error){connection.textContent='';connection.setAttribute('aria-label','Durable state unavailable');connection.className='status-pill bad';}finally{selectedJobRefresh.disabled=false;selectedJobRefresh.textContent='Refresh';}}

package/dist/dashboard.js

@@ -1,4 +1,5 @@
 import { createServer } from 'node:http';
+import { subscribeLocalCommits } from './local-commit-events.js';
 import { readFile, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -99,17 +100,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             subscribedJobs.add(job.id);
             try {
                 await bus.subscribe(job.id, async (event) => {
-                    const durable = await store.load(job.id).catch(() => null);
-                    const task = durable?.tasks.find(candidate => candidate.id === event.task_id) ?? null;
-                    const statePatch = durable ? {
-                        jobId: durable.id,
-                        jobState: durable.state,
-                        jobUpdatedAt: durable.updatedAt,
-                        taskId: task?.id ?? null,
-                        taskState: task?.state ?? null,
-                        taskUpdatedAt: task?.updatedAt ?? null,
-                    } : null;
-                    const payload = JSON.stringify({ event, statePatch });
+                    const payload = JSON.stringify({ event });
                     for (const client of clients)
                         client.write(`event: relay\ndata: ${payload}\n\n`);
                 });
@@ -119,6 +110,16 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             }
         }
     };
+    const unsubscribeLocalCommits = subscribeLocalCommits(durable => {
+        const known = lastKnownJobs?.find(job => job.id === durable.id && job.repository === durable.repository && job.prNumber === durable.prNumber);
+        const githubState = known?.githubState;
+        const current = { ...durable, githubState, runtimeStatus: deriveJobRuntimeStatus(durable, githubState) };
+        if (lastKnownJobs && known)
+            Object.assign(known, current);
+        const payload = JSON.stringify({ job: current });
+        for (const client of clients)
+            client.write(`data: ${payload}\n\n`);
+    });
     const snapshot = async (requestedJobId = jobId, forceRefresh = false, target) => {
         await subscribeDiscovered();
         if (overviewProvider) {
@@ -563,15 +564,6 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
         res.writeHead(404);
         res.end('Not found');
     });
-    const interval = setInterval(() => {
-        if (clients.size === 0)
-            return;
-        void snapshot().then(value => {
-            for (const client of clients)
-                client.write(`data: ${value.json}\n\n`);
-        }).catch(() => undefined);
-    }, Math.max(10000, refreshMs));
-    interval.unref();
     const heartbeat = setInterval(() => {
         if (clients.size === 0)
             return;
@@ -579,7 +571,7 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             client.write(': heartbeat\n\n');
     }, SSE_HEARTBEAT_MS);
     heartbeat.unref();
-    server.on('close', () => { clearInterval(interval); clearInterval(heartbeat); clients.clear(); });
+    server.on('close', () => { unsubscribeLocalCommits(); clearInterval(heartbeat); clients.clear(); });
     server.listen(port, '127.0.0.1');
     return server;
 }

package/dist/execution-boundary.js

@@ -0,0 +1,23 @@
+const executionBoundaryLocks = new Map();
+/**
+ * Serialize the durable execution-generation boundary across reconciler
+ * instances in one relay process. Launch, routing, and terminal persistence
+ * must not observe and write the same queued generation concurrently.
+ */
+export async function withExecutionBoundary(jobId, taskId, work) {
+    const key = `${jobId}/${taskId}`;
+    const previous = executionBoundaryLocks.get(key);
+    let release;
+    const current = new Promise(resolve => { release = resolve; });
+    executionBoundaryLocks.set(key, current);
+    if (previous)
+        await previous;
+    try {
+        return await work();
+    }
+    finally {
+        release();
+        if (executionBoundaryLocks.get(key) === current)
+            executionBoundaryLocks.delete(key);
+    }
+}

package/dist/github-client.js

@@ -142,27 +142,33 @@ export class GhApiClient {
         if (rateLimited)
             this.assertAvailable();
         const commandArgs = includeHeaders ? [args[0] ?? '', '--include', ...args.slice(1)] : args;
-        return await new Promise((resolve) => {
-            const child = spawnOwnedProcess('gh', commandArgs, { invocation: 'github.api', spawn: { env } });
-            let stdout = '';
-            let stderr = '';
-            child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
-            child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
-            child.on('error', error => resolve({ status: null, headers: {}, body: '', stderr: error.message }));
-            if (input !== undefined)
-                child.stdin?.write(input);
-            child.stdin?.end();
-            child.on('close', code => {
-                const response = parseGitHubCliHeaders(stdout, includeHeaders);
-                const failed = code !== 0;
-                const message = failed ? stderr.trim() || response.body.trim() || `gh exited ${code}` : '';
-                if (failed && rateLimited)
-                    this.noteFailure(message);
-                if (!failed && rateLimited)
-                    this.noteSuccess();
-                resolve({ ...response, stderr: failed ? message : undefined });
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const result = await new Promise((resolve) => {
+                const child = spawnOwnedProcess('gh', commandArgs, { invocation: 'github.api', spawn: { env } });
+                let stdout = '';
+                let stderr = '';
+                child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+                child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
+                child.on('error', error => resolve({ status: null, headers: {}, body: '', stderr: error.message }));
+                if (input !== undefined)
+                    child.stdin?.write(input);
+                child.stdin?.end();
+                child.on('close', (code, signal) => {
+                    const response = parseGitHubCliHeaders(stdout, includeHeaders);
+                    const failed = code !== 0;
+                    const message = failed ? stderr.trim() || response.body.trim() || `gh exited ${code}; signal=${signal ?? "none"}` : '';
+                    resolve({ ...response, stderr: failed ? message : undefined, signal });
+                });
             });
-        });
+            if (result.signal && attempt === 0)
+                continue;
+            if (result.stderr && rateLimited)
+                this.noteFailure(result.stderr);
+            if (!result.stderr && rateLimited)
+                this.noteSuccess();
+            return result;
+        }
+        throw new Error('GitHub CLI retry exhausted');
     }
     async spawnGh(args, input, env = process.env, rateLimited = true) {
         return (await this.runGh(args, input, env, rateLimited, false)).body;

package/dist/job-execution-slot.js

@@ -0,0 +1,12 @@
+/**
+ * One active execution per Job, irrespective of adapter or current reconciler.
+ * A claimed QUEUED execution also occupies the slot; synchronous P0/self work
+ * occupies it by its RUNNING state even though it has no execution UUID.
+ */
+export function jobHasActiveExecution(job, except = {}) {
+    const worker = job.tasks.some(task => task.id !== except.taskId
+        && (task.state === 'RUNNING' || (task.executionId !== null && !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(task.state))));
+    const planner = (job.plans ?? []).some(plan => plan.id !== except.planId
+        && plan.executionId !== null && plan.status === 'PLANNING');
+    return worker || planner;
+}

package/dist/job-worktree-cleanup.js

@@ -0,0 +1,10 @@
+import { cleanupCompletedJobWorktree } from './workspace.js';
+/** Mechanical effect selected by job-lifecycle Graph on a completed PR. */
+export async function cleanupMergedJobWorktree(job, projectPathForJob) {
+    if (!projectPathForJob)
+        throw new Error('No canonical project resolver for Worktree cleanup');
+    const result = await cleanupCompletedJobWorktree(await projectPathForJob(job), job);
+    // A blocked cleanup must be retried on a subsequent completed-Job reconcile.
+    if (result.status === 'blocked')
+        throw new Error(result.reason ?? 'Unsafe Worktree cleanup');
+}

package/dist/local-commit-events.js

@@ -0,0 +1,10 @@
+const listeners = new Set();
+/** Notify dashboard listeners only after authoritative SQLite state is committed. */
+export function publishLocalCommit(job) {
+    for (const listener of listeners)
+        listener(structuredClone(job));
+}
+export function subscribeLocalCommits(listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}

package/dist/managed-worker-input.js

@@ -0,0 +1,62 @@
+import { agentContractPrompt, executionContextPrompt } from './execution-context.js';
+import { agentGraphPrompt } from './agent-graph.js';
+import { createReviewChairExecutionPlan } from './review-chair.js';
+import { taskTagWorkerPrompt } from './task-tag.js';
+import { executionEventSource } from './reconciler-runtime.js';
+export async function managedWorkerInput(job, task, context) {
+    if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository || job.prNumber <= 0)
+        return task.input;
+    const selectedAgent = task.agentName && context ? await agentContractPrompt(context, task.agentName) : '';
+    const selectedGraph = task.agentGraph && context ? await agentGraphPrompt(context, task.agentGraph) : '';
+    const chairPlan = task.review?.role === 'chair' && context
+        ? createReviewChairExecutionPlan(context.agents, task.review.target)
+        : null;
+    if (!task.output)
+        throw new Error(`Task ${task.id} requires an explicit output contract`);
+    if (!task.executionId)
+        throw new Error(`Task ${task.id} requires an executionId before worker input is built`);
+    const sourceId = executionEventSource(job.id, task.id, task.executionId);
+    const prUrl = `https://github.com/${job.repository}/pull/${job.prNumber}`;
+    const taskUrl = task.taskUrl ?? `${prUrl}#issuecomment-${task.id}`;
+    const output = task.output.kind === 'file'
+        ? `file\nPath: ${task.output.path}`
+        : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`;
+    const taskTag = taskTagWorkerPrompt(job);
+    return `[Agents Relay managed task]
+Job URL: ${prUrl}
+Job ID: ${job.id}
+Task URL: ${taskUrl}
+Task ID: ${task.id}
+Project: ${task.projectName ?? context?.project.name ?? 'unspecified'}
+Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.
+${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? selectedAgent + '\n\n' : ''}${selectedGraph ? selectedGraph + '\n\n' : ''}${chairPlan ? `[Review Chair execution plan]\n${JSON.stringify(chairPlan, null, 2)}\n\nUse this runtime-discovered panel to create sibling durable specialist Tasks. Preserve each specialistTasks entry as review metadata, keep the target immutable, and synthesize structured results with synthesizeReview semantics before returning the unified revision plan.\n\n` : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
+[Output contract]
+${output}
+${taskTag}[Execution event contract — mandatory]
+Use the canonical Neo events-bus with exactly Job ${job.id} and Task ${task.id}.
+Your exact event source identity is: ${sourceId}
+Every lifecycle event for this execution MUST set source.id to that exact string. Do not derive, rename, or replace it.
+Follow the events-bus skill/protocol. For sandboxed Codex or hosted ChatGPT,
+publish through the federated MCP tool events__publish; do not open NATS directly.
+For a direct non-sandbox local worker, use NEO_EVENTS_EMIT when the caller provides it.
+As your FIRST execution action, before reading files, editing code, running commands, or doing other work,
+you MUST publish exactly one canonical task.started event for this exact Job/Task.
+
+${task.adapter === 'chatgpt' ? `Because ChatGPT execution continues asynchronously after the submit process exits, you MUST keep reporting liveness while the task is active. Publish meaningful progress/milestone events when there is real progress to report. If no meaningful milestone has been published for 30 seconds during active work, publish a non-terminal task.heartbeat event with status running, visibility orchestrator, this exact source.id, and a concise description of the current operation. Continue heartbeats after each further 30 seconds of active silence until a terminal task event is published. Do not invent percentage progress.` : `You MAY publish progress events while working. For long silent active work, follow the events-bus heartbeat policy.`}
+Before returning or allowing the worker process to exit, you MUST publish exactly one canonical terminal event:
+- task.completed only after the declared output is durable;
+- task.failed for implementation, tool, command, test, patch, commit, push, runtime, or other execution failure that prevents completion;
+- task.blocked only when genuine human/external action is required;
+- task.cancelled only when execution was cancelled.
+
+If any execution step fails and you cannot continue, publish task.failed with the concrete reason BEFORE exiting.
+Never exit after task.started without publishing exactly one terminal task event.
+Do not publish duplicate terminal task events.
+The worker owns task.started and task terminal events. Relay-owned task.process.launched, task.process.exited,
+and task.process.async_exited are process lifecycle only and NEVER replace the worker task lifecycle.
+The ChatGPT/Codex conversation or process exit is never the task result.
+
+[Final event gate]
+Before your final return, verify that a terminal event for this exact Job/Task was published.
+If no terminal event has been published, publish task.failed before exiting.`;
+}

package/dist/owned-process.js

@@ -4,6 +4,9 @@ import { basename } from 'node:path';
 import { observability } from './observability.js';
 const owned = new Map();
 const byChild = new WeakMap();
+export function ownedProcessTerminationReason(child) {
+    return byChild.get(child)?.terminationReason ?? null;
+}
 let exitHookInstalled = false;
 function audit(record, event, outcome, data) {
     observability().record({
@@ -113,7 +116,7 @@ export function spawnOwnedProcess(command, args, options) {
         record.timeoutTimer.unref();
     }
     child.once('exit', (code, signal) => {
-        audit(record, 'process.exited', code === 0 ? 'succeeded' : 'failed', { exitStatus: code, signal });
+        audit(record, 'process.exited', code === 0 ? 'succeeded' : 'failed', { exitStatus: code, signal, terminationReason: record.terminationReason ?? null });
         // `close` waits for inherited stdio. End any descendants left behind by a
         // wrapper before they can keep the caller alive indefinitely.
         if (!record.terminating)
@@ -143,6 +146,7 @@ export async function terminateOwnedProcess(child, reason, graceMs) {
         return;
     if (!record.terminating) {
         record.terminating = true;
+        record.terminationReason = reason;
         const outcome = signalOwned(record, 'SIGTERM');
         audit(record, 'process.signal', outcome === 'error' ? 'failed' : 'succeeded', { reason, signal: 'SIGTERM', delivered: outcome === 'sent', alreadyGone: outcome === 'gone' });
         record.forceTimer = setTimeout(() => forceOwned(record, reason), graceMs ?? record.graceMs);

package/dist/planned-review-head.js

@@ -0,0 +1,17 @@
+/** A planner-created dependent review must freeze its head only after implementation completes. */
+export async function bindPlannedReviewHead(store, task) {
+    const current = await store.pullRequestHead?.();
+    if (!current?.sha)
+        throw new Error(`Review ${task.id} requires current PR head SHA`);
+    task.reviewHeadSha = current.sha;
+    const rule = [
+        'Review the current immutable PR head as a PRE-MERGE approval gate.',
+        'Distinguish code added by this implementation from pre-existing PR baseline/seed files present before the Task started.',
+        'Preserved baseline files are not automatically extra changes merely because they differ from main; still review them for real risks.',
+        'Do not require PR MERGED, Job COMPLETED, or post-merge E2E evidence before review approval:',
+        'those events must follow approval and are verified by the independent E2E runner.',
+    ].join(' ');
+    if (!task.input.includes(rule))
+        task.input += '\n\n' + rule;
+    await store.saveTask(task);
+}

package/dist/planner-runtime.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { jobHasActiveExecution } from './job-execution-slot.js';
 import { eventFor } from './events.js';
 import { materializePlannerChild, parsePlannerResult, validatePlannerHierarchy } from './planner.js';
 import { samePlannerChildDefinition } from './planner-child.js';
@@ -92,11 +93,14 @@ export async function launchPlanExecution(ports, job, plan) {
         await ports.emit(eventFor(job.id, plan.id, null, 'planner.failed', 'failed', `Planner ${plan.id}: Planner unavailable`, 'user'));
         return;
     }
-    const claimed = await withExecutionBoundary(job.id, plan.id, async () => {
+    const claimed = await withExecutionBoundary(job.id, '__job_execution_slot__', async () => {
         const freshJob = await ports.store.load(job.id);
         const fresh = (freshJob.plans ?? []).find(item => item.id === plan.id);
         if (!fresh || fresh.status !== 'PLANNING')
             return null;
+        // A Planner is an execution too: no overlapping worker or second Planner.
+        if (jobHasActiveExecution(freshJob, { planId: fresh.id }))
+            return null;
         const live = ports.live.get(fresh.id);
         if (fresh.executionId && fresh.leaseOwner === ports.options.owner && live?.executionId === fresh.executionId)
             return null;

package/dist/planner.js

@@ -100,7 +100,7 @@ export function materializePlannerChild(job, planner, spec, executionContext) {
     const source = 'round' in planner ? planner.source : planner.planningSource ?? 'model-planner';
     const round = 'round' in planner ? planner.round : planner.planningRound ?? 1;
     const plannerHeadSha = 'round' in planner ? planner.headSha : undefined;
-    const reviewHeadSha = spec.agentName === 'reviewer' ? plannerHeadSha ?? job.headSha : undefined;
+    const reviewHeadSha = spec.agentName === 'reviewer' && !(spec.dependencies?.length) ? plannerHeadSha ?? job.headSha : undefined;
     return createTaskEntity(job, { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, agentGraph: spec.agentGraph, review: spec.review, parentTaskId: spec.parentTaskId ?? null, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: decisionId, planningSource: source, planningRound: round, reviewHeadSha });
 }
 export function planningSpec(task) {

package/dist/pool.js

@@ -263,7 +263,7 @@ export class RepositoryWorkerPool {
             if (routedWebhook)
                 return;
             const lifecycle = ['task.started', 'task.completed', 'task.failed', 'task.blocked', 'task.unblocked', 'task.cancelled', 'review.started', 'review.approved', 'review.changes_required', 'review.blocked'].includes(event.type);
-            const wake = event.type === 'job.wake' || event.type === 'github.webhook';
+            const wake = event.type === 'job.wake' || event.type === 'github.webhook' || event.type === 'review.created';
             if (!lifecycle && !wake)
                 return;
             if (repository && prNumber)

package/dist/projected-store.js

@@ -1,3 +1,4 @@
+import { publishLocalCommit } from './local-commit-events.js';
 import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
 import { DurableDefinitionConflictError, isDurableDefinitionConflict, sameTaskDefinition } from './store-task-definition.js';
 import { decideProjectionFailure } from './workflow/projection-conflict-v2.js';
@@ -221,6 +222,7 @@ export class ProjectedDurableStore {
             payload: { operation: 'save_job', value },
             priority: ['COMPLETED', 'CANCELLED'].includes(job.state) ? 100 : 20,
         });
+        publishLocalCommit(job);
         observability().record({
             stage: 'store', event: 'store.commit', outcome: 'succeeded',
             message: `Job ${job.id} committed`,
@@ -243,6 +245,7 @@ export class ProjectedDurableStore {
             payload: { operation: 'append_plan', value: plan },
             priority: 30,
         });
+        publishLocalCommit(job);
     }
     async savePlan(plan) {
         const job = await this.load(plan.jobId);
@@ -260,6 +263,7 @@ export class ProjectedDurableStore {
             payload: { operation: 'save_plan', value: plan },
             priority: 30,
         });
+        publishLocalCommit(job);
     }
     async appendTask(task) {
         if (!task.jobId)
@@ -278,6 +282,7 @@ export class ProjectedDurableStore {
             payload: { operation: 'append_task', value: task },
             priority: 40,
         });
+        publishLocalCommit(job);
         observability().record({
             stage: 'store', event: 'store.commit', outcome: 'succeeded',
             message: `Task ${task.id} appended`,
@@ -305,6 +310,7 @@ export class ProjectedDurableStore {
             payload: { operation: 'save_task', value },
             priority: terminal ? 100 : 50,
         });
+        publishLocalCommit(job);
         observability().record({
             stage: 'store', event: 'store.commit', outcome: 'succeeded',
             message: `Task ${task.id} committed (${task.state})`,

package/dist/reconciler-review.js

@@ -113,7 +113,11 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
             jobId: job.id, id, kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: 'reviewer',
             parentTaskId: null, dependencies: reviewGateTasks.map(item => item.id), capabilities: ['review'],
             workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter,
-            input: 'Review existing PR #' + job.prNumber + ' at exactly head SHA ' + headSha + '. Job objective: ' + (job.objective ?? job.description ?? job.title) + '. Use the selected reviewer agent contract as the authoritative review protocol.',
+            input: 'Review existing PR #' + job.prNumber + ' at exactly head SHA ' + headSha + '. Job objective: ' + (job.objective ?? job.description ?? job.title) + '. Use the selected reviewer agent contract as the authoritative review protocol. ' +
+                'This is a PRE-MERGE artifact approval gate: inspect the exact PR head, requested changes, applicable source/test requirements, and genuine blocking defects in the proposed changes. ' +
+                'Do not block approval because automatic merge, Job COMPLETED, or post-merge E2E evidence has not occurred yet; those are downstream effects of review approval and independently verified later. ' +
+                'Do not treat historical failed attempts or launch anomalies as current artifact defects if the latest implementation and tests succeeded; report historical lifecycle observations separately. ' +
+                'Compare implementation changes with the PR head that existed before the implementation, not only against main: preserved seed or baseline files are not automatically unrelated additions.',
             output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.routing, continuation: null, continuationDeliveredAt: null,
             reviewHeadSha: headSha, attempt: 0, maxAttempts: this.options.reviewer?.maxAttempts ?? 2,
             leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null,
@@ -267,6 +271,12 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         const currentHeadSha = await this.store.headSha?.();
         if ((currentHeadSha && currentHeadSha !== headSha) || (job.headSha && job.headSha !== headSha))
             return { applied: false, reconcile: false, reason: event.type + '.stale' };
+        // Planner-created reviewer tasks predate the final-review Job gate. Bind
+        // their first trustworthy review event to PENDING before dispatching it.
+        if (!job.review && task.planningDecisionId) {
+            job.review = { outcome: 'pending', headSha, taskId: task.id, evidence: null, updatedAt: event.timestamp || new Date().toISOString() };
+            await this.store.saveJob(job);
+        }
         const taskDecision = tryTransitionTaskEvent(task, event.type);
         if (!taskDecision.accepted || !taskDecision.target)
             return { applied: false, reconcile: false, reason: event.type + '.ignored' };

package/dist/reconciler-runtime.js

@@ -17,29 +17,8 @@ function executionIdFromSource(sourceId, jobId, taskId) {
 }
 const terminalExecutionClaims = new Set();
 const activeExecutionOwners = new Map();
-const executionBoundaryLocks = new Map();
-/**
- * Serialize the durable execution-generation boundary across reconciler
- * instances in one relay process. Launch, routing, and terminal persistence
- * must not observe and write the same queued generation concurrently.
- */
-export async function withExecutionBoundary(jobId, taskId, work) {
-    const key = `${jobId}/${taskId}`;
-    const previous = executionBoundaryLocks.get(key);
-    let release;
-    const current = new Promise(resolve => { release = resolve; });
-    executionBoundaryLocks.set(key, current);
-    if (previous)
-        await previous;
-    try {
-        return await work();
-    }
-    finally {
-        release();
-        if (executionBoundaryLocks.get(key) === current)
-            executionBoundaryLocks.delete(key);
-    }
-}
+import { withExecutionBoundary } from './execution-boundary.js';
+export { withExecutionBoundary } from './execution-boundary.js';
 function claimTerminalExecution(sourceId) {
     terminalExecutionClaims.add(sourceId);
     const cleanup = setTimeout(() => terminalExecutionClaims.delete(sourceId), 60000);
@@ -302,12 +281,12 @@ export class ReconcilerRuntimeBase {
         }
         const job = await this.store.load(jobId);
         const task = job.tasks.find(item => item.id === taskId);
-        if (!task || (task.executionId !== executionId && !terminalExecutionClaimed(jobId, taskId, executionId)))
+        if (terminalExecutionClaimed(jobId, taskId, executionId) || !task || task.executionId !== executionId)
             return;
         if (task.adapter !== 'chatgpt' && task.executionId === executionId && live?.executionId === executionId)
             rearmTerminalEventDeadline(this.terminalTimers, taskId, task.timeoutMs - (Date.now() - live.launchBarrier), this.options.postExitTerminalGraceMs ?? 15_000, () => this.detach(this.timeoutTask(jobId, taskId, executionId), jobId, taskId, 'post-exit terminal event timeout'));
-        await this.emit(eventFor(jobId, taskId, task.parentTaskId, task.adapter === 'chatgpt' ? 'task.process.async_exited' : 'task.process.exited', live?.execution.processExit ? (live.execution.processExit.exitCode === 0 ? 'succeeded' : 'failed') : (error ? 'failed' : 'succeeded'), result?.summary ?? (error ? 'Worker runtime exited with error' : 'Worker runtime exited'), 'orchestrator', { authoritative: false, waitingForTerminalEvent: true, exitCode: live?.execution.processExit?.exitCode ?? null,
-            signal: live?.execution.processExit?.signal ?? null, stderr: live?.execution.processExit?.stderr ?? '', processError: error, executionId, pid: live?.execution.pid ?? null }, { id: executionEventSource(jobId, taskId, executionId), agent: 'relay', component: 'agents-relay' }));
+        await this.emit(eventFor(jobId, taskId, task.parentTaskId, task.adapter === 'chatgpt' ? 'task.process.async_exited' : 'task.process.exited', live?.execution.processExit ? (live.execution.processExit.exitCode === 0 ? 'succeeded' : 'failed') : (error ? 'failed' : 'succeeded'), result?.summary ?? (live?.execution.processExit?.terminationReason === 'parent-shutdown' ? 'Worker interrupted by daemon shutdown' : error ? 'Worker runtime exited with error' : 'Worker runtime exited'), 'orchestrator', { authoritative: false, waitingForTerminalEvent: true, exitCode: live?.execution.processExit?.exitCode ?? null,
+            signal: live?.execution.processExit?.signal ?? null, terminationReason: live?.execution.processExit?.terminationReason ?? null, stderr: live?.execution.processExit?.stderr ?? '', processError: error, executionId, pid: live?.execution.pid ?? null }, { id: executionEventSource(jobId, taskId, executionId), agent: 'relay', component: 'agents-relay' }));
     }
     async timeoutTask(jobId, taskId, executionId) {
         const live = this.live.get(taskId);
@@ -363,9 +342,8 @@ export class ReconcilerRuntimeBase {
                     const prior = eventExecutionId ? task.executionHistory?.find(item => item.id === eventExecutionId) : undefined;
                     // A duplicate launch can leave one worker orphaned after another worker
                     // has already produced the terminal fact. Accept only a known execution
-                    // from the same durable attempt and only when its fact is newer than its
-                    // launch. A prior retry attempt cannot complete a newer generation.
-                    if (!prior || prior.attempt !== task.attempt || !event.timestamp || new Date(event.timestamp).getTime() < new Date(prior.startedAt).getTime())
+                    // from the same durable attempt. A prior retry attempt cannot complete a newer generation.
+                    if (!prior || prior.attempt !== task.attempt)
                         return false;
                 }
                 const terminalWaiter = this.terminalWaiters.get(task.id);
@@ -373,9 +351,7 @@ export class ReconcilerRuntimeBase {
             },
             facts: (_job, task) => {
                 const processExitedAfterPublishedTerminal = task.failureReason === 'worker_exit_without_terminal_event';
-                const freshEnough = processExitedAfterPublishedTerminal
-                    || !event.timestamp
-                    || new Date(event.timestamp).getTime() >= new Date(task.updatedAt).getTime();
+                const freshEnough = processExitedAfterPublishedTerminal || this.isCorrelatedWorkerEvent(task, event);
                 return { recoverableExecution: this.isRecoverableWatchdogFailure(task) && freshEnough };
             },
             mutate: (job, task) => {

package/dist/reconciler.js

@@ -1,3 +1,4 @@
+import { bindPlannedReviewHead } from './planned-review-head.js';
 import { randomUUID } from 'node:crypto';
 import { storySizeTimeoutMs, chatGptStartAckTimeoutMs } from './types.js';
 import { dependencyReady, schedule, transitionTaskEvent } from './scheduler.js';
@@ -6,17 +7,18 @@ import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
 import { createPlanRound, materializePlannerChild, pendingPlan } from './planner.js';
 import { dispatchPlannerOrchestration, plannerOrchestrationFacts } from './workflow/planner-orchestration-v2.js';
-import { agentContractPrompt, executionContextPrompt, resolveExecutionContext } from './execution-context.js';
-import { agentGraphPrompt } from './agent-graph.js';
+import { resolveExecutionContext } from './execution-context.js';
 import { ReconcilerReviewBase } from './reconciler-review.js';
 import { executeManualPlan } from './manual-plan.js';
 import { executionEventSource, withExecutionBoundary } from './reconciler-runtime.js';
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
 import { pendingTroubleshooterTasks } from './troubleshooter.js';
-import { prepareManagedExecutionWorktree, taskUsesCanonicalProjectRun } from './workspace.js';
-import { createReviewChairExecutionPlan } from './review-chair.js';
-import { taskTagWorkerPrompt } from './task-tag.js';
+import { assertCleanWorktreeAtHead, prepareManagedExecutionWorktree, taskUsesCanonicalProjectRun } from './workspace.js';
+import { cleanupMergedJobWorktree } from './job-worktree-cleanup.js';
+import { jobHasActiveExecution } from './job-execution-slot.js';
+import { managedWorkerInput } from './managed-worker-input.js';
+export { managedWorkerInput } from './managed-worker-input.js';
 import { recoverExpiredExecutions, recoverStartupOrphans as recoverStartupExecutionOrphans } from './execution-recovery.js';
 import { dispatchJobReconcile } from './workflow/job-reconcile-v2.js';
 import { applyOrchestratorRescue } from './workflow/orchestrator-rescue.js';
@@ -24,63 +26,6 @@ import { launchPlanExecution } from './planner-runtime.js';
 import { classifyFailure, errorMessage, observability, withObservabilityCorrelation } from './observability.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
-export async function managedWorkerInput(job, task, context) {
-    if (!['codex', 'chatgpt'].includes(task.adapter) || !job.repository || job.prNumber <= 0)
-        return task.input;
-    const selectedAgent = task.agentName && context ? await agentContractPrompt(context, task.agentName) : '';
-    const selectedGraph = task.agentGraph && context ? await agentGraphPrompt(context, task.agentGraph) : '';
-    const chairPlan = task.review?.role === 'chair' && context
-        ? createReviewChairExecutionPlan(context.agents, task.review.target)
-        : null;
-    if (!task.output)
-        throw new Error(`Task ${task.id} requires an explicit output contract`);
-    if (!task.executionId)
-        throw new Error(`Task ${task.id} requires an executionId before worker input is built`);
-    const sourceId = executionEventSource(job.id, task.id, task.executionId);
-    const prUrl = `https://github.com/${job.repository}/pull/${job.prNumber}`;
-    const taskUrl = task.taskUrl ?? `${prUrl}#issuecomment-${task.id}`;
-    const output = task.output.kind === 'file'
-        ? `file\nPath: ${task.output.path}`
-        : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`;
-    const taskTag = taskTagWorkerPrompt(job);
-    return `[Agents Relay managed task]
-Job URL: ${prUrl}
-Job ID: ${job.id}
-Task URL: ${taskUrl}
-Task ID: ${task.id}
-Project: ${task.projectName ?? context?.project.name ?? 'unspecified'}
-Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.
-${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? selectedAgent + '\n\n' : ''}${selectedGraph ? selectedGraph + '\n\n' : ''}${chairPlan ? `[Review Chair execution plan]\n${JSON.stringify(chairPlan, null, 2)}\n\nUse this runtime-discovered panel to create sibling durable specialist Tasks. Preserve each specialistTasks entry as review metadata, keep the target immutable, and synthesize structured results with synthesizeReview semantics before returning the unified revision plan.\n\n` : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
-[Output contract]
-${output}
-${taskTag}[Execution event contract — mandatory]
-Use the canonical Neo events-bus with exactly Job ${job.id} and Task ${task.id}.
-Your exact event source identity is: ${sourceId}
-Every lifecycle event for this execution MUST set source.id to that exact string. Do not derive, rename, or replace it.
-Follow the events-bus skill/protocol. For sandboxed Codex or hosted ChatGPT,
-publish through the federated MCP tool events__publish; do not open NATS directly.
-For a direct non-sandbox local worker, use NEO_EVENTS_EMIT when the caller provides it.
-As your FIRST execution action, before reading files, editing code, running commands, or doing other work,
-you MUST publish exactly one canonical task.started event for this exact Job/Task.
-
-${task.adapter === 'chatgpt' ? `Because ChatGPT execution continues asynchronously after the submit process exits, you MUST keep reporting liveness while the task is active. Publish meaningful progress/milestone events when there is real progress to report. If no meaningful milestone has been published for 30 seconds during active work, publish a non-terminal task.heartbeat event with status running, visibility orchestrator, this exact source.id, and a concise description of the current operation. Continue heartbeats after each further 30 seconds of active silence until a terminal task event is published. Do not invent percentage progress.` : `You MAY publish progress events while working. For long silent active work, follow the events-bus heartbeat policy.`}
-Before returning or allowing the worker process to exit, you MUST publish exactly one canonical terminal event:
-- task.completed only after the declared output is durable;
-- task.failed for implementation, tool, command, test, patch, commit, push, runtime, or other execution failure that prevents completion;
-- task.blocked only when genuine human/external action is required;
-- task.cancelled only when execution was cancelled.
-
-If any execution step fails and you cannot continue, publish task.failed with the concrete reason BEFORE exiting.
-Never exit after task.started without publishing exactly one terminal task event.
-Do not publish duplicate terminal task events.
-The worker owns task.started and task terminal events. Relay-owned task.process.launched, task.process.exited,
-and task.process.async_exited are process lifecycle only and NEVER replace the worker task lifecycle.
-The ChatGPT/Codex conversation or process exit is never the task result.
-
-[Final event gate]
-Before your final return, verify that a terminal event for this exact Job/Task was published.
-If no terminal event has been published, publish task.failed before exiting.`;
-}
 export class Reconciler extends ReconcilerReviewBase {
     constructor(store, options) {
         super(store, options);
@@ -93,6 +38,7 @@ export class Reconciler extends ReconcilerReviewBase {
                 await this.launch(job, task);
         }, context => `effect.launchTask:${context.jobId}:${context.taskId ?? 'task'}:${String(context.data?.attempt ?? 0)}`));
         this.workflowEffects.register(new CallbackWorkflowEffectHandler('effect.cancelActiveTasks', async (context) => this.cancelActiveTasks(context.jobId, String(context.data?.reason ?? 'Job terminated'))));
+        this.workflowEffects.register(new CallbackWorkflowEffectHandler('effect.cleanupJobWorktree', async (context) => cleanupMergedJobWorktree(await this.store.load(context.jobId), this.options.projectPathForJob), context => `effect.cleanupJobWorktree:${context.jobId}`));
         this.workflowEffects.register(new CallbackWorkflowEffectHandler('effect.mergePullRequest', async (context) => {
             const headSha = typeof context.data?.headSha === 'string' ? context.data.headSha : null;
             if (!headSha || !this.store.mergePullRequest)
@@ -106,14 +52,14 @@ export class Reconciler extends ReconcilerReviewBase {
             this.detach(this.deliverContinuation(scheduled, task), scheduled.id, task.id, 'continuation');
         }
         const capacity = Math.max(0, (this.options.maxConcurrent ?? 4) - this.live.size - this.plannerLive.size);
-        const dispatchable = scheduled.tasks
+        const dispatchable = (jobHasActiveExecution(scheduled) ? [] : scheduled.tasks)
             .filter(task => task.state === 'QUEUED'
             && task.executionId === null
             && task.kind !== 'planner'
             && task.adapter !== 'orchestrator'
             && dependencyReady(task, new Map(scheduled.tasks.map(item => [item.id, item]))))
             .sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2'))
-            .slice(0, capacity);
+            .slice(0, Math.min(capacity, 1));
         for (const task of dispatchable) {
             await transitionTaskEvent(task, 'dispatch', { dispatchable: true }, async (actionId) => {
                 const outcomes = await this.workflowEffects.execute([actionId], { jobId: scheduled.id, taskId: task.id, transitionKey: `dispatch:${task.attempt}`, data: { attempt: task.attempt } });
@@ -380,13 +326,17 @@ export class Reconciler extends ReconcilerReviewBase {
             await this.store.saveTask(task);
             return;
         }
-        const claimedTask = await withExecutionBoundary(job.id, task.id, async () => {
+        const claimedTask = await withExecutionBoundary(job.id, '__job_execution_slot__', async () => {
             const freshJob = await this.store.load(job.id);
             let freshTask = freshJob.tasks.find(item => item.id === task.id);
             if (!freshTask || freshTask.state !== 'QUEUED' || !dependencyReady(freshTask, new Map(freshJob.tasks.map(item => [item.id, item]))))
                 return;
             if (freshTask.executionId !== null)
                 return;
+            if (jobHasActiveExecution(freshJob, { taskId: freshTask.id }))
+                return;
+            if (freshTask.agentName === 'reviewer' && freshTask.planningDecisionId && freshTask.dependencies.length)
+                await bindPlannedReviewHead(this.store, freshTask);
             if (!freshTask.routing && freshTask.adapter !== 'orchestrator') {
                 freshTask = (await this.routeTaskForExecution(freshJob, freshTask)).task;
             }
@@ -426,6 +376,8 @@ export class Reconciler extends ReconcilerReviewBase {
                 if (!managedHead)
                     throw new Error(`PR #${job.prNumber} has no resolvable head ref`);
                 projectPath = await prepareManagedExecutionWorktree(projectPath, job.repository, job.prNumber, managedHead, task.executionId);
+                if (role === 'reviewer')
+                    await assertCleanWorktreeAtHead(projectPath, managedHead.sha);
             }
             executionContext = await this.resolvedContext(job, task, role, projectPath);
         }

package/dist/runtime-status.js

@@ -32,13 +32,16 @@ export function deriveJobRuntimeStatus(job, prState = 'OPEN') {
             return 'WAITING';
         return 'WAITING';
     }
-    const reviewTasks = job.tasks.filter(task => task.agentName === 'reviewer');
-    const reviewActive = reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state))
-        || job.review?.outcome === 'pending'
-        || job.review?.outcome === 'started';
+    // Draft or queued reviewers must not mask implementation that is still active.
+    const implementation = implementationTasks(job);
+    if (implementation.some(task => task.state === 'RUNNING'))
+        return 'RUNNING';
+    if (implementation.some(task => task.state === 'QUEUED'))
+        return 'QUEUED';
+    const reviewRunning = job.tasks.some(task => task.agentName === 'reviewer' && task.state === 'RUNNING');
     if (job.review?.outcome === 'approved' && prState === 'OPEN')
         return 'MERGE_PENDING';
-    if (reviewActive || (job.reviewEnabled !== false && implementationComplete(job) && job.review?.outcome !== 'approved'))
+    if (reviewRunning)
         return 'REVIEWING';
     if (job.tasks.some(task => task.state === 'RUNNING'))
         return 'RUNNING';

package/dist/scheduler.js

@@ -9,7 +9,10 @@ export function completionGateSatisfied(job) {
         return false;
     if (job.executionMode !== 'autonomous')
         return true;
-    const planSatisfied = (job.plans ?? []).some(plan => plan.status === 'SUCCEEDED' && plan.objectiveStatus === 'satisfied');
+    const latest = [...(job.plans ?? [])].sort((a, b) => a.round - b.round).at(-1);
+    const previousReviewFinished = job.tasks.some(task => task.agentName === 'reviewer' && task.state === 'SUCCEEDED');
+    const planSatisfied = latest?.status === 'SUCCEEDED' && (latest.objectiveStatus === 'satisfied'
+        || (latest.objectiveStatus === 'in_progress' && latest.plannerResult?.next_tasks?.length === 0 && previousReviewFinished));
     const legacySatisfied = (job.plans?.length ?? 0) === 0 && job.tasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && task.plannerResult?.objective_status === 'satisfied');
     return (planSatisfied || legacySatisfied) && implementationTasks(job).every(task => task.state === 'SUCCEEDED');
 }

package/dist/workflow/contracts.js

@@ -4,6 +4,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'cancel',
     'dispatch',
     'effect.cancelActiveTasks.failed',
+    'effect.cleanupJobWorktree.failed',
     'effect.launchTask.failed',
     'effect.mergePullRequest.failed',
     'execution.orphaned',
@@ -66,6 +67,7 @@ export const WORKFLOW_EFFECT_NAMES = [
     'effect.launchTask',
     'effect.cancelActiveTasks',
     'effect.mergePullRequest',
+    'effect.cleanupJobWorktree',
 ];
 export const WORKFLOW_EFFECT_POLICIES = {
     'effect.launchTask': {
@@ -80,6 +82,12 @@ export const WORKFLOW_EFFECT_POLICIES = {
         retry: 'workflow',
         observability: 'workflow.effect',
     },
+    'effect.cleanupJobWorktree': {
+        idempotency: 'job-completed',
+        failureEvent: 'effect.cleanupJobWorktree.failed',
+        retry: 'workflow',
+        observability: 'workflow.effect',
+    },
     'effect.mergePullRequest': {
         idempotency: 'job-head-sha',
         failureEvent: 'effect.mergePullRequest.failed',

package/dist/workspace.js

@@ -1,4 +1,4 @@
-import { mkdir, readdir, stat } from 'node:fs/promises';
+import { lstat, mkdir, readdir, realpath, stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnOwnedProcess } from './owned-process.js';
@@ -122,7 +122,7 @@ export function taskUsesCanonicalProjectRun(task, tasks) {
 async function git(path, args) {
     return (await gitOutput(['-C', path, ...args])).trim();
 }
-export async function prepareManagedExecutionWorktree(projectPath, repository, prNumber, head, executionId) {
+export async function prepareManagedExecutionWorktree(projectPath, repository, prNumber, head, _executionId, workspaceRoot = defaultWorkspaceRoot()) {
     const primary = await git(projectPath, ['rev-parse', '--show-toplevel']);
     const projectRelative = (await git(projectPath, ['rev-parse', '--show-prefix'])).replace(/\/$/, '');
     const remote = await git(primary, ['config', '--get', 'remote.origin.url']);
@@ -133,14 +133,25 @@ export async function prepareManagedExecutionWorktree(projectPath, repository, p
     if (fetched !== head.sha)
         throw new Error(`PR #${prNumber} head changed while preparing execution checkout (${head.sha} -> ${fetched})`);
     const safeRepo = repository.replace(/[^A-Za-z0-9_.-]+/g, '-');
-    const safeExecution = executionId.replace(/[^A-Za-z0-9_.-]+/g, '-');
-    const worktree = join(dirname(primary), '.worktrees', 'agents-relay', `${safeRepo}-pr-${prNumber}`, safeExecution);
+    // One stable checkout per Job; retries and reviewers share the same directory.
+    const worktree = managedJobWorktreePath(repository, prNumber, workspaceRoot);
     await mkdir(dirname(worktree), { recursive: true });
     try {
         const existingRoot = await git(worktree, ['rev-parse', '--show-toplevel']);
         const existingHead = await git(worktree, ['rev-parse', 'HEAD']);
-        if (resolve(existingRoot) !== resolve(worktree) || existingHead !== head.sha)
-            throw new Error(`Existing execution worktree ${worktree} is not the expected PR head`);
+        if (await realpath(existingRoot) !== await realpath(worktree))
+            throw new Error(`Worktree ownership mismatch: ${worktree}`);
+        if (existingHead !== head.sha) {
+            // Never wipe dirty files or commits unique to this Job checkout. A clean
+            // ancestor can safely advance to the remote PR head without reset --hard.
+            const dirty = await git(worktree, ['status', '--porcelain']);
+            if (dirty)
+                throw new Error(`Job worktree has changes while PR head advanced: ${worktree}`);
+            const ancestor = await gitOutput(['-C', worktree, 'merge-base', '--is-ancestor', existingHead, head.sha]).then(() => true, () => false);
+            if (!ancestor)
+                throw new Error(`Job worktree has non-fast-forward history; preserve commits: ${worktree}`);
+            await git(worktree, ['merge', '--ff-only', head.sha]);
+        }
         return projectRelative ? join(worktree, projectRelative) : worktree;
     }
     catch (error) {
@@ -164,3 +175,67 @@ function repositoryPathRank(path, root) {
         return 3;
     return 1;
 }
+/** Stable checkout identity for the entire managed PR/Job lifecycle. */
+export function managedJobWorktreePath(repository, prNumber, workspaceRoot = defaultWorkspaceRoot()) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || !Number.isSafeInteger(prNumber) || prNumber <= 0)
+        throw new Error('Invalid managed Job checkout identity');
+    return join(workspaceRoot, '.worktrees', 'agents-relay', `${repository.replace('/', '-')}-pr-${prNumber}`, 'job');
+}
+/**
+ * Graph-owned eligibility: called only after authoritative MERGED -> COMPLETED.
+ * This function only performs the mechanical, conservative cleanup effect.
+ */
+export async function cleanupCompletedJobWorktree(projectPath, job, workspaceRoot = defaultWorkspaceRoot()) {
+    if (job.state !== 'COMPLETED')
+        return { status: 'blocked', reason: 'Job is not completed' };
+    if (!job.headSha)
+        return { status: 'blocked', reason: 'No durable PR head SHA' };
+    if (job.tasks.some(task => task.executionId !== null || task.leaseOwner !== null))
+        return { status: 'blocked', reason: 'Task still owns an execution or lease' };
+    if ((job.plans ?? []).some(plan => plan.executionId !== null || plan.leaseOwner !== null))
+        return { status: 'blocked', reason: 'Planner still owns an execution or lease' };
+    const worktree = managedJobWorktreePath(job.repository, job.prNumber, workspaceRoot);
+    let metadata;
+    try {
+        metadata = await lstat(worktree);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { status: 'absent' };
+        throw error;
+    }
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        return { status: 'blocked', reason: 'Worktree path is not an owned directory' };
+    const primary = await git(projectPath, ['rev-parse', '--show-toplevel']);
+    const origin = await git(primary, ['config', '--get', 'remote.origin.url']);
+    if (githubRepositoryFromRemote(origin) !== job.repository)
+        return { status: 'blocked', reason: 'Canonical repository identity mismatch' };
+    const registered = await git(primary, ['worktree', 'list', '--porcelain']);
+    const ownedRoot = await realpath(worktree);
+    const registeredPaths = registered.split('\n').filter(line => line.startsWith('worktree '));
+    const matching = await Promise.all(registeredPaths.map(async (line) => {
+        try {
+            return await realpath(line.slice('worktree '.length)) === ownedRoot;
+        }
+        catch {
+            return false;
+        }
+    }));
+    if (!matching.includes(true))
+        return { status: 'blocked', reason: 'Worktree is not registered with the canonical repository' };
+    const head = await git(worktree, ['rev-parse', 'HEAD']);
+    if (head !== job.headSha)
+        return { status: 'blocked', reason: 'Worktree contains unique or stale commits' };
+    if (await git(worktree, ['status', '--porcelain']))
+        return { status: 'blocked', reason: 'Worktree has uncommitted or untracked changes' };
+    await git(primary, ['worktree', 'remove', worktree]);
+    return { status: 'removed' };
+}
+/** Reviewer must never inspect local, uncommitted content as an immutable SHA. */
+export async function assertCleanWorktreeAtHead(projectPath, headSha) {
+    const actual = await git(projectPath, ['rev-parse', 'HEAD']);
+    if (actual !== headSha)
+        throw new Error(`Review checkout has stale HEAD: ${actual}, expected ${headSha}`);
+    if (await git(projectPath, ['status', '--porcelain']))
+        throw new Error(`Review checkout has uncommitted changes: ${projectPath}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.63",
+  "version": "2.0.65",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {

package/workflow/job-lifecycle.mmd

@@ -68,3 +68,9 @@ cancelled -->|on: pr.merged| cancelCancelledMerge
 cancelCancelledMerge --> completed
 cancelled -->|on: effect.cancelActiveTasks.failed| cancelled
 completed -->|on: effect.cancelActiveTasks.failed| completed
+
+%% Cleanup eligibility belongs to the lifecycle graph and is retryable after restart.
+cleanupCompletedWorktree["action: effect.cleanupJobWorktree"]
+completed -->|on: pr.merged| cleanupCompletedWorktree
+cleanupCompletedWorktree --> completed
+completed -->|on: effect.cleanupJobWorktree.failed| completed