agents-relay 2.0.232 → 2.0.234

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.
package/README.md CHANGED
@@ -79,7 +79,7 @@ These paths always represent the current canonical graphs. Historical graph defi
79
79
 
80
80
  ## Quick start
81
81
 
82
- For new work, create a local Job through Agents Relay. Use `job adopt` to bind a known legacy PR number without GitHub access; the external GitHub projection creates a display PR after the first meaningful code commit. Tasks are validated against the SQLite Job, not GitHub markers.
82
+ For new work, create a local Job through Agents Relay. The external GitHub projection may create a display PR after the first meaningful code commit. Tasks are validated against the SQLite Job, not GitHub markers; existing PR-bound Jobs remain readable.
83
83
 
84
84
  ~~~sh
85
85
  cat > job.md <<'EOF'
@@ -89,7 +89,7 @@ Standalone Job context. Put a Mermaid block first when a workflow/state/architec
89
89
  EOF
90
90
 
91
91
  npx agents-relay job create --repo OWNER/REPO \
92
- --id job-1 --title "Objective" --objective-file job.md
92
+ --title "Objective" --objective-file job.md
93
93
 
94
94
  # The orchestrator decides the initial batch separately
95
95
  cat > task.md <<'EOF'
@@ -159,18 +159,12 @@ All task producers use the same story-size contract: `S`≈5 minutes, `M`≈15 m
159
159
 
160
160
  There is no Job scheduling or cron support. Reconciliation resumes objective planning from durable state, including after a missed wake-up or restart. See [objective-driven Jobs](docs/objective-driven-jobs.md).
161
161
 
162
- GitHub projection creates or reuses a display PR after a meaningful source-branch commit; `job adopt` is reserved for existing legacy PR bindings. Re-running it is idempotent: it reuses the PR and maintains exactly one trusted agents-relay:job:v1 marker. Job creation is always create-only and always enables auto-merge; `--no-auto-merge` is not a `job create` option. Existing Jobs can still change that setting with `job update`. Task execution options belong to `task create`, and the orchestrator may create zero, one, or multiple initial Tasks according to user intent.
163
-
164
- To create a Job on an existing unmanaged PR, use the explicit `job adopt` compatibility action:
165
-
166
- ~~~sh
167
- npx agents-relay job adopt --repo OWNER/REPO --pr 6 --id job-6 --title "Existing objective"
168
- ~~~
162
+ GitHub projection creates or reuses a display PR after a meaningful source-branch commit. Job creation is always create-only and always enables auto-merge; `--no-auto-merge` is not a `job create` option. Existing Jobs can still change that setting with `job update`. Task execution options belong to `task create`, and the orchestrator may create zero, one, or multiple initial Tasks according to user intent.
169
163
 
170
164
  Use `job update` for partial mutable metadata changes on an already healthy Job marker/binding:
171
165
 
172
166
  ~~~sh
173
- npx agents-relay job update --repo OWNER/REPO --pr 6 --id job-6 --priority P0 --no-auto-merge
167
+ npx agents-relay job update --id JOB_ID --priority P0 --no-auto-merge
174
168
  ~~~
175
169
 
176
170
  Request an eligible new review with `npx agents-relay review job --repo OWNER/REPO --pr NUMBER --id JOB_ID`.
package/dist/cli-help.js CHANGED
@@ -37,7 +37,7 @@ Usage:
37
37
  npx agents-relay job <create|update|show|list|run|shortcut-receipt|merge|unblock|cancel|pause|resume> [options]
38
38
 
39
39
  Actions:
40
- create Create a durable Job, optionally binding an existing unmanaged PR
40
+ create Create a durable SQLite-authoritative Job
41
41
  update Partially update mutable metadata on a healthy existing Job
42
42
  show Show one durable Job
43
43
  run Opt in to direct Agent Graph shortcuts for one existing Task
@@ -50,11 +50,11 @@ Actions:
50
50
  resume Clear pause metadata and requeue interrupted work
51
51
 
52
52
  Common options:
53
- --repo OWNER/REPO GitHub repository
53
+ --repo OWNER/REPO Required for create; optional Job identity check otherwise
54
54
  --id JOB_ID Durable job identifier
55
55
 
56
56
  Shortcut execution:
57
- agents-relay job run --mode shortcut --id JOB --repo OWNER/REPO --task-id TASK
57
+ agents-relay job run --mode shortcut --id JOB --task-id TASK
58
58
  [--store-dir DIR] [--project-path DIR] [--shared-root DIR] [--concurrency 4]
59
59
 
60
60
  The selected Task must have an Agent Graph. Project shortcuts at
@@ -66,7 +66,7 @@ events are wake signals. Human approval remains hostInvocation-only.
66
66
  Shortcut Job completion requires durable contentOnly=true and no PR, merge, or review gates.
67
67
 
68
68
  Record an asynchronous result with:
69
- agents-relay job shortcut-receipt --id JOB --repo OWNER/REPO --task-id TASK
69
+ agents-relay job shortcut-receipt --id JOB --task-id TASK
70
70
  --node-id NODE --wait-id WAIT --revision REV --execution-id EXECUTION
71
71
  --output-file result.json --content-sha256 SHA256
72
72
 
@@ -74,7 +74,7 @@ The file must contain the completed shortcut result object. SHA256 is computed
74
74
  over its canonical JSON content and must equal the persisted wait content hash.
75
75
 
76
76
  Example:
77
- npx agents-relay job show --repo OWNER/REPO --id 101`,
77
+ npx agents-relay job show --id 101`,
78
78
  prompt: `Read-only exact PromptBuilder output for a durable Plan or Task.
79
79
 
80
80
  agents-relay prompt --id JOB --plan-id PLAN --adapter codex|chatgpt|z [--output FILE]
@@ -120,48 +120,45 @@ Required: --repo OWNER/REPO --id JOB_ID.
120
120
  Optional: --thread-id THREAD_ID persists a reviewer override; omitted uses Job reviewer/creator thread or legacy route. Rejects pending reviews and wakes managed reconciliation.`,
121
121
  'job create': `Create a SQLite-authoritative Job (objective-only).
122
122
 
123
- Required: --repo OWNER/REPO and a standalone Job objective. Job ID defaults to an auto-incrementing store-global number; --id may only reference an existing numeric Job. Existing PR adoption is an explicit separate command: job adopt.
123
+ Required: --repo OWNER/REPO and a standalone Job objective. Job ID defaults to an auto-incrementing store-global number; --id may only reference an existing numeric Job.
124
124
  Common: --id JOB_ID (optional), --title TEXT, --objective-file PATH|- (preferred), --objective MARKDOWN (short/simple only), --project-path RELATIVE_PATH, --priority P0|P1|P2|P3, --initial-plan, --no-review, --shortcut-execution, --tag JSON, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID. --objective and --objective-file are mutually exclusive.
125
125
  Job creation enables auto-merge by default. By default it is create-only; --initial-plan validates the first real Planner round before atomically creating the durable Job and Plan, then publishes the normal wake. --shortcut-execution creates a create-only content-only Job with durable direct Graph execution policy, no auto-merge, and no review; select it before Tasks are materialized and do not combine it with --initial-plan. Re-running create against an already healthy Job is idempotent and does not mutate its metadata.
126
126
 
127
127
  Example:
128
128
  npx agents-relay job create --repo OWNER/REPO --project-path vlog --title "Episode" --objective-file episode.md --initial-plan`,
129
- 'job adopt': `Adopt an existing PR as a SQLite-authoritative Job.
130
-
131
- Required: --repo OWNER/REPO and --pr NUMBER. The Job ID is allocated atomically from the global SQLite sequence. Optional --id references an already-existing numeric Job only.`,
132
129
  'job update': `Partially update mutable metadata on a healthy existing Job.
133
130
 
134
- Required: --repo OWNER/REPO and --id JOB_ID.
131
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO verifies the stored Job identity.
135
132
  Mutable: --title, --objective-file PATH|- (preferred) or --objective MARKDOWN, --project-path RELATIVE_PATH, --priority, --tag JSON, --auto-merge|--no-auto-merge, --review|--no-review, --content-only|--no-content-only, --reviewer-thread-id ID, --creator-thread-id ID, --implementation-thread-id ID, and continuation options. The objective updates local SQLite; PR body changes are independent external actions. Content-only completion requires no PR/merge/review requirements and explicit --no-auto-merge --no-review --content-only.
136
133
  Unspecified fields are preserved. Local Job/PR identity mismatch is rejected.
137
134
 
138
135
  Example:
139
- npx agents-relay job update --repo OWNER/REPO --id 101 --priority P0 --no-auto-merge`,
136
+ npx agents-relay job update --id 101 --priority P0 --no-auto-merge`,
140
137
  'job show': `Show one durable Job.
141
138
 
142
- Required: --repo OWNER/REPO and --id JOB_ID.
139
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO validates the repository.
143
140
 
144
141
  Example:
145
- npx agents-relay job show --repo OWNER/REPO --id 101`,
146
- 'job list': `List managed Jobs in a repository.
142
+ npx agents-relay job show --id 101`,
143
+ 'job list': `List managed Jobs across repositories, or filter by repository.
147
144
 
