agents-relay 1.0.155 → 1.0.157

package/dist/cli-help.js

@@ -46,7 +46,7 @@ Example:
 
 Required: --repo OWNER/REPO, --id JOB_ID, and either --head BRANCH or --pr NUMBER.
 With --head, reuse/create the PR for that head. With --pr, bind an existing unmanaged PR.
-Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --no-auto-merge, --no-review. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
+Common: --base BRANCH (default: main), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --mode fixed|autonomous, --no-auto-merge, --no-review, --task-fields JSON. --objective and --objective-file are mutually exclusive. For a new --head Job, one is required and must contain enough standalone context to complete the Job without the originating chat/thread. Objective Markdown is also the default PR body; --body is an explicit override.
 Job creation never creates executable tasks. The orchestrator decides the initial task batch separately. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
 
 Example:
@@ -54,7 +54,7 @@ Example:
     'job update': `Partially update mutable metadata on a healthy existing Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
-Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --mode fixed|autonomous, --schedule, --auto-merge|--no-auto-merge, --review|--no-review, and continuation options. Updating the objective also updates the PR body.
+Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --mode fixed|autonomous, --schedule, --task-fields JSON, --auto-merge|--no-auto-merge, --review|--no-review, and continuation options. Updating the objective also updates the PR body.
 Unspecified fields are preserved. Marker/binding corruption is never repaired implicitly; update fails with a precise diagnostic instead.
 
 Example:

package/dist/cli-support.js

@@ -3,6 +3,7 @@ import { InMemoryStore, GitHubStore } from './store.js';
 import { githubAuthContext } from './github-auth.js';
 import { NatsEventBus, eventFor } from './events.js';
 import { parseJobSchedule } from './scheduler.js';
+import { parseJobTaskFieldsJson } from './task-fields.js';
 export const SERVICE_DEFAULTS = { port: 8787, watchdogMs: 300000, webhookWatchdogMs: 300000, dashboardRefreshMs: 300000 };
 export class ServiceEventBus {
     upstream;
@@ -97,6 +98,7 @@ export function chatGptTabClosePolicy(args) {
     return value;
 }
 export function requestedExecutionMode(args) { const value = arg(args, '--mode', arg(args, '--execution-mode')); return value ? executionMode(args) : undefined; }
+export function taskFieldsFromArgs(args) { return parseJobTaskFieldsJson(arg(args, '--task-fields')); }
 export function continuation(args) { const kind = arg(args, '--continue-kind'); const target = arg(args, '--continue-target'); return kind && target ? { kind: kind, target, input: arg(args, '--continue-input') || undefined } : null; }
 export function scheduleFromArgs(args) {
     const cron = arg(args, '--schedule');

package/dist/cli.js

@@ -25,7 +25,7 @@ import { runBlockerCommand } from './cli-blocker.js';
 import { helpText, usage } from './cli-help.js';
 import { parseAgentGraph } from './agent-graph.js';
 export { helpText } from './cli-help.js';
-import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, requestManagedReconciliation, } from './cli-support.js';
+import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, taskFieldsFromArgs, requestManagedReconciliation, } from './cli-support.js';
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
 export async function ensureManagedGitHubJob(client, repositoryName, trustedAuthors, options) {
     if (!options.id)
@@ -51,6 +51,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         description: pr.body || undefined,
         priority: options.priority ?? 'P2',
         executionMode: options.executionMode ?? 'fixed',
+        taskFields: options.taskFields,
         autoMerge: options.autoMerge ?? true,
         reviewEnabled: options.reviewEnabled ?? true,
         prNumber: pr.number,
@@ -342,6 +343,7 @@ async function runJobCommand(action, args) {
             priority: priority(args),
             executionMode: requestedExecutionMode(args),
             schedule: scheduleFromArgs(args),
+            taskFields: taskFieldsFromArgs(args),
             autoMerge: !hasArg(args, '--no-auto-merge'),
             reviewEnabled: !hasArg(args, '--no-review'),
             continuation: continuation(args),
@@ -406,6 +408,8 @@ async function runJobCommand(action, args) {
         job.executionMode = executionMode(args, job.executionMode ?? 'fixed');
     if (hasArg(args, '--schedule'))
         job.schedule = scheduleFromArgs(args);
+    if (hasArg(args, '--task-fields'))
+        job.taskFields = taskFieldsFromArgs(args);
     if (hasArg(args, '--auto-merge') && hasArg(args, '--no-auto-merge'))
         throw new Error('choose only one of --auto-merge or --no-auto-merge');
     if (hasArg(args, '--auto-merge'))

package/dist/dashboard-html.js

@@ -320,8 +320,9 @@ function syncFilters(){
 }
 function repoName(repository){if(typeof repository!=='string'||!repository)return 'unknown-repo';const parts=repository.split('/').filter(Boolean);return parts.at(-1)||repository;}
 function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();if(!jobs.length){jobList.append(element('li','empty',text('No durable jobs discovered.')));return;}if(!visible.length){jobList.append(element('li','empty',text('No jobs match the selected repo.')));return;}for(const job of visible){const row=element('div','job-row'+(isCompleteUnmerged(job)?' complete-unmerged':''));row.setAttribute('aria-current',String(job.id===selectedJob));row.addEventListener('click',()=>selectJob(job.id));const content=element('div','job-content');const select=document.createElement('button');select.type='button';select.className='job-button';select.setAttribute('aria-current',String(job.id===selectedJob));select.title=job.title||job.id;select.addEventListener('click',event=>{event.stopPropagation();selectJob(job.id);});select.append(element('span','job-title',text(repoName(job.repository)+'/PR#'+value(job.prNumber)+': '+value(job.title||job.id))));const states=element('span','job-status-line');states.append(element('span','badge '+value(job.state),text(value(job.state))),element('span','badge '+value(job.runtimeStatus||'IDLE'),text(value(job.runtimeStatus||'IDLE'))));if(job.executionMode==='autonomous')states.append(element('span','badge flag-autonomous',text('AUTONOMOUS')));if(job.reviewEnabled!==false&&job.githubState!=='MERGED')states.append(element('span','badge flag-review',text('REVIEW REQUIRED')));if(job.githubState==='MERGED'&&job.publication?.version)states.append(element('span','badge SUCCEEDED',text('v'+job.publication.version)));if(isCompleteUnmerged(job))states.append(element('span','badge MERGE_PENDING',text('MERGE PENDING')));const primary=element('div','job-primary');primary.append(states);const lastLine=element('div','job-last-line');lastLine.append(element('span','subtle',text(compactCounts(counts(job.tasks)))),element('span','subtle',text(relativeTime(job.updatedAt))));content.append(select,primary,lastLine);row.append(content);jobList.append(element('li','',row));}}
-function taskNode(task,children,depth){const li=element('li');const nested=children.get(task.id)||[];const line=element('div','task-line');if(nested.length){const key=(selectedJob||'')+':'+task.id;const collapsed=collapsedTasks.has(key);const fold=document.createElement('button');fold.type='button';fold.className='task-fold';fold.setAttribute('aria-expanded',String(!collapsed));fold.setAttribute('aria-label',(collapsed?'Expand ':'Collapse ')+task.id);fold.textContent=collapsed?'▸':'▾';line.append(fold);const ul=element('ul','tree');ul.hidden=collapsed;for(const child of nested)ul.append(taskNode(child,children,depth+1));fold.addEventListener('click',()=>{const next=!ul.hidden;ul.hidden=next;fold.setAttribute('aria-expanded',String(!next));fold.setAttribute('aria-label',(next?'Expand ':'Collapse ')+task.id);fold.textContent=next?'▸':'▾';if(next)collapsedTasks.add(key);else collapsedTasks.delete(key);});li.append(line,ul);}else li.append(line);const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{const deselect=selectedTaskId===task.id;selectedTaskId=deselect?null:task.id;eventTaskId=deselect?null:task.id;rememberSelection();clearEvents();renderAll();void loadEventHistory();});const id=element('span','task-id',text(task.id));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));line.append(row);return li;}
-function buildTree(tasks){taskTree.replaceChildren();if(!Array.isArray(tasks)||!tasks.length){taskTree.append(element('li','empty',text('No tasks in durable state.')));return;}const known=new Set(tasks.map(task=>task.id));const children=new Map();const roots=[];for(const task of tasks){if(!task.parentTaskId||!known.has(task.parentTaskId))roots.push(task);else{const siblings=children.get(task.parentTaskId)||[];siblings.push(task);children.set(task.parentTaskId,siblings);}}for(const task of roots)taskTree.append(taskNode(task,children,0));}
+function taskFieldDisplays(job,task){const out=[];for(const [name,value] of Object.entries(task.fields||{})){const def=job?.taskFields?.[name];const display=def?.values?.[value];if(typeof display==='string'&&display)out.push({name,label:def.label||name,value,display});}return out;}
+function taskNode(task,children,depth){const li=element('li');const nested=children.get(task.id)||[];const line=element('div','task-line');if(nested.length){const key=(selectedJob||'')+':'+task.id;const collapsed=collapsedTasks.has(key);const fold=document.createElement('button');fold.type='button';fold.className='task-fold';fold.setAttribute('aria-expanded',String(!collapsed));fold.setAttribute('aria-label',(collapsed?'Expand ':'Collapse ')+task.id);fold.textContent=collapsed?'▸':'▾';line.append(fold);const ul=element('ul','tree');ul.hidden=collapsed;for(const child of nested)ul.append(taskNode(child,children,depth+1));fold.addEventListener('click',()=>{const next=!ul.hidden;ul.hidden=next;fold.setAttribute('aria-expanded',String(!next));fold.setAttribute('aria-label',(next?'Expand ':'Collapse ')+task.id);fold.textContent=next?'▸':'▾';if(next)collapsedTasks.add(key);else collapsedTasks.delete(key);});li.append(line,ul);}else li.append(line);const row=document.createElement('button');row.type='button';row.className='task-row';row.setAttribute('aria-current',String(task.id===selectedTaskId));row.title=task.id;row.addEventListener('click',()=>{const deselect=selectedTaskId===task.id;selectedTaskId=deselect?null:task.id;eventTaskId=deselect?null:task.id;rememberSelection();clearEvents();renderAll();void loadEventHistory();});const id=element('span','task-id',text(task.id));id.style.paddingLeft=Math.min(depth,4)*6+'px';row.append(id,element('span','badge '+value(task.state),text(task.state)));for(const field of taskFieldDisplays(selected(),task)){const badge=element('span','task-field',text(field.display));badge.title=field.label+': '+field.value;row.append(badge);}line.append(row);return li;}
+function buildTree(tasks){taskTree.replaceChildren();if(!Array.isArray(tasks)||!tasks.length){taskTree.append(element('li','empty',text('No tasks in durable state.')));return;}const work=tasks.filter(task=>task.kind!=='planner');if(!work.length){taskTree.append(element('li','empty',text('No work tasks in durable state.')));return;}const known=new Set(work.map(task=>task.id));const children=new Map();const roots=[];for(const task of work){if(!task.parentTaskId||!known.has(task.parentTaskId))roots.push(task);else{const siblings=children.get(task.parentTaskId)||[];siblings.push(task);children.set(task.parentTaskId,siblings);}}for(const task of roots)taskTree.append(taskNode(task,children,0));}
 function attemptBudget(task){const attempt=Number(task?.attempt)||0;const max=Number(task?.maxAttempts)||0;if(max>=3&&max%3===0){const effectiveMax=Math.max(max,Math.ceil(attempt/3)*3);return attempt+' / 3×'+(effectiveMax/3);}return attempt+' / '+max;}
 const TASK_STATES=['DRAFT','QUEUED','RUNNING','BLOCKED','SUCCEEDED','FAILED','CANCELLED'];
 async function setTaskState(task,state,select){const job=selected();if(!job||state===task.state)return;select.disabled=true;try{const response=await fetch('/api/task-state?id='+encodeURIComponent(job.id)+'&task='+encodeURIComponent(task.id)+'&state='+encodeURIComponent(state),{method:'POST'});if(!response.ok)throw new Error(response.status+' '+response.statusText);const updated=await response.json();const index=jobs.findIndex(candidate=>candidate.id===job.id);if(index>=0)jobs[index]=updated;else jobs.push(updated);renderAll();void loadEventHistory();}catch(error){select.title='Set task state: '+error.message;select.value=task.state;}finally{select.disabled=false;}}

package/dist/planner-child.js

@@ -1,3 +1,3 @@
 export function samePlannerChildDefinition(left, right) {
-    return JSON.stringify({ id: left.id, input: left.input, output: left.output, review: left.review ?? null, priority: left.priority, storySize: left.storySize ?? 'M', projectName: left.projectName, agentName: left.agentName, agentGraph: left.agentGraph, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, output: right.output, review: right.review ?? null, priority: right.priority, storySize: right.storySize ?? 'M', projectName: right.projectName, agentName: right.agentName, agentGraph: right.agentGraph, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
+    return JSON.stringify({ id: left.id, parentTaskId: left.parentTaskId, input: left.input, output: left.output, review: left.review ?? null, priority: left.priority, storySize: left.storySize ?? 'M', projectName: left.projectName, agentName: left.agentName, agentGraph: left.agentGraph, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, parentTaskId: right.parentTaskId, input: right.input, output: right.output, review: right.review ?? null, priority: right.priority, storySize: right.storySize ?? 'M', projectName: right.projectName, agentName: right.agentName, agentGraph: right.agentGraph, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
 }

package/dist/planner.js

@@ -34,11 +34,11 @@ export function createPlannerRoundTask(job, options = {}) {
     };
     return {
         jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner',
-        parentTaskId: previousPlanner?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator',
+        parentTaskId: null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator',
         input: plannerInput(context), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0,
         maxAttempts: options.manual ? 1 : 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null,
         result: null, plannerResult: null, error: null, timeoutMs: options.timeoutMs ?? storySizeTimeoutMs('M'),
-        createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: round,
+        createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: round, previousPlannerTaskId: previousPlanner?.id ?? null,
         plannerGuidance: options.guidance, manualPlanning: options.manual === true,
     };
 }
@@ -47,7 +47,7 @@ export function planningSpec(task) {
         throw new Error(`Initial task ${task.id} requires an output contract`);
     if (!['codex', 'chatgpt', 'orchestrator'].includes(task.adapter))
         throw new Error(`Initial task ${task.id} requires a supported adapter`);
-    return { id: task.id, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph, review: task.review, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
+    return { id: task.id, parentTaskId: task.parentTaskId, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph, review: task.review, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
 }
 function record(value, field = 'result') {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -189,6 +189,7 @@ export function parsePlannerResult(value) {
         ids.add(id);
         if (typeof task.input !== 'string' || task.input.length === 0)
             throw new Error(`Planner next_tasks[${index}].input is required`);
+        const parentTaskId = task.parentTaskId === undefined || task.parentTaskId === null ? task.parentTaskId : optionalString(task.parentTaskId, `next_tasks[${index}].parentTaskId`);
         const adapter = task.adapter;
         if (adapter !== undefined && !['codex', 'chatgpt'].includes(String(adapter)))
             throw new Error(`Planner next_tasks[${index}].adapter must be codex or chatgpt when provided`);
@@ -221,7 +222,7 @@ export function parsePlannerResult(value) {
         if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs < 0)
             throw new Error(`Planner next_tasks[${index}].timeoutMs is invalid`);
         return {
-            id, input: task.input, priority, storySize,
+            id, parentTaskId, input: task.input, priority, storySize,
             projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'), agentGraph, review,
             dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'), workerRequirements: requirements,
             adapter: adapter, output: output, routing: route,
@@ -230,6 +231,32 @@ export function parsePlannerResult(value) {
     });
     return { objective_status: status, assessment: root.assessment, next_tasks, unblocks };
 }
+export function validatePlannerHierarchy(existing, specs) {
+    const existingById = new Map(existing.map(task => [task.id, task]));
+    const specsById = new Map(specs.map(spec => [spec.id, spec]));
+    for (const spec of specs) {
+        const parent = spec.parentTaskId;
+        if (!parent)
+            continue;
+        if (parent === spec.id)
+            throw new Error(`Planner next task ${spec.id} cannot parent itself`);
+        const existingParent = existingById.get(parent);
+        if (existingParent?.kind === 'planner')
+            throw new Error(`Planner next task ${spec.id} cannot use planner round ${parent} as parentTaskId`);
+        if (!existingParent && !specsById.has(parent))
+            throw new Error(`Planner next task ${spec.id} references unknown parentTaskId ${parent}`);
+    }
+    for (const spec of specs) {
+        const seen = new Set([spec.id]);
+        let parent = spec.parentTaskId ?? null;
+        while (parent && specsById.has(parent)) {
+            if (seen.has(parent))
+                throw new Error(`Planner next_tasks parentTaskId cycle includes ${parent}`);
+            seen.add(parent);
+            parent = specsById.get(parent)?.parentTaskId ?? null;
+        }
+    }
+}
 export function parsePlannerOutput(output) {
     const trimmed = output.trim();
     const candidate = trimmed.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '').trim();

package/dist/reconciler-runtime.js

@@ -5,6 +5,7 @@ import { eventFor } from './events.js';
 import { WorkflowEffectExecutor } from './workflow/effects.js';
 import { workflowEffectFailureEvent } from './workflow/contracts.js';
 import { ReconcileCoordinator } from './reconcile-coordinator.js';
+import { acceptedReportedTaskFields, eventDataWithoutTaskFields } from './task-fields.js';
 export function executionEventSource(jobId, taskId, executionId) { return `job/${jobId}/task/${taskId}/execution/${executionId}`; }
 function eventSourceId(event) { return typeof event.source?.id === 'string' ? event.source.id : undefined; }
 const terminalExecutionClaims = new Set();
@@ -338,8 +339,11 @@ export class ReconcilerRuntimeBase {
                 task.updatedAt = event.timestamp || new Date().toISOString();
                 this.terminalWaiters.get(task.id)?.resolve();
                 this.terminalWaiters.delete(task.id);
+                const reportedFields = acceptedReportedTaskFields(job, event.data);
+                if (reportedFields)
+                    task.fields = { ...(task.fields ?? {}), ...reportedFields };
                 if (event.type === 'task.completed') {
-                    task.result = { summary: event.message || `Task ${task.id} completed`, data: event.data };
+                    task.result = { summary: event.message || `Task ${task.id} completed`, data: eventDataWithoutTaskFields(event.data) };
                     task.error = null;
                     task.failureReason = undefined;
                 }

package/dist/reconciler.js

@@ -4,7 +4,7 @@ import { dependencyReady, schedule, transitionJobEvent, transitionTaskEvent } fr
 import { implementationComplete } from './runtime-status.js';
 import { LaunchFailure, StartAckTimeout } from './adapters.js';
 import { eventFor } from './events.js';
-import { createPlannerRoundTask, parsePlannerResult, plannerInput } from './planner.js';
+import { createPlannerRoundTask, parsePlannerResult, plannerInput, validatePlannerHierarchy } from './planner.js';
 import { agentContractPrompt, executionContextPrompt, resolveExecutionContext } from './execution-context.js';
 import { agentGraphPrompt, validateAgentSelection } from './agent-graph.js';
 import { ReconcilerReviewBase } from './reconciler-review.js';
@@ -17,6 +17,7 @@ import { pendingTroubleshooterTasks } from './troubleshooter.js';
 import { prepareManagedExecutionWorktree } from './workspace.js';
 import { createReviewChairExecutionPlan } from './review-chair.js';
 import { samePlannerChildDefinition } from './planner-child.js';
+import { taskFieldsWorkerPrompt } from './task-fields.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) {
@@ -37,6 +38,7 @@ export async function managedWorkerInput(job, task, context) {
     const output = task.output.kind === 'file'
         ? `file\nPath: ${task.output.path}`
         : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`;
