agents-relay 2.0.53 → 2.0.55

package/README.md

@@ -4,6 +4,10 @@ Agents Relay is a generic TypeScript runtime for durable asynchronous agent jobs
 
 V2 separates **operational execution state** from that collaboration record. A local RelayStore may use SQLite/WAL for runtime snapshots, event idempotency and a durable GitHub projection outbox. ProjectedDurableStore bootstraps from the existing GitHub representation, commits Job/Plan/Task runtime changes locally, and lets GitHubProjectionWriter project them asynchronously. GitHub therefore remains the human-readable durable Job/Plan/Task/Review surface without being required for every high-frequency runtime transition.
 
+The canonical V2 architecture contract is
+[DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md). README sections below describe
+the runtime; they do not replace that contract.
+
 ## V2 architecture
 
 ```mermaid

package/dist/cli-help.js

@@ -123,9 +123,12 @@ Required: --task-id ID and the normal Job storage options.`,
     'task list': `List durable Tasks for one Job.
 
 Required: the normal Job storage options.`,
+    'task start': `Mark one orchestrator-owned self Task RUNNING when the creating orchestrator actually begins the work.
+
+Required: --task-id ID and the normal Job storage options. The Task must use adapter=orchestrator and be QUEUED. Start must occur before task complete.`,
     'task complete': `Complete one orchestrator-owned Task after the creating orchestrator has finished the work.
 
-Required: --task-id ID, --summary TEXT, and the normal Job storage options. The Task must use adapter=orchestrator and be QUEUED or RUNNING. This command is for the same orchestrator turn that created the self-task; it is not a deferred handoff mechanism.`,
+Required: --task-id ID, --summary TEXT, and the normal Job storage options. The Task must use adapter=orchestrator and already be RUNNING. This command is for the same orchestrator turn that created the self-task; it is not a deferred handoff mechanism.`,
     'task retry': `Retry one durable Task.
 
 Required: --task-id ID and the normal Job storage options.`,

package/dist/cli-support.js

@@ -162,20 +162,24 @@ export async function publishTaskUnblocked(bus, job, taskId, reason) { if (!bus)
 catch (error) {
     process.stderr.write(`warning: unblock event unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
 } }
