agents-relay 1.0.31 → 1.0.33

package/README.md

@@ -31,9 +31,16 @@ npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id chil
   --capabilities model,chatgpt,browser-harness
 ~~~
 
-Jobs default to `fixed`, preserving the original submit-and-run behavior. Use
-`--mode autonomous` with `init` or `job create` to make reconciliation own
-planner progress. The durable status JSON and dashboard show the mode. An
+Jobs default to `fixed`, preserving the original submit-and-run behavior. Every
+executable task is now created by a completed durable planning decision. `job
+create --start` records `planner-0` (supplied by the orchestrator) and the
+initial task atomically from the caller's perspective; retrying the command is
+idempotent. Use `--mode autonomous` with `init` or `job create` to make
+reconciliation own planner progress. Autonomous creation with only an objective
+may create a model planner first, but it cannot materialize work until that
+planner succeeds. Fixed jobs never grow another planning round.
+
+The durable status JSON and dashboard show the mode and planning provenance. An
 autonomous runtime uses the bundled `skills/agents-relay/agents/planner.agent.md` by default; `--planner-command` is an optional override
 snapshot as JSON on stdin and must return `{ "objective_status": "in_progress"|"satisfied", "assessment": "...", "next_tasks": [...] }`.
 Planner-created tasks use stable IDs and the existing parent/subtask tree, so
@@ -107,7 +114,7 @@ The minimal agent-network surface is machine-driven registration and discovery.
 
 Managed tasks are descriptive work for agents, not shell commands. Use `codex` or `chatgpt` for worker tasks. Commands such as tests, build tools, Markad Vision, ffmpeg, and other CLIs are invoked by the orchestrator or by an executing agent; they are not worker adapters.
 
-Every model-backed task declares a durable output with `--output task-pr` or `--output file --output-path PATH`. Agents Relay enriches the prompt with the PR URL, job/task identity, output contract, and mandatory terminal-event contract.
+Every model-backed task declares a durable output with `--output task-pr` or `--output file --output-path PATH`. Agents Relay bootstraps workers with the managed PR URL, durable task-comment URL, job/task identity, project, output contract, and mandatory terminal-event contract; workers retrieve the task intent from GitHub rather than receiving a duplicate copy of the stored task prompt.
 
 For Codex and ChatGPT, **events are authoritative task state**. Event publication uses the canonical Neo `events-bus` surface (`events__publish` for sandboxed/hosted workers, or `NEO_EVENTS_EMIT` for direct local workers); Agents Relay only subscribes and reconciles. Relay publishes `task.process.launched` only after successful adapter launch; `task.started` is worker-owned and must be a new, correlated start acknowledgement. Codex publishes `task.process.exited` when its synchronous runtime exits, while ChatGPT publishes `task.process.async_exited` after its submission runtime exits; neither substitutes for `task.completed`, `task.failed`, `task.blocked`, or `task.cancelled`. The ChatGPT worker-owned tab follows the configured close policy: `after-start` waits for the correlated start acknowledgement, `never` keeps it open for debug, and `after-terminal` waits for a new exact-task terminal event; start-ack failure closes only the owned tab after 60 seconds. The executing agent must publish exactly one correlated terminal event. Relay persists the matching durable state only from that terminal event. Model-backed tasks require an event bus and time out explicitly if no terminal event arrives.
 

package/dist/adapters.js