+    const taskFields = taskFieldsWorkerPrompt(job);
     return `[Agents Relay managed task]
 Job URL: ${prUrl}
 Job ID: ${job.id}
@@ -51,7 +53,7 @@ ${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? sele
 [Output contract]
 ${output}
 
-[Execution event contract — mandatory]
+${taskFields}[Execution event contract — mandatory]
 Use the canonical Neo events-bus with exactly Job ${job.id} and Task ${task.id}.
 Your exact event source identity is: ${sourceId}
 Every lifecycle event for this execution MUST set source.id to that exact string. Do not derive, rename, or replace it.
@@ -455,7 +457,7 @@ export class Reconciler extends ReconcilerReviewBase {
         let promise;
         try {
             const executionContext = await this.plannerContext(job, task);
-            const context = { job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.parentTaskId, executionContext, retryFeedback: task.plannerRetryFeedback, guidance: task.plannerGuidance };
+            const context = { job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: task.previousPlannerTaskId ?? null, executionContext, retryFeedback: task.plannerRetryFeedback, guidance: task.plannerGuidance };
             task.input = plannerInput(context);
             await this.store.saveTask(task);
             promise = planner.plan(context, controller.signal);
@@ -495,6 +497,7 @@ export class Reconciler extends ReconcilerReviewBase {
         try {
             const result = parsePlannerResult(raw);
             const executionContext = await this.plannerContext(job, task);
+            validatePlannerHierarchy(job.tasks, result.next_tasks);
             if (result.unblocks.length > 0 && !this.store.registerBlockerDependent)
                 throw new Error('Durable store does not support Planner cross-Job unblock registration');
             for (const unblock of result.unblocks)
@@ -546,6 +549,6 @@ export class Reconciler extends ReconcilerReviewBase {
     plannerChild(job, planner, spec, executionContext) {
         validateAgentSelection(executionContext, spec.agentName, spec.agentGraph);
         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, agentGraph: spec.agentGraph, review: spec.review, 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 };
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, agentGraph: spec.agentGraph, review: spec.review, parentTaskId: spec.parentTaskId ?? null, 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 };
     }
 }

package/dist/task-fields.js

@@ -0,0 +1,68 @@
+const FIELD_NAME = /^[A-Za-z0-9_.-]+$/;
+export function parseJobTaskFields(value, option = '--task-fields') {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${option} must be a JSON object`);
+    const out = {};
+    for (const [name, rawDefinition] of Object.entries(value)) {
+        if (!FIELD_NAME.test(name) || name.length > 64)
+            throw new Error(`${option} contains invalid field name ${name}`);
+        if (!rawDefinition || typeof rawDefinition !== 'object' || Array.isArray(rawDefinition))
+            throw new Error(`${option}.${name} must be an object`);
+        const definition = rawDefinition;
+        const label = definition.label;
+        if (label !== undefined && (typeof label !== 'string' || !label.trim() || label.length > 64))
+            throw new Error(`${option}.${name}.label must be a non-empty string up to 64 characters`);
+        const rawValues = definition.values;
+        if (!rawValues || typeof rawValues !== 'object' || Array.isArray(rawValues) || Object.keys(rawValues).length === 0)
+            throw new Error(`${option}.${name}.values must be a non-empty object`);
+        const values = {};
+        for (const [fieldValue, display] of Object.entries(rawValues)) {
+            if (!FIELD_NAME.test(fieldValue) || fieldValue.length > 64)
+                throw new Error(`${option}.${name}.values contains invalid value ${fieldValue}`);
+            if (typeof display !== 'string' || !display || display.length > 32)
+                throw new Error(`${option}.${name}.values.${fieldValue} must be a non-empty string up to 32 characters`);
+            values[fieldValue] = display;
+        }
+        out[name] = { ...(typeof label === 'string' ? { label } : {}), values };
+    }
+    return out;
+}
+export function parseJobTaskFieldsJson(raw) {
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--task-fields must be valid JSON');
+    }
+    return parseJobTaskFields(parsed);
+}
+export function acceptedReportedTaskFields(job, data) {
+    const raw = data?.taskFields;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !job.taskFields)
+        return undefined;
+    const accepted = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (typeof value !== 'string')
+            continue;
+        const definition = job.taskFields[name];
+        if (definition?.values[value] !== undefined)
+            accepted[name] = value;
+    }
+    return Object.keys(accepted).length ? accepted : undefined;
+}
+export function eventDataWithoutTaskFields(data) {
+    if (!data || !Object.prototype.hasOwnProperty.call(data, 'taskFields'))
+        return data;
+    const { taskFields: _taskFields, ...rest } = data;
+    return Object.keys(rest).length ? rest : undefined;
+}
+export function taskFieldsWorkerPrompt(job) {
+    if (!job.taskFields || Object.keys(job.taskFields).length === 0)
+        return '';
+    return `[Job-defined Task fields]\nThe Job defines these Task result fields: ${JSON.stringify(job.taskFields)}\nWhen a field applies to this execution, report its exact allowed value in the terminal event under data.taskFields. Example: data: { taskFields: { e2e: \"pass\" } }. These fields are separate from Task lifecycle state.\n\n`;
+}

