agents-relay 2.0.53 → 2.0.54

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

@@ -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,6 +402,11 @@ 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 {
@@ -459,7 +461,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.53",
+  "version": "2.0.54",
   "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

@@ -131,6 +131,14 @@ When success depends on the actual current UI, browser state, store listing, run
 
 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.