+export async function publishOrchestratorTaskStarted(bus, job, task) {
+    if (!bus)
+        return;
+    try {
+        await bus.publish(eventFor(job.id, task.id, task.parentTaskId, 'task.started', 'running', `Task ${task.id} started by orchestrator`, 'orchestrator', { adapter: 'orchestrator' }, { agent: 'relay', component: 'agents-relay' }));
+    }
+    catch (error) {
+        process.stderr.write(`warning: orchestrator task start event unavailable for ${job.id}/${task.id}: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
 export async function publishOrchestratorTaskCompletion(bus, job, task, summary) {
     if (!bus)
         return;
-    const events = [
-        eventFor(job.id, task.id, task.parentTaskId, 'task.started', 'running', `Task ${task.id} started by orchestrator`, 'orchestrator', { adapter: 'orchestrator' }, { agent: 'relay', component: 'agents-relay' }),
-        eventFor(job.id, task.id, task.parentTaskId, 'task.completed', 'succeeded', `Task ${task.id} completed by orchestrator`, 'orchestrator', { adapter: 'orchestrator', summary }, { agent: 'relay', component: 'agents-relay' }),
-    ];
-    for (const event of events) {
-        try {
-            await bus.publish(event);
-        }
-        catch (error) {
-            process.stderr.write(`warning: orchestrator task event unavailable for ${job.id}/${task.id}: ${error instanceof Error ? error.message : String(error)}\n`);
-        }
+    try {
+        await bus.publish(eventFor(job.id, task.id, task.parentTaskId, 'task.completed', 'succeeded', `Task ${task.id} completed by orchestrator`, 'orchestrator', { adapter: 'orchestrator', summary }, { agent: 'relay', component: 'agents-relay' }));
+    }
+    catch (error) {
+        process.stderr.write(`warning: orchestrator task completion event unavailable for ${job.id}/${task.id}: ${error instanceof Error ? error.message : String(error)}\n`);
     }
 }
 export async function publishDependentUnblocked(bus, targets, reason) { if (!bus)

package/dist/cli.js

@@ -18,7 +18,7 @@ import { decisionMode, LayaCliDecisionEngine } from './decision.js';
 import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
 import { transitionJobEvent } from './scheduler.js';
-import { applyOrchestratorCompleteAction, applyTaskHoldAction, dispatchTaskAction } from './task-actions.js';
+import { applyOrchestratorStartAction, applyOrchestratorCompleteAction, applyTaskHoldAction, dispatchTaskAction } from './task-actions.js';
 import { applyJobActivateAction, applyJobCancelAction } from './job-actions.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
@@ -30,7 +30,7 @@ import { parseAgentGraph } from './agent-graph.js';
 import { runJobUnblockCommand, runTaskUnblockCommand } from './cli-unblock.js';
 import { createJobEntity, createTaskEntity } from './workflow/entity-creation.js';
 export { helpText } from './cli-help.js';
-import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, publishDependentUnblocked, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, jobTagFromArgs, requestManagedReconciliation, relayControlJob, relayTaskCommand, withEventBus, } from './cli-support.js';
+import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, publishDependentUnblocked, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, jobTagFromArgs, requestManagedReconciliation, relayControlJob, relayTaskCommand, withEventBus } 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)
@@ -157,10 +157,10 @@ async function runManagedTaskCommand(action, args) {
     console.log(JSON.stringify(task, null, 2));
 }
 async function runTaskCommand(action, args) {
-    if (!['create', 'update', 'show', 'list', 'complete', 'retry', 'unblock', 'cancel'].includes(action))
+    if (!['create', 'update', 'show', 'list', 'start', 'complete', 'retry', 'unblock', 'cancel'].includes(action))
         throw new Error(usage);
     const managed = Boolean(arg(args, '--repo') && arg(args, '--pr') && !arg(args, '--file'));
-    if (managed && ['create', 'complete', 'retry', 'cancel'].includes(action)) {
+    if (managed && ['create', 'start', 'complete', 'retry', 'cancel'].includes(action)) {
         await runManagedTaskCommand(action, args);
         return;
     }
@@ -201,6 +201,13 @@ async function runTaskCommand(action, args) {
         await runTaskUnblockCommand(args, store, job, task, localFile);
         return;
     }
+    if (action === 'start') {
+        await applyOrchestratorStartAction(task);
+        await store.saveTask(task);
+        await saveLocal(localFile, await store.load(job.id));
+        console.log(JSON.stringify(task, null, 2));
+        return;
+    }
     if (action === 'complete') {
         const summary = arg(args, '--summary');
         if (!summary)

package/dist/dashboard.js

@@ -280,6 +280,8 @@ export function serveDashboard(store, port = 8787, bus, refreshMs = 300000, jobI
                 let result;
                 if (body.action === 'create' && body.task && resolvedActions?.taskCreate)
                     result = await resolvedActions.taskCreate(requestedJobId, body.task);
+                else if (body.action === 'start' && isTaskId(requestedTaskId) && resolvedActions?.taskStart)
+                    result = await resolvedActions.taskStart(requestedJobId, requestedTaskId);
                 else if (body.action === 'retry' && isTaskId(requestedTaskId) && resolvedActions?.taskRetry)
                     result = await resolvedActions.taskRetry(requestedJobId, requestedTaskId);
                 else if (body.action === 'cancel' && isTaskId(requestedTaskId) && resolvedActions?.taskCancel)

package/dist/reconciler-review.js

@@ -4,10 +4,9 @@ import { implementationComplete, implementationTasks } from './runtime-status.js
 import { eventFor } from './events.js';
 import { workerCandidates } from './worker-routing.js';
 import { routeExecution } from './execution-routing.js';
-import { ReconcilerRuntimeBase, withExecutionBoundary } from './reconciler-runtime.js';
+import { ReconcilerRuntimeBase } from './reconciler-runtime.js';
 import { dispatchReviewLifecycle, reviewOutcome } from './workflow/review-v2.js';
 import { createTaskEntity } from './workflow/entity-creation.js';
-const taskRouteClaims = new Set();
 export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
     async currentHeadSha(job) { return await this.store.headSha?.() ?? job.headSha ?? job.review?.headSha ?? null; }
     reviewFacts(job, prState, headSha) {
@@ -159,72 +158,62 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
             reason: 'worker-router',
         };
     }
-    async routeExecutableTasks(job) {
+    async routeTaskForExecution(job, task) {
+        if (task.routing)
+            return { task, routed: false };
+        if (!task.output || task.adapter === 'orchestrator')
+            return { task, routed: false };
         const usage = this.options.usageSnapshotProvider ? await this.options.usageSnapshotProvider() : undefined;
         const registered = await this.store.listAgents();
         const candidates = workerCandidates(this.options.adapters, registered, usage);
         const runtimeSummary = this.options.runtimeSummaryProvider?.();
-        for (const candidate of job.tasks.filter(item => item.kind !== 'planner' && item.adapter !== 'orchestrator' && ['QUEUED', 'BLOCKED'].includes(item.state) && item.output && !item.workerSelection && (item.workerRequirements || item.planningSource === 'model-planner'))) {
-            const claimKey = `${job.id}/${candidate.id}`;
-            if (taskRouteClaims.has(claimKey))
-                continue;
-            taskRouteClaims.add(claimKey);
-            try {
-                await withExecutionBoundary(job.id, candidate.id, async () => {
-                    const freshJob = await this.store.load(job.id);
-                    const task = freshJob.tasks.find(item => item.id === candidate.id);
-                    if (!task || !['QUEUED', 'BLOCKED'].includes(task.state) || task.workerSelection || !task.output)
-                        return;
-                    const requirements = task.workerRequirements ?? { capabilities: [] };
-                    const taskFacts = {
-                        job: {
-                            id: freshJob.id, title: freshJob.title, objective: freshJob.objective ?? null,
-                            description: freshJob.description ?? null, priority: freshJob.priority ?? null,
-                            executionMode: freshJob.executionMode, repository: freshJob.repository,
-                            prNumber: freshJob.prNumber, state: freshJob.state,
-                        },
-                        task: {
-                            id: task.id, kind: task.kind ?? 'work', storySize: task.storySize ?? 'M',
-                            priority: task.priority ?? null, agentName: task.agentName ?? null,
-                            parentTaskId: task.parentTaskId, dependencies: task.dependencies,
-                            capabilities: task.capabilities, input: task.input,
-                            attachments: task.attachments ?? [], output: task.output ?? null,
-                            state: task.state, attempt: task.attempt, maxAttempts: task.maxAttempts,
-                        },
-                        storySize: task.storySize ?? 'M',
-                    };
-                    const routingConstraints = task.routing ? { provider: task.routing.provider, model: task.routing.model, profile: task.routing.profile, reasoning: task.routing.reasoning } : undefined;
-                    const parent = task.agentName === 'troubleshooter' && task.parentTaskId ? freshJob.tasks.find(item => item.id === task.parentTaskId) : undefined;
-                    const parentRouteFailedBeforeStart = Boolean(parent?.routing && /exited before publishing task\.started|worker_exit_before_start|launch failed/i.test(parent.error ?? parent.failureReason ?? ''));
-                    const excludedRoutes = parentRouteFailedBeforeStart && parent?.routing
-                        ? [{ provider: parent.routing.provider, model: parent.routing.model, profile: parent.routing.profile }]
-                        : [];
-                    const routed = await routeExecution(candidates, requirements, {
-                        decisionEngine: this.options.decisionEngine,
-                        decisionMode: this.options.decisionMode,
-                        taskFacts: { ...taskFacts, recovery_parent_failed_route: excludedRoutes[0] ?? null },
-                        usage,
-                        registered,
-                        chatgptRunning: runtimeSummary?.chatgptRunning ?? 0,
-                        routingConstraints,
-                        excludedRoutes,
-                        auditStore: this.options.decisionAuditStore,
-                        auditTask: task,
-                    });
-                    task.workerSelection = routed.selection;
-                    task.adapter = routed.candidate.adapter;
-                    task.routing = routed.candidate.routing;
-                    task.timeoutMs = task.timeoutMs || taskOverallTimeoutMs(task.storySize ?? 'M', task.routing.reasoning);
-                    task.updatedAt = new Date().toISOString();
-                    await this.store.saveTask(task);
-                    await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'worker.selected', 'queued', `Worker ${routed.selection.workerId} selected for task ${task.id}`, 'user', { workerSelection: routed.selection, workerRequirements: requirements }, { agent: 'relay', component: 'agents-relay' }));
-                    await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'model.selected', 'queued', `Selected ${task.routing.model} · thinking ${task.routing.reasoning ?? 'unknown'}`, 'user', { routing: task.routing }, { agent: 'relay', component: 'agents-relay' }));
-                });
-            }
-            finally {
-                taskRouteClaims.delete(claimKey);
-            }
-        }
+        const requirements = task.workerRequirements ?? { capabilities: [] };
+        const taskFacts = {
+            job: {
+                id: job.id, title: job.title, objective: job.objective ?? null,
+                description: job.description ?? null, priority: job.priority ?? null,
+                executionMode: job.executionMode, repository: job.repository,
+                prNumber: job.prNumber, state: job.state,
+            },
+            task: {
+                id: task.id, kind: task.kind ?? 'work', storySize: task.storySize ?? 'M',
+                priority: task.priority ?? null, agentName: task.agentName ?? null,
+                parentTaskId: task.parentTaskId, dependencies: task.dependencies,
+                capabilities: task.capabilities, input: task.input,
+                attachments: task.attachments ?? [], output: task.output ?? null,
+                state: task.state, attempt: task.attempt, maxAttempts: task.maxAttempts,
+            },
+            storySize: task.storySize ?? 'M',
+        };
+        const routingConstraints = undefined;
+        const parent = task.agentName === 'troubleshooter' && task.parentTaskId
+            ? job.tasks.find(item => item.id === task.parentTaskId)
+            : undefined;
+        const parentRouteFailedBeforeStart = Boolean(parent?.routing && /exited before publishing task\.started|worker_exit_before_start|launch failed/i.test(parent.error ?? parent.failureReason ?? ''));
+        const excludedRoutes = parentRouteFailedBeforeStart && parent?.routing
+            ? [{ provider: parent.routing.provider, model: parent.routing.model, profile: parent.routing.profile }]
+            : [];
+        const routed = await routeExecution(candidates, requirements, {
+            decisionEngine: this.options.decisionEngine,
+            decisionMode: this.options.decisionMode,
+            taskFacts: { ...taskFacts, recovery_parent_failed_route: excludedRoutes[0] ?? null },
+            usage,
+            registered,
+            chatgptRunning: runtimeSummary?.chatgptRunning ?? 0,
+            routingConstraints,
+            excludedRoutes,
+            auditStore: this.options.decisionAuditStore,
+            auditTask: task,
+        });
+        task.workerSelection = routed.selection;
+        task.adapter = routed.candidate.adapter;
+        task.routing = routed.candidate.routing;
+        task.timeoutMs = task.timeoutMs || taskOverallTimeoutMs(task.storySize ?? 'M', task.routing.reasoning);
+        task.updatedAt = new Date().toISOString();
+        await this.store.saveTask(task);
+        await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'worker.selected', 'queued', 'Worker ' + routed.selection.workerId + ' selected for task ' + task.id, 'user', { workerSelection: routed.selection, workerRequirements: requirements }, { agent: 'relay', component: 'agents-relay' }));
+        await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'model.selected', 'queued', 'Selected ' + task.routing.model + ' · thinking ' + (task.routing.reasoning ?? 'unknown'), 'user', { routing: task.routing }, { agent: 'relay', component: 'agents-relay' }));
+        return { task, routed: true };
     }
     async applyReviewEvent(event) {
         const job = await this.store.load(event.job_id);

package/dist/reconciler.js

@@ -14,7 +14,7 @@ import { executionEventSource, withExecutionBoundary } from './reconciler-runtim
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
 import { pendingTroubleshooterTasks } from './troubleshooter.js';
-import { prepareManagedExecutionWorktree } from './workspace.js';
+import { prepareManagedExecutionWorktree, taskUsesCanonicalProjectRun } from './workspace.js';
 import { createReviewChairExecutionPlan } from './review-chair.js';
 import { taskTagWorkerPrompt } from './task-tag.js';
 import { recoverExpiredExecutions, recoverStartupOrphans as recoverStartupExecutionOrphans } from './execution-recovery.js';
@@ -100,7 +100,6 @@ export class Reconciler extends ReconcilerReviewBase {
         }, context => `effect.mergePullRequest:${context.jobId}:${String(context.data?.headSha ?? 'missing')}`));
     }
     async dispatchExecutableTasks(jobId) {
-        await this.routeExecutableTasks(await this.store.load(jobId));
         const scheduled = schedule(await this.store.load(jobId));
         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');
@@ -111,7 +110,6 @@ export class Reconciler extends ReconcilerReviewBase {
             && task.executionId === null
             && task.kind !== 'planner'
             && task.adapter !== 'orchestrator'
-            && (!['codex', 'chatgpt'].includes(task.adapter) || Boolean(task.routing))
             && dependencyReady(task, new Map(scheduled.tasks.map(item => [item.id, item]))))
             .sort((a, b) => compareTaskPriority(a, b, scheduled.priority ?? 'P2'))
             .slice(0, capacity);
@@ -368,13 +366,6 @@ export class Reconciler extends ReconcilerReviewBase {
         return withObservabilityCorrelation({ repository: job.repository, prNumber: job.prNumber, jobId: job.id, taskId: task.id }, () => this.launchCorrelated(job, task));
     }
     async launchCorrelated(job, task) {
-        const adapter = this.options.adapters.find(x => x.name === task.adapter);
-        if (!adapter) {
-            await transitionTaskEvent(task, 'fail');
-            task.error = `No adapter ${task.adapter}`;
-            await this.store.saveTask(task);
-            return;
-        }
         if (['codex', 'chatgpt'].includes(task.adapter) && !this.options.eventBus) {
             await transitionTaskEvent(task, 'block');
             task.error = 'Model-backed tasks require an event bus for authoritative lifecycle state';
@@ -383,11 +374,17 @@ export class Reconciler extends ReconcilerReviewBase {
         }
         const claimedTask = await withExecutionBoundary(job.id, task.id, async () => {
             const freshJob = await this.store.load(job.id);
-            const freshTask = freshJob.tasks.find(item => item.id === task.id);
+            let freshTask = freshJob.tasks.find(item => item.id === task.id);
             if (!freshTask || freshTask.state !== 'QUEUED' || !dependencyReady(freshTask, new Map(freshJob.tasks.map(item => [item.id, item]))))
                 return;
             if (freshTask.executionId !== null)
                 return;
+            if (!freshTask.routing && freshTask.adapter !== 'orchestrator') {
+                freshTask = (await this.routeTaskForExecution(freshJob, freshTask)).task;
+            }
+            if (['codex', 'chatgpt'].includes(freshTask.adapter) && !freshTask.routing) {
+                throw new Error('Task ' + freshTask.id + ' requires routing metadata before execution claim');
+            }
             const leaseMs = Math.max(this.options.leaseMs ?? 300000, freshTask.timeoutMs);
             const startedAt = (this.options.now ?? new Date()).getTime();
             freshTask.attempt += 1;
@@ -405,12 +402,18 @@ export class Reconciler extends ReconcilerReviewBase {
         if (!claimedTask)
             return;
         task = claimedTask;
+        const adapter = this.options.adapters.find(x => x.name === task.adapter);
+        if (!adapter) {
+            await this.failLaunch(job.id, task.id, task.executionId, 'No adapter ' + task.adapter);
+            return;
+        }
         let executionContext;
         let managedHead = null;
         try {
             const role = task.agentName === 'reviewer' ? 'reviewer' : task.agentName === 'troubleshooter' ? 'troubleshooter' : task.parentTaskId ? 'nested-worker' : 'worker';
             let projectPath = this.options.projectPathForJob ? await this.options.projectPathForJob(job) : task.routing?.cwd ?? process.cwd();
-            if (['codex', 'chatgpt'].includes(task.adapter) && this.store.pullRequestHead && task.executionId) {
+            const canonicalProjectRun = taskUsesCanonicalProjectRun(task, job.tasks);
+            if (['codex', 'chatgpt'].includes(task.adapter) && this.store.pullRequestHead && task.executionId && !canonicalProjectRun) {
                 managedHead = await this.store.pullRequestHead();
                 if (!managedHead)
                     throw new Error(`PR #${job.prNumber} has no resolvable head ref`);
@@ -433,9 +436,12 @@ export class Reconciler extends ReconcilerReviewBase {
         let execution;
         const sourceId = executionEventSource(job.id, task.id, durableExecutionId);
         const baseWorkerInput = await managedWorkerInput(job, task, executionContext);
+        const canonicalProjectRun = taskUsesCanonicalProjectRun(task, job.tasks);
         const workerInput = managedHead
             ? `${baseWorkerInput}\n\n[Managed PR checkout]\nExecution cwd: ${executionContext.project.path}\nExpected PR head: ${managedHead.ref} @ ${managedHead.sha}\nThis checkout is isolated from the user's primary checkout. Commit only here. Push durable changes with: git push origin HEAD:${managedHead.ref}\nDo not switch, reset, merge into, or commit on the primary checkout.`
-            : baseWorkerInput;
+            : canonicalProjectRun
+                ? `${baseWorkerInput}\n\n[Canonical Neo project run]\nExecution cwd: ${executionContext.project.path}\nThis Task owns or descends from a durable runs/ artifact. Work directly in this canonical project directory so all continuations, reviews, QA, and publication steps share the same runs/ evidence. Do not create or switch to an Agents Relay task worktree for this runtime work. Keep generated/private execution artifacts under runs/ and do not commit them.`
+                : baseWorkerInput;
         const workerTask = { ...task, input: workerInput, routing: task.routing ? { ...task.routing, cwd: executionContext.project.path } : task.routing };
         const startAckSetup = task.adapter === 'chatgpt' ? await this.startAck(job.id, task.id, sourceId, Date.now(), this.options.startAckTimeoutMs ?? chatGptStartAckTimeoutMs(task.timeoutMs)) : null;
         const closePolicy = task.chatgptTabClosePolicy ?? this.options.chatgptTabClosePolicy ?? adapter.tabClosePolicy ?? 'after-start';
@@ -459,7 +465,7 @@ export class Reconciler extends ReconcilerReviewBase {
         void (execution.launched ?? Promise.resolve()).then(() => this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.process.launched', 'running', `Task ${task.id} process launched`, 'user', { adapter: adapter.id, model: task.routing?.model }, { agent: 'relay', component: 'agents-relay' }))).catch(error => this.failLaunch(job.id, task.id, durableExecutionId, error instanceof Error ? error.message : String(error), 'launch'));
         if (startAckSetup)
             void startAckSetup.ack.finally(() => { void startAckSetup.stop(); }).catch(() => { });
-        this.live.set(task.id, { jobId: job.id, taskId: task.id, executionId: durableExecutionId, execution, controller, launchBarrier: Date.now(), workerStarted: false, processSettled: false });
+        this.live.set(task.id, { jobId: job.id, taskId: task.id, executionId: durableExecutionId, execution, controller, launchBarrier: startedAt, workerStarted: false, processSettled: false });
         this.registerExecutionOwner(job.id, task.id, durableExecutionId);
         observability().record({
             stage: 'transition', event: 'task.dispatch', outcome: 'succeeded',

package/dist/relayd.js

@@ -13,10 +13,10 @@ import { ProjectedDurableStore } from './projected-store.js';
 import { discoverLocalRelayStoreSnapshots, relayStorePath, SQLiteRelayStore } from './relay-store.js';
 import { githubAuthContext } from './github-auth.js';
 import { dashboardJobAction, isEntrypoint, runtimePlanner, runtimeReviewer, startService, SERVICE_DEFAULTS } from './cli.js';
-import { eventBusResolutionMessage, publishOrchestratorTaskCompletion, resolveEventBus } from './cli-support.js';
+import { eventBusResolutionMessage, publishOrchestratorTaskStarted, publishOrchestratorTaskCompletion, resolveEventBus } from './cli-support.js';
 import { eventFor } from './events.js';
 import { applyJobActivateAction } from './job-actions.js';
-import { applyOrchestratorCompleteAction } from './task-actions.js';
+import { applyOrchestratorStartAction, applyOrchestratorCompleteAction } from './task-actions.js';
 import { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
 import { codexAndZaiUsageRegistry } from './usage.js';
 import { defaultWorkspaceRoot, discoverWorkspaceRepositories, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
@@ -308,6 +308,21 @@ export async function runDaemon(argv) {
         await pool.reconcileTarget(overview.job.repository, overview.job.prNumber, jobId, 'control.task.create');
         return await store.load(jobId);
     };
+    const workspaceTaskStart = async (jobId, taskId) => {
+        const overview = cachedOverviews.find(item => item.job.id === jobId);
+        if (!overview)
+            throw new Error(`Managed job ${jobId} not found`);
+        const store = runtimeStore(overview.job.repository, overview.job.prNumber);
+        const job = await store.load(jobId);
+        const task = job.tasks.find(item => item.id === taskId);
+        if (!task)
+            throw new Error(`Task ${taskId} not found`);
+        await applyOrchestratorStartAction(task);
+        await store.saveTask(task);
+        await publishOrchestratorTaskStarted(bus, job, task);
+        await pool.reconcileTarget(overview.job.repository, overview.job.prNumber, jobId, 'control.task.start');
+        return await store.load(jobId);
+    };
     const workspaceTaskComplete = async (jobId, taskId, summary) => {
         const overview = cachedOverviews.find(item => item.job.id === jobId);
         if (!overview)
@@ -388,6 +403,7 @@ export async function runDaemon(argv) {
         cancel: workspaceJobAction('cancel'),
         jobSetState: workspaceJobSetState,
         taskCreate: workspaceTaskCreate,
+        taskStart: workspaceTaskStart,
         taskRetry: workspaceTaskAction('retry'),
         taskCancel: workspaceTaskAction('cancel'),
         taskComplete: workspaceTaskComplete,

package/dist/task-actions.js

@@ -5,6 +5,7 @@ export const TASK_UNBLOCK_RETRY_ACTION = 'task.unblock.retry';
 export const TASK_CANCEL_ACTION = 'task.cancel';
 export const TASK_RELEASE_ACTION = 'task.release';
 export const TASK_HOLD_ACTION = 'task.hold';
+export const TASK_START_ACTION = 'task.start';
 export const TASK_COMPLETE_ACTION = 'task.complete';
 export const TASK_QUEUE_ACTION = 'task.queue';
 function lifecycleRejection(task, action) {
@@ -79,12 +80,29 @@ export async function applyTaskQueueAction(job, task) {
     clearExecution(task);
     return task;
 }
+export async function applyOrchestratorStartAction(task) {
+    if (task.adapter !== 'orchestrator')
+        throw new Error('task start is only valid for adapter=orchestrator self-tasks');
+    const originalState = task.state;
+    try {
+        await transitionTaskEvent(task, 'task.started');
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('No enabled workflow transition')) {
+            throw new Error(`Task ${task.id} is ${originalState}; only QUEUED orchestrator tasks can be started`);
+        }
+        throw error;
+    }
+    task.attempt = Math.max(task.attempt, 1);
+    task.updatedAt = new Date().toISOString();
+    return task;
+}
 export async function applyOrchestratorCompleteAction(task, summary) {
     if (task.adapter !== 'orchestrator')
         throw new Error('task complete is only valid for adapter=orchestrator self-tasks');
     const originalState = task.state;
-    tryTransitionTaskEvent(task, 'task.started');
-    task.attempt = Math.max(task.attempt, 1);
+    if (task.state !== 'RUNNING')
+        throw new Error(`Task ${task.id} is ${originalState}; orchestrator task must be started before completion`);
     task.result = { summary };
     clearExecution(task);
     try {
@@ -92,7 +110,7 @@ export async function applyOrchestratorCompleteAction(task, summary) {
     }
     catch (error) {
         if (error instanceof Error && error.message.startsWith('No enabled workflow transition')) {
-            throw new Error(`Task ${task.id} is ${originalState}; only QUEUED or RUNNING orchestrator tasks can be completed`);
+            throw new Error(`Task ${task.id} is ${originalState}; only RUNNING orchestrator tasks can be completed`);
         }
         throw error;
     }
@@ -127,6 +145,8 @@ export async function dispatchTaskAction(store, request) {
         await applyTaskReleaseAction(task);
     else if (request.id === TASK_HOLD_ACTION)
         await applyTaskHoldAction(task);
+    else if (request.id === TASK_START_ACTION)
+        await applyOrchestratorStartAction(task);
     else if (request.id === TASK_QUEUE_ACTION)
         await applyTaskQueueAction(job, task);
     else

package/dist/workspace.js

@@ -92,6 +92,24 @@ export function resolveRepositoryProjectPath(repositoryRoot, projectPath) {
         throw new Error('Job projectPath escapes repository root');
     return target;
 }
+export function isProjectRunPath(path) {
+    if (!path)
+        return false;
+    const normalized = path.replace(/\\/g, '/').replace(/^\.\//, '');
+    return normalized === 'runs' || normalized.startsWith('runs/');
+}
+export function taskUsesCanonicalProjectRun(task, tasks) {
+    const byId = new Map(tasks.map(item => [item.id, item]));
+    const seen = new Set();
+    let current = task;
+    while (current && !seen.has(current.id)) {
+        seen.add(current.id);
+        if (current.output?.kind === 'file' && isProjectRunPath(current.output.path))
+            return true;
+        current = current.parentTaskId ? byId.get(current.parentTaskId) : undefined;
+    }
+    return false;
+}
 async function git(path, args) {
     return (await execFileAsync('git', ['-C', path, ...args])).stdout.trim();
 }

package/package.json

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

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

@@ -32,6 +32,15 @@ If an intermediate result does not need that independent lifecycle, keep it insi
 
 Keep sibling Tasks at a comparable abstraction level. Do not mix a whole product milestone with tiny implementation steps as peers.
 
+### Architecture Lens
+
+When the resolved project context exposes a canonical design-principles
+document or architecture contract, identify the principles materially relevant
+to each architecture-sensitive Task. Put only the resulting task-specific
+questions, constraints, or already-decided answers in that Task's input. Do not
+copy the full project principles into every Task. For Agents Relay itself, use
+DESIGN-PRINCIPLES.md and its Architecture Lens.
+
 The graph is the explanation for the decomposition: every emitted Task should map to a meaningful boundary in the graph, and important graph boundaries should not be omitted accidentally.
 
 ### Semantic ownership vs execution flow

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

@@ -125,12 +125,34 @@ The scheduler heartbeat filters cached managed Jobs, reloads each due Job to val
 
 ## Task evidence and head identity
 
+### Canonical Neo Project runs boundary
+
+`runs/` is durable runtime evidence, not source code and not temporary checkout state. When a Task's declared file output is under `runs/`, that Task and every semantic descendant execute directly in the canonical resolved project directory. Agents Relay MUST NOT create or switch those Tasks into per-execution Git worktrees.
+
+This is a strong execution boundary:
+
+- tracked source/code work may use a managed PR worktree;
+- Neo Project runtime work under `runs/` uses the canonical project directory;
+- continuations, reviews, QA, render, and publication Tasks beneath a `runs/` owner reuse that same canonical runtime directory;
+- `runs/` remains ignored/private and must not be committed merely to move evidence between Tasks;
+- a new Task/worktree must never make prior run evidence disappear.
+
+For example, a `neo-build-log` episode whose output is `runs/2026-10-02/package.md` executes in the canonical `neo/neo-build-log` project directory, and its review/render/publish descendants see the same `runs/2026-10-02/` tree.
+
 Task inputs must make evidence freshness and target identity explicit when those facts affect correctness. A Task may bind its own review, audit, or source evidence to an immutable SHA/version. That frozen target belongs to that Task; it must not be propagated mechanically into later dependent work. A downstream release, deploy, publication, or other Task that runs after dependencies complete must resolve the current durable Job/PR head at execution time unless the Job objective explicitly requires the earlier immutable target.
 
 When success depends on the actual current UI, browser state, store listing, runtime state, or another externally observable surface, the Task contract must require fresh evidence from that real current surface. Reusing an existing screenshot, prepared asset, cached observation, or older evidence is valid only when the Job explicitly permits it.
 
 This does not weaken immutable review semantics: final review and specialist review Tasks should continue to declare and inspect one exact immutable target/version.
 
+When project context exposes a canonical design-principles or architecture
+contract, Final Review must also verify the reviewed immutable target against
+the principles that materially apply to the Job objective and changed area.
+The reviewer should consume that project context rather than duplicating the
+full architecture contract in the review Task. A second authority path or
+stateful action is a blocking architecture finding when the project contract
+forbids it.
+
 ## Dependency vs block and authoritative unblock
 
 `dependencies` describe normal DAG ordering. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; Relay simply releases dependent work when its prerequisites succeed. `BLOCKED` is different: it records that execution reached a runtime/external condition that invalidates normal progress.