package/package.json

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

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

@@ -6,7 +6,7 @@ Before producing tasks, read and follow `../contracts/task-job-contract.md`.
 
 You are a pure planning agent. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. You return one structured planning result. You do not call the Agents Relay CLI, persist state, create Jobs, or mutate Tasks yourself.
 
-Relay persists each successful planner invocation as one planner round and creates the returned Tasks under that round.
+Relay persists each successful planner invocation as one planner-history round. Returned work Tasks are not automatically children of that round; use `parentTaskId` only when the business Task graph needs hierarchy.
 
 ## Planning contract
 
@@ -88,7 +88,7 @@ For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
 
 For `objective_status: "satisfied"`, `assessment` may be a concise evidence-based completion assessment without a graph.
 
-Each item in next_tasks contains id, input, output, and storySize. `unblocks`, when present, is an array of `{repository, prNumber, jobId, taskId, resolutionMode?}` records identifying Tasks that must remain waiting until the current Job resolves their blocker. It may also contain priority, projectName, agentName, dependencies, capabilities, workerRequirements, maxAttempts, and timeoutMs. Adapter/routing fields are selected by Relay after planning; do not invent them.
+Each item in next_tasks contains id, input, output, and storySize. `unblocks`, when present, is an array of `{repository, prNumber, jobId, taskId, resolutionMode?}` records identifying Tasks that must remain waiting until the current Job resolves their blocker. It may also contain parentTaskId, priority, projectName, agentName, dependencies, capabilities, workerRequirements, maxAttempts, and timeoutMs. Adapter/routing fields are selected by Relay after planning; do not invent them.
 
 ### Exact `next_tasks` serialization
 