@@ -108,7 +108,12 @@ export class StartAckTimeout extends LaunchFailure {
 }
 async function loadBrowserWorkerRuntime(context, explicit) {
     const resolvedSkill = context?.skills.find(skill => skill.name === 'chatgpt-browser-worker');
-    const candidate = explicit ?? (resolvedSkill ? join(dirname(resolvedSkill.path), 'agents', 'browser-worker.agent.md') : undefined);
+    // Once a worker receives a resolved execution context, that context owns
+    // skill discovery. The explicit path remains the fallback for direct
+    // adapter use, where no shared context has been resolved yet.
+    const candidate = resolvedSkill
+        ? join(dirname(resolvedSkill.path), 'agents', 'browser-worker.agent.md')
+        : explicit;
     if (!candidate)
         throw new Error('chatgpt-browser-worker is not visible in the resolved execution context');
     try {

package/dist/cli.js

@@ -14,7 +14,7 @@ import { NatsEventBus, eventFor } from './events.js';
 import { serveDashboard } from './dashboard.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { discoverAgents } from './registry.js';
-import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
+import { AgentObjectivePlanner, CommandObjectivePlanner, orchestratorPlanningDecision } from './planner.js';
 import { extendRetryBudget } from './scheduler.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath } from './workspace.js';
@@ -270,7 +270,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         if (!(error instanceof Error) || !error.message.includes('has no durable'))
             throw error;
         const now = new Date().toISOString();
-        job = { id: options.id, title: options.title || pr.title || 'Agents Relay job', objective: options.objective || pr.body || undefined, description: pr.body || undefined, priority: options.priority ?? 'P2', executionMode: options.executionMode ?? 'fixed', autoMerge: options.autoMerge ?? true, prNumber: pr.number, repository: repositoryName, state: 'OPEN', continuation: options.continuation ?? null, createdAt: now, updatedAt: now, tasks: [] };
+        job = { id: options.id, title: options.title || pr.title || 'Agents Relay job', objective: options.objective || pr.body || undefined, description: pr.body || undefined, priority: options.priority ?? 'P2', executionMode: options.executionMode ?? 'fixed', autoMerge: options.autoMerge ?? true, prNumber: pr.number, repository: repositoryName, state: 'OPEN', continuation: options.continuation ?? null, initialPlanning: options.initialTasks?.length ? { status: 'pending', decisionId: 'planner-0' } : undefined, createdAt: now, updatedAt: now, tasks: [] };
     }
     if (!job.description && pr.body)
         job.description = pr.body;
@@ -286,9 +286,40 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
         job.priority = 'P2';
     if (!job.title && pr.title)
         job.title = pr.title;
-    await store.saveJob(job);
+    if (options.initialTasks?.length) {
+        const decisionId = job.initialPlanning?.decisionId ?? 'planner-0';
+        job.initialPlanning = { status: 'pending', decisionId };
+        job.updatedAt = new Date().toISOString();
+        await store.saveJob(job);
+        const decision = orchestratorPlanningDecision(job, options.initialTasks, decisionId, null, 0);
+        if (!(await store.load(options.id)).tasks.some(task => task.id === decision.id))
+            await store.appendTask(decision);
+        for (const original of options.initialTasks) {
+            const task = { ...original, parentTaskId: decision.id, planningDecisionId: decision.id, planningSource: 'orchestrator', planningRound: 0 };
+            if (!(await store.load(options.id)).tasks.some(item => item.id === task.id))
+                await store.appendTask(task);
+        }
+        job.initialPlanning = { status: 'complete', decisionId };
+        job.updatedAt = new Date().toISOString();
+        await store.saveJob(job);
+    }
+    else
+        await store.saveJob(job);
     return { job: await store.load(options.id), pr };
 }
+async function appendPlannedTask(store, job, task) {
+    const existing = job.tasks.find(item => item.id === task.id);
+    if (existing)
+        return existing;
+    const decisionId = `plan-${task.id}`;
+    const decision = orchestratorPlanningDecision(job, [task], decisionId, task.parentTaskId, job.tasks.filter(item => item.kind === 'planner').length, 'orchestrator');
+    if (!job.tasks.some(item => item.id === decision.id))
+        await store.appendTask(decision);
+    const planned = { ...task, parentTaskId: task.parentTaskId ?? null, planningDecisionId: decision.id, planningSource: 'orchestrator', planningRound: decision.planningRound };
+    await store.appendTask(planned);
+    job.tasks.push(planned, decision);
+    return planned;
+}
 function workerTaskFromArgs(job, args, now, requireInput = false) {
     const model = arg(args, '--model');
     const adapterValue = arg(args, '--adapter');
@@ -438,12 +469,12 @@ async function runJobCommand(action, args) {
     if (!id)
         throw new Error('--id is required for managed GitHub jobs');
     const start = hasArg(args, '--start');
+    const initialTask = start ? workerTaskFromArgs({ id, title: '', executionMode: 'fixed', prNumber: 0, repository: repo, state: 'OPEN', continuation: null, createdAt: '', updatedAt: '', tasks: [] }, args, new Date().toISOString(), true) : undefined;
     if (start && action !== 'create')
         throw new Error('--start is only supported by job create');
     if (start) {
         if (!hasArg(args, '--adapter'))
             throw new Error('job create --start requires --adapter codex|chatgpt');
-        workerTaskFromArgs({ id, title: '', executionMode: 'fixed', prNumber: 0, repository: repo, state: 'OPEN', continuation: null, createdAt: '', updatedAt: '', tasks: [] }, args, new Date().toISOString(), true);
     }
     const auth = await githubAuthContext(args);
     const client = auth.client;
@@ -465,18 +496,11 @@ async function runJobCommand(action, args) {
         prNumber,
         head: arg(args, '--head') || undefined,
         base: arg(args, '--base', 'main'),
-        body: arg(args, '--body') || undefined
+        body: arg(args, '--body') || undefined,
+        initialTasks: initialTask ? [initialTask] : undefined
     });
-    if (start) {
-        const task = workerTaskFromArgs(result.job, args, new Date().toISOString(), true);
-        const existing = result.job.tasks.find(item => item.id === task.id);
-        const store = new GitHubStore(client, repo, result.pr.number, trustedAuthors);
-        await store.appendTask(task);
-        if (!existing) {
-            await publishWake(eventBus(args), result.job, task.id, `Task ${task.id} submitted`);
-            result.job.tasks.push(task);
-        }
-    }
+    if (start)
+        await publishWake(eventBus(args), result.job, initialTask?.id ?? 'initial', `Initial planning decision and task ${initialTask?.id ?? 'initial'} recorded`);
     console.log(JSON.stringify({ repository: repo, pr: result.pr.number, job: result.job.id, executionMode: result.job.executionMode, state: result.job.state, task: start ? arg(args, '--task-id', 'initial') : undefined }, null, 2));
 }
 export function runtimePlanner(args) { const plannerCommand = arg([...args], '--planner-command'); const modelRuntime = arg([...args], '--codex', 'codex'); return plannerCommand ? new CommandObjectivePlanner(plannerCommand) : new AgentObjectivePlanner(modelRuntime); }
