agents-relay 2.0.64 → 2.0.65

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/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/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/reconciler.js

@@ -7,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';
@@ -25,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);
@@ -94,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)
@@ -107,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 } });
@@ -381,13 +326,15 @@ 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') {
@@ -429,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/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.64",
+  "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