148
- Required: --repo OWNER/REPO.
145
+ Optional: --repo OWNER/REPO filters results.
149
146
 
150
147
  Example:
151
- npx agents-relay job list --repo OWNER/REPO`,
148
+ npx agents-relay job list`,
152
149
  'job merge': `Legacy entry point; external GitHub PR merges are not initiated by this CLI.
153
150
 
154
- Managed Jobs use Graph-owned local merge and publication. Identify a Job with --repo OWNER/REPO and --id JOB_ID.`,
155
- 'job unblock': `Authoritatively unblock BLOCKED Troubleshooter Tasks in one Job.\n\nRequired: --repo OWNER/REPO --id JOB_ID --reason TEXT. Each unblocked Troubleshooter is queued as the same Task and must rerun, verify the condition, and issue a fresh resolution before retrying an original failed Task.`,
151
+ Managed Jobs use Graph-owned local merge and publication. Identify a Job with --id JOB_ID; --repo OWNER/REPO is optional.`,
152
+ 'job unblock': `Authoritatively unblock BLOCKED Troubleshooter Tasks in one Job.\n\nRequired: --id JOB_ID --reason TEXT. Optional: --repo OWNER/REPO. Each unblocked Troubleshooter is queued as the same Task and must rerun, verify the condition, and issue a fresh resolution before retrying an original failed Task.`,
156
153
  'job cancel': `Cancel a durable Job and its unfinished Tasks through the authoritative Relay Graph.
157
154
 
158
- Required: --repo OWNER/REPO and --id JOB_ID. No PR number is required.`,
155
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO checks identity. No PR number is required.`,
159
156
  'job pause': `Pause a durable Job without inventing a PAUSED lifecycle state.
160
157
 
161
- Required: --repo OWNER/REPO --id JOB_ID. Running worker and Planner generations are interrupted durably and resume as uncompleted work.`,
158
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO. Running worker and Planner generations are interrupted durably and resume as uncompleted work.`,
162
159
  'job resume': `Resume a paused durable Job.
163
160
 
164
- Required: --repo OWNER/REPO --id JOB_ID. Interrupted work is requeued and normal reconciliation continues.`,
161
+ Required: --id JOB_ID. Optional: --repo OWNER/REPO. Interrupted work is requeued and normal reconciliation continues.`,
165
162
  escalation: `Run the canonical escalation workflow for a suspected human/external blocker.\n\nRequired: --intent TEXT|--intent-file PATH and --blocked-on TEXT|--blocked-on-file PATH. Optional: --context/--context-file, --on-needs-user/--on-needs-user-file, --cwd. The workflow/escalation.mmd graph invokes an operator-configured executor and owns the resolved / failed / needs_user branches. Only needs_user selects the block-for-user path. Set AGENTS_RELAY_ESCALATION_COMMAND to an absolute executable path or JSON argv array (for example ["/opt/homebrew/bin/neo","escalation"]). No Neo executable is assumed by Relay; missing/broken executors produce technical_failure.`,
