agents-relay 1.0.97 → 1.0.99

package/README.md

@@ -51,7 +51,7 @@ Jobs separate durable lifecycle from derived runtime status. Durable lifecycle i
 
 Lifecycle transition authority lives in the directly renderable canonical sources [`workflow/job-lifecycle.mmd`](workflow/job-lifecycle.mmd) and [`workflow/task-lifecycle.mmd`](workflow/task-lifecycle.mmd); see [`docs/workflow-engine.md`](docs/workflow-engine.md) for the executable Mermaid profile and runtime boundary.
 
-Graph-engine rollout is confidence-gated with `AGENTS_RELAY_WORKFLOW_MODE=legacy|shadow|graph` (default `legacy`). `shadow` keeps legacy authoritative while comparing the Mermaid decision and exposing `{mode,matches,mismatches}` at `/api/workflow-rollout`; `graph` is explicit opt-in until the shadow cutover gate is approved.
+The canonical Mermaid Graph Engine is the single authoritative Job/Task lifecycle decision path. Lifecycle events, guards, deterministic mutations, and declarative effects are defined by the workflow graphs and executed through the shared graph runtime.
 
 Job objectives and Task inputs are Markdown. Prefer `--objective-file` / `--input-file` (use `-` for stdin) for durable long-form context; inline `--objective` / `--input` remain for short/simple text and are mutually exclusive with the file variants. When a diagram materially clarifies the work, put Mermaid first and then Markdown detail. A newly created Job must capture enough context to finish independently of the originating chat. Its PR body contains exactly one hidden `agents-relay:job:v1` metadata marker followed by the objective Markdown; there is no separate Job comment duplicating the objective. Objective and Job metadata updates rewrite that same PR body. Legacy Job-comment markers remain readable and are migrated into the PR body on the next Job save.
 

package/dist/dashboard.js

@@ -5,7 +5,6 @@ import { join } from 'node:path';
 import { readUsageSnapshot } from './usage.js';
 import { deriveJobRuntimeStatus } from './runtime-status.js';
 import { DeliveryDeduper, parseGitHubWebhook, verifyGitHubWebhook } from './github-webhook.js';
-import { workflowRolloutSnapshot } from './workflow/rollout.js';
 const GITHUB_REPOSITORY_PATTERN = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,36}[A-Za-z0-9])?)\/([A-Za-z0-9._-]{1,100})$/;
 const SSE_HEARTBEAT_MS = 15000;
 const EVENTS_HISTORY_FILE = process.env.EVENTS_BUS_DATA_DIR ? join(process.env.EVENTS_BUS_DATA_DIR, 'events.jsonl') : join(homedir(), 'Library', 'Application Support', 'EventsBus', 'events.jsonl');
@@ -268,11 +267,6 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
             res.end(JSON.stringify(events));
             return;
         }
