agents-relay 1.0.68 → 1.0.69

package/README.md

@@ -49,6 +49,10 @@ npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id chil
 
 Jobs separate durable lifecycle from derived runtime status. Durable lifecycle is `DRAFT | ACTIVE | COMPLETED | CANCELLED`: a newly created unscheduled Job is DRAFT, creating executable work activates it, and scheduled Jobs are ACTIVE because the scheduler is allowed to advance them. Runtime status (`IDLE`, `WAITING`, `QUEUED`, `RUNNING`, `BLOCKED`, `FAILED`, `REVIEWING`, `MERGE_PENDING`, `MERGED`, or `CANCELLED`) is computed from Tasks, Review, PR, and schedule facts and is never persisted as lifecycle truth.
 
+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.
+
 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 objective becomes the default PR body and objective updates keep the PR body synchronized.
 
 Jobs default to `fixed`. `job create` persists only the durable job and never

package/dist/cli.js

@@ -15,7 +15,7 @@ import { serveDashboard } from './dashboard.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
-import { extendRetryBudget, parseJobSchedule, transitionTask } from './scheduler.js';
+import { extendRetryBudget, parseJobSchedule, transitionJobEvent, transitionTaskEvent } from './scheduler.js';
 import { dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.js';
@@ -419,8 +419,7 @@ async function runTaskCommand(action, args) {
         await store.appendTask(task);
         const refreshed = await store.load(job.id);
         if (refreshed.state === 'DRAFT') {
-            refreshed.state = 'ACTIVE';
-            refreshed.updatedAt = now;
+            await transitionJobEvent(refreshed, 'activate');
             await store.saveJob(refreshed);
         }
         const durableTask = (await store.load(job.id)).tasks.find(item => item.id === task.id) ?? task;
@@ -439,13 +438,14 @@ async function runTaskCommand(action, args) {
     if (action === 'retry' || action === 'cancel') {
         if (action === 'retry')
             task.maxAttempts = extendRetryBudget(task);
-        task.state = action === 'retry' ? 'QUEUED' : 'CANCELLED';
+        await transitionTaskEvent(task, action === 'retry' ? 'retry' : 'cancel');
         task.error = action === 'retry' ? null : 'Cancelled by user';
-        task.updatedAt = new Date().toISOString();
+        task.leaseOwner = null;
+        task.leaseExpiresAt = null;
+        task.executionId = null;
         await store.saveTask(task);
         if (action === 'retry' && job.state === 'DRAFT') {
-            job.state = 'ACTIVE';
-            job.updatedAt = task.updatedAt;
+            await transitionJobEvent(job, 'activate');
             await store.saveJob(job);
         }
         await saveLocal(localFile, job);
@@ -486,13 +486,16 @@ async function runTaskCommand(action, args) {
     task.maxAttempts = integerArg(args, '--max-attempts', task.maxAttempts);
     if (hasArg(args, '--draft') && hasArg(args, '--queue'))
         throw new Error('--draft and --queue are mutually exclusive');
-    if (hasArg(args, '--draft'))
-        transitionTask(task, 'DRAFT');
+    if (hasArg(args, '--draft') && task.state === 'QUEUED')
+        await transitionTaskEvent(task, 'hold');
     if (hasArg(args, '--queue')) {
         const taskMap = new Map(job.tasks.map(item => [item.id, item]));
         if (!task.dependencies.every(dep => taskMap.get(dep)?.state === 'SUCCEEDED'))
             throw new Error('Task dependencies must succeed before queueing');
-        transitionTask(task, 'QUEUED');
+        if (task.state === 'DRAFT')
+            await transitionTaskEvent(task, 'release');
+        else if (task.state === 'FAILED' || task.state === 'BLOCKED')
+            await transitionTaskEvent(task, 'retry');
     }
     if (hasArg(args, '--max-attempts') && task.maxAttempts < task.attempt)
         throw new Error('--max-attempts cannot be less than the current attempt count');
@@ -603,8 +606,7 @@ async function runJobCommand(action, args) {
             throw new Error(`Cannot merge cancelled job ${job.id}`);
         const headSha = await store.headSha();
         await store.mergePullRequest(headSha ?? undefined);
-        job.state = 'COMPLETED';
-        job.updatedAt = new Date().toISOString();
+        await transitionJobEvent(job, 'pr.merged');
         await store.saveJob(job);
         console.log(JSON.stringify(await store.load(id), null, 2));
         return;
@@ -613,15 +615,15 @@ async function runJobCommand(action, args) {
         if (job.state === 'COMPLETED')
             throw new Error(`Cannot cancel completed job ${job.id}`);
         for (const task of job.tasks.filter(item => !['SUCCEEDED', 'CANCELLED'].includes(item.state))) {
-            transitionTask(task, 'CANCELLED');
+            await transitionTaskEvent(task, 'cancel');
             task.error = 'Job cancelled';
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
+            task.executionId = null;
             await store.saveTask(task);
         }
         await store.closePullRequest();
-        job.state = 'CANCELLED';
-        job.updatedAt = new Date().toISOString();
+        await transitionJobEvent(job, 'cancel');
         await store.saveJob(job);
         console.log(JSON.stringify(await store.load(id), null, 2));
         return;
@@ -674,23 +676,22 @@ export function dashboardJobAction(store, reconciler, action) {
         if (action === 'start') {
             if (job.state !== 'DRAFT')
                 throw new Error(`Job ${job.id} is not startable (${job.state})`);
-            job.state = 'ACTIVE';
-            job.updatedAt = new Date().toISOString();
+            await transitionJobEvent(job, 'activate');
             await store.saveJob(job);
         }
         else if (action === 'cancel') {
             if (job.state === 'COMPLETED' || job.state === 'CANCELLED')
                 throw new Error(`Job ${job.id} is not cancellable (${job.state})`);
             for (const task of job.tasks.filter(item => !['SUCCEEDED', 'CANCELLED'].includes(item.state))) {
-                transitionTask(task, 'CANCELLED');
+                await transitionTaskEvent(task, 'cancel');
                 task.error = 'Job cancelled';
                 task.leaseOwner = null;
                 task.leaseExpiresAt = null;
+                task.executionId = null;
                 await store.saveTask(task);
             }
             await store.closePullRequest?.();
-            job.state = 'CANCELLED';
-            job.updatedAt = new Date().toISOString();
+            await transitionJobEvent(job, 'cancel');
             await store.saveJob(job);
             return await store.load(job.id);
         }

package/dist/dashboard.js

@@ -5,6 +5,7 @@ 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');
@@ -496,6 +497,11 @@ 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/markers.js

@@ -34,7 +34,7 @@ function contentBeforeDelimiter(body, heading, end) {
 }
 export function renderJobComment(job) {
     const objective = job.objective?.trim() || '_No objective recorded._';
-    const { objective: _objective, tasks: _tasks, ...metadata } = job;
+    const { objective: _objective, description: _description, tasks: _tasks, ...metadata } = job;
     return `${marker(JOB_MARKER, metadata)}
 # Agents Relay job: ${job.title}
 
@@ -70,7 +70,7 @@ export function parseJob(body) {
     const job = parseMarker(body, JOB_MARKER);
     if (!job)
         return null;
-    const objective = job.objective ?? contentBeforeDelimiter(body, '\n## Objective\n\n', JOB_OBJECTIVE_END) ?? markdownSection(body, '\n## Objective\n');
+    const objective = job.objective ?? job.description ?? contentBeforeDelimiter(body, '\n## Objective\n\n', JOB_OBJECTIVE_END) ?? markdownSection(body, '\n## Objective\n');
     const parsed = { ...job, objective };
     if (parsed.executionMode === undefined)
         return { ...parsed, executionMode: 'fixed' };

package/dist/pool.js

@@ -7,9 +7,9 @@ export function needsLifecycleReconciliation(job, now = Date.now()) {
     // DRAFT create-only Jobs stay dormant until a caller explicitly creates work.
     if (job.tasks.length === 0)
         return false;
-    if (job.tasks.some(task => task.state === 'QUEUED' || (task.state === 'DRAFT' && task.dependencies.length > 0)))
+    if (job.tasks.some(task => (task.state === 'QUEUED' && task.executionId === null) || (task.state === 'DRAFT' && task.dependencies.length > 0)))
         return true;
-    return job.tasks.some(task => task.state === 'RUNNING' && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now);
+    return job.tasks.some(task => ['RUNNING', 'QUEUED'].includes(task.state) && task.executionId !== null && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now);
 }
 export function terminalManagedJobs(items) { return items.filter(item => item.githubState !== 'OPEN' && ((item.githubState === 'MERGED' && item.job.state !== 'COMPLETED') || (item.githubState === 'CLOSED' && item.job.state !== 'CANCELLED'))).map(item => item.job).sort(compareJobPriority); }
 export async function aggregateManagedGitHubJobs(client, repositories, trustedAuthors) {
@@ -48,8 +48,8 @@ export class RepositoryWorkerPool {
             if (capacity <= 0)
                 break;
             const store = new GitHubStore(this.client, job.repository, job.prNumber, this.trustedAuthors);
-            const ready = job.tasks.filter(task => task.state === 'QUEUED' || (task.state === 'DRAFT' && task.dependencies.length > 0)).length;
-            const expiredRunning = job.tasks.some(task => task.state === 'RUNNING' && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= Date.now());
+            const ready = job.tasks.filter(task => (task.state === 'QUEUED' && task.executionId === null) || (task.state === 'DRAFT' && task.dependencies.length > 0)).length;
+            const expiredRunning = job.tasks.some(task => ['RUNNING', 'QUEUED'].includes(task.state) && task.executionId !== null && task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= Date.now());
             if (!needsLifecycleReconciliation(job))
                 continue;
             const allowance = Math.max(1, Math.min(capacity, ready || (expiredRunning ? 1 : 0) || 1));

package/dist/reconciler.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { storySizeTimeoutMs, taskOverallTimeoutMs, chatGptStartAckTimeoutMs } from './types.js';
-import { dependencyReady, schedule, transitionTask } from './scheduler.js';
+import { dependencyReady, schedule, transitionJobEvent, transitionTaskEvent } from './scheduler.js';
 import { implementationComplete } from './runtime-status.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
@@ -125,16 +125,23 @@ export class Reconciler {
                 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();
-                    transitionTask(task, 'CANCELLED');
+                    await transitionTaskEvent(task, 'cancel');
                     task.error = reason;
                     task.leaseOwner = null;
                     task.leaseExpiresAt = null;
+                    task.executionId = null;
                     await this.store.saveTask(task);
                 }
                 const terminalState = prState === 'MERGED' ? 'COMPLETED' : 'CANCELLED';
                 if (job.state !== terminalState) {
-                    job.state = terminalState;
-                    job.updatedAt = new Date().toISOString();
+                    if (!['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'].includes(job.state)) {
+                        // Compatibility repair for legacy records that persisted derived runtime status as lifecycle.
+                        job.state = terminalState;
+                        job.updatedAt = new Date().toISOString();
+                    }
+                    else {
+                        await transitionJobEvent(job, prState === 'MERGED' ? 'pr.merged' : 'pr.closed', prState === 'CLOSED' ? { notMerged: true } : {});
+                    }
                     await this.store.saveJob(job);
                 }
                 return this.store.load(jobId);
@@ -167,11 +174,11 @@ export class Reconciler {
                 for (const task of scheduled.tasks.filter(item => item.state === 'SUCCEEDED' && (item.continuation || scheduled.continuation) && !item.continuationDeliveredAt))
                     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);
-                for (const task of scheduled.tasks.filter(t => t.state === 'QUEUED' && dependencyReady(t, new Map(scheduled.tasks.map(item => [item.id, item])))).sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2')).slice(0, capacity)) {
+                for (const task of scheduled.tasks.filter(t => t.state === 'QUEUED' && t.executionId === null && dependencyReady(t, new Map(scheduled.tasks.map(item => [item.id, item])))).sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2')).slice(0, capacity)) {
                     if (task.kind === 'planner')
                         await this.launchPlanner(scheduled, task);
                     else if (task.adapter === 'orchestrator') {
-                        transitionTask(task, 'RUNNING');
+                        await transitionTaskEvent(task, 'task.started');
                         task.leaseOwner = null;
                         task.leaseExpiresAt = null;
                         task.executionId = null;
@@ -204,7 +211,7 @@ export class Reconciler {
         const staleTask = job.review.taskId ? job.tasks.find(task => task.id === job.review?.taskId) : undefined;
         if (staleTask && ['DRAFT', 'QUEUED', 'RUNNING'].includes(staleTask.state)) {
             this.live.get(staleTask.id)?.execution.cancel();
-            transitionTask(staleTask, 'CANCELLED');
+            await transitionTaskEvent(staleTask, 'cancel');
             staleTask.error = 'Review evidence became stale after the PR head changed';
             staleTask.leaseOwner = null;
             staleTask.leaseExpiresAt = null;
@@ -303,15 +310,6 @@ export class Reconciler {
             return;
         const evidence = { summary: event.message || `Review ${outcome}`, data: { ...(event.data ?? {}), review: reviewData ?? { headSha }, headSha, outcome } };
         job.review = { outcome, headSha, taskId: task.id, evidence, updatedAt: event.timestamp || new Date().toISOString() };
-        if (outcome !== 'started') {
-            task.state = 'SUCCEEDED';
-            task.result = evidence;
-            task.error = null;
-            task.leaseOwner = null;
-            task.leaseExpiresAt = null;
-            task.updatedAt = job.review.updatedAt;
-            await this.store.saveTask(task);
-        }
         if (outcome === 'changes_required') {
             const rawIssues = Array.isArray(reviewData?.issues) ? reviewData.issues : [];
             const issues = rawIssues.map(item => {
@@ -335,7 +333,7 @@ export class Reconciler {
                     agentName: 'review-fix', parentTaskId: task.id, dependencies: [task.id], capabilities: ['implementation'],
                     adapter: 'codex', input, output: { kind: 'task_pr' },
                     routing: { provider: 'openai', model: 'gpt-5.6-luna', reasoning: 'medium', decidedBy: 'review-fix', decidedAt: now },
-                    continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3,
+                    continuation: null, continuationDeliveredAt: null, state: 'DRAFT', attempt: 0, maxAttempts: 3,
                     leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null,
                     error: null, timeoutMs: storySizeTimeoutMs('M'), createdAt: now, updatedAt: now
                 };
@@ -353,7 +351,7 @@ export class Reconciler {
         }
     }
     async recoverLostExecutions(job, now) {
-        for (const task of job.tasks.filter(item => item.state === 'RUNNING')) {
+        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)
@@ -365,17 +363,18 @@ export class Reconciler {
                 planner.controller.abort();
                 this.plannerLive.delete(task.id);
             }
+            const failedEvent = task.state === 'RUNNING' ? 'task.failed' : 'fail';
+            await transitionTaskEvent(task, failedEvent);
+            task.error = expired ? 'Lease expired' : 'Execution owner restarted';
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            task.executionId = null;
             if (task.attempt < task.maxAttempts) {
-                transitionTask(task, 'QUEUED');
-                task.leaseOwner = null;
-                task.leaseExpiresAt = null;
+                await transitionTaskEvent(task, 'retry');
                 await this.store.saveTask(task);
             }
             else {
-                task.error = expired ? 'Lease expired after maximum attempts' : 'Execution owner restarted after maximum attempts';
-                task.leaseOwner = null;
-                task.leaseExpiresAt = null;
-                transitionTask(task, 'FAILED');
+                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' }));
             }
@@ -445,13 +444,13 @@ export class Reconciler {
     async launch(job, task) {
         const adapter = this.options.adapters.find(x => x.name === task.adapter);
         if (!adapter) {
-            transitionTask(task, 'FAILED');
+            await transitionTaskEvent(task, 'fail');
             task.error = `No adapter ${task.adapter}`;
             await this.store.saveTask(task);
             return;
         }
         if (['codex', 'chatgpt'].includes(task.adapter) && !this.options.eventBus) {
-            transitionTask(task, 'BLOCKED');
+            await transitionTaskEvent(task, 'block');
             task.error = 'Model-backed tasks require an event bus for authoritative lifecycle state';
             await this.store.saveTask(task);
             return;
@@ -464,7 +463,7 @@ export class Reconciler {
             workerInput = managedWorkerInput(job, task, executionContext);
         }
         catch (error) {
-            transitionTask(task, 'BLOCKED');
+            await transitionTaskEvent(task, 'block');
             task.error = error instanceof Error ? error.message : String(error);
             await this.store.saveTask(task);
             return;
@@ -481,7 +480,8 @@ export class Reconciler {
                 return;
             const leaseMs = Math.max(this.options.leaseMs ?? 300000, freshTask.timeoutMs);
             const startedAt = (this.options.now ?? new Date()).getTime();
-            transitionTask(freshTask, 'RUNNING');
+            if (freshTask.executionId !== null)
+                return;
             freshTask.attempt += 1;
             freshTask.leaseOwner = this.options.owner;
             freshTask.leaseExpiresAt = new Date(startedAt + leaseMs).toISOString();
@@ -574,13 +574,13 @@ export class Reconciler {
         if (!planner) {
             task.attempt = task.maxAttempts;
             task.error = 'No objective planner configured';
-            transitionTask(task, 'FAILED');
+            await transitionTaskEvent(task, 'fail');
             await this.store.saveTask(task);
             await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${task.error}`, 'user'));
             return;
         }
         const startedAt = (this.options.now ?? new Date()).getTime();
-        transitionTask(task, 'RUNNING');
+        await transitionTaskEvent(task, 'task.started');
         task.attempt += 1;
         task.leaseOwner = this.options.owner;
         task.leaseExpiresAt = new Date(startedAt + Math.max(this.options.leaseMs ?? 300000, task.timeoutMs)).toISOString();
@@ -618,7 +618,10 @@ export class Reconciler {
             task.error = error.message;
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
-            transitionTask(task, task.attempt < task.maxAttempts ? 'QUEUED' : 'FAILED');
+            task.executionId = null;
+            await transitionTaskEvent(task, 'task.failed');
+            if (task.attempt < task.maxAttempts)
+                await transitionTaskEvent(task, 'retry');
             await this.store.saveTask(task);
             await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'planner.failed' : 'planner.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Planner ${task.id}: ${error.message}`, 'user'));
             this.detach(this.reconcile(jobId), jobId, task.id, 'planner retry reconciliation');
@@ -638,7 +641,8 @@ export class Reconciler {
             task.error = null;
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
-            transitionTask(task, 'SUCCEEDED');
+            task.executionId = null;
+            await transitionTaskEvent(task, 'task.completed');
             await this.store.saveTask(task);
             for (const child of children)
                 if (!job.tasks.some(item => item.id === child.id))
@@ -656,9 +660,12 @@ export class Reconciler {
                 task.error = message;
                 task.leaseOwner = null;
                 task.leaseExpiresAt = null;
-                transitionTask(task, task.attempt < task.maxAttempts ? 'QUEUED' : 'FAILED');
+                task.executionId = null;
+                await transitionTaskEvent(task, 'task.failed');
+                if (task.attempt < task.maxAttempts)
+                    await transitionTaskEvent(task, 'retry');
                 await this.store.saveTask(task);
-                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${message}`, 'user'));
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, task.state === 'FAILED' ? 'planner.failed' : 'planner.retry', task.state === 'FAILED' ? 'failed' : 'queued', `Planner ${task.id}: ${message}`, 'user'));
             }
         }
         this.detach(this.reconcile(jobId), jobId, task.id, 'planner follow-up reconciliation');
@@ -686,19 +693,29 @@ export class Reconciler {
         if (sourceAgent === 'relay' || sourceComponent === 'agents-relay')
             return;
         const live = this.live.get(event.task_id);
-        if (live && event.job_id === live.jobId) {
-            if (event.timestamp && new Date(event.timestamp).getTime() < live.launchBarrier)
-                return;
-            live.workerStarted = true;
+        if (live && event.job_id === live.jobId && event.timestamp && new Date(event.timestamp).getTime() < live.launchBarrier)
             return;
-        }
         const job = await this.store.load(event.job_id);
         const task = job.tasks.find(item => item.id === event.task_id);
-        if (!task || task.state !== 'FAILED' || !this.isRecoverableWatchdogFailure(task))
+        if (!task)
+            return;
+        const claimedExecution = task.state === 'QUEUED' && task.executionId !== null && task.leaseOwner !== null;
+        const exactLiveExecution = live && event.job_id === live.jobId && task.executionId === live.executionId;
+        if ((exactLiveExecution || claimedExecution) && task.state === 'QUEUED') {
+            await transitionTaskEvent(task, 'task.started');
+            task.failureReason = undefined;
+            task.error = null;
+            task.updatedAt = event.timestamp || new Date().toISOString();
+            await this.store.saveTask(task);
+            if (live)
+                live.workerStarted = true;
+            return;
+        }
+        if (task.state !== 'FAILED' || !this.isRecoverableWatchdogFailure(task))
             return;
         if (event.timestamp && new Date(event.timestamp).getTime() < new Date(task.updatedAt).getTime())
             return;
-        transitionTask(task, 'RUNNING');
+        await transitionTaskEvent(task, 'reconcile.started');
         task.failureReason = undefined;
         task.error = null;
         task.updatedAt = event.timestamp || new Date().toISOString();
@@ -728,23 +745,35 @@ export class Reconciler {
         cleanup.unref();
         const job = await this.store.load(jobId);
         const task = job.tasks.find(item => item.id === taskId);
-        if (!task || task.executionId !== executionId || task.state !== 'RUNNING')
+        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 });
-        await this.applyTerminalEvent(event);
+        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);
+        }
         await this.emit(event);
     }
     async runtimeSettled(jobId, taskId, executionId, result, error) {
         const live = this.live.get(taskId);
-        const workerStarted = live?.executionId === executionId && live.workerStarted;
+        const liveWorkerStarted = live?.executionId === executionId && live.workerStarted;
         if (live?.executionId === executionId)
             this.live.delete(taskId);
         const job = await this.store.load(jobId);
         const task = job.tasks.find(item => item.id === taskId);
+        const workerStarted = liveWorkerStarted || task?.state === 'RUNNING';
         if (!task || task.executionId !== executionId)
             return;
         await this.emit(eventFor(jobId, taskId, task.parentTaskId, task.adapter === 'chatgpt' ? 'task.process.async_exited' : 'task.process.exited', error ? 'failed' : 'succeeded', error ?? result?.summary ?? 'Worker runtime exited', 'orchestrator', { authoritative: false, waitingForTerminalEvent: true, processError: error }, { agent: 'relay', component: 'agents-relay' }));
-        if (task.state === 'RUNNING' && task.adapter === 'codex')
+        if (['QUEUED', 'RUNNING'].includes(task.state) && task.adapter === 'codex')
             this.scheduleUnexpectedExit(jobId, taskId, executionId, workerStarted === true);
     }
     scheduleUnexpectedExit(jobId, taskId, executionId, workerStarted) {
@@ -758,14 +787,25 @@ export class Reconciler {
     async failUnexpectedExit(jobId, taskId, executionId, workerStarted) {
         const job = await this.store.load(jobId);
         const task = job.tasks.find(item => item.id === taskId);
-        if (!task || task.executionId !== executionId || task.state !== 'RUNNING')
+        if (!task || task.executionId !== executionId || !['QUEUED', 'RUNNING'].includes(task.state))
             return;
         const reason = workerStarted ? 'worker_exit_without_terminal_event' : 'worker_exit_before_start';
         const message = workerStarted
             ? `Worker ${taskId} exited after task.started without publishing a terminal task event`
             : `Worker ${taskId} exited before publishing task.started`;
         const event = eventFor(jobId, taskId, task.parentTaskId, 'task.failed', 'failed', message, 'user', { reason, terminalGraceMs: this.options.terminalExitGraceMs ?? 1000 }, { agent: 'relay', component: 'agents-relay', watchdog: true });
-        await this.applyTerminalEvent(event);
+        if (task.state === 'QUEUED') {
+            this.clearExecution(task.id, executionId);
+            task.error = message;
+            task.failureReason = reason;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            await transitionTaskEvent(task, 'fail');
+            await this.store.saveTask(task);
+        }
+        else {
+            await this.applyTerminalEvent(event);
+        }
         await this.emit(event);
     }
     async timeoutTask(jobId, taskId, executionId) {
@@ -776,12 +816,23 @@ export class Reconciler {
         }
         const job = await this.store.load(jobId);
         const task = job.tasks.find(item => item.id === taskId);
-        if (!task || task.executionId !== executionId || task.state !== 'RUNNING') {
+        if (!task || task.executionId !== executionId || !['QUEUED', 'RUNNING'].includes(task.state)) {
             this.clearExecution(taskId, executionId);
             return;
         }
         const event = eventFor(jobId, taskId, task.parentTaskId, 'task.failed', 'failed', `Task ${taskId} timed out waiting for the mandatory terminal worker event`, 'user', { reason: 'terminal_event_timeout', timeoutMs: task.timeoutMs });
-        await this.applyTerminalEvent(event);
+        if (task.state === 'QUEUED') {
+            task.error = event.message;
+            task.failureReason = 'terminal_event_timeout';
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            await transitionTaskEvent(task, 'fail');
+            await this.store.saveTask(task);
+            this.clearExecution(task.id, executionId);
+        }
+        else {
+            await this.applyTerminalEvent(event);
+        }
         await this.emit(event);
     }
     async applyTerminalEvent(event) {
@@ -792,7 +843,7 @@ export class Reconciler {
         if (task.state === 'FAILED' && this.isRecoverableWatchdogFailure(task) && this.isWorkerOwnedEvent(event)) {
             if (event.timestamp && new Date(event.timestamp).getTime() < new Date(task.updatedAt).getTime())
                 return;
-            transitionTask(task, 'RUNNING');
+            await transitionTaskEvent(task, 'reconcile.started');
             task.failureReason = undefined;
             task.error = null;
         }
@@ -811,24 +862,24 @@ export class Reconciler {
             task.result = { summary: event.message || `Task ${task.id} completed`, data: event.data };
             task.error = null;
             task.failureReason = undefined;
-            transitionTask(task, 'SUCCEEDED');
+            await transitionTaskEvent(task, 'task.completed');
             await this.store.saveTask(task);
             await this.deliverContinuation(job, task);
         }
         else if (event.type === 'task.failed') {
             task.error = event.message || `Task ${task.id} failed`;
             task.failureReason = typeof event.data?.reason === 'string' ? event.data.reason : undefined;
-            transitionTask(task, 'FAILED');
+            await transitionTaskEvent(task, 'task.failed');
             await this.store.saveTask(task);
         }
         else if (event.type === 'task.blocked') {
             task.error = event.message || `Task ${task.id} blocked`;
-            transitionTask(task, 'BLOCKED');
+            await transitionTaskEvent(task, 'task.blocked');
             await this.store.saveTask(task);
         }
         else if (event.type === 'task.cancelled') {
             task.error = event.message || `Task ${task.id} cancelled`;
-            transitionTask(task, 'CANCELLED');
+            await transitionTaskEvent(task, 'task.cancelled');
             await this.store.saveTask(task);
         }
         this.detach(this.reconcile(job.id), job.id, task.id, 'terminal-event reconciliation');

package/dist/scheduler.js

@@ -1,4 +1,4 @@
-import { assertTaskTransition } from './types.js';
+import { decideJobLifecycle, decideTaskLifecycle } from './workflow/rollout.js';
 export function dependencyReady(task, tasks) { return task.dependencies.every(id => tasks.get(id)?.state === 'SUCCEEDED'); }
 export function detectCycles(tasks) { const map = new Map(tasks.map(t => [t.id, t])); const visiting = new Set(); const done = new Set(); const visit = (id) => { if (visiting.has(id))
     throw new Error(`Dependency cycle at ${id}`); if (done.has(id))
@@ -25,12 +25,16 @@ export function schedule(job) {
     const map = new Map(job.tasks.map(t => [t.id, t]));
     for (const task of scopedTasks) {
         const ready = dependencyReady(task, map);
-        if (task.state === 'DRAFT' && task.dependencies.length > 0 && ready)
-            transitionTask(task, 'QUEUED');
-        else if (task.state === 'QUEUED' && !ready)
-            transitionTask(task, 'DRAFT');
-        else if (task.state === 'QUEUED' && ready && task.error !== null)
-            transitionTask(task, 'QUEUED');
+        const facts = {
+            dependenciesSatisfied: task.dependencies.length > 0 && ready,
+            dependenciesUnsatisfied: task.dependencies.length > 0 && !ready,
+            runnable: ready,
+        };
+        const decision = decideTaskLifecycle(task, 'reconcile', facts);
+        if (decision.reason === 'ambiguous')
+            throw new Error(`Ambiguous automatic task transition from ${task.state}`);
+        if (decision.accepted && decision.target)
+            applyTaskState(task, decision.target);
     }
     if (job.schedule) {
         const planners = scopedTasks.filter(task => task.kind === 'planner');
@@ -52,8 +56,25 @@ export function extendRetryBudget(task, windowSize = 3) {
     const usedOrBudgeted = Math.max(task.maxAttempts, task.attempt);
     return Math.max(windowSize, (Math.floor(usedOrBudgeted / windowSize) + 1) * windowSize);
 }
-export function transitionTask(task, state) { assertTaskTransition(task.state, state); task.state = state; if (['QUEUED', 'RUNNING', 'SUCCEEDED'].includes(state))
+function applyTaskState(task, state) { task.state = state; if (['QUEUED', 'RUNNING', 'SUCCEEDED'].includes(state))
     task.error = null; task.updatedAt = new Date().toISOString(); }
+export async function transitionTaskEvent(task, event, context = {}) {
+    const decision = decideTaskLifecycle(task, event, context);
+    if (!decision.accepted || !decision.target)
+        throw new Error(decision.reason === 'ambiguous'
+            ? `Ambiguous workflow transition from ${task.state} on ${event}`
+            : `No enabled workflow transition from ${task.state} on ${event}`);
+    applyTaskState(task, decision.target);
+}
+export async function transitionJobEvent(job, event, context = {}) {
+    const decision = decideJobLifecycle(job, event, context);
+    if (!decision.accepted || !decision.target)
+        throw new Error(decision.reason === 'ambiguous'
+            ? `Ambiguous workflow transition from ${job.state} on ${event}`
+            : `No enabled workflow transition from ${job.state} on ${event}`);
+    job.state = decision.target;
+    job.updatedAt = new Date().toISOString();
+}
 export const SCHEDULE_RESOLUTION_MS = 600_000;
 export const RUN_BUCKET_LABEL_COUNT = 144;
 const CRON_PART = /^(?:\*|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/;

package/dist/types.js

@@ -1,10 +1,7 @@
+import { jobLifecycleWorkflow, taskLifecycleWorkflow } from './workflow/definitions.js';
 export const STORY_SIZE_TIMEOUT_MS = { S: 300000, M: 900000, L: 2700000 };
 export function storySizeTimeoutMs(size) { return STORY_SIZE_TIMEOUT_MS[size]; }
 export function taskOverallTimeoutMs(size, reasoning) { return storySizeTimeoutMs(size) * (reasoning?.toLowerCase() === 'high' ? 2 : 1); }
 export function chatGptStartAckTimeoutMs(overallTimeoutMs) { return Math.min(600000, Math.max(120000, Math.floor(overallTimeoutMs / 3))); }
-const jobLifecycleTransitions = { DRAFT: ['ACTIVE', 'COMPLETED', 'CANCELLED'], ACTIVE: ['COMPLETED', 'CANCELLED'], COMPLETED: [], CANCELLED: ['COMPLETED'] };
-const taskTransitions = { DRAFT: ['QUEUED', 'BLOCKED', 'CANCELLED'], QUEUED: ['DRAFT', 'RUNNING', 'BLOCKED', 'FAILED', 'CANCELLED'], RUNNING: ['BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'QUEUED'], BLOCKED: ['QUEUED', 'CANCELLED'], SUCCEEDED: [], FAILED: ['QUEUED', 'RUNNING', 'CANCELLED'], CANCELLED: [] };
-export function assertJobLifecycleTransition(from, to) { if (from !== to && !jobLifecycleTransitions[from].includes(to))
-    throw new Error(`Invalid job transition ${from} -> ${to}`); }
-export function assertTaskTransition(from, to) { if (from !== to && !taskTransitions[from].includes(to))
-    throw new Error(`Invalid task transition ${from} -> ${to}`); }
+export function assertJobLifecycleTransition(from, to) { jobLifecycleWorkflow.assertStateTransition(from, to, 'job'); }
+export function assertTaskTransition(from, to) { taskLifecycleWorkflow.assertStateTransition(from, to, 'task'); }

package/dist/workflow/definitions.js

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+import { parseExecutableMermaid, WorkflowEngine } from './mermaid.js';
+function load(name, guards = {}, actions = {}) {
+    const url = new URL(`../../workflow/${name}.mmd`, import.meta.url);
+    return new WorkflowEngine(parseExecutableMermaid(readFileSync(url, 'utf8')), guards, actions);
+}
+const booleanGuard = (name) => context => context[name] === true;
+const lifecycleAction = () => { };
+export const jobLifecycleWorkflow = load('job-lifecycle', { notMerged: booleanGuard('notMerged') }, { cancelJob: lifecycleAction });
+export const taskLifecycleWorkflow = load('task-lifecycle', {
+    dependenciesSatisfied: booleanGuard('dependenciesSatisfied'),
+    dependenciesUnsatisfied: booleanGuard('dependenciesUnsatisfied'),
+    runnable: booleanGuard('runnable'),
+}, { release: lifecycleAction, hold: lifecycleAction });

package/dist/workflow/mermaid.js

@@ -0,0 +1,180 @@
+const STATE = String.raw `(?:[A-Za-z_][A-Za-z0-9_.-]*|\[\*\])`;
+const TRANSITION = new RegExp(`^(${STATE})\\s*-->\\s*(${STATE})(?:\\s*:\\s*(.+))?$`);
+const NAME = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+function parseLabel(label, line, terminal) {
+    if (!label?.trim()) {
+        if (terminal)
+            return { event: '', guard: null, actions: [] };
+        throw new Error(`Executable Mermaid transition at line ${line} requires an event label`);
+    }
+    const pieces = label.split('/');
+    if (pieces.length > 2)
+        throw new Error(`Executable Mermaid label at line ${line} may contain at most one '/' action separator`);
+    const left = pieces[0].trim();
+    const guardMatch = left.match(/^(.*?)(?:\s+\[([A-Za-z_][A-Za-z0-9_.-]*)\])?$/);
+    if (!guardMatch)
+        throw new Error(`Invalid executable Mermaid label at line ${line}`);
+    const event = guardMatch[1].trim();
+    const guard = guardMatch[2] ?? null;
+    if (!event || !NAME.test(event))
+        throw new Error(`Invalid event '${event}' at line ${line}`);
+    const actions = pieces[1]?.split(',').map(value => value.trim()).filter(Boolean) ?? [];
+    for (const action of actions)
+        if (!NAME.test(action))
+            throw new Error(`Invalid action '${action}' at line ${line}`);
+    return { event, guard, actions };
+}
+export function parseExecutableMermaid(source) {
+    const lines = source.split(/\r?\n/);
+    let headerSeen = false;
+    const states = new Set();
+    const finals = new Set();
+    const transitions = [];
+    const initials = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const lineNumber = index + 1;
+        const line = lines[index].trim();
+        if (!line || line.startsWith('%%'))
+            continue;
+        if (!headerSeen) {
+            if (line !== 'stateDiagram-v2')
+                throw new Error(`Executable Mermaid must start with stateDiagram-v2 (line ${lineNumber})`);
+            headerSeen = true;
+            continue;
+        }
+        const match = line.match(TRANSITION);
+        if (!match)
+            throw new Error(`Unsupported executable Mermaid syntax at line ${lineNumber}: ${line}`);
+        const [, from, to, label] = match;
+        const fromTerminal = from === '[*]';
+        const toTerminal = to === '[*]';
+        if (fromTerminal && toTerminal)
+            throw new Error(`Invalid [*] -> [*] transition at line ${lineNumber}`);
+        if (!fromTerminal)
+            states.add(from);
+        if (!toTerminal)
+            states.add(to);
+        if (fromTerminal) {
+            if (label?.trim())
+                throw new Error(`Initial transition at line ${lineNumber} must not have an event label`);
+            initials.push(to);
+            continue;
+        }
+        if (toTerminal) {
+            if (label?.trim())
+                throw new Error(`Final transition at line ${lineNumber} must not have an event label`);
+            finals.add(from);
+            continue;
+        }
+        transitions.push({ from, to, ...parseLabel(label, lineNumber, false), line: lineNumber });
+    }
+    if (!headerSeen)
+        throw new Error('Executable Mermaid is empty');
+    if (initials.length !== 1)
+        throw new Error(`Executable Mermaid requires exactly one [*] initial transition; found ${initials.length}`);
+    if (transitions.length === 0)
+        throw new Error('Executable Mermaid requires at least one executable transition');
+    const seen = new Set();
+    const deterministicKeys = new Set();
+    for (const transition of transitions) {
+        const key = `${transition.from}\u0000${transition.event}\u0000${transition.guard ?? ''}\u0000${transition.to}`;
+        if (seen.has(key))
+            throw new Error(`Duplicate executable transition at line ${transition.line}: ${transition.from} --${transition.event}--> ${transition.to}`);
+        seen.add(key);
+        const deterministicKey = `${transition.from}\u0000${transition.event}\u0000${transition.guard ?? ''}`;
+        if (deterministicKeys.has(deterministicKey))
+            throw new Error(`Ambiguous executable transition at line ${transition.line}: duplicate source/event/guard ${transition.from} --${transition.event} [${transition.guard ?? 'unguarded'}]`);
+        deterministicKeys.add(deterministicKey);
+    }
+    return { source, states, initial: initials[0], finals, transitions };
+}
+export class WorkflowEngine {
+    graph;
+    guards;
+    actions;
+    constructor(graph, guards = {}, actions = {}) {
+        this.graph = graph;
+        this.guards = guards;
+        this.actions = actions;
+        this.validateRegistryBindings();
+    }
+    validateRegistryBindings() {
+        for (const transition of this.graph.transitions) {
+            if (transition.guard && !this.guards[transition.guard])
+                throw new Error(`Unknown workflow guard ${transition.guard} referenced at line ${transition.line}`);
+            for (const action of transition.actions)
+                if (!this.actions[action])
+                    throw new Error(`Unknown workflow action ${action} referenced at line ${transition.line}`);
+        }
+    }
+    transitionsFrom(state) {
+        if (!this.graph.states.has(state))
+            throw new Error(`Unknown workflow state ${state}`);
+        return this.graph.transitions.filter(transition => transition.from === state);
+    }
+    assertStateTransition(from, to, kind = 'workflow') {
+        if (from === to)
+            return;
+        if (!this.graph.states.has(from) || !this.graph.states.has(to))
+            throw new Error(`Unknown ${kind} state ${!this.graph.states.has(from) ? from : to}`);
+        if (!this.graph.transitions.some(transition => transition.from === from && transition.to === to))
+            throw new Error(`Invalid ${kind} transition ${from} -> ${to}`);
+    }
+    enabledSync(state, event, context = {}) {
+        const candidates = this.transitionsFrom(state).filter(transition => transition.event === event);
+        const enabled = [];
+        for (const transition of candidates) {
+            if (!transition.guard) {
+                enabled.push(transition);
+                continue;
+            }
+            const value = this.guards[transition.guard](context);
+            if (value instanceof Promise)
+                throw new Error(`Workflow guard ${transition.guard} is asynchronous and cannot be used in a synchronous transition`);
+            if (value)
+                enabled.push(transition);
+        }
+        return enabled;
+    }
+    transitionSync(state, event, context = {}) {
+        const enabled = this.enabledSync(state, event, context);
+        if (enabled.length === 0)
+            throw new Error(`No enabled workflow transition from ${state} on ${event}`);
+        if (enabled.length > 1)
+            throw new Error(`Ambiguous workflow transition from ${state} on ${event}`);
+        const transition = enabled[0];
+        for (const actionName of transition.actions) {
+            const value = this.actions[actionName](context, transition);
+            if (value instanceof Promise)
+                throw new Error(`Workflow action ${actionName} is asynchronous and cannot be used in a synchronous transition`);
+        }
+        return transition.to;
+    }
+    async enabled(state, event, context = {}) {
+        const candidates = this.transitionsFrom(state).filter(transition => transition.event === event);
+        const enabled = [];
+        for (const transition of candidates) {
+            if (!transition.guard) {
+                enabled.push(transition);
+                continue;
+            }
+            const guard = this.guards[transition.guard];
+            if (await guard(context))
+                enabled.push(transition);
+        }
+        return enabled;
+    }
+    async transition(state, event, context = {}) {
+        const enabled = await this.enabled(state, event, context);
+        if (enabled.length === 0)
+            throw new Error(`No enabled workflow transition from ${state} on ${event}`);
+        if (enabled.length > 1)
+            throw new Error(`Ambiguous workflow transition from ${state} on ${event}`);
+        const transition = enabled[0];
+        for (const actionName of transition.actions) {
+            const action = this.actions[actionName];
+            await action(context, transition);
+        }
+        return transition.to;
+    }
+}

package/dist/workflow/rollout.js

@@ -0,0 +1,171 @@
+import { jobLifecycleWorkflow, taskLifecycleWorkflow } from './definitions.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 graphDecision(engine, from, event, context) {
+    const enabled = engine.enabledSync(from, event, context);
+    if (enabled.length === 0)
+        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
+    if (enabled.length > 1)
+        return { accepted: false, target: null, guard: null, actions: [], reason: 'ambiguous' };
+    const transition = enabled[0];
+    return {
+        accepted: true,
+        target: transition.to,
+        guard: transition.guard,
+        actions: [...transition.actions],
+        reason: 'accepted',
+    };
+}
+const taskLegacy = {
+    DRAFT: {
+        release: { target: 'QUEUED' },
+        block: { target: 'BLOCKED' },
+        cancel: { target: 'CANCELLED' },
+    },
+    QUEUED: {
+        hold: { target: 'DRAFT' },
+        'task.started': { target: 'RUNNING' },
+        block: { target: 'BLOCKED' },
+        fail: { target: 'FAILED' },
+        cancel: { target: 'CANCELLED' },
+    },
+    RUNNING: {
+        'task.blocked': { target: 'BLOCKED' },
+        'task.completed': { target: 'SUCCEEDED' },
+        'task.failed': { target: 'FAILED' },
+        'task.cancelled': { target: 'CANCELLED' },
+    },
+    BLOCKED: {
+        retry: { target: 'QUEUED' },
+        cancel: { target: 'CANCELLED' },
+    },
+    SUCCEEDED: {},
+    FAILED: {
+        retry: { target: 'QUEUED' },
+        'reconcile.started': { target: 'RUNNING' },
+        'reconcile.completed': { target: 'SUCCEEDED' },
+        'reconcile.blocked': { target: 'BLOCKED' },
+        cancel: { target: 'CANCELLED' },
+    },
+    CANCELLED: {},
+};
+const jobLegacy = {
+    DRAFT: {
+        activate: { target: 'ACTIVE' },
+        'pr.merged': { target: 'COMPLETED' },
+        cancel: { target: 'CANCELLED' },
+    },
+    ACTIVE: {
+        'pr.merged': { target: 'COMPLETED' },
+        cancel: { target: 'CANCELLED' },
+    },
+    COMPLETED: {},
+    CANCELLED: {
+        'pr.merged': { target: 'COMPLETED' },
+    },
+};
+function taskLegacyDecision(from, event, context) {
+    if (event === 'reconcile') {
+        if (from === 'DRAFT' && context.dependenciesSatisfied === true)
+            return { accepted: true, target: 'QUEUED', guard: 'dependenciesSatisfied', actions: ['release'], reason: 'accepted' };
+        if (from === 'QUEUED' && context.dependenciesUnsatisfied === true)
+            return { accepted: true, target: 'DRAFT', guard: 'dependenciesUnsatisfied', actions: ['hold'], reason: 'accepted' };
+        if (from === 'QUEUED' && context.runnable === true)
+            return { accepted: true, target: 'QUEUED', guard: 'runnable', actions: ['release'], reason: 'accepted' };
+        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
+    }
+    const transition = taskLegacy[from][event];
+    if (!transition)
+        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
+    return { accepted: true, target: transition.target, guard: transition.guard ?? null, actions: transition.actions ?? [], reason: 'accepted' };
+}
+function jobLegacyDecision(from, event, context) {
+    if (event === 'pr.closed') {
+        if ((from === 'DRAFT' || from === 'ACTIVE') && context.notMerged === true) {
+            return { accepted: true, target: 'CANCELLED', guard: 'notMerged', actions: ['cancelJob'], reason: 'accepted' };
+        }
+        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
+    }
+    const transition = jobLegacy[from][event];
+    if (!transition)
+        return { accepted: false, target: null, guard: null, actions: [], reason: 'no_transition' };
+    return { accepted: true, target: transition.target, guard: transition.guard ?? null, actions: transition.actions ?? [], reason: 'accepted' };
+}
+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]);
+}
+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, context = {}) {
+    const legacy = taskLegacyDecision(task.state, event, context);
+    const mode = workflowRolloutMode();
+    if (mode === 'legacy')
+        return legacy;
+    const graph = graphDecision(taskLifecycleWorkflow, task.state, event, context);
+    if (mode === 'shadow') {
+        report('task', task.jobId ?? 'unknown', task.id, event, task.state, context, legacy, graph);
+        return legacy;
+    }
+    return graph;
+}
+export function decideJobLifecycle(job, event, context = {}) {
+    const legacy = jobLegacyDecision(job.state, event, context);
+    const mode = workflowRolloutMode();
+    if (mode === 'legacy')
+        return legacy;
+    const graph = graphDecision(jobLifecycleWorkflow, job.state, event, context);
+    if (mode === 'shadow') {
+        report('job', job.id, undefined, event, job.state, context, legacy, graph);
+        return legacy;
+    }
+    return graph;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "1.0.68",
+  "version": "1.0.69",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
   "files": [
     "dist",
     "skills",
+    "workflow",
     "README.md",
     "LICENSE"
   ]

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

@@ -47,6 +47,8 @@ Raw `timeoutMs` is a compatibility/debug/hotfix override, not the normal task-pr
 
 ## Task readiness states
 
+Canonical Job/Task lifecycle legality is defined by the directly renderable runtime sources `workflow/job-lifecycle.mmd` and `workflow/task-lifecycle.mmd`. Producers, runtime code, docs, and agents must treat those files as the transition source of truth; the prose below explains semantics and must not become a second transition table.
+
 Task readiness is explicit and must use these semantics:
 
 - `DRAFT`: durable Task exists but is not executable now. A DRAFT Task with dependencies is promoted to `QUEUED` when all dependencies succeed. A DRAFT Task with no dependencies remains held until an explicit release to `QUEUED`.
@@ -63,6 +65,8 @@ Relay owns process lifecycle. Workers own semantic task lifecycle. A worker must
 
 ## 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.
+
 Durable Job lifecycle is intentionally small: `DRAFT | ACTIVE | COMPLETED | CANCELLED`.
 
 - `DRAFT`: durable objective exists, but the execution engine must not run it.

package/workflow/job-lifecycle.mmd

@@ -0,0 +1,15 @@
+stateDiagram-v2
+    [*] --> DRAFT
+
+    DRAFT --> ACTIVE: activate
+    DRAFT --> COMPLETED: pr.merged
+    DRAFT --> CANCELLED: cancel
+    DRAFT --> CANCELLED: pr.closed [notMerged] / cancelJob
+
+    ACTIVE --> COMPLETED: pr.merged
+    ACTIVE --> CANCELLED: cancel
+    ACTIVE --> CANCELLED: pr.closed [notMerged] / cancelJob
+
+    CANCELLED --> COMPLETED: pr.merged
+
+    COMPLETED --> [*]

package/workflow/task-lifecycle.mmd

@@ -0,0 +1,32 @@
+stateDiagram-v2
+    [*] --> DRAFT
+
+    DRAFT --> QUEUED: release
+    DRAFT --> QUEUED: reconcile [dependenciesSatisfied] / release
+    DRAFT --> BLOCKED: block
+    DRAFT --> CANCELLED: cancel
+
+    QUEUED --> DRAFT: hold
+    QUEUED --> DRAFT: reconcile [dependenciesUnsatisfied] / hold
+    QUEUED --> QUEUED: reconcile [runnable] / release
+    QUEUED --> RUNNING: task.started
+    QUEUED --> BLOCKED: block
+    QUEUED --> FAILED: fail
+    QUEUED --> CANCELLED: cancel
+
+    RUNNING --> BLOCKED: task.blocked
+    RUNNING --> SUCCEEDED: task.completed
+    RUNNING --> FAILED: task.failed
+    RUNNING --> CANCELLED: task.cancelled
+
+    BLOCKED --> QUEUED: retry
+    BLOCKED --> CANCELLED: cancel
+
+    FAILED --> QUEUED: retry
+    FAILED --> RUNNING: reconcile.started
+    FAILED --> SUCCEEDED: reconcile.completed
+    FAILED --> BLOCKED: reconcile.blocked
+    FAILED --> CANCELLED: cancel
+
+    SUCCEEDED --> [*]
+    CANCELLED --> [*]