166
163
  status: `Show live aggregate runtime status from the running Agents Relay service.
167
164
 
@@ -3,11 +3,7 @@ import { openLocalManagedStore } from './local-managed-store.js';
3
3
  import { createJobEntity } from './workflow/entity-creation.js';
4
4
  import { normalizeThreadId } from './reviewer-thread.js';
5
5
  import { discoverLocalRelayStoreSnapshots, relayStoreDirectory } from './relay-store.js';
6
- /**
7
- * Ordinary Job creation is local and objective-oriented. Legacy PR metadata is
8
- * handled by adoptExistingPullRequestJob below so the normal contract cannot accidentally
9
- * create a second external lifecycle.
10
- */
6
+ /** Create a local SQLite-authoritative Job; external PR metadata is optional compatibility data. */
11
7
  export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAuthors, options) {
12
8
  if (options.id && !/^[1-9][0-9]*$/.test(options.id))
13
9
  throw new Error('Job ID must be a positive decimal integer');
@@ -89,39 +85,3 @@ export async function ensureManagedGitHubJob(_client, repositoryName, _trustedAu
89
85
  local.relay.close();
90
86
  }
91
87
  }
92
- /** Import an existing PR without letting external labels choose the durable numeric Job ID. */
93
- export async function adoptExistingPullRequestJob(_client, repositoryName, _trustedAuthors, options) {
94
- if (!Number.isInteger(options.prNumber) || options.prNumber <= 0)
95
- throw new Error('job adopt requires a positive --pr');
96
- if (options.id && !/^[1-9][0-9]*$/.test(options.id))
97
- throw new Error('Job ID must be a positive decimal integer');
98
- const directory = options.storeDirectory ?? relayStoreDirectory();
99
- const knownJobs = (await discoverLocalRelayStoreSnapshots(directory)).flatMap(snapshot => snapshot.jobs);
100
- const matches = options.id ? knownJobs.filter(job => job.id === options.id) : knownJobs.filter(job => job.repository === repositoryName && job.prNumber === options.prNumber);
101
- if (matches.length > 1)
102
- throw new Error('Ambiguous existing immutable Job or PR binding');
103
- if (matches.length === 1) {
104
- const existing = matches[0];
105
- if (existing.repository !== repositoryName || existing.prNumber !== options.prNumber)
106
- throw new Error(`Job ID ${options.id} is already bound to another repository or PR`);
107
- return { job: existing, pr: { number: existing.prNumber, title: existing.title, body: existing.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
108
- }
109
- if (options.id)
110
- throw new Error(`Unknown numeric Job ID ${options.id}; new PR adoptions allocate IDs automatically`);
111
- const id = allocateEntityId(directory, repositoryName, 'job', `adopt:pr:${options.prNumber}`, new Set(knownJobs.map(job => job.id)));
112
- const local = openLocalManagedStore(repositoryName, options.prNumber, { directory, jobId: id, noGitHub: true });
113
- try {
114
- const existing = (await local.relay.listJobs()).find(job => job.repository === repositoryName && job.prNumber === options.prNumber);
115
- if (existing)
116
- return { job: existing, pr: { number: existing.prNumber, title: existing.title, body: existing.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
117
- const now = new Date().toISOString();
118
- const job = createJobEntity({ id, title: options.title ?? id, objective: options.objective, projectPath: options.projectPath,
119
- description: options.objective, priority: 'P2', autoMerge: true, reviewEnabled: true,
120
- prNumber: options.prNumber, repository: repositoryName, continuation: null, createdAt: now, updatedAt: now, tasks: [] });
121
- const created = local.store.createJobIfAbsent ? await local.store.createJobIfAbsent(job) : (await local.store.saveJob(job), job);
122
- return { job: created, pr: { number: options.prNumber, title: created.title, body: created.objective ?? '', state: 'OPEN', head: '', base: 'main' } };
123
- }
124
- finally {
125
- local.relay.close();
126
- }
127
- }
@@ -23,8 +23,9 @@ export async function runLocalShortcutBinding(kind, action, args) {
23
23
  return;
24
24
  }
25
25
  if (kind === 'job' && action === 'show' || kind === 'task' && action === 'list') {
26
- const { job } = await storeFor(args);
27
- if (job.repository !== repository(args) || job.executionMode !== 'shortcut' || job.contentOnly !== true)
26
+ const { job } = await storeFor(args, false, kind === 'job');
27
+ const requestedRepo = kind === 'job' ? arg(args, '--repo') : repository(args);
28
+ if ((requestedRepo && job.repository !== requestedRepo) || job.executionMode !== 'shortcut' || job.contentOnly !== true)
28
29
  throw new Error('local shortcut Job identity mismatch');
29
30
  console.log(JSON.stringify(kind === 'job' ? job : job.tasks, null, 2));
30
31
  return;
@@ -30,11 +30,11 @@ export async function activateShortcutJobForDirectRun(store, jobId) {
30
30
  return current;
31
31
  });
32
32
  }
33
- export async function runShortcutJobCommand(args, id, repo, makeRunner) {
33
+ export async function runShortcutJobCommand(args, id, makeRunner) {
34
34
  assertSqliteShortcutArgs(args);
35
35
  if (arg(args, '--mode') !== 'shortcut')
36
36
  throw new Error('job run requires --mode shortcut');
37
- const loaded = await storeFor(args);
37
+ const loaded = await storeFor(args, false, true);
38
38
  if (loaded.localFile !== null || !loaded.store.mutateJob || !loaded.store.reserveWorkflowLaunch)
39
39
  throw new Error('Shortcut execution requires the authoritative SQLite Relay store');
40
40
  const job = loaded.job;
@@ -84,7 +84,7 @@ export async function runShortcutJobCommand(args, id, repo, makeRunner) {
84
84
  await activateShortcutJobForDirectRun(loaded.store, id);
85
85
  loaded.job = await loaded.store.load(id);
86
86
  const workspaceRoot = await resolveWorkspaceRoot(arg(args, '--workspace-root') || undefined);
87
- const projectRoot = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : repo, arg(args, '--project-path') || loaded.job.projectPath || '', workspaceRoot);
87
+ const projectRoot = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : loaded.job.repository, arg(args, '--project-path') || loaded.job.projectPath || '', workspaceRoot);
88
88
  const projectPath = resolveRepositoryProjectPath(projectRoot, loaded.job.projectPath);
89
89
  const globalRoot = arg(args, '--global-root') || process.env.AGENTS_HOME || undefined;
90
90
  const missing = await missingShortcutNodes(task.agentGraph, projectPath, arg(args, '--shared-root') || process.env.AGENTS_RELAY_SHARED_ROOT || undefined, workspaceRoot, globalRoot);
@@ -143,7 +143,7 @@ export async function recordShortcutReceiptCommand(args, id) {
143
143
  throw new Error('job shortcut-receipt requires --task-id --node-id --wait-id --revision --execution-id --output-file --content-sha256');
144
144
  if (outputFile === '-')
145
145
  throw new Error('--output-file requires a local file path');
146
- const { store, localFile } = await storeFor(args);
146
+ const { store, localFile } = await storeFor(args, false, true);
147
147
  if (localFile !== null || !store.mutateJob || !store.reserveWorkflowLaunch)
148
148
  throw new Error('Shortcut receipts require the authoritative SQLite Relay store');
149
149
  const bytes = await readFile(outputFile);
@@ -79,13 +79,13 @@ function validateReadOnlyJobBinding(args) {
79
79
  throw new Error('--pr must be a positive integer');
80
80
  }
81
81
  }
82
- export async function storeFor(args, allowIdOnly = false) {
82
+ export async function storeFor(args, allowIdOnly = false, optionalRepo = false) {
83
83
  if (allowIdOnly)
84
84
  validateReadOnlyJobBinding(args);
85
85
  const file = arg(args, '--file');
86
86
  if (file) {
87
87
  const loaded = await localStore(file);
88
- if (allowIdOnly) {
88
+ if (allowIdOnly || optionalRepo) {
89
89
  const requestedId = arg(args, '--id'), requestedRepo = arg(args, '--repo');
90
90
  if (requestedId !== loaded.job.id)
91
91
  throw new Error('Local --file Job ID binding mismatch');
@@ -97,10 +97,10 @@ export async function storeFor(args, allowIdOnly = false) {
97
97
  }
98
98
  return { ...loaded, localFile: file };
99
99
  }
100
- const repo = allowIdOnly ? arg(args, '--repo') : noGitHubMode(args) ? repository(args) : arg(args, '--repo');
100
+ const repo = allowIdOnly || optionalRepo ? arg(args, '--repo') : noGitHubMode(args) ? repository(args) : arg(args, '--repo');
101
101
  const jobId = arg(args, '--id');
102
- if (!jobId || (!repo && !allowIdOnly))
103
- throw new Error('Local Job requires --repo and --id (or explicit --file)');
102
+ if (!jobId || (!repo && !allowIdOnly && !optionalRepo))
103
+ throw new Error('Local Job requires --id and, for this operation, --repo (or explicit --file)');
104
104
  const directory = arg(args, '--store-dir') || relayStoreDirectory();
105
105
  if (allowIdOnly) {
106
106
  // Read-only CLI must not initialize SQLiteRelayStore: its constructor
package/dist/cli.js CHANGED
@@ -395,10 +395,10 @@ async function runTaskCommand(action, args) {
395
395
  async function runJobCommand(action, args) {
396
396
  if (hasArg(args, '--shortcut-local'))
397
397
  return runLocalShortcutBinding('job', action, args);
398
- if (!['create', 'adopt', 'update', 'show', 'list', 'merge', 'unblock', 'cancel', 'pause', 'resume', 'run', 'shortcut-receipt'].includes(action))
398
+ if (!['create', 'update', 'show', 'list', 'merge', 'unblock', 'cancel', 'pause', 'resume', 'run', 'shortcut-receipt'].includes(action))
399
399
  throw new Error(usage);
400
- const repo = repository(args);
401
- if (action !== 'adopt' && action !== 'create')
400
+ const repo = action === 'create' ? repository(args) : arg(args, '--repo');
401
+ if (action !== 'create')
402
402
  optionalLegacyPr(args);
403
403
  let createObjective;
404
404
  if (action === 'create') {
@@ -413,19 +413,7 @@ async function runJobCommand(action, args) {
413
413
  throw new Error('job create requires --objective-file PATH|- or --objective MARKDOWN containing the complete standalone Job context');
414
414
  const legacy = ['--pr', '--head', '--base', '--body', '--local-merge-source', '--local-merge-target', '--idempotency-key'].find(flag => hasArg(args, flag));
415
415
  if (legacy)
416
- throw new Error(`job create does not accept ${legacy}; use job adopt only for existing PR bindings`);
417
- }
418
- if (action === 'adopt') {
419
- const adoptId = arg(args, '--id');
420
- const adoptPr = Number(arg(args, '--pr'));
421
- if (!Number.isInteger(adoptPr) || adoptPr <= 0)
422
- throw new Error('job adopt requires a positive --pr');
423
- const objective = await textOption(args, '--objective', '--objective-file');
424
- const result = await relayControlCommand(args, { command: 'job.adopt', repository: repo, options: {
425
- id: adoptId || undefined, prNumber: adoptPr, title: arg(args, '--title') || undefined, objective: objective || undefined, projectPath: arg(args, '--project-path') || undefined,
426
- } });
427
- console.log(JSON.stringify(result, null, 2));
428
- return;
416
+ throw new Error(`job create does not accept ${legacy}; PR binding is not supported during creation`);
429
417
  }
430
418
  if (action === 'list') {
431
419
  console.log(JSON.stringify(await relayJobList(args), null, 2));
@@ -435,8 +423,8 @@ async function runJobCommand(action, args) {
435
423
  if (!id && action !== 'create')
436
424
  throw new Error('--id is required for managed local Jobs');
437
425
  if (action === 'pause' || action === 'resume') {
438
- const target = await storeFor(args);
439
- if (target.job.repository !== repo)
426
+ const target = await storeFor(args, false, true);
427
+ if (repo && target.job.repository !== repo)
440
428
  throw new Error('Local Job/PR binding mismatch');
441
429
  const updated = action === 'pause' ? await pauseJob(target.store, id) : await resumeJob(target.store, id);
442
430
  await saveLocal(target.localFile, updated);
@@ -461,7 +449,7 @@ async function runJobCommand(action, args) {
461
449
  return;
462
450
  }
463
451
  if (action === 'run') {
464
- await runShortcutJobCommand(args, id, repo, (store, bus) => runtime(store, args, bus, codexAndZaiUsageRegistry(), true));
452
+ await runShortcutJobCommand(args, id, (store, bus) => runtime(store, args, bus, codexAndZaiUsageRegistry(), true));
465
453
  return;
466
454
  }
467
455
  if (action === 'shortcut-receipt') {
@@ -481,7 +469,7 @@ async function runJobCommand(action, args) {
481
469
  console.log(JSON.stringify(job, null, 2));
482
470
  return;
483
471
  }
484
- if (job.repository !== repo) {
472
+ if (repo && job.repository !== repo) {
485
473
  throw new Error('Local Job/PR binding mismatch');
486
474
  }
487
475
  if (action === 'merge') {
@@ -47,6 +47,8 @@ export async function managedWorkerInput(job, task, context, mode = 'production'
47
47
  join(packageRoot, 'skills/agents-relay/contracts/task-recovery-flows.md'),
48
48
  join(packageRoot, 'skills/agents-relay/contracts/blocker-job-recovery.md'),
49
49
  ] : []),
50
+ ...(role === 'worker' && context.skills.find(skill => skill.name === 'ponytail')
51
+ ? [context.skills.find(skill => skill.name === 'ponytail').path] : []),
50
52
  ...(role === 'worker' && !task.review && task.agentName !== 'review-chair'
51
53
  ? [join(packageRoot, 'skills/agents-relay/contracts/worker-self-review.md')] : []),
52
54
  ],
package/dist/planner.js CHANGED
@@ -4,6 +4,7 @@ import { readFile } from 'node:fs/promises';
4
4
  import { fileURLToPath } from 'node:url';
5
5
  import { dirname, join, resolve as resolvePath } from 'node:path';
6
6
  import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
7
+ import { reviewNeedsReplan } from './review-replan.js';
7
8
  import { unresolvedTask } from './workflow/task-resolution.js';
8
9
  import { BUNDLED_AGENTS_ROOT } from './execution-context.js';
9
10
  import { agentSourceLayers, resolveAgentMarkdown } from './agent-content-resolver.js';
@@ -33,6 +34,7 @@ function plannerTrigger(job, manual = false) {
33
34
  manualPlan: manual && !hasUnblock,
34
35
  hasUnblock,
35
36
  initialPlan: (job.plans?.length ?? 0) === 0 && !job.tasks.some(task => task.kind === 'planner'),
37
+ reviewRequired: reviewNeedsReplan(job),
36
38
  });
37
39
  if (!decision.accepted)
38
40
  throw new Error('Planner trigger graph rejected plan.requested');
@@ -59,6 +61,9 @@ function plannerTrigger(job, manual = false) {
59
61
  }
60
62
  if (source === 'initial')
61
63
  return { source: 'initial' };
64
+ if (source === 'review')
65
+ return { source: 'review', reviewTaskId: job.review?.taskId ?? undefined,
66
+ reason: 'Final Review requested changes', facts: ['Address persisted Final Review findings.'] };
62
67
  return { source: 'continuation' };
63
68
  }
64
69
  export function plannerRoundNumber(task) {
@@ -427,6 +432,9 @@ export function plannerInput(context) {
427
432
  previous_planner_task_id: context.previousPlannerTaskId,
428
433
  plan_trigger: context.trigger,
429
434
  legacy_change_cycle: context.job.changeCycle,
435
+ review_feedback: context.job.review && (context.trigger?.source === 'review' || context.job.review.outcome === 'changes_required')
436
+ ? { task_id: context.job.review.taskId, head_sha: context.job.review.headSha,
437
+ findings: boundedText(JSON.stringify(context.job.review.evidence?.data ?? {}), 6000) } : undefined,
430
438
  semantic_task_tree: semanticTaskTree(context.tasks),
431
439
  plans: (context.job.plans ?? []).map(plan => ({
432
440
  id: plan.id,
@@ -496,14 +504,12 @@ export async function buildPlannerExecutionPrompt(context, agentFile = DEFAULT_P
496
504
  throw new Error('Planner execution is missing its durable Plan and execution identity');
497
505
  const ctx = context.executionContext, selected = ctx ? await resolveAgentMarkdown('planner', BUNDLED_AGENTS_ROOT, ctx.project.path, ctx.project.sharedRoot, agentSourceLayers(ctx.project.path, ctx.project)) : undefined;
498
506
  return buildRelayWorkPrompt({ agentName: 'planner', agentContent: selected?.content ?? await readFile(agentFile, 'utf8'), adapter,
499
- contracts: [
500
- join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/contracts/task-job-contract.md'),
507
+ contracts: [join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/contracts/task-job-contract.md'),
501
508
  join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/contracts/blocker-job-recovery.md'),
502
- ],
509
+ ...(ctx?.skills.find(skill => skill.name === 'ponytail')?.path ? [ctx.skills.find(skill => skill.name === 'ponytail').path] : [])],
503
510
  contexts: ctx?.instructions.filter(item => item.path.endsWith('/AGENTS.md')) ?? [],
504
511
  projectPath: ctx?.project.gitRoot ?? ctx?.project.path ?? process.cwd(), providerInstructions: ctx?.providerInstructions?.[adapter], skillPath: join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/SKILL.md'), jobId: context.job.id,
505
- taskId: context.planExecution.planId, executionId: context.planExecution.executionId,
506
- });
512
+ taskId: context.planExecution.planId, executionId: context.planExecution.executionId, });
507
513
  }
508
514
  export class AgentObjectivePlanner {
509
515
  command;
package/dist/pool.js CHANGED
@@ -5,7 +5,10 @@ import { errorMessage, observability, withObservabilityCorrelation } from './obs
5
5
  import { jobHasActiveExecution } from './job-execution-slot.js';
6
6
  import { pendingPlan } from './planner.js';
7
7
  import { decidePlannerOrchestration, plannerOrchestrationFacts } from './workflow/planner-orchestration-v2.js';
8
- import { pendingTroubleshooterRetries } from './troubleshooter.js';
8
+ import { pendingTroubleshooterTasks, pendingTroubleshooterReopens, pendingTroubleshooterRetries } from './troubleshooter.js';
9
+ import { reviewPlanReady, reviewWorkSettled } from './review-replan.js';
10
+ import { decideReviewLifecycle } from './workflow/review-v2.js';
11
+ import { isFinalReviewAgent } from './final-review-role.js';
9
12
  const RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
10
13
  export function compareJobPriority(a, b) { return RANK[a.priority ?? 'P2'] - RANK[b.priority ?? 'P2'] || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
11
14
  export function runnableManagedJobs(items) { return items.filter(item => item.job.state === 'ACTIVE' || item.job.projectionRecovery?.status === 'repairing').map(item => item.job).sort(compareJobPriority); }
@@ -22,8 +25,22 @@ export function needsLifecycleReconciliation(job, now = Date.now()) {
22
25
  const planning = decidePlannerOrchestration(plannerOrchestrationFacts(job, Boolean(pendingPlan(job))));
23
26
  if (planning.accepted && planning.actions.length > 0)
24
27
  return true;
25
- if (pendingTroubleshooterRetries(job).length > 0)
28
+ if (pendingTroubleshooterTasks(job).length || pendingTroubleshooterReopens(job).length || pendingTroubleshooterRetries(job).length)
26
29
  return true;
30
+ // Use the canonical Review Graph for restart wake-ups; Reconciler must still verify the live head SHA.
31
+ if (job.state === 'ACTIVE' && job.headSha && job.reviewEnabled !== false) {
32
+ const reviewTasks = job.tasks.filter(task => isFinalReviewAgent(task.agentName) && task.reviewHeadSha === job.headSha);
33
+ const current = job.review?.taskId ? job.tasks.find(task => task.id === job.review?.taskId) : undefined;
34
+ const review = decideReviewLifecycle(job.review?.outcome, 'reconcile', {
35
+ reviewEnabled: true, jobActive: true, headAvailable: true,
36
+ reviewWorkSettled: reviewWorkSettled(job), reviewPlanReady: reviewPlanReady(job),
37
+ noActiveReviewTask: !reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)),
38
+ noApprovedCurrentReview: !reviewTasks.some(task => task.state === 'SUCCEEDED' && job.review?.headSha === job.headSha && job.review?.outcome === 'approved'),
39
+ currentReviewCancelled: current?.reviewHeadSha === job.headSha && current.state === 'CANCELLED',
40
+ });
41
+ if (review.accepted && review.actions.some(action => action.id === 'review.create'))
42
+ return true;
43
+ }
27
44
  if (job.tasks.some(task => (task.state === 'QUEUED' && task.executionId === null)
28
45
  || (task.state === 'RUNNING' && task.adapter === 'orchestrator' && task.executionId === null)
29
46
  || (task.state === 'DRAFT' && task.dependencies.length > 0)))
@@ -3,8 +3,9 @@ import { isFinalReviewAgent, FINAL_REVIEW_AGENT, nextFinalReviewTaskId } from '.
3
3
  import { normalizeReviewEvidence } from './review-evidence.js';
4
4
  import { browserWorkerPool } from './browser-worker-runtime.js';
5
5
  import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
6
- import { completionGateSatisfied, refreshTaskDependencies, transitionTaskEvent, tryTransitionTaskEvent } from './task-transitions.js';
7
- import { implementationComplete, implementationTasks } from './runtime-status.js';
6
+ import { refreshTaskDependencies, transitionTaskEvent, tryTransitionTaskEvent } from './task-transitions.js';
7
+ import { implementationTasks } from './runtime-status.js';
8
+ import { reviewPlanReady, reviewWorkSettled } from './review-replan.js';
8
9
  import { eventFor } from './events.js';
9
10
  import { workerCandidates } from './worker-routing.js';
10
11
  import { routeExecution } from './execution-routing.js';
@@ -47,9 +48,9 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
47
48
  return {
48
49
  reviewEnabled: job.reviewEnabled !== false,
49
50
  jobActive: job.state === 'ACTIVE' || job.projectionRecovery?.status === 'repairing',
50
- implementationComplete: implementationComplete(job),
51
+ reviewWorkSettled: reviewWorkSettled(job),
51
52
  headAvailable: Boolean(headSha),
52
- completionGateSatisfied: completionGateSatisfied(job),
53
+ reviewPlanReady: reviewPlanReady(job),
53
54
  noActiveReviewTask: !reviewTasks.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)),
54
55
  currentReviewCancelled: currentReviewTask?.reviewHeadSha === headSha && currentReviewTask.state === 'CANCELLED',
55
56
  noApprovedCurrentReview: !reviewTasks.some(task => task.state === 'SUCCEEDED' && job.review?.headSha === headSha && job.review.outcome === 'approved'),
@@ -120,11 +121,13 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
120
121
  'Use the selected reviewer agent contract as the authoritative review protocol.',
121
122
  'This is a PRE-MERGE artifact approval gate: inspect exact PR head, requirements, tests and genuine blocking defects.',
122
123
  'Do not block approval because automatic merge, Job COMPLETED, or post-merge validation has not occurred yet.',
124
+ 'All non-review Tasks have terminal outcomes. Examine FAILED and CANCELLED Tasks and their recovery evidence; never approve an unresolved required outcome.',
125
+ 'The Final Review is the Job completion check. Persist concrete, owner-attributed findings with a changes-required verdict; Relay starts a new Planner round for revisions.',
123
126
  'Do not treat historical failed attempts as current artifact defects; distinguish preserved baseline files from implementation.',
124
127
  ].join('\n\n');
125
128
  const task = createTaskEntity(job, {
126
129
  jobId: job.id, id, title: 'Review', kind: 'work', priority: job.priority, storySize: 'M', projectName: job.title, agentName: FINAL_REVIEW_AGENT,
127
- parentTaskId: null, dependencies: reviewGateTasks.map(item => item.id), capabilities: ['review'],
130
+ parentTaskId: null, dependencies: [], capabilities: ['review'],
128
131
  workerSelection: reviewerRouting.selection, adapter: reviewerRouting.candidate.adapter,
129
132
  input,
130
133
  output: { kind: 'task_pr' }, routing: reviewerRouting.candidate.routing, continuation: null, continuationDeliveredAt: null,
@@ -489,7 +492,7 @@ export class ReconcilerReviewBase extends ReconcilerRuntimeBase {
489
492
  }
490
493
  // Review approval records evidence only. The subsequent Graph reconcile
491
494
  // drives durable local Git merge delivery and terminalization.
492
- if (outcome === 'approved')
495
+ if (outcome === 'approved' || outcome === 'changes_required')
493
496
  needsReconcile = true;
494
497
  return { applied: true, reconcile: needsReconcile, reason: 'review.' + outcome, reconcileMode: needsReconcile ? 'detached' : undefined };
495
498
  }
@@ -10,7 +10,6 @@ import { publishTaskBlocked } from './cli-support.js';
10
10
  import { classifyFailedTask, supersedeCancelledTask } from './task-actions.js';
11
11
  import { requestTroubleshooterEscalation, resumeTroubleshooter } from './task-recovery.js';
12
12
  import { ensureBlockerRecovery } from './blocker-recovery.js';
13
- import { adoptExistingPullRequestJob } from './cli-job-create.js';
14
13
  import { resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
15
14
  export function createWorkspaceControl(deps) {
16
15
  const { client, trusted, noGitHub, repositories, refreshAll, requireLocalJobBinding, makeReconciler, concurrency, pool, bus, isEffectivelyBlocked, unblockTask, publishTaskUnblocked, dispatchTaskAction, registerBlockerDependency, discoverAgents, ensureManagedGitHubJob, ensureBlockerRecovery: runBlockerRecovery = ensureBlockerRecovery } = deps;
@@ -74,22 +73,6 @@ export function createWorkspaceControl(deps) {
74
73
  }
75
74
  return { repository, pr: result.pr.number, job: result.job.id, state: result.job.state };
76
75
  }
77
- if (command === 'job.adopt') {
78
- const repository = typeof body.repository === 'string' ? body.repository : '';
79
- const options = (body.options && typeof body.options === 'object' ? body.options : {});
80
- if (!repository || typeof options.prNumber !== 'number')
81
- throw new Error('job.adopt requires repository and prNumber');
82
- const result = await adoptExistingPullRequestJob(client, repository, trusted, {
83
- id: typeof options.id === 'string' ? options.id : undefined, title: typeof options.title === 'string' ? options.title : undefined,
84
- objective: typeof options.objective === 'string' ? options.objective : undefined,
85
- projectPath: typeof options.projectPath === 'string' ? options.projectPath : undefined,
86
- prNumber: options.prNumber,
87
- });
88
- if (!repositories.includes(repository))
89
- repositories.push(repository);
90
- await refreshAll();
91
- return { repository, pr: result.pr.number, job: result.job.id, state: result.job.state };
92
- }
93
76
  if (!jobId)
94
77
  throw new Error(command + ' requires jobId');
95
78
  const binding = await requireLocalJobBinding(jobId);
@@ -0,0 +1,39 @@
1
+ import { isFinalReviewAgent } from './final-review-role.js';
2
+ import { pendingTroubleshooterTasks, pendingTroubleshooterReopens, pendingTroubleshooterRetries } from './troubleshooter.js';
3
+ const terminal = new Set(['SUCCEEDED', 'FAILED', 'CANCELLED']);
4
+ /** A Final Reviewer reads all terminal outcomes, including failures, not just successes. */
5
+ export function reviewWorkSettled(job) {
6
+ const work = job.tasks.filter(task => task.kind !== 'planner' && !isFinalReviewAgent(task.agentName));
7
+ return work.some(task => task.agentName !== 'troubleshooter')
8
+ && work.every(task => terminal.has(task.state) && !['active', 'waiting'].includes(task.resolution?.state ?? ''))
9
+ && !pendingTroubleshooterTasks(job).length
10
+ && !pendingTroubleshooterReopens(job).length
11
+ && !pendingTroubleshooterRetries(job).length;
12
+ }
13
+ /** New reviews use Review -> Replan; older persisted targeted revisions remain recoverable. */
14
+ export function reviewNeedsReplan(job) {
15
+ const review = job.review;
16
+ if (!review?.taskId || review.revisionDisposition === 'targeted')
17
+ return false;
18
+ const changes = review.outcome === 'changes_required'
19
+ || (review.outcome === 'stale' && (job.reviewRevisionRounds ?? []).some(round => round.reviewTaskId === review.taskId && round.status === 'changes_required'));
20
+ return changes && !(job.plans ?? []).some(plan => plan.trigger.source === 'review' && plan.trigger.reviewTaskId === review.taskId && plan.status !== 'FAILED');
21
+ }
22
+ /** An immutable re-review must wait for the finding-driven Plan and its work to settle. */
23
+ export function reviewPlanReady(job) {
24
+ if ((job.plans ?? []).some(plan => plan.status === 'PLANNING'))
25
+ return false;
26
+ const latest = (job.plans ?? []).at(-1);
27
+ const legacy = !latest && job.tasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED');
28
+ if (!legacy && (latest?.status !== 'SUCCEEDED' || !job.tasks.some(task => task.kind !== 'planner' && !isFinalReviewAgent(task.agentName))))
29
+ return false;
30
+ const review = job.review;
31
+ if (!review?.taskId || review.revisionDisposition === 'targeted')
32
+ return true;
33
+ const requiresRevision = review.outcome === 'changes_required'
34
+ || (review.outcome === 'stale' && (job.reviewRevisionRounds ?? []).some(round => round.reviewTaskId === review.taskId && round.status === 'changes_required'));
35
+ if (!requiresRevision)
36
+ return true;
37
+ return (job.plans ?? []).some(plan => plan.status === 'SUCCEEDED'
38
+ && plan.trigger.source === 'review' && plan.trigger.reviewTaskId === review.taskId);
39
+ }
@@ -5,8 +5,8 @@ export { dependencyReady, detectCycles } from './workflow/task-reconcile.js';
5
5
  import { observability } from './observability.js';
6
6
  export function completionGateSatisfied(job) {
7
7
  const latest = [...(job.plans ?? [])].sort((a, b) => a.round - b.round).at(-1);
8
- const planSatisfied = latest?.status === 'SUCCEEDED' && latest.objectiveStatus === 'satisfied';
9
- const legacySatisfied = (job.plans?.length ?? 0) === 0 && job.tasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && task.plannerResult?.objective_status === 'satisfied');
8
+ const planSatisfied = latest?.status === 'SUCCEEDED' && (job.reviewEnabled !== false || latest.objectiveStatus === 'satisfied');
9
+ const legacySatisfied = (job.plans?.length ?? 0) === 0 && job.tasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && (job.reviewEnabled !== false || task.plannerResult?.objective_status === 'satisfied'));
10
10
  const implementation = implementationTasks(job);
11
11
  return (planSatisfied || legacySatisfied) && implementation.length > 0 && implementation.every(task => task.state === 'SUCCEEDED');
12
12
  }
@@ -1,13 +1,14 @@
1
1
  import { readFileSync } from 'node:fs';
2
2
  import { GraphRuntime } from './graph-v2.js';
3
3
  import { dispatchWorkflowGraph, dispatchWorkflowGraphSync } from './dispatcher.js';
4
+ import { reviewNeedsReplan } from '../review-replan.js';
4
5
  import { isEffectivelyBlocked, unblockNeedsNewPlan, unconsumedUnblockTrigger } from '../unblock.js';
5
6
  const source = readFileSync(new URL('../../workflow/planner-orchestration.mmd', import.meta.url), 'utf8');
6
7
  const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
7
8
  export const plannerOrchestrationV2 = new GraphRuntime(source, {
8
9
  states: new Set([
9
10
  'idle', 'check_legacy_pending', 'check_recover', 'check_plan_failure', 'check_plan_recovery', 'check_plan_recovery_exists', 'check_seed', 'check_planner', 'check_resolution_ownership',
10
- 'check_blocked', 'check_work', 'check_materialized', 'check_objective', 'wait', 'recovered', 'created',
11
+ 'check_blocked', 'check_work', 'check_materialized', 'check_review', 'wait', 'recovered', 'created',
11
12
  ]),
12
13
  guards: {
13
14
  legacyPlanningPending: boolGuard('legacyPlanningPending'),
@@ -21,7 +22,7 @@ export const plannerOrchestrationV2 = new GraphRuntime(source, {
21
22
  noBlockedWork: boolGuard('noBlockedWork'),
22
23
  noActiveImplementation: boolGuard('noActiveImplementation'),
23
24
  continuationMaterialized: boolGuard('continuationMaterialized'),
24
- objectiveUnsatisfied: boolGuard('objectiveUnsatisfied'),
25
+ reviewNeedsReplan: boolGuard('reviewNeedsReplan'),
25
26
  },
26
27
  actions: {
27
28
  'planner.createRecovery': { id: 'planner.createRecovery' },
@@ -65,6 +66,9 @@ export function plannerOrchestrationFacts(job, recoverablePendingPlan) {
65
66
  noActiveImplementation: !scopedTasks.some(task => task.kind !== 'planner' && (['QUEUED', 'RUNNING', 'AWAITING_DECISION'].includes(task.state) || (task.state === 'DRAFT' && !task.unblock))),
66
67
  resolutionOwnedByTroubleshooter: scopedTasks.some(task => task.kind !== 'planner' && task.resolution?.owner === 'troubleshooter' && ['active', 'waiting'].includes(task.resolution.state)),
67
68
  continuationMaterialized: Boolean(unconsumedUnblockTrigger(job)) || !(latestObjective === 'in_progress' && latestId && !job.tasks.some(task => task.kind !== 'planner' && task.planningDecisionId === latestId)),
68
- objectiveUnsatisfied: latestObjective !== 'satisfied',
69
+ reviewNeedsReplan: reviewNeedsReplan(job) || Boolean(unconsumedUnblockTrigger(job))
70
+ || (job.reviewEnabled === false && latestObjective !== 'satisfied')
71
+ || (!scopedPlans.some(plan => plan.status === 'SUCCEEDED')
72
+ && !scopedTasks.some(task => task.kind === 'planner' && task.state === 'SUCCEEDED')),
69
73
  };
70
74
  }
@@ -4,11 +4,12 @@ import { dispatchWorkflowGraphSync } from './dispatcher.js';
4
4
  const source = readFileSync(new URL('../../workflow/planner-trigger.mmd', import.meta.url), 'utf8');
5
5
  const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
6
6
  export const plannerTriggerV2 = new GraphRuntime(source, {
7
- states: new Set(['idle', 'check_unblock', 'check_initial', 'manual', 'unblock', 'initial', 'continuation']),
7
+ states: new Set(['idle', 'check_unblock', 'check_initial', 'check_review', 'manual', 'unblock', 'initial', 'review', 'continuation']),
8
8
  guards: {
9
9
  manualPlan: boolGuard('manualPlan'),
10
10
  hasUnblock: boolGuard('hasUnblock'),
11
11
  initialPlan: boolGuard('initialPlan'),
12
+ reviewRequired: boolGuard('reviewRequired'),
12
13
  },
13
14
  actions: {},
14
15
  events: { 'plan.requested': { id: 'plan.requested' } },
@@ -16,7 +17,7 @@ export const plannerTriggerV2 = new GraphRuntime(source, {
16
17
  export function dispatchPlannerTrigger(facts) {
17
18
  return dispatchWorkflowGraphSync(plannerTriggerV2, {
18
19
  initialState: 'idle', input: { transport: 'event', id: 'plan.requested', payload: {} }, durableFacts: facts, graphName: 'planner-trigger',
19
- isTransientState: state => state.startsWith('check_'), maxSteps: 4,
20
+ isTransientState: state => state.startsWith('check_'), maxSteps: 5,
20
21
  });
21
22
  }
22
23
  /** Compatibility/testing alias. Production callers use dispatchPlannerTrigger. */
@@ -9,9 +9,9 @@ export const reviewLifecycleV2 = new GraphRuntime(source, {
9
9
  reviewEnabled: boolGuard('reviewEnabled'),
10
10
  prOpen: boolGuard('prOpen'),
11
11
  jobActive: boolGuard('jobActive'),
12
- implementationComplete: boolGuard('implementationComplete'),
12
+ reviewWorkSettled: boolGuard('reviewWorkSettled'),
13
13
  headAvailable: boolGuard('headAvailable'),
14
- completionGateSatisfied: boolGuard('completionGateSatisfied'),
14
+ reviewPlanReady: boolGuard('reviewPlanReady'),
15
15
  noActiveReviewTask: boolGuard('noActiveReviewTask'),
16
16
  currentReviewCancelled: boolGuard('currentReviewCancelled'),
17
17
  noApprovedCurrentReview: boolGuard('noApprovedCurrentReview'),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.232",
3
+ "version": "2.0.234",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -7,6 +7,10 @@ description: Use Agents Relay for durable multi-step or multi-agent work that ne
7
7
 
8
8
  Agents Relay manages durable Jobs and Tasks. Use its CLI for Job/Task state and actions; do not read its private storage, GitHub projections, or internal service APIs. Prefer completing simple, non-delegated work directly without Relay.
9
9
 
10
+ ## Job Execution Lifecycle (JEL)
11
+
12
+ Explain **JEL** to the user: **Create → Plan → Execute → Final Review → Merge → Completed**. After work/recovery Tasks terminate (SUCCEEDED/FAILED/CANCELLED), Final Review judges completion: PASS merges; CHANGES_REQUIRED persists findings, starts Planner N+1 for minimal fixes, then re-reviews. No automatic post-success Plan. Planner/Workers use discovered **ponytail** Skill (YAGNI, reuse, minimal Tasks); preserve mandatory safeguards.
13
+
10
14
  ## 1. Choose and start a Job
11
15
 
12
16
  Use Relay when the objective requires independent Tasks, durable progress, retries, review, or cross-session handoffs. Capture the full user objective, decisions, constraints, acceptance checks, and delivery expectations in standalone Markdown before creating a Job. A fresh agent must be able to act without the originating conversation. Put a Mermaid diagram before its explanation only when it clarifies a real workflow.
@@ -15,11 +19,11 @@ For ordinary CLI use, consult `npx agents-relay --help` and `npx agents-relay <c
15
19
 
