agents-relay 2.0.265 → 2.0.266

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -124,7 +124,12 @@ export async function buildRelayWorkPrompt(input) {
124
124
  `EVENT SOURCE (exact): job/${input.jobId}/task/${input.taskId}/execution/${input.executionId}`,
125
125
  'START: After Bootstrap and the minimal event-contract preflight, publish `task.started` through the canonical events-bus before beginning Task work. Verify the publish response.',
126
126
  'PROGRESS: Publish `task.progress` with concrete progress/evidence during long-running work and before the inactivity timeout. Progress is not completion.',
127
- 'TERMINAL: After verifying durable output, publish exactly ONE `task.completed`; if you cannot fulfill the Task, publish `task.failed` with phase, reason and evidence. Do not silently exit or treat a process/browser receipt as completion.',
127
+ ...(input.sourceCommitRequired ? [
128
+ 'SOURCE DELIVERY (MANDATORY): After self review and tests, commit the actual source changes on this Job Git branch. The LAST commit must contain exact trailers `Relay-Task: ' + input.taskId + '` and `Relay-Execution: ' + input.executionId + '`. Do not stage other Workers changes or leave untracked source files.',
129
+ 'SOURCE TERMINAL: Do NOT publish task.completed on the Event Bus. Instead run the matching package CLI: `agents-relay task complete --repo <local-repository-name> --id ' + input.jobId + ' --task-id ' + input.taskId + ' --execution-id ' + input.executionId + ' --commit-sha $(git rev-parse HEAD) --summary <evidence>`. Relay validates the commit and emits completion. A direct task.completed event is rejected. Report task.failed only on a verified unresolvable blocker.',
130
+ ] : [
131
+ 'TERMINAL: After verifying durable output, publish exactly ONE `task.completed`; if you cannot fulfill the Task, publish `task.failed` with phase, reason and evidence. Do not silently exit or treat a process/browser receipt as completion.',
132
+ ]),
128
133
  'INTERACTIVE REVIEW: If this Job requires review, use only the review action and binding supplied by its Execution Context. Relay owns the suspension and resume state. Never invent a review tool or emit a terminal event while awaiting review. After resumption read the authoritative Task Context for the decision.',
129
134
  'Every event MUST use the exact source above. Do not publish `task.blocked` or `task.unblocked`; those are Relay-owned states. Relay must accept the correlated event.',
130
135
  ]),
package/dist/cli-help.js CHANGED
@@ -180,7 +180,7 @@ Returns the same summary used by the dashboard header plus a running array with
180
180
  task: `Manage durable tasks.
181
181
 
182
182
  Usage:
183
- npx agents-relay task <create|update|show|events|list|revise|retry|unblock|cancel> [options]
183
+ npx agents-relay task <create|update|show|events|list|revise|complete|retry|unblock|cancel> [options]
184
184
 
185
185
  Actions:
186
186
  create Create one durable Task under an existing Job
@@ -190,7 +190,7 @@ Actions:
190
190
  revise Submit an immutable-head targeted reviewer fix request
191
191
  retry Retry a FAILED Task
192
192
  unblock Authoritatively invalidate a BLOCKED decision
193
- complete Complete an orchestrator-owned Task
193
+ complete Verify a source Worker Git Commit, then atomically finish the current execution
194
194
  cancel Cancel a Task`,
195
195
  'task create': `Create one durable Task under an existing Job.
196
196
 
@@ -210,6 +210,15 @@ Use --clear-routing to remove routing metadata.
210
210
 
211
211
  Example:
212
212
  npx agents-relay task update --repo LOCAL_ROOT_NAME --id 101 --task-id 202 --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high`,
