agents-relay 1.0.53 → 1.0.55

package/README.md

@@ -23,12 +23,17 @@ npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1
 npx agents-relay job show --repo OWNER/REPO --pr 12 --id job-1
 ~~~
 
-Mutable queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
+Task readiness is explicit: `DRAFT` means the durable task exists but is not executable yet; `QUEUED` means Relay may execute it now; `RUNNING` means worker execution has started. Tasks created with dependencies start `DRAFT` and become `QUEUED` when those dependencies succeed. A dependency-free task created with `--draft` stays held until `task update --queue`. Once a task has run, external waiting is represented as `BLOCKED`, never by returning to `DRAFT`.
+
+Mutable draft/queued/retryable task fields can be changed in place without replacing the durable task identity. `task update` rejects `RUNNING`, `SUCCEEDED`, and `CANCELLED` tasks so active execution and terminal history cannot be rewritten. For example:
 
 ~~~sh
 npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child \
   --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high \
   --capabilities model,chatgpt,browser-harness
+
+# Explicitly release a held DRAFT task
+npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child --queue
 ~~~
 
 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 } from './scheduler.js';
+import { extendRetryBudget, parseJobSchedule, transitionTask } from './scheduler.js';
 import { dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.js';
@@ -93,16 +93,16 @@ Usage:
   npx agents-relay task <create|update|show|list|retry|cancel> [options]
 
 Actions:
-  create  Create one executable Task under an existing Job
+  create  Create one durable Task under an existing Job
   update  Update mutable Task fields
   show    Show one Task
   list    List Tasks for a Job
   retry   Retry a failed or blocked Task
   cancel  Cancel a Task`,
-    'task create': `Create one executable Task under an existing Job.
+    'task create': `Create one durable Task under an existing Job.
 
 Required: normal Job storage options plus --input TEXT and --output task-pr|file. Codex/ChatGPT tasks also require --model MODEL.
-Common: --task-id ID, --adapter codex|chatgpt|orchestrator, --priority P0|P1|P2|P3, --story-size S|M|L, --deps a,b, --parent ID.
+Common: --task-id ID, --adapter codex|chatgpt|orchestrator, --priority P0|P1|P2|P3, --story-size S|M|L, --deps a,b, --parent ID, --draft.\nTasks with dependencies start DRAFT; tasks without dependencies start QUEUED unless --draft is given.
 Directly-created Tasks are not wrapped in a synthetic Plan. Planner-generated Tasks are created internally by Relay from planner output.
 
 Example:
@@ -110,7 +110,7 @@ Example:
     'task update': `Update mutable durable Task fields in place.
 
 Required: --task-id ID and the normal Job storage options.
-Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --story-size, --input, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy.
+Mutable while not RUNNING/SUCCEEDED/CANCELLED: --adapter, --priority, --story-size, --input, --project, --agent, --parent, --deps, --capabilities, --timeout, --max-attempts, --provider, --model, --profile, --reasoning, --cwd, --chatgpt-project, --chatgpt-tab-close-policy, --draft, --queue.
 Use --clear-routing to remove routing metadata.
 
 Example:
@@ -340,6 +340,7 @@ function workerTaskFromArgs(job, args, now) {
     const routing = adapter === 'orchestrator' ? undefined : { provider: arg(args, '--provider', 'openai'), model, profile: arg(args, '--profile') || undefined, reasoning: arg(args, '--reasoning') || undefined, cwd: arg(args, '--cwd') || undefined, projectId: arg(args, '--chatgpt-project') || undefined, decidedBy: 'cli', decidedAt: now };
     const closePolicy = hasArg(args, '--chatgpt-tab-close-policy') ? chatGptTabClosePolicy(args) : undefined;
     const size = storySize(args);
+    const dependencies = arg(args, '--deps').split(',').filter(Boolean);
     const timeoutMs = adapter === 'orchestrator' ? 0 : hasArg(args, '--timeout') ? integerArg(args, '--timeout', taskOverallTimeoutMs(size, routing?.reasoning)) : taskOverallTimeoutMs(size, routing?.reasoning);
     return {
         jobId: job.id,
@@ -349,7 +350,7 @@ function workerTaskFromArgs(job, args, now) {
         projectName: arg(args, '--project') || undefined,
         agentName: arg(args, '--agent') || undefined,
         parentTaskId: arg(args, '--parent') || null,
-        dependencies: arg(args, '--deps').split(',').filter(Boolean),
+        dependencies,
         capabilities: arg(args, '--capabilities').split(',').filter(Boolean),
         adapter,
         chatgptTabClosePolicy: closePolicy,
@@ -359,7 +360,7 @@ function workerTaskFromArgs(job, args, now) {
         routing,
         continuation: continuation(args),
         continuationDeliveredAt: null,
-        state: 'QUEUED',
+        state: hasArg(args, '--draft') || dependencies.length > 0 ? 'DRAFT' : 'QUEUED',
         attempt: 0,
         maxAttempts: Number(arg(args, '--max-attempts', '3')),
         leaseOwner: null,
@@ -390,8 +391,13 @@ async function runTaskCommand(action, args) {
         task.id = id;
         await store.appendTask(task);
         const refreshed = await store.load(job.id);
-        if (refreshed.state !== 'RUNNING') {
-            refreshed.state = 'RUNNING';
+        const hasActive = refreshed.tasks.some(item => ['QUEUED', 'RUNNING'].includes(item.state));
+        const hasBlocked = refreshed.tasks.some(item => item.state === 'BLOCKED');
+        const hasDraft = refreshed.tasks.some(item => item.state === 'DRAFT');
+        const hasFailed = refreshed.tasks.some(item => item.state === 'FAILED');
+        const nextState = hasActive ? 'RUNNING' : hasBlocked ? 'BLOCKED' : hasDraft ? 'WAITING' : hasFailed ? 'FAILED' : refreshed.state;
+        if (refreshed.state !== nextState) {
+            refreshed.state = nextState;
             refreshed.updatedAt = now;
             await store.saveJob(refreshed);
         }
@@ -411,7 +417,7 @@ async function runTaskCommand(action, args) {
     if (action === 'retry' || action === 'cancel') {
         if (action === 'retry')
             task.maxAttempts = extendRetryBudget(task);
-        task.state = action === 'retry' ? 'READY' : 'CANCELLED';
+        task.state = action === 'retry' ? 'QUEUED' : 'CANCELLED';
         task.error = action === 'retry' ? null : 'Cancelled by user';
         task.updatedAt = new Date().toISOString();
         await store.saveTask(task);
@@ -456,6 +462,16 @@ async function runTaskCommand(action, args) {
         task.chatgptTabClosePolicy = chatGptTabClosePolicy(args);
     task.timeoutMs = integerArg(args, '--timeout', task.timeoutMs);
     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, '--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 (hasArg(args, '--max-attempts') && task.maxAttempts < task.attempt)
         throw new Error('--max-attempts cannot be less than the current attempt count');
     const routingFlags = ['--provider', '--model', '--profile', '--reasoning', '--cwd', '--chatgpt-project'];
@@ -508,7 +524,7 @@ async function runJobCommand(action, args) {
         throw new Error(usage);
     const repo = repository(args);
     if (action === 'create') {
-        const taskOnlyFlags = ['--start', '--task-id', '--input', '--adapter', '--provider', '--model', '--profile', '--reasoning', '--story-size', '--project', '--agent', '--parent', '--deps', '--capabilities', '--attachments', '--max-attempts', '--timeout', '--cwd', '--chatgpt-project', '--chatgpt-tab-close-policy', '--output', '--output-path'];
+        const taskOnlyFlags = ['--start', '--task-id', '--input', '--adapter', '--provider', '--model', '--profile', '--reasoning', '--story-size', '--project', '--agent', '--parent', '--deps', '--capabilities', '--attachments', '--max-attempts', '--timeout', '--cwd', '--chatgpt-project', '--chatgpt-tab-close-policy', '--output', '--output-path', '--draft', '--queue'];
         const invalid = taskOnlyFlags.find(flag => hasArg(args, flag));
         if (invalid)
             throw new Error(`job create does not accept task execution option ${invalid}; create the job first, then let the orchestrator create the initial plan/task batch`);

package/dist/dashboard.js

@@ -95,7 +95,7 @@ export const dashboardHtml = `<!doctype html>
     .job-meta span { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
     .status-pill,.badge { display:inline-flex; align-items:center; border-radius:999px; padding:.06rem .42rem; min-height:1.35rem; font-size:.68rem; font-weight:800; }
     .status-pill.ok,.badge.RUNNING,.badge.SUCCEEDED,.badge.COMPLETED { background:#e5f3e9; color:var(--ok); }
-    .status-pill.warn,.badge.BLOCKED,.badge.WAITING,.badge.QUEUED,.badge.READY,.badge.OPEN { background:#fff1d2; color:var(--warn); }
+    .status-pill.warn,.badge.BLOCKED,.badge.DRAFT,.badge.QUEUED,.badge.WAITING,.badge.OPEN { background:#fff1d2; color:var(--warn); }
     .status-pill.bad,.badge.FAILED { background:#ffe8e8; color:var(--bad); }
     .status-pill.neutral,.badge.CANCELLED { background:#edf0f4; color:var(--muted); }
     .badge.DRAFT { background:#eef2ff; color:#3f51b5; }
@@ -220,7 +220,7 @@ function markdownField(label,input){const box=element('div','detail-group');box.
 function rememberSelection(){if(selectedJob)sessionStorage.setItem('agents-relay:selected-job',selectedJob);else sessionStorage.removeItem('agents-relay:selected-job');if(selectedTaskId)sessionStorage.setItem('agents-relay:selected-task',selectedTaskId);else sessionStorage.removeItem('agents-relay:selected-task');}
 function selected(){return jobs.find(job=>job.id===selectedJob)||jobs[0]||null;}
 function counts(tasks){const out={};for(const task of Array.isArray(tasks)?tasks:[])out[task.state]=(out[task.state]||0)+1;return out;}
-function compactCounts(input){const order=['RUNNING','BLOCKED','FAILED','QUEUED','READY','WAITING','SUCCEEDED','CANCELLED'];return order.filter(state=>input[state]).map(state=>input[state]+' '+state).join(', ')||'No tasks';}
+function compactCounts(input){const order=['RUNNING','BLOCKED','FAILED','QUEUED','DRAFT','SUCCEEDED','CANCELLED'];return order.filter(state=>input[state]).map(state=>input[state]+' '+state).join(', ')||'No tasks';}
 function awaitingInitialTask(job){return job?.state==='OPEN'&&Array.isArray(job?.tasks)&&job.tasks.length===0;}
 function relativeTime(timestamp){if(!timestamp)return '—';const parsed=Date.parse(timestamp);if(!Number.isFinite(parsed))return value(timestamp);const seconds=Math.max(0,Math.round((Date.now()-parsed)/1000));if(seconds<60)return 'just now';if(seconds<3600)return Math.floor(seconds/60)+'m ago';if(seconds<86400)return Math.floor(seconds/3600)+'h ago';return Math.floor(seconds/86400)+'d ago';}
 function safePrUrl(repository,prNumber){if(typeof repository!=='string'||!Number.isInteger(prNumber)||prNumber<=0)return null;const parts=repository.split('/');if(parts.length!==2)return null;const [owner,repo]=parts;if(!owner||!repo||owner==='.'||owner==='..'||repo==='.'||repo==='..')return null;if(!/^[A-Za-z0-9-]+$/.test(owner)||!/^[A-Za-z0-9._-]+$/.test(repo))return null;return 'https://github.com/'+owner+'/'+repo+'/pull/'+prNumber;}

package/dist/pool.js

@@ -7,7 +7,7 @@ export function needsLifecycleReconciliation(job, now = Date.now()) {
     // Create-only Jobs stay OPEN until a caller explicitly creates work.
     if (job.tasks.length === 0)
         return false;
-    if (job.tasks.some(task => ['READY', 'QUEUED', 'WAITING'].includes(task.state)))
+    if (job.tasks.some(task => task.state === 'QUEUED' || (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);
 }
@@ -48,7 +48,7 @@ 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 => ['READY', 'QUEUED', 'WAITING'].includes(task.state)).length;
+            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());
             if (!needsLifecycleReconciliation(job))
                 continue;

package/dist/reconciler.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { storySizeTimeoutMs, taskOverallTimeoutMs, chatGptStartAckTimeoutMs } from './types.js';
-import { schedule, transitionTask } from './scheduler.js';
+import { dependencyReady, schedule, transitionTask } from './scheduler.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
 import { parsePlannerResult, plannerInput } from './planner.js';
@@ -160,7 +160,7 @@ 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 === 'READY').sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2')).slice(0, capacity)) {
+                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)) {
                     if (task.kind === 'planner')
                         await this.launchPlanner(scheduled, task);
                     else if (task.adapter === 'orchestrator') {
@@ -199,7 +199,7 @@ export class Reconciler {
             return;
         job.review = { ...job.review, outcome: 'stale', updatedAt: new Date().toISOString() };
         const staleTask = job.review.taskId ? job.tasks.find(task => task.id === job.review?.taskId) : undefined;
-        if (staleTask && ['QUEUED', 'READY', 'RUNNING', 'WAITING'].includes(staleTask.state)) {
+        if (staleTask && ['DRAFT', 'QUEUED', 'RUNNING'].includes(staleTask.state)) {
             this.live.get(staleTask.id)?.execution.cancel();
             transitionTask(staleTask, 'CANCELLED');
             staleTask.error = 'Review evidence became stale after the PR head changed';
@@ -218,7 +218,7 @@ export class Reconciler {
         if (review?.headSha === headSha && ['started', 'approved', 'changes_required', 'blocked'].includes(review.outcome))
             return;
         const reviewTasks = job.tasks.filter(task => task.agentName === 'reviewer' && task.reviewHeadSha === headSha);
-        if (reviewTasks.some(task => ['QUEUED', 'READY', 'RUNNING', 'WAITING'].includes(task.state)))
+        if (reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
             return;
         if (reviewTasks.some(task => task.state === 'SUCCEEDED' && review?.headSha === headSha && review.outcome === 'approved'))
             return;
@@ -235,7 +235,7 @@ export class Reconciler {
         await this.emit(eventFor(job.id, id, null, 'review.created', 'queued', `Final review task ${id} created for ${headSha} using ${reviewerRouting.reason}`, 'orchestrator', { headSha, agentName: 'reviewer', reviewerRouting: { workerId: reviewerRouting.selection.workerId, reason: reviewerRouting.reason, selectedBy: reviewerRouting.selection.selectedBy } }));
         const ready = schedule(await this.store.load(job.id));
         await this.store.saveJob(ready);
-        const reviewTask = ready.tasks.find(item => item.id === id && item.state === 'READY');
+        const reviewTask = ready.tasks.find(item => item.id === id && item.state === 'QUEUED');
         if (reviewTask && (this.options.maxConcurrent ?? 4) > this.live.size + this.plannerLive.size)
             await this.launch(ready, reviewTask);
     }
@@ -270,7 +270,7 @@ export class Reconciler {
     async routeExecutableTasks(job) {
         const usage = this.options.usageSnapshotProvider ? await this.options.usageSnapshotProvider() : undefined;
         const candidates = workerCandidates(this.options.adapters, await this.store.listAgents(), usage);
-        for (const task of job.tasks.filter(item => item.kind !== 'planner' && item.agentName !== 'reviewer' && item.adapter !== 'orchestrator' && ['QUEUED', 'READY', 'BLOCKED'].includes(item.state) && item.output && !item.workerSelection && (item.workerRequirements || item.planningSource === 'model-planner'))) {
+        for (const task of job.tasks.filter(item => item.kind !== 'planner' && item.agentName !== 'reviewer' && item.adapter !== 'orchestrator' && ['QUEUED', 'BLOCKED'].includes(item.state) && item.output && !item.workerSelection && (item.workerRequirements || item.planningSource === 'model-planner'))) {
             const requirements = task.workerRequirements ?? { capabilities: task.capabilities.length > 0 ? task.capabilities : ['model'] };
             const routed = selectWorker(candidates, requirements);
             task.workerSelection = routed.selection;
@@ -365,7 +365,7 @@ export class Reconciler {
                 this.plannerLive.delete(task.id);
             }
             if (task.attempt < task.maxAttempts) {
-                transitionTask(task, 'READY');
+                transitionTask(task, 'QUEUED');
                 task.leaseOwner = null;
                 task.leaseExpiresAt = null;
                 await this.store.saveTask(task);
@@ -391,7 +391,7 @@ export class Reconciler {
         const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
         const scopedTasks = Number.isFinite(slot) ? job.tasks.filter(task => Date.parse(task.createdAt) >= slot) : job.tasks;
         const planners = scopedTasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
-        if (planners.some(task => ['QUEUED', 'READY', 'RUNNING', 'WAITING'].includes(task.state)))
+        if (planners.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
             return job;
         if (scopedTasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
             return job;
@@ -598,7 +598,7 @@ export class Reconciler {
             task.error = error.message;
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
-            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+            transitionTask(task, task.attempt < task.maxAttempts ? 'QUEUED' : 'FAILED');
             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');
@@ -636,7 +636,7 @@ export class Reconciler {
                 task.error = message;
                 task.leaseOwner = null;
                 task.leaseExpiresAt = null;
-                transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+                transitionTask(task, task.attempt < task.maxAttempts ? 'QUEUED' : 'FAILED');
                 await this.store.saveTask(task);
                 await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${message}`, 'user'));
             }
@@ -645,7 +645,7 @@ export class Reconciler {
     }
     plannerChild(job, planner, spec) {
         const now = new Date().toISOString();
-        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: (spec.dependencies?.length ?? 0) > 0 ? 'DRAFT' : 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
     }
     clearExecution(taskId, executionId) {
         const live = this.live.get(taskId);

package/dist/scheduled-jobs.js

@@ -147,7 +147,7 @@ export async function runScheduledBucket(client, repository, trustedAuthors, ref
         await syncScheduleLabels(client, repository, job);
         return { job, status: 'skipped-idempotent' };
     }
-    const active = job.state === 'RUNNING' || job.tasks.some(task => ['READY', 'RUNNING'].includes(task.state));
+    const active = job.state === 'RUNNING' || job.tasks.some(task => ['QUEUED', 'RUNNING'].includes(task.state));
     if (active && schedule.concurrencyPolicy === 'skip') {
         schedule.lastScheduledSlot = slot.toISOString();
         schedule.nextRunAt = nextScheduleRun(schedule, now).toISOString();

package/dist/scheduler.js

@@ -32,12 +32,17 @@ export function schedule(job) {
     }
     const map = new Map(job.tasks.map(t => [t.id, t]));
     for (const task of scopedTasks) {
-        if (['QUEUED', 'WAITING'].includes(task.state) && dependencyReady(task, map))
-            transitionTask(task, 'READY');
+        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 active = scopedTasks.some(t => ['READY', 'RUNNING'].includes(t.state));
+    const active = scopedTasks.some(t => ['QUEUED', 'RUNNING'].includes(t.state));
     const blocked = scopedTasks.some(t => t.state === 'BLOCKED');
-    const waiting = scopedTasks.some(t => ['QUEUED', 'WAITING'].includes(t.state));
+    const waiting = scopedTasks.some(t => t.state === 'DRAFT');
     const failed = scopedTasks.some(t => t.state === 'FAILED');
     const cancelled = scopedTasks.every(t => t.state === 'CANCELLED');
     const next = active ? 'RUNNING' : failed ? 'FAILED' : blocked ? 'BLOCKED' : waiting ? 'WAITING' : cancelled ? 'CANCELLED' : completionGateSatisfied(job) ? 'COMPLETED' : 'WAITING';
@@ -65,7 +70,7 @@ 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 (['READY', 'RUNNING', 'SUCCEEDED'].includes(state))
+export function transitionTask(task, state) { assertTaskTransition(task.state, state); task.state = state; if (['QUEUED', 'RUNNING', 'SUCCEEDED'].includes(state))
     task.error = null; task.updatedAt = new Date().toISOString(); }
 export const SCHEDULE_RESOLUTION_MS = 600_000;
 export const RUN_BUCKET_LABEL_COUNT = 144;

package/dist/types.js

@@ -3,7 +3,7 @@ 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 jobTransitions = { OPEN: ['RUNNING', 'WAITING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], RUNNING: ['OPEN', 'WAITING', 'BLOCKED', 'COMPLETED', 'FAILED', 'CANCELLED'], WAITING: ['RUNNING', 'BLOCKED', 'COMPLETED', 'CANCELLED'], BLOCKED: ['RUNNING', 'COMPLETED', 'CANCELLED'], COMPLETED: ['RUNNING', 'CANCELLED'], FAILED: ['RUNNING', 'COMPLETED', 'CANCELLED'], CANCELLED: ['RUNNING', 'COMPLETED'] };
-const taskTransitions = { QUEUED: ['READY', 'BLOCKED', 'CANCELLED'], READY: ['RUNNING', 'BLOCKED', 'FAILED', 'CANCELLED'], RUNNING: ['WAITING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED', 'READY'], WAITING: ['READY', 'BLOCKED', 'CANCELLED'], BLOCKED: ['READY', 'CANCELLED'], SUCCEEDED: [], FAILED: ['READY', 'RUNNING', 'CANCELLED'], CANCELLED: [] };
+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 assertJobTransition(from, to) { if (from !== to && !jobTransitions[from].includes(to))
     throw new Error(`Invalid job transition ${from} -> ${to}`); }
 export function assertTaskTransition(from, to) { if (from !== to && !taskTransitions[from].includes(to))

package/package.json

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

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

@@ -30,6 +30,18 @@ Relay derives the overall execution timeout from `storySize`. If `routing.reason
 
 Raw `timeoutMs` is a compatibility/debug/hotfix override, not the normal task-production interface.
 
+## Task readiness states
+
+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`.
+- `QUEUED`: executable now; Relay may launch it immediately subject only to worker capacity/routing.
+- `RUNNING`: worker execution has actually started.
+- `BLOCKED`: execution cannot continue without an external resolution or intervention. Once a Task has entered `RUNNING`, it must not return to `DRAFT`; waiting discovered during execution is `BLOCKED`.
+- `SUCCEEDED`, `FAILED`, and `CANCELLED` are terminal outcomes, except that retry explicitly requeues a failed/blocked Task.
+
+Do not use `WAITING` as a Task state. `WAITING` remains a Job state for an active Job that is intentionally awaiting a future trigger, schedule slot, or condition.
+
 ## Worker lifecycle
 
 Relay owns process lifecycle. Workers own semantic task lifecycle. A worker must publish canonical `task.started` as its first execution action, then exactly one of `task.completed`, `task.failed`, `task.blocked`, or `task.cancelled`. Process launch/exit events do not substitute for worker semantic events.