16
20
  ```sh
17
21
  npx agents-relay job create --repo OWNER/REPO --title "Objective" --objective-file job.md --initial-plan
18
- npx agents-relay job show --repo OWNER/REPO --id JOB_ID
22
+ npx agents-relay job show --id JOB_ID
19
23
  npx agents-relay task list --repo OWNER/REPO --id JOB_ID
20
24
  ```
21
25
 
22
- Use the **Job ID returned by create**; do not invent an ID, PR number, or Task. Omit `--initial-plan` only for explicitly create-only work. For an existing GitHub PR, use `job adopt`; do not create a managed PR through raw GitHub commands. For local-only work, consult the CLI's `--no-github` option.
26
+ Use the **Job ID returned by create**; do not invent an ID, PR number, or Task. Omit `--initial-plan` only for explicitly create-only work. Existing GitHub PRs are not imported as Jobs; GitHub is audit-only and local Git owns merge/delivery. For local-only work, consult the CLI's `--no-github` option.
23
27
 
24
28
  Read `contracts/task-job-contract.md` before authoring or changing Jobs or Tasks and `contracts/orchestrator-workflows.md` when handling initial planning, P0/self Jobs, or merge/delivery boundaries. For content work, load the active Neo Project rules, its Agent Graph if present, and the relevant stage contracts—not a presumed universal production sequence.