213
+ 'task complete': `Complete a commit-required source Task through the Relay daemon. Direct task.completed Event Bus submissions cannot complete such a Task.
214
+
215
+ Required: --repo LOCAL_ROOT_NAME --id JOB_ID --task-id TASK_ID --execution-id CURRENT_EXECUTION --commit-sha FULL_GIT_SHA --summary TEXT.
216
+
217
+ Before calling, commit the Task changes on the Job source branch and ensure its checkout is fully clean. The final commit message must contain exact trailers:
218
+ Relay-Task: TASK_ID
219
+ Relay-Execution: CURRENT_EXECUTION
220
+
221
+ Relay verifies the current execution's started Git baseline, source branch HEAD, nonempty new commit, commit trailers, exact worktree and clean tracked/untracked status. It saves the proof and transitions the Task through the canonical lifecycle graph; retries with the same accepted proof are idempotent. A mismatched or uncommitted source cannot succeed. Historical pre-enforcement Tasks keep their original event contract.`,
213
222
  'task revise': `Authenticated immutable-head targeted revision request from the active Final Reviewer.
214
223
 
215
224
  Required: --repo LOCAL_ROOT_NAME --id JOB --task-id ORIGINAL --review-task-id FINAL_REVIEW --execution-id CURRENT_REVIEW_EXECUTION --head-sha EXACT_SHA --request-id STABLE_ID --findings-file PATH. The findings file contains a nonempty JSON array [{"id":"F-1","summary":"...","evidence":"..."}].
@@ -0,0 +1,12 @@
1
+ import { arg, relayControlCommand } from './cli-support.js';
2
+ /** Version-matched CLI is a request only; the daemon validates Git and owns Task success. */
3
+ export async function runTaskCompleteCommand(args) {
4
+ const jobId = arg(args, '--id'), taskId = arg(args, '--task-id');
5
+ const executionId = arg(args, '--execution-id'), commitSha = arg(args, '--commit-sha');
6
+ if (!jobId || !taskId || !executionId || !commitSha || !arg(args, '--repo'))
7
+ throw new Error('task complete requires --repo, --id, --task-id, --execution-id and --commit-sha');
8
+ const result = await relayControlCommand(args, { command: 'task.complete', jobId, taskId,
9
+ executionId, commitSha, repository: arg(args, '--repo'),
10
+ summary: arg(args, '--summary') || `Source Task ${taskId} committed ${commitSha}` });
11
+ console.log(JSON.stringify(result, null, 2));
12
+ }
package/dist/cli.js CHANGED
@@ -46,6 +46,7 @@ export { runtimeReviewer } from './reviewer-thread.js';
46
46
  import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, newLocalRepository, storeFor, saveLocal, eventBus, publishWake, priority, storySize, chatGptTabClosePolicy, continuation, rejectRemovedJobOptions, rejectRemoteLifecycleOptions, jobTagFromArgs, requestManagedReconciliation, relayControlJob, relayControlCommand, relayJobList, optionalLegacyPr, relayJobStateCommand, relayTaskCommand, withEventBus } from './cli-support.js';
47
47
  export { SERVICE_DEFAULTS, eventBus, chatGptTabClosePolicy } from './cli-support.js';
48
48
  import { dependencyValidityFromArgs, recoveryDiagnosisFromArgs, workerTaskFromArgs } from './cli-worker-task.js';
49
+ import { runTaskCompleteCommand } from './cli-task-complete.js';
49
50
  import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
50
51
  import { pauseJob, resumeJob } from './job-pause.js';
51
52
  export { ensureManagedGitHubJob } from './cli-job-create.js';
@@ -81,12 +82,16 @@ async function runManagedTaskCommand(action, args) {
81
82
  async function runTaskCommand(action, args) {
82
83
  if (hasArg(args, '--shortcut-local'))
83
84
  throw Error('Legacy Shortcut local binding is removed');
84
- if (!['create', 'update', 'show', 'context', 'events', 'comment', 'comments', 'list', 'retry', 'recover', 'unblock', 'escalate', 'resume-troubleshooter', 'cancel', 'supersede', 'classify', 'revise'].includes(action))
85
+ if (!['create', 'update', 'show', 'context', 'events', 'comment', 'comments', 'list', 'retry', 'recover', 'unblock', 'escalate', 'resume-troubleshooter', 'cancel', 'supersede', 'classify', 'revise', 'complete'].includes(action))
85
86
  throw new Error(usage);
86
87
  if (action === 'revise') {
87
88
  await runTaskReviseCommand(args);
88
89
  return;
89
90
  }
91
+ if (action === 'complete') {
92
+ await runTaskCompleteCommand(args);
93
+ return;
94
+ }
90
95
  if (action === 'context' || action === 'events') {
91
96
  await (action === 'context' ? runTaskContextCommand(args) : runTaskEventsCommand(args));
92
97
  return;
@@ -0,0 +1,112 @@
1
+ import { execFileSync } from 'node:child_process';
2
+ import { realpathSync } from 'node:fs';
3
+ import { isFinalReviewAgent } from './final-review-role.js';
4
+ const SHA = /^[a-f0-9]{40,64}$/i;
5
+ const SOURCE_REF = /^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]*$/;
6
+ /** Source delivery policy is fixed when the Task is created, not inferred from event data. */
7
+ export function sourceCommitRequired(task) {
8
+ return task.output?.kind === 'task_pr' && task.kind !== 'planner' && !task.agentGraph
9
+ && !isFinalReviewAgent(task.agentName)
10
+ && !['troubleshooter', 'planner', 'review-chair'].includes(task.agentName ?? '');
11
+ }
12
+ function git(cwd, ...args) {
13
+ return execFileSync('git', ['-C', cwd, ...args], { encoding: 'utf8', timeout: 8000,
14
+ stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 }).trim();
15
+ }
16
+ function root(job) {
17
+ if (!job.projectRoot || !job.repository)
18
+ throw new Error('Git delivery requires a canonical Job projectRoot');
19
+ const path = realpathSync(job.projectRoot);
20
+ if (realpathSync(git(path, 'rev-parse', '--show-toplevel')) !== path)
21
+ throw new Error('Git delivery projectRoot is not the canonical Git root');
22
+ return path;
23
+ }
24
+ function ref(job) {
25
+ const value = job.localMerge?.sourceRef;
26
+ if (!value || !SOURCE_REF.test(value) || value.includes('..') || value.endsWith('.lock'))
27
+ throw new Error('Git delivery requires a configured local Job source branch');
28
+ return value;
29
+ }
30
+ /** Read-only Git facts; event senders cannot select a different repository or branch. */
31
+ export function sourceCommitSha(job) {
32
+ return git(root(job), 'rev-parse', '--verify', `${ref(job)}^{commit}`);
33
+ }
34
+ /** Snapshot the source head before any Worker's code edits; persist it with this execution. */
35
+ export function startedSourceBaseline(job, taskId) {
36
+ const task = job.tasks.find(item => item.id === taskId);
37
+ return task?.gitDeliveryRequired ? sourceCommitSha(job) : null;
38
+ }
39
+ export function bindSourceBaseline(task, sha) {
40
+ if (task.gitDeliveryRequired && sha && task.executionId) {
41
+ task.gitDeliveryBaseline = { executionId: task.executionId, sha };
42
+ task.gitDelivery = undefined;
43
+ }
44
+ }
45
+ function ownedWorktree(job) {
46
+ const project = root(job);
47
+ const wanted = ref(job);
48
+ const matches = git(project, 'worktree', 'list', '--porcelain').split(/\n\s*\n/).filter(Boolean)
49
+ .map(record => {
50
+ const lines = record.split('\n');
51
+ return { path: lines.find(line => line.startsWith('worktree '))?.slice(9),
52
+ branch: lines.find(line => line.startsWith('branch '))?.slice(7) };
53
+ }).filter(item => item.branch === wanted && item.path);
54
+ if (matches.length !== 1)
55
+ throw new Error('Git delivery requires exactly one checked-out source branch worktree');
56
+ const path = realpathSync(matches[0].path);
57
+ if (git(path, 'symbolic-ref', 'HEAD') !== wanted)
58
+ throw new Error('Git delivery branch changed');
59
+ return path;
60
+ }
61
+ /** Validate exact execution/branch binding, a new nonempty commit and a fully clean source worktree. */
62
+ export function verifySourceCommit(job, task, executionId, commitSha) {
63
+ if (!task.gitDeliveryRequired || task.state !== 'RUNNING' || task.executionId !== executionId)
64
+ throw new Error('Git delivery requires an active source Task execution');
65
+ const baseline = task.gitDeliveryBaseline;
66
+ if (!baseline || baseline.executionId !== executionId || !SHA.test(baseline.sha))
67
+ throw new Error('Git delivery is missing the current execution start baseline');
68
+ if (!SHA.test(commitSha))
69
+ throw new Error('Git delivery requires a full commit SHA');
70
+ const actual = sourceCommitSha(job);
71
+ if (commitSha === baseline.sha)
72
+ throw new Error('Git delivery requires a new committed source branch HEAD');
73
+ const path = ownedWorktree(job);
74
+ if (git(path, 'rev-parse', '--verify', 'HEAD') !== actual)
75
+ throw new Error('Git delivery source worktree HEAD differs from branch');
76
+ if (git(path, 'status', '--porcelain=v1', '--untracked-files=all'))
77
+ throw new Error('Git delivery source worktree has uncommitted or untracked changes');
78
+ try {
79
+ git(path, 'merge-base', '--is-ancestor', baseline.sha, commitSha);
80
+ }
81
+ catch {
82
+ throw new Error('Git delivery commit does not descend from execution baseline');
83
+ }
84
+ try {
85
+ git(path, 'merge-base', '--is-ancestor', commitSha, actual);
86
+ }
87
+ catch {
88
+ throw new Error('Git delivery commit is not on the current Job source branch');
89
+ }
90
+ // An unrelated Worker may advance Job HEAD after this Worker commits.
91
+ // Verify the Task-owned commit itself, not the newest commit by another Worker.
92
+ const message = git(path, 'log', '-1', '--format=%B', commitSha).split('\n').map(line => line.trim());
93
+ if (!message.includes(`Relay-Task: ${task.id}`) || !message.includes(`Relay-Execution: ${executionId}`))
94
+ throw new Error('Git delivery commit must contain exact Relay-Task and Relay-Execution trailers');
95
+ if (!git(path, 'diff-tree', '--no-commit-id', '--name-only', '-r', commitSha))
96
+ throw new Error('Git delivery requires a nonempty code commit');
97
+ return { executionId, baseSha: baseline.sha, commitSha, worktree: path, verifiedAt: new Date().toISOString() };
98
+ }
99
+ /** Persisted proof alone is never sufficient: validate live Git again on every terminal ingress. */
100
+ export function sourceCompletionVerified(job, task, executionId) {
101
+ if (!task.gitDeliveryRequired)
102
+ return true;
103
+ if (!executionId || task.gitDelivery?.executionId !== executionId)
104
+ return false;
105
+ try {
106
+ const current = verifySourceCommit(job, task, executionId, task.gitDelivery.commitSha);
107
+ return current.baseSha === task.gitDelivery.baseSha && current.worktree === task.gitDelivery.worktree;
108
+ }
109
+ catch {
110
+ return false;
111
+ }
112
+ }
@@ -61,6 +61,7 @@ export async function managedWorkerInput(job, task, context, mode = 'production'
61
61
  skillPath: join(packageRoot, 'skills/agents-relay/SKILL.md'),
62
62
  taskTitle: task.title,
63
63
  workerSelfReview: role === 'worker',
64
+ sourceCommitRequired: task.gitDeliveryRequired === true,
64
65
  jobId: job.id,
65
66
  taskId: task.id,
66
67
  executionId: task.executionId,
@@ -19,6 +19,7 @@ import { monitorExecutionProcess } from './execution-process-tracker.js';
19
19
  import { HostInteractiveInvocationCoordinator, hostInvocationPorts } from './interactive-invocation.js';
20
20
  import { resumeInteractiveTask } from './interactive-resume.js';
21
21
  import { acceptTaskProgress, armInactivityWatchdog, inactivityDeadline, isCorrelatedWorkerEvent, isRecoverableWatchdogFailure } from './task-inactivity-watchdog.js';
22
+ import { startedSourceBaseline, bindSourceBaseline, sourceCompletionVerified } from './git-delivery.js';
22
23
  const activeExecutionOwners = new Map();
23
24
  import { withExecutionBoundary } from './execution-boundary.js';
24
25
  export { withExecutionBoundary } from './execution-boundary.js';
@@ -216,6 +217,7 @@ export class ReconcilerRuntimeBase {
216
217
  }
217
218
  async markWorkerStarted(event) {
218
219
  const live = this.live.get(event.task_id);
220
+ const baseline = startedSourceBaseline(await this.store.load(event.job_id), event.task_id);
219
221
  const transition = await this.taskTransitions.apply(event.job_id, event.task_id, 'task.started', {
220
222
  eligible: (job, task) => {
221
223
  if (!task.executionId || eventSourceId(event) !== executionEventSource(job.id, task.id, task.executionId))
@@ -231,6 +233,7 @@ export class ReconcilerRuntimeBase {
231
233
  && Boolean(task.executionId && eventSourceId(event) === executionEventSource(event.job_id, task.id, task.executionId)),
232
234
  }),
233
235
  mutate: (_job, task) => {
236
+ bindSourceBaseline(task, baseline);
234
237
  task.updatedAt = task.lastProgressAt = new Date().toISOString();
235
238
  task.lastProgressEventAt = event.timestamp;
236
239
  },
@@ -422,6 +425,8 @@ export class ReconcilerRuntimeBase {
422
425
  return false;
423
426
  if (isFinalReviewAgent(task.agentName) && event.type === 'task.completed')
424
427
  return false;
428
+ if (event.type === 'task.completed' && !sourceCompletionVerified(_job, task, terminalEventExecutionId ?? null))
429
+ return false;
425
430
  if (event.type === 'task.completed' && task.interactiveInvocation?.status !== undefined && task.interactiveInvocation.status !== 'approved')
426
431
  return false; // current interactive revision requires durable approval
427
432
  const modelBacked = ['codex', 'chatgpt', 'z', 'script'].includes(task.adapter);
@@ -437,7 +442,7 @@ export class ReconcilerRuntimeBase {
437
442
  facts: (_job, task) => {
438
443
  const processExitedAfterPublishedTerminal = task.failureReason === 'worker_exit_without_terminal_event';
439
444
  const freshEnough = processExitedAfterPublishedTerminal || isCorrelatedWorkerEvent(task, event);
440
- return { recoverableExecution: isRecoverableWatchdogFailure(task) && freshEnough, awaitingInteractiveDecision: lifecycleEvent === 'task.interactive_waiting' && task.interactiveInvocation?.status === 'awaiting_decision' };
445
+ return { recoverableExecution: isRecoverableWatchdogFailure(task) && freshEnough, awaitingInteractiveDecision: lifecycleEvent === 'task.interactive_waiting' && task.interactiveInvocation?.status === 'awaiting_decision', sourceDeliveryVerified: sourceCompletionVerified(_job, task, terminalEventExecutionId ?? null) };
441
446
  },
442
447
  mutate: (job, task) => {
443
448
  const modelBacked = ['codex', 'chatgpt', 'z', 'script'].includes(task.adapter);
@@ -1,6 +1,9 @@
1
1
  import { submitTargetedRevisionRequest } from './review-revision-model.js';
2
2
  import { beginInteractiveReview, abortInteractiveReview, failInteractiveReview, interactiveWaitingEvent } from './interactive-request.js';
3
3
  import { localSourceHead, localWorkingHead } from './local-git-merge.js';
4
+ import { verifySourceCommit } from './git-delivery.js';
5
+ import { eventFor } from './events.js';
6
+ import { executionEventSource } from './execution-event-identity.js';
4
7
  import { appendTaskComment } from './task-comments.js';
5
8
  import { InMemoryStore } from './store.js';
6
9
  import { openLocalManagedStore } from './local-managed-store.js';
@@ -211,6 +214,48 @@ export function createWorkspaceControl(deps) {
211
214
  // The committed receipt must not be obscured by an unrelated wake failure.
212
215
  return response;
213
216
  }
217
+ if (command === 'task.complete') {
218
+ const taskId = typeof body.taskId === 'string' ? body.taskId : '';
219
+ const executionId = typeof body.executionId === 'string' ? body.executionId : '';
220
+ const commitSha = typeof body.commitSha === 'string' ? body.commitSha : '';
221
+ const repository = typeof body.repository === 'string' ? body.repository : '';
222
+ const summary = typeof body.summary === 'string' ? body.summary.trim() : '';
223
+ if (!taskId || !executionId || !commitSha || !summary || repository !== job.repository || summary.length > 4000)
224
+ throw new Error('task.complete requires matching repository, Task/Execution IDs, commit SHA and bounded summary');
225
+ const original = job.tasks.find((item) => item.id === taskId);
226
+ if (!original || !original.gitDeliveryRequired)
227
+ throw new Error('task.complete is for commit-required source Tasks only');
228
+ if (original.state === 'SUCCEEDED' && original.gitDelivery?.executionId === executionId && original.gitDelivery.commitSha === commitSha)
229
+ return { accepted: true, idempotent: true, task: original };
230
+ const receipt = verifySourceCommit(job, original, executionId, commitSha);
231
+ await store.mutateJob(jobId, (current) => {
232
+ const task = current.tasks.find((item) => item.id === taskId);
233
+ if (!task || !task.gitDeliveryRequired || task.state !== 'RUNNING' || task.executionId !== executionId
234
+ || task.gitDeliveryBaseline?.executionId !== receipt.executionId || task.gitDeliveryBaseline.sha !== receipt.baseSha)
235
+ throw new Error('task.complete refused: stale or replaced source Task execution');
236
+ task.gitDelivery = receipt;
237
+ task.updatedAt = new Date().toISOString();
238
+ return current;
239
+ });
240
+ const reconciler = makeReconciler(store, concurrency);
241
+ const event = eventFor(jobId, taskId, original.parentTaskId, 'task.completed', 'succeeded', summary, 'worker', { commit_sha: commitSha, verified_git_delivery: true }, { id: executionEventSource(jobId, taskId, executionId), agent: original.agentName ?? 'worker', component: 'agents-relay-cli' });
242
+ try {
243
+ const outcome = await reconciler.applyEvent(event);
244
+ if (!outcome.applied)
245
+ throw new Error('task.complete rejected by Task Graph: ' + outcome.reason);
246
+ try {
247
+ await bus?.publish(event);
248
+ }
249
+ catch (error) {
250
+ process.stderr.write(`warning: task.complete event transport: ${String(error)}\n`);
251
+ }
252
+ }
253
+ finally {
254
+ await reconciler.close();
255
+ }
256
+ await pool.reconcileLocalJob(jobId, 'control.task.complete');
257
+ return { accepted: true, task: (await store.load(jobId)).tasks.find((item) => item.id === taskId) };
258
+ }
214
259
  if (command === 'task.comment') {
215
260
  const taskId = typeof body.taskId === 'string' ? body.taskId : '';
216
261
  const message = typeof body.message === 'string' ? body.message : '';
@@ -5,7 +5,7 @@ import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES, }
5
5
  const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'AWAITING_DECISION', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
6
6
  const JOB_STATES = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'];
7
7
  const conditionRegistry = new ConditionRegistry([
8
- ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'troubleshooterTask', 'awaitingInteractiveDecision', 'retryAvailable', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady'])
8
+ ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'sourceDeliveryVerified', 'troubleshooterRecovery', 'troubleshooterTask', 'awaitingInteractiveDecision', 'retryAvailable', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady'])
9
9
  ].map(booleanCondition));
10
10
  const boolGuard = (name) => conditionRegistry.guard(name);
11
11
  export const lifecycleConditions = conditionRegistry;
@@ -31,6 +31,7 @@ export const taskLifecycleV2 = load('task-lifecycle', TASK_STATES, {
31
31
  dispatchable: boolGuard('dispatchable'),
32
32
  shortcutEffectsSafe: facts => facts.durableFacts.shortcutEffectsSafe === true,
33
33
  recoverableExecution: boolGuard('recoverableExecution'),
34
+ sourceDeliveryVerified: boolGuard('sourceDeliveryVerified'),
34
35
  troubleshooterRecovery: boolGuard('troubleshooterRecovery'),
35
36
  troubleshooterTask: boolGuard('troubleshooterTask'),
36
37
  awaitingInteractiveDecision: facts => facts.durableFacts.awaitingInteractiveDecision === true,
@@ -1,6 +1,7 @@
1
1
  import { dispatchJobLifecycleSync, dispatchTaskLifecycleSync } from './lifecycle.js';
2
2
  import { deriveTaskTitle } from '../task-title.js';
3
3
  import { validateDependencyValidity } from '../dependency-validity.js';
4
+ import { sourceCommitRequired } from '../git-delivery.js';
4
5
  function dependenciesSatisfied(job, dependencies) {
5
6
  if (dependencies.length === 0)
6
7
  return true;
@@ -23,7 +24,7 @@ function validateTaskRequirements(value) {
23
24
  */
24
25
  export function createTaskEntity(job, value, options = {}) {
25
26
  validateTaskRequirements(value);
26
- const task = { ...value, title: value.title?.trim() || deriveTaskTitle(value.input, value.agentName ? `${value.agentName} task` : 'Task'), state: 'DRAFT' };
27
+ const task = { ...value, gitDeliveryRequired: sourceCommitRequired(value), title: value.title?.trim() || deriveTaskTitle(value.input, value.agentName ? `${value.agentName} task` : 'Task'), state: 'DRAFT' };
27
28
  if (!options.defer) {
28
29
  dispatchTaskLifecycleSync(task, 'reconcile', {
29
30
  dependenciesSatisfied: dependenciesSatisfied(job, task.dependencies),
@@ -26,7 +26,7 @@ function v2WorkflowDecision(runtime, from, event, facts = {}) {
26
26
  };
27
27
  }
28
28
  export function decideTaskLifecycle(task, event, facts = {}) {
29
- return v2WorkflowDecision(taskLifecycleV2, task.state, event, { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' });
29
+ return v2WorkflowDecision(taskLifecycleV2, task.state, event, { ...facts, troubleshooterTask: task.agentName === 'troubleshooter', sourceDeliveryVerified: facts.sourceDeliveryVerified !== false });
30
30
  }
31
31
  export function decideJobLifecycle(job, event, facts = {}) {
32
32
  return v2WorkflowDecision(jobLifecycleV2, job.state, event, facts);
@@ -36,7 +36,7 @@ export function dispatchTaskLifecycleSync(task, event, facts = {}) {
36
36
  const result = dispatchWorkflowGraphSync(taskLifecycleV2, {
37
37
  initialState: task.state,
38
38
  input: { transport: 'event', id: event, payload: {} },
39
- durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' },
39
+ durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter', sourceDeliveryVerified: task.gitDeliveryRequired !== true || facts.sourceDeliveryVerified === true },
40
40
  graphName: 'task-lifecycle',
41
41
  persistTransition: (_source, target) => applyTaskGraphTarget(task, target, new Date().toISOString(), event === 'task.unblocked' && task.agentName === 'troubleshooter'),
42
42
  executeAction: actionId => { actions.push(actionId); if (actionId.startsWith('mutation.'))
@@ -49,7 +49,7 @@ export function dispatchTaskLifecycleSync(task, event, facts = {}) {
49
49
  export async function dispatchTaskLifecycle(task, event, facts = {}, executeEffect, persist) {
50
50
  const actions = [];
51
51
  const result = await dispatchWorkflowGraph(taskLifecycleV2, {
52
- initialState: task.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter' },
52
+ initialState: task.state, input: { transport: 'event', id: event, payload: {} }, durableFacts: { ...facts, troubleshooterTask: task.agentName === 'troubleshooter', sourceDeliveryVerified: task.gitDeliveryRequired !== true || facts.sourceDeliveryVerified === true },
53
53
  graphName: 'task-lifecycle',
54
54
  persistTransition: async (_source, target) => { applyTaskGraphTarget(task, target, new Date().toISOString(), event === 'task.unblocked' && task.agentName === 'troubleshooter'); await persist?.(); },
55
55
  executeAction: async (actionId) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.265",
3
+ "version": "2.0.266",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -15,6 +15,10 @@ Relay owns durable Jobs and Tasks; do one-shot work directly. On Neo Master, **u
15
15
  - Deliver: optional verified non-force origin/main push after completion; never changes Job state.
16
16
  - Daemon: no Workspace scan and no `--workspace` requirement. Neo's `package.published` watcher restarts package-backed PM2 services after npm `latest` is confirmed.
17
17
 
18
+ ## Source Worker completion
19
+
20
+ New source Tasks (`gitDeliveryRequired: true`) must commit with `Relay-Task: ID` and `Relay-Execution: EXECUTION_ID` trailers, then run the matching `agents-relay task complete` CLI with `--repo --id --task-id --execution-id --commit-sha --summary`. Relay verifies clean Git HEAD and execution before emitting completion. **Never directly emit `task.completed`**. File, Reviewer, Troubleshooter and legacy Tasks retain normal events.
21
+
18
22
  ## Job Execution Lifecycle (JEL)
19
23
 
20
24
  **JEL:** Create → [Plan] → Execute → Final Review → local Merge → Completed. Plan-free Coordinator uses the same lifecycle. PASS merges; CHANGES_REQUIRED records findings and starts Planner N+1 for minimal fixes, then re-reviews. No post-success Plan. Planner/Workers use **ponytail** (YAGNI, reuse, minimal Tasks) without bypassing safety gates.
@@ -21,6 +21,7 @@ Every Implementation, Reviewer, and Troubleshooter execution publishes `task.sta
21
21
  `task.started` and `task.progress` reset the Task inactivity timeout only when Relay accepts the event for the exact current execution. Progress is nonterminal, must be newer than the last accepted progress event, and cannot extend a terminal or stale execution.
