agents-relay 2.0.64 → 2.0.66

package/README.md

@@ -151,6 +151,22 @@ Use `job update` for partial mutable metadata changes on an already healthy Job
 npx agents-relay job update --repo OWNER/REPO --pr 6 --id job-6 --priority P0 --no-auto-merge
 ~~~
 
+Request an eligible new review with `npx agents-relay review request --repo OWNER/REPO --pr NUMBER --id JOB_ID`.
+Pass optional `--thread-id THREAD_ID` to persist a reviewer-thread override for subsequent
+review routing. Without it, Relay uses the stored reviewer thread, then creator thread,
+or the legacy review path when neither exists. This request wakes graph-owned
+review orchestration; it is not a delivery receipt.
+
+Review destinations are durable Job facts. `job create` and `job update` accept
+`--reviewer-thread-id` and `--creator-thread-id`; a reviewer ID takes precedence
+over the creator/origin ID. A local runtime invocation may pass
+`--thread-id` as an explicit one-run review override. When a destination exists,
+final-review routing requires a ChatGPT/browser-workspace worker and submits the
+review request as a verified `new-turn` to that existing thread with the Job ID,
+PR number, and immutable review head SHA. Failure still follows the ordinary
+review task retry/recovery path; a transport failure is never treated as
+review delivery.
+
 `job update` validates the trusted Job marker first. Missing, malformed, duplicated, mismatched, or conflicting bindings fail with a precise diagnostic and are not repaired implicitly. The orchestrator handles exceptional repair explicitly according to the Job contract, then retries the update. `job show` reads one Job and `job list` lists managed Jobs in a repository.
 
 Managed GitHub task create/update/show/list/retry/cancel and reconcile/serve commands also require a durable Job marker. Orchestrators do not need raw GitHub commands for normal Job creation or metadata updates: Agents Relay uses its authenticated GitHub client internally.

package/dist/adapters.js