25
29
 
@@ -19,11 +19,9 @@ Use `speckit-checklist` only as requirements-quality guidance; do not create
19
19
  or edit checklists in this read-only Reviewer role. A Spec Kit analysis never
20
20
  replaces independent implementation and acceptance-evidence review.
21
21
 
22
- ## Targeted revision ownership
22
+ ## Findings and re-planning ownership
23
23
 
24
- For actionable findings, identify the original responsible durable Task ID. When the **execution-pinned Relay CLI supports** `task revise`, submit each owner's findings with a stable request ID, the exact active Reviewer execution identity, immutable head SHA and findings file; check the durable receipt. An ambiguous owner must be reported, not guessed. Do not edit artifacts, invoke Planner for every issue, or claim CLI submission completed a revision.
25
-
26
- **Bootstrap compatibility:** During a managed rollout that is itself introducing `task revise`, the execution-pinned CLI may not yet expose the command. Verify genuine command unavailability via its help/usage output. In that one case, **do not fail a completed review solely because the CLI does not exist**. Publish the canonical `task.completed` verdict `changes-required` with exact `head_sha`, complete actionable `data.findings` (including owner Task IDs where known), and `data.revision_submission: "cli-unavailable"`. Relay owns fallback remediation through its existing Review Graph. Never claim targeted requests were persisted. This fallback is NOT permission to ignore an available CLI's validation error, stale execution, authorization failure or missing evidence; those remain fail-closed.
24
+ Final Review is the sole whole-Job completion check. Examine all terminal Tasks, including FAILED and CANCELLED; these may be historically superseded by verified replacement work, but an unresolved required outcome is **CHANGES_REQUIRED**, never PASS. For each blocking finding, provide its concrete evidence, minimum remediation and responsible original Task ID when known. Put the **complete actionable findings in the `task.completed` verdict** (`data.findings`) at the immutable head SHA. Relay records this verdict in the Job and starts the next Planner round to assign the minimal fix Tasks. Do not call `task revise`, create Tasks, or initiate a separate Planner from this Reviewer; the JEL owns the handoff. Existing persisted targeted-revision requests remain supported by the runtime for backward compatibility.
27
25
 