@@ -621,8 +645,7 @@ async function main() {
             throw new Error('record requires --summary');
         const commit = arg(args, '--commit');
         const task = { jobId: job.id, id, projectName: arg(args, '--project') || undefined, agentName: arg(args, '--agent', 'orchestrator'), parentTaskId: arg(args, '--parent') || null, dependencies: arg(args, '--deps').split(',').filter(Boolean), capabilities: [], adapter: 'orchestrator', input: arg(args, '--input', summary), continuation: null, continuationDeliveredAt: null, state: 'SUCCEEDED', attempt: 1, maxAttempts: 1, leaseOwner: null, leaseExpiresAt: null, executionId: commit || null, threadId: null, result: { summary, data: commit ? { commit } : undefined }, error: null, timeoutMs: 0, createdAt: now, updatedAt: now };
-        await store.appendTask(task);
-        job.tasks.push(task);
+        await appendPlannedTask(store, job, task);
         await saveLocal(localFile, job);
         console.log(`Recorded ${id}`);
         return;
@@ -631,16 +654,15 @@ async function main() {
         const now = new Date().toISOString();
         const task = workerTaskFromArgs(job, args, now);
         task.id = arg(args, '--task-id', randomUUID());
-        await store.appendTask(task);
-        job.tasks.push(task);
+        const planned = await appendPlannedTask(store, job, task);
         if (job.state !== 'RUNNING') {
             job.state = 'RUNNING';
             job.updatedAt = now;
             await store.saveJob(job);
         }
         await saveLocal(localFile, job);
-        await publishWake(bus, job, task.id, `Task ${task.id} submitted`);
-        console.log(`Submitted ${task.id}`);
+        await publishWake(bus, job, planned.id, `Planning decision recorded and task ${planned.id} submitted`);
+        console.log(`Submitted ${planned.id}`);
         return;
     }
     if (command === 'status') {

package/dist/dashboard.js

@@ -240,7 +240,7 @@ function renderJobList(){jobList.replaceChildren();const visible=filteredJobs();
 function taskNode(task,children,depth){const li=element('li');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',()=>{selectedTaskId=task.id;eventTaskId=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)));li.append(row);const nested=children.get(task.id)||[];if(nested.length){const ul=element('ul','tree');for(const child of nested)ul.append(taskNode(child,children,depth+1));li.append(ul);}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 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;}
-function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Task',task.id),field('Kind',task.kind||'work'),field('State',task.state),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),chatField(task));if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));taskDetailRoot.append(groups);}
+function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Task',task.id),field('Kind',task.kind||'work'),field('State',task.state),field('Planning decision',task.planningDecisionId||'—'),field('Planning source',task.planningSource||'—'),field('Planning round',task.planningRound===undefined?'—':String(task.planningRound)),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),chatField(task));if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));taskDetailRoot.append(groups);}
 function reviewStatus(job){const review=job?.review;if(!review)return 'Not started';if(review.outcome==='approved'&&review.headSha===job.headSha)return 'MERGE READY · approved';const stale=Array.isArray(job?.tasks)&&job.tasks.some(task=>task.agentName==='reviewer'&&task.reviewHeadSha&&job.headSha&&task.reviewHeadSha!==job.headSha);if(stale)return 'STALE · awaiting review';return String(review.outcome||'pending').replace('_',' ').toUpperCase();}
 function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent='— '+value(job.title||job.id);if(job.id!==selectedJob){selectedJob=job.id;selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('GitHub state',job.githubState||'UNKNOWN'),field('Durable state',job.state),field('Execution mode',job.executionMode||'fixed'),field('Status',awaitingInitialTask(job)?'Awaiting initial task':job.state),field('Review',reviewStatus(job)),field('Review head SHA',job.review?.headSha||job.headSha||'—'),field('Objective',job.objective||job.description||job.title),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}
 function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();}

package/dist/planner.js

@@ -4,6 +4,17 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { taskOverallTimeoutMs } from './types.js';
 import { executionContextPrompt } from './execution-context.js';
+export function planningSpec(task) {
+    if (!task.output && task.adapter !== 'orchestrator')
+        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, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
+}
+export function orchestratorPlanningDecision(job, tasks, id, parentTaskId, round, source = 'orchestrator') {
+    const now = new Date().toISOString();
+    return { jobId: job.id, id, kind: 'planner', priority: job.priority, storySize: 'S', agentName: source === 'orchestrator' ? 'orchestrator' : 'planner', parentTaskId, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: `Planning decision supplied by ${source} for ${tasks.length} task(s)`, state: 'SUCCEEDED', attempt: 1, maxAttempts: 1, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: { summary: source === 'orchestrator' ? 'Initial task set supplied by orchestrator' : 'Planning decision completed' }, plannerResult: { objective_status: 'in_progress', assessment: source === 'orchestrator' ? 'Initial task set supplied by orchestrator' : 'Planning decision completed', next_tasks: tasks.map(planningSpec) }, error: null, timeoutMs: 0, createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: source, planningRound: round };
+}
 function record(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Planner result must be an object');

package/dist/reconciler.js

@@ -13,17 +13,20 @@ export function managedWorkerInput(job, task, context) {
     if (!task.output)
         throw new Error(`Task ${task.id} requires an explicit output contract`);
     const prUrl = `https://github.com/${job.repository}/pull/${job.prNumber}`;
+    const taskUrl = task.taskUrl ?? `${prUrl}#issuecomment-${task.id}`;
     const output = task.output.kind === 'file'
         ? `file\nPath: ${task.output.path}`
         : `task/PR\nPR: ${prUrl}\nTask: ${task.id}`;
     return `[Agents Relay managed task]
-PR: ${prUrl}
-Job: ${job.id}
-Task: ${task.id}
-Parent task: ${task.parentTaskId ?? 'none'}
+Job URL: ${prUrl}
+Job ID: ${job.id}
+Task URL: ${taskUrl}
+Task ID: ${task.id}
 Project: ${task.projectName ?? context?.project.name ?? 'unspecified'}
 
-${context ? executionContextPrompt(context) + '\n\n' : ''}${task.input}${task.parentTaskId ? '\n\n[Nested delegation contract]\nAny sub-work must be created as a durable Agents Relay child task with parentTaskId=' + task.id + '; do not directly spawn arbitrary child agents.' : ''}
+Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.
+
+${context ? executionContextPrompt(context) + '\n\n' : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
 
 [Output contract]
 ${output}
@@ -126,12 +129,17 @@ export class Reconciler {
                 }
             }
             await this.recoverLostExecutions(job, now);
+            await this.recoverPlannerChildren(job);
             for (const task of job.tasks)
                 if (task.state === 'CANCELLED') {
                     this.live.get(task.id)?.execution.cancel();
                     this.plannerLive.get(task.id)?.controller.abort();
                 }
             let scheduled = schedule(await this.store.load(jobId));
+            if (prState === 'OPEN') {
+                await this.ensureFinalReview(scheduled, prState, headSha);
+                scheduled = schedule(await this.store.load(jobId));
+            }
             if (prState === 'OPEN' && scheduled.executionMode === 'autonomous') {
                 scheduled = schedule(await this.maybeCreatePlanner(scheduled));
             }
@@ -285,16 +293,24 @@ export class Reconciler {
     async maybeCreatePlanner(job) {
         if (job.executionMode !== 'autonomous')
             return job;
+        if (job.initialPlanning?.status === 'pending')
+            return job;
         const planners = job.tasks.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)))
             return job;
         if (job.tasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
             return job;
+        if (job.tasks.length > 0 && !planners.some(task => task.state === 'SUCCEEDED'))
+            return job;
         if (job.tasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
             return job;
+        if (planners.length > 0 && planners.at(-1)?.plannerResult?.objective_status === 'in_progress' && !job.tasks.some(task => task.planningDecisionId === planners.at(-1)?.id))
+            return job;
         const latest = planners.at(-1);
         if (latest?.plannerResult?.objective_status === 'satisfied')
             return job;
+        if (latest && job.review && job.review.outcome !== 'approved')
+            return job;
         const used = new Set(job.tasks.map(task => task.id));
         let number = planners.length + 1;
         let id = `planner-${number}`;
@@ -303,11 +319,26 @@ export class Reconciler {
             id = `planner-${number}`;
         }
         const now = new Date().toISOString();
-        const task = { jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner', parentTaskId: latest?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: latest?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now };
+        const task = { jobId: job.id, id, kind: 'planner', storySize: 'M', agentName: 'planner', parentTaskId: latest?.id ?? null, dependencies: [], capabilities: ['planner'], adapter: 'orchestrator', input: plannerInput({ job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: latest?.id ?? null }), continuation: null, continuationDeliveredAt: null, state: 'QUEUED', attempt: 0, maxAttempts: 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), createdAt: now, updatedAt: now, planningDecisionId: id, planningSource: 'model-planner', planningRound: planners.length + 1 };
         await this.store.appendTask(task);
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
         return this.store.load(job.id);
     }
+    async recoverPlannerChildren(job) {
+        for (const planner of job.tasks.filter(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && task.plannerResult)) {
+            const children = planner.plannerResult?.next_tasks.map(spec => this.plannerChild(job, planner, spec)) ?? [];
+            for (const child of children) {
+                const existing = job.tasks.find(item => item.id === child.id);
+                if (existing) {
+                    if (!samePlannerChildDefinition(existing, child))
+                        throw new Error(`Planner task ${child.id} already exists with a different definition`);
+                    continue;
+                }
+                await this.store.appendTask(child);
+                job.tasks.push(child);
+            }
+        }
+    }
     async resolvedContext(job, task, role) {
         const projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job) : task.routing?.cwd ?? process.cwd();
         return resolveExecutionContext(projectPath, role, {
@@ -481,14 +512,15 @@ export class Reconciler {
         }
         try {
             const result = parsePlannerResult(raw);
-            for (const spec of result.next_tasks) {
-                const child = this.plannerChild(job, task, spec);
+            const children = result.next_tasks.map(spec => this.plannerChild(job, task, spec));
+            for (const child of children) {
                 const existing = job.tasks.find(item => item.id === child.id);
                 if (!existing)
-                    await this.store.appendTask(child);
+                    continue;
                 else if (!samePlannerChildDefinition(existing, child))
                     throw new Error(`Planner task ${child.id} already exists with a different definition`);
             }
+            // Persist the completed decision before exposing executable children.
             task.plannerResult = result;
             task.result = { summary: result.assessment, data: { objective_status: result.objective_status, next_tasks: result.next_tasks } };
             task.error = null;
@@ -496,22 +528,32 @@ export class Reconciler {
             task.leaseExpiresAt = null;
             transitionTask(task, 'SUCCEEDED');
             await this.store.saveTask(task);
+            for (const child of children)
+                if (!job.tasks.some(item => item.id === child.id))
+                    await this.store.appendTask(child);
             await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.completed', 'succeeded', `Planner ${task.id} completed: ${result.objective_status}`, 'orchestrator', { objective_status: result.objective_status }));
         }
         catch (caught) {
             const message = caught instanceof Error ? caught.message : String(caught);
-            task.error = message;
-            task.leaseOwner = null;
-            task.leaseExpiresAt = null;
-            transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
-            await this.store.saveTask(task);
-            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${message}`, 'user'));
+            if (task.state === 'SUCCEEDED') {
+                task.error = `Child materialization failed: ${message}`;
+                await this.store.saveTask(task);
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.children_failed', 'failed', `Planner ${task.id} child materialization failed: ${message}`, 'user'));
+            }
+            else {
+                task.error = message;
+                task.leaseOwner = null;
+                task.leaseExpiresAt = null;
+                transitionTask(task, task.attempt < task.maxAttempts ? 'READY' : 'FAILED');
+                await this.store.saveTask(task);
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.failed', 'failed', `Planner ${task.id}: ${message}`, 'user'));
+            }
         }
         this.detach(this.reconcile(jobId), jobId, task.id, 'planner follow-up reconciliation');
     }
     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 ?? [], adapter: spec.adapter, input: spec.input, output: spec.output, routing: spec.routing, 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', spec.routing?.reasoning), createdAt: now, updatedAt: now };
+        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 ?? [], adapter: spec.adapter, input: spec.input, output: spec.output, routing: spec.routing, 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', spec.routing?.reasoning), 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/store.js

@@ -82,7 +82,7 @@ function immutableTaskDefinition(task) {
     } : undefined;
     return {
         jobId: task.jobId, id: task.id, priority: task.priority, storySize: task.storySize ?? 'M', projectName: task.projectName, agentName: task.agentName,
-        kind: task.kind ?? 'work', parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter,
+        kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, adapter: task.adapter,
         input: task.input, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
     };
 }