22
22
 
23
23
  - `task.completed`: assigned responsibility finished and its role-specific output is durable, regardless of whether a reviewed artifact passed.
24
+ For newly created source Tasks with `gitDeliveryRequired=true`, do **not** publish `task.completed` directly. Complete through `agents-relay task complete --repo ... --id ... --task-id ... --execution-id ... --commit-sha ... --summary ...` after a fresh Git commit. Relay validates the commit and emits the correlated Task completion itself; direct Event Bus completion is rejected.
24
25
  - `task.failed`: assigned responsibility could not be fulfilled; include failure phase, reason, and evidence in `data`.
25
26
 
26
27
  `task.blocked` and `task.unblocked` are **Relay-owned lifecycle facts**, not agent terminal outcomes. Transport acceptance is not proof Relay accepted the transition. Every lifecycle event must use the exact Job, Task, and execution source identity provided by Relay; stale/duplicate execution events cannot change current state.
@@ -10,3 +10,7 @@ For every Task that implements or changes code, configuration, documentation, me
10
10
  This worker self-review **does not replace** Relay's independent SHA-bound final Reviewer, required human approvals, Graph-managed review/revision, or delivery/merge gates. A worker must not approve its own final review, merge, or invent verification evidence.
11
11
 
12
12
  For read-only research or diagnostic Tasks, validate findings and evidence; do not invent artifact modifications or review rounds.