28
26
  ## Review Decision
29
27
 
@@ -19,6 +19,12 @@ A CLI rejection (`PLAN_APPLY_VALIDATION_FAILED`) is distinct from a missing appl
19
19
 
20
20
  Read current Plan, prior rounds, and Task history through the execution-bound Relay `plan context` CLI response. Do not infer Plan status from GitHub or PR comments. A Plan records its trigger/context (including unblock/change facts), assessment, and generated Task IDs; Plan records are not semantic parents for work Tasks.
21
21
 
22
+ ## Ponytail — keep Plans and Tasks lean
23
+
24
+ Apply the installed `ponytail` Skill (`full`) when resolved in the execution context. Its ladder is mandatory: question if the extra Task is needed (YAGNI), reuse existing helpers/tests, keep scope minimal, and only split by truly independent Agent responsibility. Never add a Task solely to repeat successful checks or because some optional test could exist; do not defer mandatory security or correctness checks. The Final Reviewer—not a second completion Planner—decides whether the Job objective is satisfied.
25
+
26
+ For `plan_trigger.source = review`, consume the persisted Final Reviewer findings and propose **only minimal revision Tasks** that close them, keeping original Task history. Do not create a fresh Final Reviewer Task; Relay creates it when all Tasks are terminal. Never claim earlier failures succeeded or leave an unresolved required failure without a proper resolution.
27
+
22
28
  ## Planning contract