@@ -434,7 +434,7 @@ export class GitHubStore {
         const all = [];
         let cursor = null;
         do {
-            const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!,$cursor:String){repository(owner:$owner,name:$name){pullRequest(number:$number){comments(first:100,after:$cursor){nodes{id databaseId body updatedAt author{login}} pageInfo{hasNextPage endCursor}}}}}', { owner, name, number: this.prNumber, cursor });
+            const data = await this.graphql('query($owner:String!,$name:String!,$number:Int!,$cursor:String){repository(owner:$owner,name:$name){pullRequest(number:$number){comments(first:100,after:$cursor){nodes{id databaseId url body updatedAt author{login}} pageInfo{hasNextPage endCursor}}}}}', { owner, name, number: this.prNumber, cursor });
             const repository = data.repository;
             const pr = repository?.pullRequest;
             const comments = pr?.comments;
@@ -444,6 +444,7 @@ export class GitHubStore {
                 all.push({
                     id: Number(value.databaseId ?? 0),
                     nodeId: typeof value.id === 'string' ? value.id : undefined,
+                    url: typeof value.url === 'string' ? value.url : undefined,
                     body: String(value.body ?? ''),
                     updatedAt: String(value.updatedAt ?? ''),
                     authorLogin: typeof author?.login === 'string' ? author.login : null
@@ -486,7 +487,13 @@ export class GitHubStore {
         if (!job)
             throw new Error(`Managed GitHub job ${jobId} has no durable ${JOB_MARKER} marker in PR #${this.prNumber}; run agents-relay job adopt --repo ${this.repository} --pr ${this.prNumber} --id ${jobId}`);
         const soleTrustedJob = jobs.length === 1;
-        job.tasks = comments.map(x => parseTask(x.body)).filter((x) => x !== null).filter(task => isTaskForJob(task, jobId, soleTrustedJob));
+        job.tasks = comments.map(comment => {
+            const task = parseTask(comment.body);
+            if (!task)
+                return null;
+            const taskUrl = comment.url ?? (comment.id > 0 ? `https://github.com/${this.repository}/pull/${this.prNumber}#issuecomment-${comment.id}` : undefined);
+            return taskUrl ? { ...task, taskUrl } : task;
+        }).filter((x) => x !== null).filter(task => isTaskForJob(task, jobId, soleTrustedJob));
         return job;
     }
     async listAgents() { return (await this.list()).filter(comment => this.isTrusted(comment)).map(x => parseAgent(x.body)).filter((x) => x !== null); }

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -96,6 +96,16 @@ ChatGPT thread identity is diagnostic only. It is not persisted as a resumable t
 
 ## Autonomous planner
 
+No executable task may be materialized without a completed durable planning
+decision. Job creation with caller-supplied initial work records an
+orchestrator-owned `planner-0` decision before its initial tasks; autonomous
+mode must not start a model planner in that case. Objective-only autonomous
+jobs may start a real model planner, and planner children are created only
+after that planner succeeds. Fixed jobs do not automatically create another
+planning round. Each task exposes `planningDecisionId`, `planningSource`, and
+`planningRound` for dashboard lineage. Nested worker delegation must create its
+durable planning decision and children through Relay as well.
+
 Planner-created child tasks must also be descriptive agent work. They must select `codex` or `chatgpt` and include an explicit output contract. A planner must never generate shell-command worker tasks.
 
 ## Durable truth