13
+
14
+ ## Commit-required source Tasks
15
+
16
+ If the authoritative Task Context says `gitDeliveryRequired: true`, the final self-review is followed by a **real Git commit** on the Task's Job source branch, before completion. Include exact `Relay-Task: TASK_ID` and `Relay-Execution: EXECUTION_ID` commit trailers; verify no untracked or modified source files remain. Call the same-version `agents-relay task complete` CLI with the full commit SHA and bound execution ID. This CLI is the only authorized success path for the Task. A direct `task.completed` Event Bus message is not acceptable. Missing output, dirty source, wrong commit ancestry, stale execution or failed checks are not success; keep working or report an evidenced blocker.
@@ -25,6 +25,8 @@ depUnsat["guard: dependenciesUnsatisfied"]
25
25
  runnable["guard: runnable"]
26
26
  dispatchable["guard: dispatchable"]
27
27
  recoverStart["guard: recoverableExecution"]
28
+ sourceDeliveryReady["guard: sourceDeliveryVerified"]
29
+ recoverSourceDeliveryReady["guard: sourceDeliveryVerified"]
28
30
  recoverComplete["guard: recoverableExecution"]
29
31
  recoverBlocked["guard: recoverableExecution"]
30
32
  recoverFailed["guard: recoverableExecution"]