@@ -100,6 +100,7 @@ Use these exact serialized forms:
 - `agentGraph`, when present, is one executable Mermaid Agent Graph **string** using `flowchart TD|TB|LR|RL`, for example `"flowchart LR\n  build-log-editor --> build-log-producer"`. Do not emit `graph LR`, and do not emit an object with `nodes` or `edges`.
 - `priority`, when present, is exactly `"P0"`, `"P1"`, `"P2"`, or `"P3"`; otherwise omit it.
 - `storySize` is exactly `"S"`, `"M"`, or `"L"`.
+- `parentTaskId`, when present, is the durable parent work Task ID in the current Job. Never point it at a `plan-N` planner round.
 
 A valid non-satisfied response:
 

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

@@ -50,6 +50,12 @@ For feature/refactor work with no failure to diagnose, root cause is not require
 
 Keep these concepts distinct: observation is not root cause; hypothesis is not root cause; requested approach is not implemented solution; implementation is not validation.
 
+### Job-defined Task fields
+
+Canonical `Task.state` is reserved for Relay lifecycle only. A Job may declare `taskFields`, a map of Job-specific result fields. Each field declares an optional label and an allowed `values` map whose keys are durable values and whose values are display strings. A Task stores reported values separately in `fields`.
+
+A model-backed worker reports applicable Job-defined values in its canonical terminal event under `data.taskFields`, for example `{"taskFields":{"e2e":"pass"}}`. Relay validates reported names and values against the Job declaration, copies only valid values into the Task marker's `fields`, and does not reinterpret them as lifecycle state. The raw `data.taskFields` transport payload is not duplicated inside `result.data`. Jobs without `taskFields` are unchanged.
+
 ## Worker routing order
 
 Every new model-backed executable task follows this order:
@@ -144,11 +150,11 @@ The public CLI resource surface is:
 
 `job create` persists only durable Job state. It never creates executable work. `task create` creates a real executable Task directly under the Job; direct orchestrator-created Tasks are not wrapped in synthetic planner Tasks and have no planner-round provenance. `plan` is the explicit public operation for invoking the Planner against an existing Job; it is not generic CRUD for planner records.
 
-Relay invokes the planner agent, validates its structured result, persists that invocation as one real `plan-N` round, then materializes `next_tasks` under that planning round. `--prompt` / `--prompt-file` add caller guidance to the durable planning input without replacing the Job objective. The planner agent itself does not call Relay CLI or persist Tasks. Only an actual planner invocation creates a planning round. Historical `planner-N` rounds remain readable and participate in round numbering.
+Relay invokes the planner agent, validates its structured result, persists that invocation as one real `plan-N` round, then materializes `next_tasks`. Planner rounds are planning-history records, not business-tree parents. Their history is linked by planner provenance (`previousPlannerTaskId` / planning-round metadata); business Task hierarchy is expressed only through work Task `parentTaskId`. `--prompt` / `--prompt-file` add caller guidance to the durable planning input without replacing the Job objective. The planner agent itself does not call Relay CLI or persist Tasks. Only an actual planner invocation creates a planning round. Historical `planner-N` rounds remain readable and participate in round numbering.
 
 A zero-task autonomous Job stays idle under ordinary reconciliation, but an explicit `plan` command can start it immediately. An autonomous Job may also begin with one or more direct orchestrator-created Tasks and no Plan. After that direct batch completes, Relay may create the next real planning round through the same round-construction/execution path used by manual `plan`. Later rounds continue until the objective is satisfied. Fixed Jobs never create autonomous planner rounds automatically.
 
-Planner-produced Tasks obey this same contract, including explicit `storySize`.
+Planner-produced Tasks obey this same contract, including explicit `storySize`. A planner may set `parentTaskId` to another Task ID in the current Job to create durable business hierarchy. Omit it for root Tasks. Never use a `plan-N` Task as a business parent.
 
 ### Optional Review Chair Tasks