@@ -122,7 +122,7 @@ function findSubmittedReceipt(value) {
     if (!value || typeof value !== 'object')
         return undefined;
     const record = value;
-    if (record.operation === 'submit' && record.status === 'submitted')
+    if ((record.operation === 'submit' || record.operation === 'new-turn' || record.mode === 'new-turn') && record.status === 'submitted')
         return record;
     for (const key of ['result', 'output', 'data', 'stdout']) {
         const nested = findSubmittedReceipt(record[key]);
@@ -200,13 +200,64 @@ export async function ensureChatGptBrowserWorkspace(command = process.env.AGENTS
     }
     await admin.ensureWorkspace(CHATGPT_BROWSER_WORKSPACE, CHATGPT_BROWSER_WORKSPACE_POOL_SIZE);
 }
-async function runBrowserWorker(cli, configFile, signal) {
+/**
+ * The upstream new-turn action accepts idempotency_key but does not enforce it.
+ * Inspect the current thread before resubmitting after an ambiguous exit.
+ * If the transcript is not observable, fail closed rather than duplicate.
+ */
+async function findExistingReviewTurn(cli, sessionId, delivery, signal) {
+    const pathname = delivery.projectId
+        ? `/g/${encodeURIComponent(delivery.projectId)}/c/${encodeURIComponent(delivery.threadId)}`
+        : `/c/${encodeURIComponent(delivery.threadId)}`;
+    const marker = `Relay delivery ID: ${delivery.requestId}`;
+    const inspectJs = `(() => {
+    const legacy = [...document.querySelectorAll('[data-message-author-role="user"]')]
+      .map(e => ({text: (e.innerText || '').trim(), id: e.getAttribute('data-message-id') || ''})).filter(x => x.text);
+    if (legacy.length) return legacy;
+    return [...document.querySelectorAll('h4')].filter(e => (e.innerText || '').trim() === 'You said:')
+      .map((e,i) => ({text: (e.parentElement?.innerText || '').trim(), id: 'dom-user-' + i})).filter(x => x.text);
+  })()`;
+    const script = [
+        'import json, time',
+        'from urllib.parse import urlsplit',
+        `url = ${JSON.stringify(`https://chatgpt.com${pathname}`)}`,
+        `marker = ${JSON.stringify(marker)}`,
+        'goto_url(url)',
+        'wait_for_load()',
+        'if urlsplit(page_info().get("url", "")).path.rstrip("/") != urlsplit(url).path.rstrip("/"): raise RuntimeError("review thread redirect mismatch")',
+        'turns = []',
+        'for attempt in range(30):',
+        `    turns = js(${JSON.stringify(inspectJs)}) or []`,
+        '    if turns: break',
+        '    time.sleep(0.5)',
+        'if not turns: raise RuntimeError("review thread transcript unavailable; refusing ambiguous resubmission")',
+        'matches = [turn for turn in turns if marker in turn.get("text", "")]',
+        'if len(matches) > 1: raise RuntimeError("duplicate review delivery detected; manual reconciliation required")',
+        'print(json.dumps({"found": bool(matches), "user_message_id": matches[0].get("id") if matches else None}), flush=True)',
+    ].join('\n');
+    const envelope = parseWorkspaceJson(await browserWorkspaceCommand(cli, ['session', 'exec', sessionId], script, signal));
+    if (envelope.ok !== true || typeof envelope.stdout !== 'string')
+        throw new Error('review thread inspection returned no executable result');
+    const observation = parseWorkspaceJson(envelope.stdout);
+    if (typeof observation.found !== 'boolean')
+        throw new Error('review thread inspection returned no authoritative result');
+    if (!observation.found)
+        return null;
+    return { status: 'submitted', mode: 'new-turn', thread_id: delivery.threadId, project_id: delivery.projectId,
+        verified_by: 'existing-user-turn', user_message_id: typeof observation.user_message_id === 'string' ? observation.user_message_id : null };
+}
+async function runBrowserWorker(cli, configFile, signal, action = 'temporary-submit', delivery) {
     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);
+        if (delivery) {
+            const existing = await findExistingReviewTurn(cli, sessionId, delivery, signal);
+            if (existing)
+                return JSON.stringify(existing);
+        }
+        return await browserWorkspaceCommand(cli, ['platform', 'run', 'chatgpt', action, '--session-id', sessionId, '--config', configFile], undefined, signal);
     }
     finally {
         await browserWorkspaceCommand(cli, ['session', 'stop', sessionId]).catch(() => { });
@@ -218,13 +269,20 @@ function browserWorkerRunner() {
         const promise = (async () => {
             const configFile = join(process.env.TMPDIR ?? '/tmp', `agents-relay-chatgpt-${randomUUID()}.json`);
             try {
-                await writeFile(configFile, JSON.stringify({
+                const delivery = request.thread;
+                await writeFile(configFile, JSON.stringify(delivery ? {
+                    project_id: delivery.projectId ?? _route.projectId ?? null,
+                    thread_id: delivery.threadId,
+                    message: `${request.prompt}\n\nRelay delivery ID: ${delivery.requestId}`,
+                    idempotency_key: delivery.requestId,
+                } : {
                     prompt: request.prompt,
                     file: request.files ?? [],
                 }));
                 if (signal.aborted)
                     throw new Error('browser-worker execution aborted');
-                const output = await runBrowserWorker(cli, configFile, signal);
+                const action = delivery ? 'new-turn' : 'temporary-submit';
+                const output = await runBrowserWorker(cli, configFile, signal, action, delivery);
                 return JSON.stringify(parseDriverJson(output));
             }
             finally {
@@ -246,11 +304,10 @@ function parseBrowserWorkerResponse(output) {
     if (!value || typeof value !== 'object')
         throw new Error('browser-worker returned an invalid JSON response');
     const response = value;
-    if (response.operation !== 'submit' || response.status !== 'submitted') {
+    const verified = response.verified === true || response.verified_by !== undefined;
+    if (response.status !== 'submitted' || !verified) {
         throw new Error('browser-worker did not return a submitted receipt');
     }
-    if (response.verified !== true)
-        throw new Error('browser-worker submission was not verified');
     return response;
 }
 export class ChatGptAdapter {
@@ -287,10 +344,19 @@ 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 ?? browserWorkerRunner())(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 } : {}),
+                ...(task.chatgptThreadDelivery ? { thread: task.chatgptThreadDelivery } : {}),
+                tabClosePolicy: policy,
+            }, route, controller.signal);
             try {
                 const output = await (run.submitted ?? run.promise);
                 const response = parseBrowserWorkerResponse(output);
+                if (task.chatgptThreadDelivery && (typeof response.thread_id !== 'string' || response.thread_id !== task.chatgptThreadDelivery.threadId)) {
+                    throw new Error('browser-worker submitted to an unexpected ChatGPT thread');
+                }
+                execution.deliveryReceipt = { ...response };
                 launchResolve();
                 if (policy === 'after-start' && context.waitForWorkerStart)
                     await context.waitForWorkerStart;
@@ -307,6 +373,8 @@ export class ChatGptAdapter {
                     summary: 'ChatGPT task submitted; terminal task state is event-owned',
                     data: {
                         submitted: true,
+                        mode: response.mode ?? 'temporary-submit',
+                        threadId: response.thread_id ?? response.diagnostic_thread_id ?? null,
                         diagnosticThreadId: response.diagnostic_thread_id ?? null,
                         userMessageId: response.user_message_id ?? null,
                         verifiedBy: response.verified_by ?? null,

package/dist/cli-help.js

@@ -1,4 +1,4 @@
-export const usage = 'agents-relay <job|task|plan|blocker|projection|escalation|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
+export const usage = 'agents-relay <job|task|review|plan|blocker|projection|escalation|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -8,6 +8,7 @@ Usage:
 Commands:
   job create|update|show|list|merge|unblock|cancel  Manage durable GitHub-backed jobs
   task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
+  review request           Request graph-owned review (optional thread override)
   plan                     Invoke the Planner for an existing managed Job
   blocker add|resolve|show  Manage cross-Job blocker dependencies
   projection conflicts|resolve  Inspect and repair deterministic GitHub projection conflicts
@@ -44,11 +45,20 @@ Common options:
 
 Example:
   npx agents-relay job show --repo OWNER/REPO --pr 12 --id job-1`,
+    review: `Request a new SHA-bound reviewer turn through the existing Relay lifecycle.
+
+Usage: npx agents-relay review request --repo OWNER/REPO --pr NUMBER --id JOB_ID [--thread-id THREAD_ID]
+
+When provided, --thread-id persists a reviewer destination; otherwise the Job reviewer thread, then creator thread, then legacy review route is used. The command wakes Relay. Review Task creation, idempotency, routing and delivery remain graph/daemon-owned. Rejects in-flight/queued reviews; does not itself mark review delivered.`,
+    'review request': `Request a review in an existing ChatGPT thread.
+
+Required: --repo OWNER/REPO --pr NUMBER --id JOB_ID.
+Optional: --thread-id THREAD_ID persists a reviewer override; omitted uses Job reviewer/creator thread or legacy route. Rejects pending reviews and wakes managed reconciliation.`,
     'job create': `Create a durable Job and its trusted marker.
 
 Required: --repo OWNER/REPO, --id JOB_ID, and either --head BRANCH or --pr NUMBER.
 With --head, reuse/create the PR for that head. With --pr, bind an existing unmanaged PR.
-Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --no-review, --tag JSON. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
+Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --no-review, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
 Job creation always enables auto-merge and never creates executable tasks. The orchestrator decides the initial task batch separately. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
 
 Example:
@@ -56,7 +66,7 @@ Example:
     'job update': `Partially update mutable metadata on a healthy existing Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
-Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --mode fixed|autonomous, --schedule, --tag JSON, --auto-merge|--no-auto-merge, --review|--no-review, and continuation options. Updating the objective also updates the PR body.
+Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --mode fixed|autonomous, --schedule, --tag JSON, --auto-merge|--no-auto-merge, --review|--no-review, --reviewer-thread-id ID, --creator-thread-id ID, and continuation options. Updating the objective also updates the PR body.
 Unspecified fields are preserved. Marker/binding corruption is never repaired implicitly; update fails with a precise diagnostic instead.
 
 Example:
@@ -185,7 +195,7 @@ Example:
 
 Required: --file PATH for local demo mode, or --repo OWNER/REPO --pr NUMBER --id JOB_ID.
 
-Managed GitHub jobs are reconciled by agents-relayd. The CLI publishes a job.wake request and does not launch workers; NATS is auto-detected when reachable; use --events nats to require it explicitly.
+Managed GitHub jobs are reconciled by agents-relayd. The CLI publishes a job.wake request and does not launch workers; NATS is auto-detected when reachable; use --events nats to require it explicitly. Local/runtime invocations may use --thread-id ID to override the durable reviewer/creator thread for ChatGPT review delivery.
 
 Example:
   npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1`,
@@ -198,7 +208,7 @@ Example:
     serve: `Run the dashboard and reconciliation service for a managed job.
 
 Required: --file PATH for local demo mode, or --repo OWNER/REPO --pr NUMBER --id JOB_ID.
-Common: --port PORT, --interval MS, --events nats (optional; reachable NATS is auto-detected).
+Common: --port PORT, --interval MS, --events nats (optional; reachable NATS is auto-detected), --thread-id ID (reviewer-thread override).
 
 Example:
   npx agents-relay serve --repo OWNER/REPO --pr 12 --id job-1`,

package/dist/cli-review.js

@@ -0,0 +1,35 @@
+import { storeFor, arg, hasArg, withEventBus, requestManagedReconciliation } from './cli-support.js';
+import { normalizeThreadId, resolveReviewerThreadDestination } from './reviewer-thread.js';
+export function reviewRequestThreadOverride(args) {
+    const values = [...args];
+    return hasArg(values, '--thread-id')
+        ? normalizeThreadId(arg(values, '--thread-id'), '--thread-id')
+        : undefined;
+}
+export async function runReviewCommand(action, reviewArgs) {
+    if (action !== 'request')
+        throw new Error('review supports: request');
+    if (!arg(reviewArgs, '--repo') || !arg(reviewArgs, '--pr') || !arg(reviewArgs, '--id'))
+        throw new Error('review request requires --repo, --pr and --id');
+    const threadId = reviewRequestThreadOverride(reviewArgs);
+    const { store, job, localFile } = await storeFor(reviewArgs);
+    if (localFile)
+        throw new Error('review request requires a managed GitHub Job');
+    if (job.state === 'CANCELLED' || job.state === 'COMPLETED')
+        throw new Error('Cannot request review for terminal Job');
+    if (!job.reviewEnabled)
+        throw new Error('Review disabled for this Job');
+    if (job.tasks.some(task => task.agentName === 'reviewer' && ['RUNNING', 'QUEUED', 'DRAFT'].includes(task.state)))
+        throw new Error('Review already queued or running; refusing duplicate request');
+    if (job.review?.outcome === 'approved')
+        throw new Error('Current head already approved; review request not needed');
+    if (threadId !== undefined) {
+        job.reviewerThreadId = threadId;
+        job.updatedAt = new Date().toISOString();
+        await store.saveJob(job);
+    }
+    const destination = resolveReviewerThreadDestination(job);
+    await withEventBus(reviewArgs, async (bus) => requestManagedReconciliation(bus, job));
+    console.log(JSON.stringify({ jobId: job.id, pr: job.prNumber, reviewerThreadId: destination?.threadId ?? null, status: 'requested', note: 'Relay graph will create the review Task once eligible; this is not a delivery receipt.' }, null, 2));
+    return;
+}

package/dist/cli.js

@@ -32,6 +32,9 @@ import { createJobEntity, createTaskEntity } from './workflow/entity-creation.js
 import { runCliEntrypoint } from './cli-shutdown.js';
 import { shutdownOwnedProcesses } from './owned-process.js';
 export { helpText } from './cli-help.js';
+import { runReviewCommand } from './cli-review.js';
+import { normalizeThreadId, runtimeReviewer } from './reviewer-thread.js';
+export { runtimeReviewer } from './reviewer-thread.js';
 import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, publishDependentUnblocked, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, jobTagFromArgs, requestManagedReconciliation, relayControlJob, relayTaskCommand, withEventBus } from './cli-support.js';
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
 export async function ensureManagedGitHubJob(client, repositoryName, trustedAuthors, options) {
@@ -59,6 +62,8 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         tag: options.tag,
         autoMerge: true,
         reviewEnabled: options.reviewEnabled ?? true,
+        ...(options.reviewerThreadId ? { reviewerThreadId: normalizeThreadId(options.reviewerThreadId, 'reviewer thread ID') } : {}),
+        ...(options.creatorThreadId ? { creatorThreadId: normalizeThreadId(options.creatorThreadId, 'creator thread ID') } : {}),
         prNumber: pr.number,
         repository: repositoryName,
         continuation: options.continuation ?? null,
@@ -390,6 +395,8 @@ async function runJobCommand(action, args) {
             tag: jobTagFromArgs(args),
             reviewEnabled: !hasArg(args, '--no-review'),
             continuation: continuation(args),
+            ...(hasArg(args, '--reviewer-thread-id') ? { reviewerThreadId: arg(args, '--reviewer-thread-id') } : {}),
+            ...(hasArg(args, '--creator-thread-id') ? { creatorThreadId: arg(args, '--creator-thread-id') } : {}),
             prNumber,
             head: arg(args, '--head') || undefined,
             base: arg(args, '--base', 'main'),
@@ -459,6 +466,10 @@ async function runJobCommand(action, args) {
         job.reviewEnabled = true;
     if (hasArg(args, '--no-review'))
         job.reviewEnabled = false;
+    if (hasArg(args, '--reviewer-thread-id'))
+        job.reviewerThreadId = normalizeThreadId(arg(args, '--reviewer-thread-id'), '--reviewer-thread-id');
+    if (hasArg(args, '--creator-thread-id'))
+        job.creatorThreadId = normalizeThreadId(arg(args, '--creator-thread-id'), '--creator-thread-id');
     if (hasArg(args, '--continue-kind') || hasArg(args, '--continue-target')) {
         const next = continuation(args);
         if (!next)
@@ -470,8 +481,7 @@ async function runJobCommand(action, args) {
     console.log(JSON.stringify(await store.load(id), null, 2));
 }
 export function runtimePlanner(args) { const plannerCommand = arg([...args], '--planner-command'); const modelRuntime = arg([...args], '--codex', 'codex'); return plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); }
-export function runtimeReviewer() { return { requirements: { capabilities: ['model'] } }; }
-export function runtime(store, args, bus, usageRegistry = codexAndZaiUsageRegistry()) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, usageSnapshotProvider: () => usageRegistry.snapshot(), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), reviewer: runtimeReviewer(), eventBus: bus, emit, chatgptTabClosePolicy: policy, projectPathForJob: async (job) => resolveRepositoryProjectPath(await resolveManagedProjectPath(job.repository, arg(args, '--project-path'), arg(args, '--workspace-root') || defaultWorkspaceRoot()), job.projectPath) }); }
+export function runtime(store, args, bus, usageRegistry = codexAndZaiUsageRegistry()) { const emit = (event) => { process.stderr.write(`${JSON.stringify(event)}\n`); }; const modelRuntime = arg(args, '--codex', 'codex'); const policy = chatGptTabClosePolicy(args); const planner = runtimePlanner(args); return new Reconciler(store, { owner: arg(args, '--owner', `cli-${process.pid}`), maxConcurrent: Number(arg(args, '--concurrency', '4')), leaseMs: Number(arg(args, '--lease-ms', '300000')), adapters: [new CodexAdapter(modelRuntime), new ChatGptAdapter({ tabClosePolicy: policy })], continuations: [new CodexThreadContinuation(modelRuntime), new CommandContinuation(), new WebhookContinuation()], planner, usageSnapshotProvider: () => usageRegistry.snapshot(), decisionEngine: executionDecisionEngine(), decisionMode: decisionMode(), reviewer: runtimeReviewer(args), eventBus: bus, emit, chatgptTabClosePolicy: policy, projectPathForJob: async (job) => resolveRepositoryProjectPath(await resolveManagedProjectPath(job.repository, arg(args, '--project-path'), arg(args, '--workspace-root') || defaultWorkspaceRoot()), job.projectPath) }); }
 export function dashboardJobAction(store, reconciler, action) {
     return async (jobId) => {
         const job = await store.load(jobId);
@@ -572,7 +582,7 @@ async function main() {
         return;
     }
     if (args.includes('--help') || args.includes('-h')) {
-        console.log(helpText(command, command === 'job' || command === 'task' || command === 'context' ? args[0] : undefined));
+        console.log(helpText(command, command === 'job' || command === 'task' || command === 'context' || command === 'review' ? args[0] : undefined));
         return;
     }
     if (command === 'job') {
@@ -585,6 +595,11 @@ async function main() {
         await runTaskCommand(action ?? '', taskArgs);
         return;
     }
+    if (command === 'review') {
+        const [action, ...reviewArgs] = args;
+        await runReviewCommand(action ?? '', reviewArgs);
+        return;
+    }
     if (command === 'context') {
         const [action, ...contextArgs] = args;
         await runContextCommand(action ?? '', contextArgs);

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-review.js

@@ -7,6 +7,7 @@ import { routeExecution } from './execution-routing.js';
 import { ReconcilerRuntimeBase } from './reconciler-runtime.js';
 import { dispatchReviewLifecycle, reviewOutcome } from './workflow/review-v2.js';
 import { createTaskEntity } from './workflow/entity-creation.js';
+import { chatgptThreadRequirements, resolveReviewerThreadDestination } from './reviewer-thread.js';
 export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
     async currentHeadSha(job) { return await this.store.headSha?.() ?? job.headSha ?? job.review?.headSha ?? null; }
     reviewFacts(job, prState, headSha) {
@@ -108,17 +109,35 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         const id = this.nextFinalReviewTaskId(job, headSha);
         const now = new Date().toISOString();
         const reviewGateTasks = implementationTasks(job);
-        const reviewerRouting = await this.selectReviewer(reviewGateTasks);
+        const reviewThread = resolveReviewerThreadDestination(job, this.options.reviewer?.threadId);
+        const reviewerRouting = await this.selectReviewer(reviewGateTasks, reviewThread ? chatgptThreadRequirements(this.options.reviewer?.requirements) : undefined);
+        const chatgptThreadDelivery = reviewThread ? {
+            kind: 'new-turn',
+            threadId: reviewThread.threadId,
+            threadSource: reviewThread.source,
+            requestId: `${job.id}:${id}:${headSha}`,
+            jobId: job.id,
+            prNumber: job.prNumber,
+            reviewHeadSha: headSha,
+            projectId: reviewerRouting.candidate.routing.projectId ?? null,
+        } : undefined;
+        const input = [
+            `Job ID: ${job.id}`,
+            `Review PR #${job.prNumber} at exactly head SHA ${headSha}.`,
+            `Review 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 exact PR head, requirements, tests and genuine blocking defects.',
+            'Do not block approval because automatic merge, Job COMPLETED, or post-merge E2E evidence has not occurred yet.',
+            'Do not treat historical failed attempts as current artifact defects; distinguish preserved baseline files from implementation.',
+        ].join('\n\n');
         const task = createTaskEntity(job, {
             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. ' +
-                '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.',
+            input,
             output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.routing, continuation: null, continuationDeliveredAt: null,
+            chatgptThreadDelivery,
             reviewHeadSha: headSha, attempt: 0, maxAttempts: this.options.reviewer?.maxAttempts ?? 2,
             leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null,
             error: null, timeoutMs: this.options.reviewer?.timeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now
@@ -149,7 +168,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
         const ready = schedule(await this.store.load(job.id));
         await this.store.saveJob(ready);
     }
-    async selectReviewer(implementationTasks) {
+    async selectReviewer(implementationTasks, requirementsOverride) {
         const configured = this.options.reviewer;
         const registered = await this.store.listAgents();
         const usage = this.options.usageSnapshotProvider ? await this.options.usageSnapshotProvider() : undefined;
@@ -185,7 +204,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
             },
         };
         const runtimeSummary = this.options.runtimeSummaryProvider?.();
-        const routed = await routeExecution(workers, configured?.requirements ?? { capabilities: ['model'] }, {
+        const routed = await routeExecution(workers, requirementsOverride ?? configured?.requirements ?? { capabilities: ['model'] }, {
             decisionEngine: this.options.decisionEngine,
             decisionMode: this.options.decisionMode,
             taskFacts,

package/dist/reconciler.js

@@ -7,17 +7,19 @@ 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 { recordThreadDelivery } from './reviewer-thread.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 +27,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 +39,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 +53,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 +327,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 +377,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);
         }
@@ -456,9 +406,7 @@ export class Reconciler extends ReconcilerReviewBase {
         const workerTask = { ...task, input: workerInput, routing: task.routing ? { ...task.routing, cwd: executionContext.project.path } : task.routing };
         const startAckSetup = task.adapter === 'chatgpt' ? await this.startAck(job.id, task.id, sourceId, Date.now(), this.options.startAckTimeoutMs ?? chatGptStartAckTimeoutMs(task.timeoutMs)) : null;
         const closePolicy = task.chatgptTabClosePolicy ?? this.options.chatgptTabClosePolicy ?? adapter.tabClosePolicy ?? 'after-start';
-        const terminalWait = task.adapter === 'chatgpt' && closePolicy === 'after-terminal'
-            ? this.terminalWait(task.id, durableExecutionId, startedAt - 1)
-            : null;
+        const terminalWait = task.adapter === 'chatgpt' && closePolicy === 'after-terminal' ? this.terminalWait(task.id, durableExecutionId, startedAt - 1) : null;
         const launchContext = {
             ...(startAckSetup ? { waitForWorkerStart: startAckSetup.ack } : {}),
             ...(terminalWait ? { waitForTerminal: terminalWait.promise } : {}),
@@ -473,7 +421,7 @@ export class Reconciler extends ReconcilerReviewBase {
             await this.failLaunch(job.id, task.id, task.executionId, error instanceof Error ? error.message : String(error));
             return;
         }
-        void (execution.launched ?? Promise.resolve()).then(() => this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.process.launched', 'running', `Task ${task.id} process launched`, 'user', { adapter: adapter.id, model: task.routing?.model, pid: execution.pid ?? null, executionId: durableExecutionId }, { agent: 'relay', component: 'agents-relay' }))).catch(error => this.failLaunch(job.id, task.id, durableExecutionId, error instanceof Error ? error.message : String(error), 'launch'));
+        void (execution.launched ?? Promise.resolve()).then(() => Promise.all([recordThreadDelivery(this.store, job.id, task.id, durableExecutionId, workerTask), this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.process.launched', 'running', `Task ${task.id} process launched`, 'user', { adapter: adapter.id, model: task.routing?.model, pid: execution.pid ?? null, executionId: durableExecutionId }, { agent: 'relay', component: 'agents-relay' }))])).catch(error => this.failLaunch(job.id, task.id, durableExecutionId, error instanceof Error ? error.message : String(error), 'launch'));
         if (startAckSetup)
             void startAckSetup.ack.finally(() => { void startAckSetup.stop(); }).catch(() => { });
         this.live.set(task.id, { jobId: job.id, taskId: task.id, executionId: durableExecutionId, execution, controller, launchBarrier: startedAt, workerStarted: false, processSettled: false });

package/dist/relayd.js

@@ -198,7 +198,7 @@ export async function runDaemon(argv) {
             job, githubState: snapshot.facts.state, draft: false, mergedAt: null, closedAt: null, publication: null,
         }));
     }));
-    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { 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(), projectPathForJob: async (job) => resolveRepositoryProjectPath(repositoryPaths.get(job.repository) ?? await resolveManagedProjectPath(job.repository, explicitProjectPath, workspaceRoot), job.projectPath) });
+    const makeReconciler = (store, maxConcurrent) => new Reconciler(store, { 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 refreshAll = async (full = false) => {
         if (client.rateLimitStatus().limited)
             return cachedOverviews;

package/dist/reviewer-thread.js

@@ -0,0 +1,45 @@
+import { arg, hasArg } from './cli-support.js';
+export function normalizeThreadId(value, label = 'thread ID') {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be a string`);
+    const threadId = value.trim();
+    if (!threadId)
+        throw new Error(`${label} cannot be empty`);
+    if (threadId.length > 256)
+        throw new Error(`${label} cannot exceed 256 characters`);
+    return threadId;
+}
+export function resolveReviewerThreadDestination(job, override) {
+    const overridden = override === undefined ? undefined : normalizeThreadId(override, '--thread-id');
+    if (overridden)
+        return { threadId: overridden, source: 'override' };
+    const reviewerThreadId = job.reviewerThreadId ? normalizeThreadId(job.reviewerThreadId, 'Job reviewer thread ID') : undefined;
+    if (reviewerThreadId)
+        return { threadId: reviewerThreadId, source: 'reviewer' };
+    const creatorThreadId = job.creatorThreadId ? normalizeThreadId(job.creatorThreadId, 'Job creator thread ID') : undefined;
+    return creatorThreadId ? { threadId: creatorThreadId, source: 'creator' } : null;
+}
+export function chatgptThreadRequirements(configured) {
+    const base = configured ?? { capabilities: ['model'] };
+    const capabilities = new Set([...base.capabilities, 'model', 'chatgpt', 'browser-workspace']);
+    return { ...base, capabilities: [...capabilities], runtime: 'chatgpt' };
+}
+export function runtimeReviewer(args = []) {
+    const values = [...args];
+    const threadId = arg(values, '--thread-id', '');
+    if (hasArg(values, '--thread-id'))
+        normalizeThreadId(threadId, '--thread-id');
+    return { requirements: { capabilities: ['model'] }, ...(threadId.trim() ? { threadId: threadId.trim() } : {}) };
+}
+export async function recordThreadDelivery(store, jobId, taskId, executionId, workerTask) {
+    const delivery = workerTask.chatgptThreadDelivery;
+    if (!delivery || delivery.deliveredAt)
+        return;
+    const current = (await store.load(jobId)).tasks.find(item => item.id === taskId);
+    if (current?.executionId !== executionId || current.state !== 'RUNNING' || !current.chatgptThreadDelivery)
+        return;
+    current.chatgptThreadDelivery = { ...current.chatgptThreadDelivery, deliveredAt: new Date().toISOString() };
+    await store.saveTask(current);
+}

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.66",
   "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