23
29
 
24
30
  **Plan the whole objective before choosing Task boundaries.**
@@ -53,7 +53,7 @@ Read `troubleshooter-qa.md` beside the Prompt-pinned Relay Skill for user-editab
53
53
  - Never blindly retry a deterministic failure. Event-history inspection is a hard precondition for retry; if event history cannot be retrieved, record that observability blocker explicitly rather than pretending diagnosis is complete.
54
54
  - Never create a second P0 Job for the same root cause when a suitable active one already exists; reuse/adopt/reconcile it.
55
55
  - P0 fixes must follow the P0/self-job contract: durable Job first, orchestrator-owned Task immediately, direct execution by this recovery orchestrator, no reviewer gate unless explicitly required.
56
- - Repository PR creation/adoption/repair still goes through Agents Relay.
56
+ - Relay owns the local Job lifecycle and optional GitHub PR projection; do not import external PRs as Jobs.
57
57
  - Keep fixes narrowly scoped; do not use a failed application task as permission for broad platform refactoring.
58
58
  - If a P0 fix publishes a package or changes a managed service, verify the released artifact and dependent service health before retrying the original Task.
59
59
  - Do not mark an immediate recovery successful merely because a repair PR was opened. A deferred recovery may complete after it has durably registered the exact original Task/attempt on the blocker Job; Relay then owns the later generation-safe wake-up.
@@ -6,6 +6,12 @@ Before `job create`, the orchestrator converts the relevant discussion into a st
6
6
 
7
7
  This contract defines orchestrator-owned exception workflows that sit above normal Agents Relay task/job execution.
8
8
 
9
+ ## Review-driven JEL continuation
10
+
11
+ After the Initial Plan materializes its Tasks, Relay waits for **all non-review Tasks to be terminal**, including Troubleshooter recoveries. The Final Reviewer reads every Task result (including FAILED and CANCELLED), the original Job objective, the immutable head and test evidence. An outstanding required failure must be reported as a finding and cannot pass the merge gate. The Final Review is the **completion check**; do not schedule a second Planner merely to ask whether the objective is satisfied.
12
+
13
+ `review.approved` with valid durable evidence permits Relay-owned merge/delivery. `review.changes_required` persists the immutable Reviewer's findings in the Job and initiates a **new Planner round**, whose sole automatic objective is to address those findings with the minimum necessary revision Tasks. Once those Tasks terminate, repeat Final Review. No speculative verification Task or separate completion-check Planner is allowed. Preserve older targeted-revision histories for restart compatibility; new Review rounds should use the Review → Replan path. A real blocker/recovery may use its separate canonical trigger without pretending to be a Review finding.
14
+
9
15
  ## Normal managed Job start workflow
10
16
 
11
17
  For a normal managed Job, the preferred bootstrap is one command:
@@ -18,7 +24,7 @@ job create --initial-plan
18
24
  -> normal routing, execution, and reconciliation