-        if (req.url === '/api/workflow-rollout') {
-            res.writeHead(200, { 'content-type': 'application/json' });
-            res.end(JSON.stringify(workflowRolloutSnapshot()));
-            return;
-        }
         if (req.url === '/api/status') {
             const status = statusProvider ? statusProvider() : { limited: false, cooldownUntil: null };
             res.writeHead(200, { 'content-type': 'application/json' });

package/dist/reconciler-runtime.js

@@ -165,13 +165,14 @@ export class ReconcilerRuntimeBase {
         this.detach(this.reconcile(job.id), job.id, task.id, 'late worker-start reconciliation');
     }
     isRecoverableWatchdogFailure(task) {
-        if (['worker_start_timeout', 'terminal_event_timeout', 'worker_exit_before_start', 'worker_exit_without_terminal_event'].includes(task.failureReason ?? ''))
+        if (['worker_start_timeout', 'terminal_event_timeout', 'worker_exit_before_start', 'worker_exit_without_terminal_event', 'worker_delivery_after_start'].includes(task.failureReason ?? ''))
             return true;
         const error = task.error ?? '';
         return error.includes('worker_start_timeout')
             || error.includes('timed out waiting for the mandatory terminal worker event')
             || error.includes('exited before publishing task.started')
-            || error.includes('exited after task.started without publishing a terminal task event');
+            || error.includes('exited after task.started without publishing a terminal task event')
+            || error.includes('Worker delivery failed after task.started');
     }
     isCorrelatedWorkerEvent(task, event) {
         return task.executionId !== null && eventSourceId(event) === executionEventSource(event.job_id, task.id, task.executionId);
@@ -187,19 +188,18 @@ export class ReconcilerRuntimeBase {
         const task = job.tasks.find(item => item.id === taskId);
         if (!task || task.executionId !== executionId || !['QUEUED', 'RUNNING'].includes(task.state))
             return;
-        const event = eventFor(jobId, taskId, task.parentTaskId, 'task.failed', 'failed', `Worker ${phase} failed: ${message}`, 'user', { phase, reason: phase === 'start-ack' ? 'worker_start_timeout' : undefined }, { agent: 'relay', component: 'agents-relay', watchdog: true });
-        if (task.state === 'QUEUED') {
-            this.clearExecution(task.id, executionId);
-            task.error = event.message;
-            task.failureReason = phase === 'start-ack' ? 'worker_start_timeout' : undefined;
-            task.leaseOwner = null;
-            task.leaseExpiresAt = null;
-            await transitionTaskEvent(task, 'fail');
-            await this.store.saveTask(task);
-        }
-        else {
-            await this.applyTerminalEvent(event, true);
+        if (task.state === 'RUNNING') {
+            await this.emit(eventFor(jobId, taskId, task.parentTaskId, 'task.process.delivery_failed', 'failed', `Worker ${phase} reported after task.started: ${message}`, 'orchestrator', { phase, authoritative: false, executionId }, { agent: 'relay', component: 'agents-relay' }));
+            return;
         }
+        const event = eventFor(jobId, taskId, task.parentTaskId, 'task.failed', 'failed', `Worker ${phase} failed: ${message}`, 'user', { phase, reason: phase === 'start-ack' ? 'worker_start_timeout' : undefined }, { agent: 'relay', component: 'agents-relay', watchdog: true });
+        this.clearExecution(task.id, executionId);
+        task.error = event.message;
+        task.failureReason = phase === 'start-ack' ? 'worker_start_timeout' : undefined;
+        task.leaseOwner = null;
+        task.leaseExpiresAt = null;
+        await transitionTaskEvent(task, 'fail');
+        await this.store.saveTask(task);
         await this.emit(event);
     }
     async runtimeSettled(jobId, taskId, executionId, result, error) {

package/dist/reconciler.js

@@ -12,6 +12,7 @@ import { executionEventSource } from './reconciler-runtime.js';
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
 import { pendingTroubleshooterTasks } from './troubleshooter.js';
+import { prepareManagedExecutionWorktree } from './workspace.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) {
@@ -203,7 +204,7 @@ export class Reconciler extends ReconcilerReviewBase {
         for (const task of job.tasks.filter(item => !['SUCCEEDED', 'FAILED', 'CANCELLED'].includes(item.state))) {
             this.live.get(task.id)?.execution.cancel();
             this.plannerLive.get(task.id)?.controller.abort();
-            await transitionTaskEvent(task, 'cancel');
+            await transitionTaskEvent(task, task.state === 'RUNNING' ? 'task.cancelled' : 'cancel');
             task.error = reason;
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
@@ -214,8 +215,7 @@ export class Reconciler extends ReconcilerReviewBase {
     async recoverLostExecutions(job, now) {
         for (const task of job.tasks.filter(item => item.state === 'RUNNING' || (item.state === 'QUEUED' && item.executionId !== null))) {
             const expired = task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now;
-            const ownerLost = task.leaseOwner !== null && task.leaseOwner !== this.options.owner;
-            if (!expired && !ownerLost)
+            if (!expired)
                 continue;
             this.live.get(task.id)?.execution.cancel();
             const planner = this.plannerLive.get(task.id);
@@ -226,7 +226,7 @@ export class Reconciler extends ReconcilerReviewBase {
             }
             const failedEvent = task.state === 'RUNNING' ? 'task.failed' : 'fail';
             await transitionTaskEvent(task, failedEvent);
-            task.error = expired ? 'Lease expired' : 'Execution owner restarted';
+            task.error = 'Lease expired';
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
             task.executionId = null;
@@ -237,7 +237,7 @@ export class Reconciler extends ReconcilerReviewBase {
             else {
                 task.error += ' after maximum attempts';
                 await this.store.saveTask(task);
-                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.failed', 'failed', task.error, 'user', { reason: expired ? 'lease_expired' : 'execution_owner_lost' }));
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.failed', 'failed', task.error, 'user', { reason: 'lease_expired' }));
             }
         }
     }
@@ -294,8 +294,8 @@ export class Reconciler extends ReconcilerReviewBase {
             }
         }
     }
-    async resolvedContext(job, task, role) {
-        const projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job) : task.routing?.cwd ?? process.cwd();
+    async resolvedContext(job, task, role, projectPathOverride) {
+        const projectPath = projectPathOverride ?? (this.options.projectPathForJob ? await this.options.projectPathForJob(job) : task.routing?.cwd ?? process.cwd());
         return resolveExecutionContext(projectPath, role, {
             ...(this.options.executionContextRoots ?? {}),
             registeredAgents: await this.store.listAgents(),
@@ -316,17 +316,6 @@ export class Reconciler extends ReconcilerReviewBase {
             await this.store.saveTask(task);
             return;
         }
-        let executionContext;
-        try {
-            const role = task.agentName === 'reviewer' ? 'reviewer' : task.agentName === 'troubleshooter' ? 'troubleshooter' : task.parentTaskId ? 'nested-worker' : 'worker';
-            executionContext = await this.resolvedContext(job, task, role);
-        }
-        catch (error) {
-            await transitionTaskEvent(task, 'block');
-            task.error = error instanceof Error ? error.message : String(error);
-            await this.store.saveTask(task);
-            return;
-        }
         const claimKey = `${job.repository}#${job.prNumber}:${task.id}`;
         if (taskLaunchClaims.has(claimKey))
             return;
@@ -354,13 +343,38 @@ export class Reconciler extends ReconcilerReviewBase {
         if (!claimedTask)
             return;
         task = claimedTask;
+        let executionContext;
+        let managedHead = null;
+        try {
+            const role = task.agentName === 'reviewer' ? 'reviewer' : task.agentName === 'troubleshooter' ? 'troubleshooter' : task.parentTaskId ? 'nested-worker' : 'worker';
+            let projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job) : task.routing?.cwd ?? process.cwd();
+            if (['codex', 'chatgpt'].includes(task.adapter) && this.store.pullRequestHead && task.executionId) {
+                managedHead = await this.store.pullRequestHead();
+                if (!managedHead)
+                    throw new Error(`PR #${job.prNumber} has no resolvable head ref`);
+                projectPath = await prepareManagedExecutionWorktree(projectPath, job.repository, job.prNumber, managedHead, task.executionId);
+            }
+            executionContext = await this.resolvedContext(job, task, role, projectPath);
+        }
+        catch (error) {
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            task.executionId = null;
+            await transitionTaskEvent(task, 'block');
+            task.error = `Execution checkout unavailable: ${error instanceof Error ? error.message : String(error)}`;
+            await this.store.saveTask(task);
+            return;
+        }
         const startedAt = Date.now();
         const durableExecutionId = task.executionId;
         const controller = new AbortController();
         let execution;
         const sourceId = executionEventSource(job.id, task.id, durableExecutionId);
-        const workerInput = await managedWorkerInput(job, task, executionContext);
-        const workerTask = { ...task, input: workerInput, routing: task.routing ? { ...task.routing, cwd: task.routing.cwd ?? executionContext.project.path } : task.routing };
+        const baseWorkerInput = await managedWorkerInput(job, task, executionContext);
+        const workerInput = managedHead
+            ? `${baseWorkerInput}\n\n[Managed PR checkout]\nExecution cwd: ${executionContext.project.path}\nExpected PR head: ${managedHead.ref} @ ${managedHead.sha}\nThis checkout is isolated from the user's primary checkout. Commit only here. Push durable changes with: git push origin HEAD:${managedHead.ref}\nDo not switch, reset, merge into, or commit on the primary checkout.`
+            : baseWorkerInput;
+        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'

package/dist/scheduler.js

@@ -1,4 +1,4 @@
-import { decideJobLifecycle, decideTaskLifecycle } from './workflow/rollout.js';
+import { decideJobLifecycle, decideTaskLifecycle } from './workflow/lifecycle.js';
 import { reconcileTaskDependencies } from './workflow/task-reconcile.js';
 export { dependencyReady, detectCycles } from './workflow/task-reconcile.js';
 import { applyJobWorkflowDecision, applyTaskWorkflowDecision } from './workflow/runtime.js';

package/dist/store-github.js

@@ -25,7 +25,7 @@ export class GitHubStore {
     }
     async prNode() {
         const { owner, name } = this.repoParts();
-        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id state merged mergedAt closedAt body}}}', { owner, name, number: this.prNumber });
+        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){id state merged mergedAt closedAt body headRefName headRefOid}}}', { owner, name, number: this.prNumber });
         const repository = data.repository;
         const pr = repository?.pullRequest;
         if (!pr)
@@ -86,13 +86,13 @@ export class GitHubStore {
     async updatePullRequestBody(body) {
         await this.client.request('repos/' + this.repository + '/pulls/' + this.prNumber, { method: 'PATCH', body: JSON.stringify({ body }) });
     }
-    async headSha() {
-        const { owner, name } = this.repoParts();
-        const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){headRefOid}}}', { owner, name, number: this.prNumber });
-        const repository = data.repository;
-        const pr = repository?.pullRequest;
-        return typeof pr?.headRefOid === 'string' ? pr.headRefOid : null;
+    async pullRequestHead() {
+        const pr = await this.prNode();
+        const ref = typeof pr.headRefName === 'string' ? pr.headRefName : '';
+        const sha = typeof pr.headRefOid === 'string' ? pr.headRefOid : '';
+        return ref && sha ? { ref, sha } : null;
     }
+    async headSha() { return (await this.pullRequestHead())?.sha ?? null; }
     async load(jobId) {
         const comments = (await this.list()).filter(comment => this.isTrusted(comment));
         const bodyJob = parseJob(await this.pullRequestBody());

package/dist/troubleshooter.js

@@ -38,8 +38,9 @@ function recoveryTargetsTask(recovery, original) {
         return recovery.parentTaskId === original.id;
     return recovery.id.startsWith(`troubleshoot-${slug(original.id)}-a`);
 }
-function hasActiveRecovery(job, original) {
-    return job.tasks.some(task => recoveryTargetsTask(task, original) && ACTIVE_RECOVERY_STATES.has(task.state));
+function hasRecoveryBarrier(job, original) {
+    return job.tasks.some(task => recoveryTargetsTask(task, original)
+        && (ACTIVE_RECOVERY_STATES.has(task.state) || ['FAILED', 'CANCELLED'].includes(task.state)));
 }
 export function pendingTroubleshooterTasks(job) {
     const existing = new Set(job.tasks.filter(task => task.agentName === 'troubleshooter').map(task => task.id));
@@ -48,7 +49,7 @@ export function pendingTroubleshooterTasks(job) {
         if (!['FAILED', 'BLOCKED'].includes(task.state) || task.kind === 'planner' || task.agentName === 'troubleshooter' || !belongsToCurrentRun(job, task))
             continue;
         const id = troubleshooterTaskId(task);
-        if (existing.has(id) || hasActiveRecovery(job, task))
+        if (existing.has(id) || hasRecoveryBarrier(job, task))
             continue;
         const now = new Date().toISOString();
         recoveries.push({

package/dist/workflow/lifecycle.js

@@ -0,0 +1,8 @@
+import { jobLifecycleWorkflow, taskLifecycleWorkflow } from './definitions.js';
+import { graphWorkflowDecision } from './runtime.js';
+export function decideTaskLifecycle(task, event, facts = {}) {
+    return graphWorkflowDecision(taskLifecycleWorkflow, task.state, event, facts);
+}
+export function decideJobLifecycle(job, event, facts = {}) {
+    return graphWorkflowDecision(jobLifecycleWorkflow, job.state, event, facts);
+}

package/dist/workflow/task-reconcile.js

@@ -1,4 +1,4 @@
-import { decideTaskLifecycle } from './rollout.js';
+import { decideTaskLifecycle } from './lifecycle.js';
 import { applyTaskWorkflowDecision } from './runtime.js';
 export function dependencyReady(task, tasks) {
     return task.dependencies.every(id => tasks.get(id)?.state === 'SUCCEEDED');

package/dist/workspace.js

@@ -1,5 +1,5 @@
-import { readdir, stat } from 'node:fs/promises';
-import { join, relative, resolve } from 'node:path';
+import { mkdir, readdir, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -75,6 +75,40 @@ export async function resolveManagedProjectPath(repository, explicitProjectPath
         return resolve(explicitProjectPath);
     return repository ? resolveWorkspaceRepositoryPath(repository, root) : resolve(cwd);
 }
+async function git(path, args) {
+    return (await execFileAsync('git', ['-C', path, ...args])).stdout.trim();
+}
+export async function prepareManagedExecutionWorktree(projectPath, repository, prNumber, head, executionId) {
+    const primary = await git(projectPath, ['rev-parse', '--show-toplevel']);
+    const remote = await git(primary, ['config', '--get', 'remote.origin.url']);
+    if (githubRepositoryFromRemote(remote) !== repository)
+        throw new Error(`Primary checkout ${primary} does not match ${repository}`);
+    await git(primary, ['fetch', 'origin', `refs/heads/${head.ref}:refs/remotes/origin/${head.ref}`]);
+    const fetched = await git(primary, ['rev-parse', `refs/remotes/origin/${head.ref}`]);
+    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);
+    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`);
+        return worktree;
+    }
+    catch (error) {
+        try {
+            await stat(worktree);
+        }
+        catch {
+            await git(primary, ['worktree', 'add', '--detach', worktree, head.sha]);
+            return worktree;
+        }
+        throw error;
+    }
+}
 function repositoryPathRank(path, root) {
     const relativePath = relative(root, path);
     if (!relativePath.includes('/'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.97",
+  "version": "1.0.99",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/cli.js dist/relayd.js",
-    "test": "npm run build && node --test test/*.test.js",
+    "test": "npm run build && node --test --test-force-exit test/*.test.js",
     "test:chatgpt-temp-quality": "AGENTS_RELAY_RUN_CHATGPT_TEMP_QUALITY=1 AGENTS_RELAY_CHATGPT_BROWSER_WORKER_AGENT=/Users/chengli/Workspace/neo/skills/chatgpt-browser-worker/agents/browser-worker.agent.md sh -c \"npm run build && node test/quality/run-temporary-chat.mjs\"",
     "dev": "tsx src/cli.ts"
   },

package/skills/agents-relay/agents/planner.agent.md

@@ -8,15 +8,62 @@ You are a pure planning agent. Relay invokes you with the durable Job, existing
 
 Relay persists each successful planner invocation as one planner round and creates the returned Tasks under that round.
 
+## Planning contract
+
+**Plan the whole objective before choosing Task boundaries.**
+
+For every non-satisfied objective:
+
+1. Reconstruct the end-to-end execution flow from the current durable state to objective completion.
+2. Express that flow as a compact Mermaid graph in `assessment`.
+3. Mark the points in that graph that deserve durable Task boundaries.
+4. Create only the next useful executable Task batch from those boundaries.
+
+A Task is **not** just a workflow step. Create a Task when its outcome deserves an independent durable lifecycle because it may need to be:
+
+- discussed or referenced later;
+- independently reviewed, approved, revised, or compared;
+- blocked/retried/reconciled independently;
+- waited on as a meaningful external dependency;
+- executed in parallel with a separately meaningful outcome; or
+- preserved as an independently useful deliverable or decision.
+
+If an intermediate result does not need that independent lifecycle, keep it inside the executing Task's agent graph/workflow rather than promoting it to another Task.
+
+Keep sibling Tasks at a comparable abstraction level. Do not mix a whole product milestone with tiny implementation steps as peers.
+
+The graph is the explanation for the decomposition: every emitted Task should map to a meaningful boundary in the graph, and important graph boundaries should not be omitted accidentally.
+
+### Examples
+
+Prefer:
+
+```text
+Task: Create and publish today's vlog
+  internal graph: collect media -> select story -> script -> edit -> captions -> QA -> publish
+```
+
+when nobody needs to separately review or discuss those intermediate outputs.
+
+But when script approval is a real durable gate, prefer:
+
+```text
+Task 1: Produce script for review
+  -> approval/revision boundary
+Task 2: Produce and publish the approved vlog
+```
+
+Do not create separate Tasks merely for "analyze", "format", "call tool", "check status", or other internal mechanics.
+
 ## Rules
 
 - Treat durable Job/Task state as authoritative.
 - Never invent completed work or evidence.
 - First decide whether the objective is already satisfied.
 - If satisfied, return `objective_status: "satisfied"` and `next_tasks: []`.
-- Otherwise return only the next useful executable batch.
+- Otherwise return only the next useful executable batch from the graph-derived Task boundaries.
 - Do not repeat completed work or recreate an existing Task unless replacement work is explicitly needed.
-- Prefer small independently verifiable Tasks with stable IDs.
+- Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.
 - A Task describes what an agent must accomplish; never emit a shell command as a worker Task.
 - Use dependencies only when execution order actually matters.
 - Every child Task must declare `workerRequirements`; worker-router selects the worker and model-router selects provider/model/reasoning afterward.
@@ -30,4 +77,11 @@ Relay persists each successful planner invocation as one planner round and creat
 
 Return exactly one JSON object with `objective_status`, `assessment`, and `next_tasks`.
 
+For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
+
+1. a compact Mermaid graph of the full remaining objective flow;
+2. a short explanation of the chosen durable Task boundaries.
+
+For `objective_status: "satisfied"`, `assessment` may be a concise evidence-based completion assessment without a graph.
+
 Each item in `next_tasks` contains `id`, `input`, `workerRequirements`, `output`, and `storySize`. It may also contain priority, projectName, agentName, dependencies, capabilities, maxAttempts, and timeoutMs. Adapter/routing fields are selected by Relay after planning; do not invent them.

package/skills/agents-relay/contracts/task-job-contract.md

@@ -104,6 +104,10 @@ Relay owns process lifecycle. Workers own semantic task lifecycle. A worker must
 
 Relay allocates the durable `executionId` before launching model-backed work and gives that worker one exact event source identity: `job/<job-id>/task/<task-id>/execution/<execution-id>`. Every semantic lifecycle event from that execution must copy the identity verbatim in `source.id`. Relay correlates model-worker lifecycle only by this execution identity; `source.agent`, `source.component`, provider/adapter names, and `data.worker_owned` are diagnostic/legacy metadata and MUST NOT authorize or correlate lifecycle state. A retry receives a new execution identity, so events from an older execution are ignored.
 
+A durable execution lease survives Relay process/owner restarts until its `leaseExpiresAt`. A different Relay owner is not evidence that the worker died and MUST NOT by itself reclaim or retry that execution. Recovery may reclaim only after the durable lease expires or another authoritative terminal/liveness fact proves the execution ended.
+
+For a GitHub-backed Job, every mutating model-backed execution runs from an isolated worktree pinned to that PR's current head SHA. It must not run from or switch the user's primary checkout. Relay verifies the remote repository and exact PR head before launch and fails closed when it cannot prepare that checkout. Concurrent PR Jobs for the same repository use separate execution worktrees.
+
 ## Job lifecycle and runtime status
 
 The canonical durable lifecycle transition graphs are `workflow/job-lifecycle.mmd` and `workflow/task-lifecycle.mmd`. They use Relay's minimal executable Mermaid `stateDiagram-v2` profile and are the single source of truth for transition legality; do not maintain a parallel JSON/YAML transition table. Runtime status is not part of those lifecycle graphs.

package/dist/workflow/rollout.js

@@ -1,185 +0,0 @@
-import { jobLifecycleWorkflow, taskLifecycleWorkflow } from './definitions.js';
-import { classifyWorkflowActions, emptyWorkflowDecision, } from './contracts.js';
-import { graphWorkflowDecision } from './runtime.js';
-let modeOverride = null;
-let reporter = null;
-let matches = 0;
-let mismatches = 0;
-export function parseWorkflowRolloutMode(value) {
-    if (value === undefined || value === '')
-        return 'legacy';
-    if (value === 'legacy' || value === 'shadow' || value === 'graph')
-        return value;
-    throw new Error(`Invalid AGENTS_RELAY_WORKFLOW_MODE '${value}'; expected legacy, shadow, or graph`);
-}
-export function workflowRolloutMode() {
-    return modeOverride ?? parseWorkflowRolloutMode(process.env.AGENTS_RELAY_WORKFLOW_MODE);
-}
-export function setWorkflowRolloutMode(mode) { modeOverride = mode; }
-export function setWorkflowShadowReporter(value) { reporter = value; }
-export function resetWorkflowRolloutDiagnostics() { matches = 0; mismatches = 0; }
-export function workflowRolloutSnapshot() {
-    return { mode: workflowRolloutMode(), matches, mismatches };
-}
-function accepted(target, guard = null, actions = []) {
-    const actionList = [...actions];
-    return {
-        accepted: true,
-        target,
-        guard,
-        actions: actionList,
-        ...classifyWorkflowActions(actionList),
-        reason: 'accepted',
-    };
-}
-const CLEAR = ['mutation.clearError', 'mutation.clearFailureReason'];
-const taskLegacy = {
-    DRAFT: {
-        release: { target: 'QUEUED', actions: CLEAR },
-        block: { target: 'BLOCKED' },
-        cancel: { target: 'CANCELLED' },
-    },
-    QUEUED: {
-        hold: { target: 'DRAFT' },
-        'task.started': { target: 'RUNNING', actions: CLEAR },
-        block: { target: 'BLOCKED' },
-        fail: { target: 'FAILED' },
-        'effect.launchTask.failed': { target: 'FAILED' },
-        cancel: { target: 'CANCELLED' },
-    },
-    RUNNING: {
-        'task.blocked': { target: 'BLOCKED' },
-        'task.completed': { target: 'SUCCEEDED', actions: CLEAR },
-        'task.failed': { target: 'FAILED' },
-        'task.cancelled': { target: 'CANCELLED' },
-    },
-    BLOCKED: {
-        retry: { target: 'QUEUED', actions: CLEAR },
-        cancel: { target: 'CANCELLED' },
-    },
-    SUCCEEDED: {},
-    FAILED: {
-        retry: { target: 'QUEUED', actions: CLEAR },
-        'reconcile.started': { target: 'RUNNING', actions: CLEAR },
-        'reconcile.completed': { target: 'SUCCEEDED', actions: CLEAR },
-        'reconcile.blocked': { target: 'BLOCKED' },
-        cancel: { target: 'CANCELLED' },
-    },
-    CANCELLED: {},
-};
-const CANCEL_EFFECT = ['effect.cancelActiveTasks'];
-const MERGE_EFFECT = ['effect.mergePullRequest'];
-const jobLegacy = {
-    DRAFT: {
-        activate: { target: 'ACTIVE' },
-        'pr.merged': { target: 'COMPLETED', actions: CANCEL_EFFECT },
-        cancel: { target: 'CANCELLED' },
-    },
-    ACTIVE: {
-        'pr.merged': { target: 'COMPLETED', actions: CANCEL_EFFECT },
-        cancel: { target: 'CANCELLED' },
-    },
-    COMPLETED: {
-        'effect.cancelActiveTasks.failed': { target: 'COMPLETED' },
-    },
-    CANCELLED: {
-        'pr.merged': { target: 'COMPLETED', actions: CANCEL_EFFECT },
-        'effect.cancelActiveTasks.failed': { target: 'CANCELLED' },
-    },
-};
-function taskLegacyDecision(from, event, facts) {
-    if (event === 'reconcile') {
-        if (from === 'DRAFT' && facts.dependenciesSatisfied === true)
-            return accepted('QUEUED', 'dependenciesSatisfied', CLEAR);
-        if (from === 'QUEUED' && facts.dependenciesUnsatisfied === true)
-            return accepted('DRAFT', 'dependenciesUnsatisfied');
-        if (from === 'QUEUED' && facts.runnable === true)
-            return accepted('QUEUED', 'runnable', CLEAR);
-        return emptyWorkflowDecision('no_transition');
-    }
-    if (event === 'dispatch') {
-        if (from === 'QUEUED' && facts.dispatchable === true)
-            return accepted('QUEUED', 'dispatchable', ['effect.launchTask']);
-        return emptyWorkflowDecision('no_transition');
-    }
-    const transition = taskLegacy[from][event];
-    if (!transition)
-        return emptyWorkflowDecision('no_transition');
-    return accepted(transition.target, transition.guard ?? null, transition.actions ?? []);
-}
-function jobLegacyDecision(from, event, facts) {
-    if (event === 'pr.closed') {
-        if ((from === 'DRAFT' || from === 'ACTIVE') && facts.notMerged === true) {
-            return accepted('CANCELLED', 'notMerged', CANCEL_EFFECT);
-        }
-        return emptyWorkflowDecision('no_transition');
-    }
-    if (event === 'review.approved' || event === 'implementation.completed') {
-        if (from === 'ACTIVE' && facts.autoMerge === true)
-            return accepted('ACTIVE', 'autoMerge', MERGE_EFFECT);
-        return emptyWorkflowDecision('no_transition');
-    }
-    if (event === 'effect.mergePullRequest.failed' && from === 'ACTIVE')
-        return accepted('ACTIVE');
-    const transition = jobLegacy[from][event];
-    if (!transition)
-        return emptyWorkflowDecision('no_transition');
-    return accepted(transition.target, transition.guard ?? null, transition.actions ?? []);
-}
-function sameDecision(a, b) {
-    return a.accepted === b.accepted
-        && a.target === b.target
-        && a.guard === b.guard
-        && a.reason === b.reason
-        && a.actions.length === b.actions.length
-        && a.actions.every((value, index) => value === b.actions[index])
-        && a.mutations.length === b.mutations.length
-        && a.mutations.every((value, index) => value === b.mutations[index])
-        && a.effects.length === b.effects.length
-        && a.effects.every((value, index) => value === b.effects[index]);
-}
-function report(kind, jobId, taskId, event, from, facts, legacy, graph) {
-    const match = sameDecision(legacy, graph);
-    if (match)
-        matches += 1;
-    else
-        mismatches += 1;
-    const diagnostic = {
-        type: match ? 'workflow.shadow.match' : 'workflow.shadow.mismatch',
-        kind,
-        jobId,
-        ...(taskId ? { taskId } : {}),
-        event,
-        from,
-        facts: { ...facts },
-        legacy,
-        graph,
-    };
-    reporter?.(diagnostic);
-    if (!match && !reporter)
-        console.warn(JSON.stringify(diagnostic));
-}
-export function decideTaskLifecycle(task, event, facts = {}) {
-    const legacy = taskLegacyDecision(task.state, event, facts);
-    const mode = workflowRolloutMode();
-    if (mode === 'legacy')
-        return legacy;
-    const graph = graphWorkflowDecision(taskLifecycleWorkflow, task.state, event, facts);
-    if (mode === 'shadow') {
-        report('task', task.jobId ?? 'unknown', task.id, event, task.state, facts, legacy, graph);
-        return legacy;
-    }
-    return graph;
-}
-export function decideJobLifecycle(job, event, facts = {}) {
-    const legacy = jobLegacyDecision(job.state, event, facts);
-    const mode = workflowRolloutMode();
-    if (mode === 'legacy')
-        return legacy;
-    const graph = graphWorkflowDecision(jobLifecycleWorkflow, job.state, event, facts);
-    if (mode === 'shadow') {
-        report('job', job.id, undefined, event, job.state, facts, legacy, graph);
-        return legacy;
-    }
-    return graph;
-}