@@ -173,7 +175,8 @@ running -->|on: review.changes_required| reviewChangesRunningClearError
173
175
  reviewChangesRunningClearError --> reviewChangesRunningClearReason
174
176
  reviewChangesRunningClearReason --> succeeded
175
177
  running -->|on: review.blocked| runningBlockAllowed
176
- running -->|on: task.completed| completeClearError
178
+ running -->|on: task.completed| sourceDeliveryReady
179
+ sourceDeliveryReady -->|true| completeClearError
177
180
  completeClearError --> completeClearReason
178
181
  completeClearReason --> succeeded
179
182
  running -->|on: task.failed| failed
@@ -213,7 +216,8 @@ failed -->|on: task.started| recoverStart
213
216
  recoverStart -->|true| recoverStartClearError
214
217
  recoverStartClearError --> recoverStartClearReason
215
218
  recoverStartClearReason --> running
216
- failed -->|on: task.completed| recoverComplete
219
+ failed -->|on: task.completed| recoverSourceDeliveryReady
220
+ recoverSourceDeliveryReady -->|true| recoverComplete
217
221
  recoverComplete -->|true| recoverCompleteClearError
218
222
  recoverCompleteClearError --> recoverCompleteClearReason
219
223
  recoverCompleteClearReason --> succeeded