19
25
  ```
20
26
 
21
- Without `--initial-plan`, `job create` remains create-only and establishes durable Job/PR state without execution. `agents-relay plan` remains available for an existing create-only/adopted Job. Unless the user explicitly requested **create-only / no execution**, the orchestrator should use `job create --initial-plan` rather than issuing two separate commands.
27
+ Without `--initial-plan`, `job create` remains create-only and establishes durable Job state without execution. `agents-relay plan` remains available for an existing create-only Job. Unless the user explicitly requested **create-only / no execution**, the orchestrator should use `job create --initial-plan` rather than issuing two separate commands.
22
28
 
23
29
  The initial decomposition belongs to that durable Planner round. The orchestrator must not hand-author the initial child Task batch as a substitute. If initial planning fails, the create command fails visibly after preserving the durable Job/Plan evidence; the orchestrator must not silently invent Tasks. Every Job follows this same objective-driven lifecycle. After a completed implementation batch, Relay automatically creates subsequent Plan rounds until the latest successful Plan reports `objective_status: satisfied`; there is no fixed/autonomous execution mode or Job scheduling.
24
30
 
@@ -15,7 +15,7 @@ For long-form content, use files instead of shell-quoted arguments:
15
15
 
16
16
  When creating a new Job from an active discussion, the orchestrator must consolidate **all context needed to finish the Job without the originating thread** into the Job objective before creation. Include, as applicable: goal, relevant background, decisions already made, requirements, constraints, lifecycle/workflow semantics, non-goals, implementation boundaries, acceptance criteria, delivery/review instructions, and any important known issues. Do not create a Job whose objective is only a one-line summary when the discussion contains material implementation context.
17
17
 
18
- Use `job create` with standalone objective Markdown, or `job adopt` for an existing PR when authorized. Use Relay CLI for subsequent Job reads and updates; do not infer Job state or objective from GitHub.
18
+ Use `job create` with standalone objective Markdown. Existing PRs are not imported as Jobs. Use Relay CLI for subsequent Job reads and updates; do not infer Job state or objective from GitHub.
19
19
 
20
20
  ## Task producers
21
21
 
@@ -6,7 +6,7 @@ Real goal: select and use durable Relay Jobs/Tasks only when needed, plan and ve
6
6
 
7
7
  The provider-independent `capabilities.json` contains 35 cases across:
8
8
  - direct vs managed routing (including unauthorized job creation);
9
- - create/create-only/adopt/local-only and durable dependency handoffs;
9
+ - create/create-only/legacy PR-bound inspection/local-only and durable dependency handoffs;
10
10
  - Planner apply, rejected candidate, and unknown/stale execution;
11
11
  - role-specific Spec Kit selection, assigned-Task boundaries, read-only review, and non-spec fallbacks;
12
12
  - Task event and status authority, correct execution identity;
@@ -2,7 +2,7 @@
2
2
  "schema": "agents-relay-skill-capabilities-v1",
3
3
  "instruction": "Use SKILL.md with the scenario. Return the intended action, CLI subcommand or direct tool, what must be checked, and what must not be assumed. Do not perform side effects.",
4
4
  "output_schema": {
5
- "decision": "direct|create|adopt|inspect|plan|task_create|review|recover|escalate|service|worker_context",
5
+ "decision": "direct|create|inspect|plan|task_create|review|recover|escalate|service|worker_context",
6
6
  "action": "string",
7
7
  "verification": "string",
8
8
  "avoid": "string"
@@ -53,14 +53,17 @@
53
53
  },
54
54
  {
55
55
  "id": "existing-pr",
56
- "capability": "create",
57
- "request": "Adopt an existing GitHub PR into Relay, preserving its history.",
56
+ "capability": "inspect",
57
+ "request": "I have a legacy Relay Job that was previously bound to a GitHub PR. Show its current durable status and preserve its history.",
58
58
  "expected": {
59
- "decision": "adopt",
60
- "command": "job adopt"
59
+ "decision": "inspect",
60
+ "command": "job show",
61
+ "flags": [
62
+ "--id"
63
+ ]
61
64
  },
62
65
  "forbidden": [
63
- "job create",
66
+ "job adopt",
64
67
  "raw GitHub PR create"
65
68
  ]
66
69
  },
@@ -89,7 +89,7 @@ try {
89
89
  rules:['DO NOT run tools, shell commands, or perform any side effects.',
90
90
  'For each scenario return what an agent should DO NEXT, as if it were an intended action, not a command to execute now.',
91
91
  'Return only JSON: {"results":[{"id":"case id","decision":"enum","action":"specific intended CLI command with required flags OR protocol event","verification":"brief evidence to confirm","avoid":"brief safety constraint"}]}.',
92
- 'decision must be one of: direct, create, adopt, inspect, plan, task_create, review, recover, escalate, service, worker_context.',
92
+ 'decision must be one of: direct, create, inspect, plan, task_create, review, recover, escalate, service, worker_context.',
93
93
  'Use the actual Relay CLI or event contracts in the skill. Do not guess output IDs.',
94
94
  'In action include exact relevant CLI flags, not only the action name; for task events use exact event names.',
95
95
  'For cases with role_contract, follow that exact agent role and use stage-appropriate Spec Kit skills only for spec-oriented delivery.',
@@ -16,7 +16,7 @@ checkResolution["state: check_resolution_ownership"]
16
16
  checkBlocked["state: check_blocked"]
17
17
  checkWork["state: check_work"]
18
18
  checkMaterialized["state: check_materialized"]
19
- checkObjective["state: check_objective"]
19
+ checkReview["state: check_review"]
20
20
  wait["state: wait"]
21
21
  recovered["state: recovered"]
22
22
  created["state: created"]
@@ -32,7 +32,7 @@ resolutionOwned["guard: resolutionOwnedByTroubleshooter"]
32
32
  noBlocked["guard: noBlockedWork"]
33
33
  noActiveWork["guard: noActiveImplementation"]
34
34
  materialized["guard: continuationMaterialized"]
35
- unsatisfied["guard: objectiveUnsatisfied"]
35
+ reviewRequired["guard: reviewNeedsReplan"]
36
36
 
37
37
  recoverAction["action: planner.recoverPending"]
38
38
  createRecovery["action: planner.createRecovery"]
@@ -84,9 +84,9 @@ noActiveWork -->|true| checkMaterialized
84
84
 
85
85
  checkMaterialized -->|on: planner.reconcile| materialized
86
86
  materialized -->|false| wait
87
- materialized -->|true| checkObjective
87
+ materialized -->|true| checkReview
88
88
 
89
- checkObjective -->|on: planner.reconcile| unsatisfied
90
- unsatisfied -->|false| wait
91
- unsatisfied -->|true| createAction
89
+ checkReview -->|on: planner.reconcile| reviewRequired
90
+ reviewRequired -->|false| wait
91
+ reviewRequired -->|true| createAction
92
92
  createAction --> created
@@ -7,14 +7,17 @@ flowchart LR
7
7
  idle["state: idle"]
8
8
  checkUnblock["state: check_unblock"]
9
9
  checkInitial["state: check_initial"]
10
+ checkReview["state: check_review"]
10
11
  manual["state: manual"]
11
12
  unblock["state: unblock"]
12
13
  initial["state: initial"]
13
14
  continuation["state: continuation"]
15
+ review["state: review"]
14
16
 
15
17
  manualGuard["guard: manualPlan"]
16
18
  unblockGuard["guard: hasUnblock"]
17
19
  initialGuard["guard: initialPlan"]
20
+ reviewGuard["guard: reviewRequired"]
18
21
 
19
22
  idle -->|on: plan.requested| manualGuard
20
23
  manualGuard -->|true| manual
@@ -26,4 +29,8 @@ unblockGuard -->|false| checkInitial
26
29
 
27
30
  checkInitial -->|on: plan.requested| initialGuard
28
31
  initialGuard -->|true| initial
29
- initialGuard -->|false| continuation
32
+ initialGuard -->|false| checkReview
33
+
34
+ checkReview -->|on: plan.requested| reviewGuard
35
+ reviewGuard -->|true| review
36
+ reviewGuard -->|false| continuation
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  title: Review Lifecycle
3
- description: Manages review creation, immutable verdicts, changes-required, and re-review. The implementationComplete guard ignores only durably resolved cancel_supersede cancellations and failed Tasks with a valid superseded classification targeting succeeded work.
3
+ description: Manages review creation, immutable verdicts, changes-required, and re-review. Review is eligible after all non-review Tasks are terminal, regardless of outcome. Approval still requires verified implementation outcomes before merge.
4
4
  ---
5
5
  flowchart LR
6
6
  %% relay: initial none
@@ -15,16 +15,16 @@ stale["state: STALE"]
15
15
 
16
16
  reviewEnabledNone["guard: reviewEnabled"]
17
17
  jobActiveNone["guard: jobActive"]
18
- implementationCompleteNone["guard: implementationComplete"]
18
+ workTerminalNone["guard: reviewWorkSettled"]
19
19
  headAvailableNone["guard: headAvailable"]
20
- completionGateNone["guard: completionGateSatisfied"]
20
+ reviewPlanReadyNone["guard: reviewPlanReady"]
21
21
  noActiveReviewNone["guard: noActiveReviewTask"]
22
22
  noApprovedReviewNone["guard: noApprovedCurrentReview"]
23
23
  reviewEnabledStale["guard: reviewEnabled"]
24
24
  jobActiveStale["guard: jobActive"]
25
- implementationCompleteStale["guard: implementationComplete"]
25
+ workTerminalStale["guard: reviewWorkSettled"]
26
26
  headAvailableStale["guard: headAvailable"]
27
- completionGateStale["guard: completionGateSatisfied"]
27
+ reviewPlanReadyStale["guard: reviewPlanReady"]
28
28
  noActiveReviewStale["guard: noActiveReviewTask"]
29
29
  noApprovedReviewStale["guard: noApprovedCurrentReview"]
30
30
  pendingRetry["guard: noActiveReviewTask"]
@@ -56,14 +56,14 @@ mergeStarted["action: review.requestMerge"]
56
56
  none -->|on: reconcile| reviewEnabledNone
57
57
  reviewEnabledNone -->|true| jobActiveNone
58
58
  reviewEnabledNone -->|false| none
59
- jobActiveNone -->|true| implementationCompleteNone
59
+ jobActiveNone -->|true| workTerminalNone
60
60
  jobActiveNone -->|false| none
61
- implementationCompleteNone -->|true| headAvailableNone
62
- implementationCompleteNone -->|false| none
63
- headAvailableNone -->|true| completionGateNone
61
+ workTerminalNone -->|true| headAvailableNone
62
+ workTerminalNone -->|false| none
63
+ headAvailableNone -->|true| reviewPlanReadyNone
64
64
  headAvailableNone -->|false| none
65
- completionGateNone -->|true| noActiveReviewNone
66
- completionGateNone -->|false| none
65
+ reviewPlanReadyNone -->|true| noActiveReviewNone
66
+ reviewPlanReadyNone -->|false| none
67
67
  noActiveReviewNone -->|true| noApprovedReviewNone
68
68
  noActiveReviewNone -->|false| none
69
69
  noApprovedReviewNone -->|true| createNone
@@ -73,14 +73,14 @@ createNone --> pending
73
73
  stale -->|on: reconcile| reviewEnabledStale
74
74
  reviewEnabledStale -->|true| jobActiveStale
75
75
  reviewEnabledStale -->|false| stale
76
- jobActiveStale -->|true| implementationCompleteStale
76
+ jobActiveStale -->|true| workTerminalStale
77
77
  jobActiveStale -->|false| stale
78
- implementationCompleteStale -->|true| headAvailableStale
79
- implementationCompleteStale -->|false| stale
80
- headAvailableStale -->|true| completionGateStale
78
+ workTerminalStale -->|true| headAvailableStale
79
+ workTerminalStale -->|false| stale
80
+ headAvailableStale -->|true| reviewPlanReadyStale
81
81
  headAvailableStale -->|false| stale
82
- completionGateStale -->|true| noActiveReviewStale
83
- completionGateStale -->|false| stale
82
+ reviewPlanReadyStale -->|true| noActiveReviewStale
83
+ reviewPlanReadyStale -->|false| stale
84
84
  noActiveReviewStale -->|true| noApprovedReviewStale
85
85
  noActiveReviewStale -->|false| stale
86
86
  noApprovedReviewStale -->|true| createStale
@@ -151,6 +151,20 @@ limitOwnerResolution --> changes
151
151
  prepareRereview --> stale
152
152
  changes -->|on: head.changed| cancelChanges
153
153
  cancelChanges --> stale
154
+ %% Only a Review-finding-driven Plan with settled revision Tasks opens re-review.
155
+ reviewChangesReady["guard: reviewPlanReady"]
156
+ reviewChangesSettled["guard: reviewWorkSettled"]
157
+ reviewChangesInactive["guard: noActiveReviewTask"]
158
+ createChanges["action: review.create"]
159
+ changes -->|on: reconcile| reviewChangesReady
160
+ reviewChangesReady -->|true| reviewChangesSettled
161
+ reviewChangesReady -->|false| changes
162
+ reviewChangesSettled -->|true| reviewChangesInactive
163
+ reviewChangesSettled -->|false| changes
164
+ reviewChangesInactive -->|true| createChanges
165
+ reviewChangesInactive -->|false| changes
166
+ createChanges --> pending
167
+
154
168
  blocked -->|on: review.retry| reviewUnblocked
155
169
  reviewUnblocked -->|true| pending
156
170
  reviewUnblocked -->|false| blocked