agents-relay 2.0.231 → 2.0.233

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.
Files changed (32) hide show
  1. package/dist/blocker-recovery.js +325 -0
  2. package/dist/blockers.js +7 -1
  3. package/dist/cli-blocker.js +35 -2
  4. package/dist/cli-help.js +6 -0
  5. package/dist/dashboard-data.js +17 -12
  6. package/dist/dashboard-html.js +1 -1
  7. package/dist/dashboard-workflow-inspection.js +1 -1
  8. package/dist/managed-worker-input.js +6 -0
  9. package/dist/planner.js +12 -3
  10. package/dist/pool.js +19 -2
  11. package/dist/reconciler-review.js +9 -6
  12. package/dist/relayd-control.js +87 -1
  13. package/dist/review-replan.js +39 -0
  14. package/dist/task-transitions.js +2 -2
  15. package/dist/workflow/blocker-recovery.js +32 -0
  16. package/dist/workflow/blocker-resolution-v2.js +1 -1
  17. package/dist/workflow/planner-orchestration-v2.js +7 -3
  18. package/dist/workflow/planner-trigger-v2.js +3 -2
  19. package/dist/workflow/review-v2.js +2 -2
  20. package/package.json +1 -1
  21. package/skills/agents-relay/SKILL.md +5 -1
  22. package/skills/agents-relay/agents/job-acceptance-reviewer.agent.md +2 -4
  23. package/skills/agents-relay/agents/planner.agent.md +7 -0
  24. package/skills/agents-relay/agents/troubleshooter.agent.md +2 -1
  25. package/skills/agents-relay/contracts/blocker-job-recovery.md +23 -0
  26. package/skills/agents-relay/contracts/orchestrator-workflows.md +6 -0
  27. package/skills/agents-relay/contracts/task-recovery-flows.md +2 -1
  28. package/workflow/blocker-recovery.mmd +51 -0
  29. package/workflow/blocker-resolution.mmd +5 -5
  30. package/workflow/planner-orchestration.mmd +6 -6
  31. package/workflow/planner-trigger.mmd +8 -1
  32. package/workflow/review-lifecycle.mmd +31 -17
@@ -0,0 +1,325 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { ensureManagedGitHubJob } from './cli-job-create.js';
3
+ import { DisabledGitHubClient } from './no-github.js';
4
+ import { openLocalManagedStore } from './local-managed-store.js';
5
+ import { discoverLocalRelayStoreSnapshots, relayStoreDirectory } from './relay-store.js';
6
+ import { registerBlockerDependency } from './blockers.js';
7
+ import { dispatchBlockerRecovery } from './workflow/blocker-recovery.js';
8
+ function normalizeRepository(value) {
9
+ const trimmed = value.trim().replace(/\.git$/, '');
10
+ if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.-]+$/.test(trimmed) || trimmed.includes('..')) {
11
+ throw new Error(`Invalid repository identity: ${value}`);
12
+ }
13
+ return trimmed;
14
+ }
15
+ function repositoryOwner(value) {
16
+ return value.split('/')[0].toLowerCase();
17
+ }
18
+ function normalizedIntent(value) {
19
+ return value.trim().replace(/\s+/g, ' ');
20
+ }
21
+ function intentFingerprint(input, blockedAttempt) {
22
+ const stable = {
23
+ targetRepository: normalizeRepository(input.targetRepository),
24
+ dependentRepository: normalizeRepository(input.dependentRepository),
25
+ dependentJobId: input.dependentJobId,
26
+ dependentTaskId: input.dependentTaskId,
27
+ blockedAttempt,
28
+ reason: normalizedIntent(input.reason),
29
+ title: normalizedIntent(input.title),
30
+ objective: normalizedIntent(input.objective),
31
+ projectPath: input.projectPath ?? null,
32
+ resolutionMode: input.resolutionMode,
33
+ };
34
+ return createHash('sha256').update(JSON.stringify(stable)).digest('hex');
35
+ }
36
+ function validateInput(input) {
37
+ const requestId = input.requestId.trim();
38
+ const title = input.title.trim();
39
+ const objective = input.objective.trim();
40
+ const reason = normalizedIntent(input.reason);
41
+ if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{7,199}$/.test(requestId))
42
+ throw new Error('Blocker recovery requestId must be 8-200 safe identity characters');
43
+ if (title.length < 10 || title.length > 200)
44
+ throw new Error('Blocker recovery title must be 10-200 characters');
45
+ if (reason.length < 20 || reason.length > 1000)
46
+ throw new Error('Blocker recovery reason must be 20-1000 characters');
47
+ const normalizedObjective = normalizedIntent(objective);
48
+ const targetRepository = normalizeRepository(input.targetRepository);
49
+ const dependentRepository = normalizeRepository(input.dependentRepository);
50
+ if (normalizedObjective.length < 120 || normalizedObjective.length > 20000)
51
+ throw new Error('Blocker recovery objective must contain 120-20000 characters of standalone context');
52
+ if (input.origin !== 'planner' && input.origin !== 'troubleshooter')
53
+ throw new Error('Blocker recovery origin must be planner or troubleshooter');
54
+ if (input.resolutionMode !== 'merge' && input.resolutionMode !== 'verified')
55
+ throw new Error('Blocker recovery resolutionMode must be merge or verified');
56
+ if (!normalizedObjective.includes(targetRepository))
57
+ throw new Error(`Blocker recovery objective must identify target repository ${targetRepository}`);
58
+ if (!normalizedObjective.includes(input.dependentTaskId))
59
+ throw new Error(`Blocker recovery objective must identify dependent Task ${input.dependentTaskId}`);
60
+ if (input.projectPath && (input.projectPath.startsWith('/') || input.projectPath.includes('\\')
61
+ || input.projectPath.split('/').some(segment => segment === '' || segment === '.' || segment === '..'))) {
62
+ throw new Error('Blocker recovery projectPath must be a normalized repository-relative path');
63
+ }
64
+ if (targetRepository === dependentRepository)
65
+ throw new Error('Blocker recovery requires a distinct target repository');
66
+ if (repositoryOwner(targetRepository) !== repositoryOwner(dependentRepository)) {
67
+ throw new Error('Blocker recovery target and dependent repositories must share one owner/workspace trust boundary');
68
+ }
69
+ }
70
+ function receipt(input, blockerJobId, outcome, planningRecoveryRequired, request, now) {
71
+ return {
72
+ requestId: input.requestId,
73
+ reason: request.reason,
74
+ status: planningRecoveryRequired ? 'planning_required' : request.status === 'planned' ? 'planned' : 'registered',
75
+ blockerJobId,
76
+ blockerRepository: request.targetRepository,
77
+ dependentRepository: request.dependentRepository,
78
+ dependentJobId: request.dependentJobId,
79
+ dependentTaskId: request.dependentTaskId,
80
+ resolutionMode: request.resolutionMode,
81
+ outcome,
82
+ planningRecoveryRequired,
83
+ createdAt: request.createdAt,
84
+ updatedAt: now,
85
+ };
86
+ }
87
+ function makeRequest(input, now, blockedAttempt) {
88
+ return {
89
+ requestId: input.requestId.trim(),
90
+ intentFingerprint: intentFingerprint(input, blockedAttempt),
91
+ reason: normalizedIntent(input.reason),
92
+ status: 'created',
93
+ targetRepository: normalizeRepository(input.targetRepository),
94
+ dependentRepository: normalizeRepository(input.dependentRepository),
95
+ dependentJobId: input.dependentJobId,
96
+ dependentTaskId: input.dependentTaskId,
97
+ blockedAttempt,
98
+ title: input.title.trim(),
99
+ objective: input.objective.trim(),
100
+ projectPath: input.projectPath,
101
+ resolutionMode: input.resolutionMode,
102
+ origin: input.origin,
103
+ authorized: input.authorized,
104
+ createdAt: now,
105
+ updatedAt: now,
106
+ };
107
+ }
108
+ function planningRequired(job) {
109
+ if (job.state === 'COMPLETED' || job.state === 'CANCELLED')
110
+ return false;
111
+ const latestPlan = [...(job.plans ?? [])].sort((left, right) => right.round - left.round)[0];
112
+ return job.state === 'DRAFT' || latestPlan?.status !== 'SUCCEEDED';
113
+ }
114
+ function requestStatus(job, planningRecoveryRequired) {
115
+ if (planningRecoveryRequired)
116
+ return 'planning_required';
117
+ if ((job.plans ?? []).some(plan => plan.status === 'SUCCEEDED'))
118
+ return 'planned';
119
+ return 'registered';
120
+ }
121
+ async function loadKnownCandidate(directory, input, request) {
122
+ const snapshots = await discoverLocalRelayStoreSnapshots(directory);
123
+ const matchingRequests = snapshots.flatMap(snapshot => snapshot.jobs.filter(job => job.blockerRecoveryRequest?.requestId === request.requestId));
124
+ if (matchingRequests.length > 1)
125
+ throw new Error(`Ambiguous blocker recovery requestId ${request.requestId}`);
126
+ const summary = matchingRequests[0];
127
+ if (!summary)
128
+ return null;
129
+ const store = openLocalManagedStore(summary.repository, 0, { directory, jobId: summary.id, noGitHub: true });
130
+ const job = await store.store.load(summary.id);
131
+ const stored = job.blockerRecoveryRequest;
132
+ if (!stored
133
+ || stored.intentFingerprint !== request.intentFingerprint
134
+ || stored.targetRepository !== request.targetRepository
135
+ || stored.dependentRepository !== request.dependentRepository
136
+ || stored.dependentJobId !== request.dependentJobId
137
+ || stored.dependentTaskId !== request.dependentTaskId) {
138
+ throw new Error(`Blocker recovery requestId ${request.requestId} is already bound to a different durable intent`);
139
+ }
140
+ return { store, job, request: stored };
141
+ }
142
+ async function loadAuthoritativeCandidate(directory, request) {
143
+ const snapshots = await discoverLocalRelayStoreSnapshots(directory);
144
+ const candidates = snapshots.flatMap(snapshot => snapshot.jobs.filter(job => normalizeRepository(job.repository) === request.targetRepository
145
+ && (job.unblocks ?? []).some(relation => normalizeRepository(relation.repository) === request.dependentRepository
146
+ && relation.jobId === request.dependentJobId
147
+ && relation.taskId === request.dependentTaskId
148
+ && relation.blockedAttempt === request.blockedAttempt)));
149
+ if (candidates.length > 1)
150
+ throw new Error(`Ambiguous authoritative blocker dependency for ${request.dependentJobId}/${request.dependentTaskId}`);
151
+ const summary = candidates[0];
152
+ if (!summary)
153
+ return null;
154
+ const store = openLocalManagedStore(request.targetRepository, 0, { directory, jobId: summary.id, noGitHub: true });
155
+ const job = await store.store.load(summary.id);
156
+ return { store, job, request };
157
+ }
158
+ function adoptionValid(candidate, request) {
159
+ if (candidate.job.state === 'CANCELLED')
160
+ return false;
161
+ if (candidate.job.repository !== request.targetRepository)
162
+ return false;
163
+ if (candidate.job.blockerResolutionMode && candidate.job.blockerResolutionMode !== request.resolutionMode)
164
+ return false;
165
+ const stored = candidate.job.blockerRecoveryRequest;
166
+ return !stored || (stored.intentFingerprint === request.intentFingerprint && stored.targetRepository === request.targetRepository
167
+ && stored.dependentRepository === request.dependentRepository && stored.dependentJobId === request.dependentJobId
168
+ && stored.dependentTaskId === request.dependentTaskId);
169
+ }
170
+ async function closeStores(stores) {
171
+ for (const store of stores)
172
+ store.relay.close();
173
+ }
174
+ export async function ensureBlockerRecovery(input) {
175
+ validateInput(input);
176
+ const directory = input.storeDirectory ?? relayStoreDirectory();
177
+ const now = input.now ?? new Date().toISOString();
178
+ const dependentRepository = normalizeRepository(input.dependentRepository);
179
+ const dependentStore = openLocalManagedStore(dependentRepository, 0, { directory, jobId: input.dependentJobId, noGitHub: true });
180
+ const opened = [dependentStore];
181
+ let candidate = null;
182
+ let finalStore = null;
183
+ let outcome = 'created';
184
+ try {
185
+ const dependentJob = await dependentStore.store.load(input.dependentJobId);
186
+ const task = dependentJob.tasks.find(item => item.id === input.dependentTaskId);
187
+ if (!task)
188
+ throw new Error(`Dependent Task ${input.dependentTaskId} not found`);
189
+ if (!['FAILED', 'BLOCKED'].includes(task.state))
190
+ throw new Error(`Dependent Task ${task.id} must be failed or blocked before blocker recovery (${task.state})`);
191
+ const request = makeRequest(input, now, task.attempt);
192
+ const known = await loadKnownCandidate(directory, input, request);
193
+ if (known) {
194
+ opened.push(known.store);
195
+ candidate = known;
196
+ }
197
+ else {
198
+ const authoritative = await loadAuthoritativeCandidate(directory, request);
199
+ if (authoritative) {
200
+ opened.push(authoritative.store);
201
+ candidate = authoritative;
202
+ }
203
+ }
204
+ const authorizedRepositories = input.authorizedRepositories.map(normalizeRepository);
205
+ const targetResolvable = authorizedRepositories.includes(request.targetRepository);
206
+ const trustBoundaryValid = repositoryOwner(request.targetRepository) === repositoryOwner(request.dependentRepository);
207
+ const knownRequest = known !== null;
208
+ const authoritativeDependency = !knownRequest && candidate !== null;
209
+ const validAdoption = candidate ? adoptionValid(candidate, request) : false;
210
+ let blockerJobId = candidate?.job.id;
211
+ let planningRecovery = false;
212
+ const decision = await dispatchBlockerRecovery({
213
+ authorized: input.authorized,
214
+ knownRequest,
215
+ authoritativeDependency,
216
+ adoptionValid: validAdoption,
217
+ targetValid: targetResolvable,
218
+ trustBoundaryValid,
219
+ }, async (actionId) => {
220
+ if (actionId === 'recovery.createBlocker') {
221
+ const created = await ensureManagedGitHubJob(new DisabledGitHubClient(), request.targetRepository, new Set(), {
222
+ idempotencyKey: `blocker-recovery:${request.requestId}`,
223
+ title: request.title,
224
+ objective: request.objective,
225
+ projectPath: request.projectPath,
226
+ noGitHub: true,
227
+ storeDirectory: directory,
228
+ });
229
+ blockerJobId = created.job.id;
230
+ outcome = 'created';
231
+ planningRecovery = true;
232
+ const createdStore = openLocalManagedStore(request.targetRepository, 0, { directory, jobId: created.job.id, noGitHub: true });
233
+ opened.push(createdStore);
234
+ finalStore = createdStore;
235
+ if (!createdStore.store.mutateJob)
236
+ throw new Error('Blocker recovery requires atomic durable Job mutation');
237
+ await createdStore.store.mutateJob(created.job.id, current => ({
238
+ ...current,
239
+ blockerRecoveryRequest: { ...request, blockedAttempt: task.attempt, updatedAt: now },
240
+ blockerResolutionMode: request.resolutionMode,
241
+ }));
242
+ return {};
243
+ }
244
+ if (actionId !== 'recovery.adoptExistingBlocker' && actionId !== 'recovery.registerDependency') {
245
+ throw new Error(`Unsupported blocker recovery action ${actionId}`);
246
+ }
247
+ if (actionId === 'recovery.adoptExistingBlocker') {
248
+ if (!candidate)
249
+ throw new Error('Graph selected adoption without a verified blocker Job');
250
+ blockerJobId = candidate.job.id;
251
+ finalStore = candidate.store;
252
+ outcome = 'reused';
253
+ }
254
+ if (actionId === 'recovery.registerDependency') {
255
+ if (!blockerJobId)
256
+ throw new Error('Graph selected dependency registration without a blocker Job');
257
+ const targetStore = finalStore ?? openLocalManagedStore(request.targetRepository, 0, { directory, jobId: blockerJobId, noGitHub: true });
258
+ finalStore = targetStore;
259
+ if (!opened.includes(targetStore))
260
+ opened.push(targetStore);
261
+ const before = await targetStore.store.load(blockerJobId);
262
+ if (before.blockerResolutionMode && before.blockerResolutionMode !== request.resolutionMode) {
263
+ throw new Error(`Blocker ${blockerJobId} already uses ${before.blockerResolutionMode} resolution`);
264
+ }
265
+ const relation = await registerBlockerDependency({
266
+ blockerStore: targetStore.store,
267
+ blockerJobId,
268
+ dependentStore: dependentStore.store,
269
+ dependentJobId: request.dependentJobId,
270
+ dependentTaskId: request.dependentTaskId,
271
+ resolutionMode: request.resolutionMode,
272
+ expectedAttempt: task.attempt,
273
+ now,
274
+ });
275
+ if (!targetStore.store.mutateJob)
276
+ throw new Error('Blocker recovery requires atomic durable Job mutation');
277
+ const current = await targetStore.store.load(blockerJobId);
278
+ const prior = current.blockerRecoveryRequest;
279
+ if (prior && prior.intentFingerprint !== request.intentFingerprint) {
280
+ throw new Error(`Blocker Job ${blockerJobId} is already bound to a different recovery intent`);
281
+ }
282
+ planningRecovery = planningRequired(current);
283
+ const status = requestStatus(current, planningRecovery);
284
+ await targetStore.store.mutateJob(blockerJobId, job => ({
285
+ ...job,
286
+ blockerRecoveryRequest: {
287
+ ...(prior ?? request), blockedAttempt: relation.blockedAttempt,
288
+ status, updatedAt: now,
289
+ },
290
+ blockerResolutionMode: request.resolutionMode,
291
+ }));
292
+ if (outcome !== 'created')
293
+ outcome = before.unblocks?.some(item => item.jobId === request.dependentJobId && item.taskId === request.dependentTaskId) ? 'reused' : 'registered';
294
+ }
295
+ return {};
296
+ });
297
+ if (!decision.accepted)
298
+ throw new Error(`Blocker recovery graph rejected request ${request.requestId}: ${decision.reason}`);
299
+ if (decision.target !== 'ready' || !blockerJobId)
300
+ throw new Error(`Blocker recovery graph did not produce ready state for ${request.requestId}`);
301
+ finalStore ??= openLocalManagedStore(request.targetRepository, 0, { directory, jobId: blockerJobId, noGitHub: true });
302
+ if (!opened.includes(finalStore))
303
+ opened.push(finalStore);
304
+ const finalJob = await finalStore.store.load(blockerJobId);
305
+ planningRecovery = planningRequired(finalJob);
306
+ const receiptNow = now;
307
+ const final = await finalStore.store.load(blockerJobId);
308
+ await dependentStore.store.mutateJob(request.dependentJobId, current => {
309
+ const index = current.tasks.findIndex(item => item.id === request.dependentTaskId);
310
+ if (index < 0)
311
+ throw new Error(`Dependent Task ${request.dependentTaskId} disappeared`);
312
+ const updated = {
313
+ ...current.tasks[index],
314
+ blockerRecoveryReceipt: receipt(input, blockerJobId, outcome, planningRecovery, final.blockerRecoveryRequest ?? request, receiptNow),
315
+ };
316
+ current.tasks[index] = updated;
317
+ current.updatedAt = receiptNow;
318
+ return current;
319
+ });
320
+ return receipt(input, blockerJobId, outcome, planningRecovery, final.blockerRecoveryRequest ?? request, now);
321
+ }
322
+ finally {
323
+ await closeStores(new Set(opened));
324
+ }
325
+ }
package/dist/blockers.js CHANGED
@@ -14,6 +14,11 @@ export async function registerBlockerDependency(options) {
14
14
  const task = dependentJob.tasks.find(item => item.id === options.dependentTaskId);
15
15
  if (!task)
16
16
  throw new Error(`Dependent task ${options.dependentTaskId} not found`);
17
+ if (task.jobId && task.jobId !== dependentJob.id)
18
+ throw new Error(`Dependent task ${task.id} is bound to another Job`);
19
+ if (options.expectedAttempt !== undefined && task.attempt !== options.expectedAttempt) {
20
+ throw new Error(`Dependent task ${task.id} advanced from expected attempt ${options.expectedAttempt} to ${task.attempt}`);
21
+ }
17
22
  if (!['DRAFT', 'FAILED', 'BLOCKED'].includes(task.state))
18
23
  throw new Error(`Dependent task ${task.id} is not waiting/blocked/failed (${task.state})`);
19
24
  const now = options.now ?? new Date().toISOString();
@@ -101,7 +106,8 @@ export async function resolveBlockerDependencies(options) {
101
106
  const targetMatches = !!task && ['DRAFT', 'FAILED', 'BLOCKED', 'QUEUED'].includes(task.state) && task.attempt === relation.blockedAttempt;
102
107
  let note = 'dependent task released from dependency wait';
103
108
  const decision = await dispatchBlockerResolution({
104
- resolutionAllowed: !(mode === 'verified' && options.resolution !== 'verified'),
109
+ resolutionConditionMet: blocker.state === 'COMPLETED'
110
+ && (mode === 'verified' ? options.resolution === 'verified' : options.resolution === 'merge'),
105
111
  targetMatches,
106
112
  effectivelyBlocked: !!task && isEffectivelyBlocked(task),
107
113
  alreadyUnblocked: Boolean(task?.unblock && ['DRAFT', 'QUEUED'].includes(task.state)),
@@ -1,8 +1,41 @@
1
- import { arg, relayControlCommand, relayControlJob, repository } from './cli-support.js';
1
+ import { arg, hasArg, relayControlCommand, relayControlJob, repository, textOption } from './cli-support.js';
2
2
  import { usage } from './cli-help.js';
3
3
  export async function runBlockerCommand(action, args) {
4
- if (!['add', 'resolve', 'show'].includes(action))
4
+ if (!['add', 'ensure', 'resolve', 'show'].includes(action))
5
5
  throw new Error(usage);
6
+ if (action === 'ensure') {
7
+ const dependentRepository = repository(args);
8
+ const dependentJobId = arg(args, '--id');
9
+ const targetRepository = arg(args, '--target-repo');
10
+ const requestId = arg(args, '--request-id');
11
+ const dependentTaskId = arg(args, '--dependent-task');
12
+ const reason = arg(args, '--reason');
13
+ const title = arg(args, '--title');
14
+ const objective = await textOption(args, '--objective', '--objective-file');
15
+ const origin = arg(args, '--origin', 'troubleshooter');
16
+ const modeValue = arg(args, '--resolution', 'merge');
17
+ if (!dependentJobId || !targetRepository || !requestId || !dependentTaskId || !title || !reason) {
18
+ throw new Error('blocker ensure requires --id, --target-repo, --request-id, --dependent-task, --title, and --reason');
19
+ }
20
+ if (!objective.trim())
21
+ throw new Error('blocker ensure requires --objective-file PATH|- or --objective MARKDOWN');
22
+ if (!hasArg(args, '--authorized'))
23
+ throw new Error('blocker ensure requires explicit --authorized');
24
+ if (!['planner', 'troubleshooter'].includes(origin))
25
+ throw new Error('--origin must be planner or troubleshooter');
26
+ if (!['merge', 'verified'].includes(modeValue))
27
+ throw new Error('--resolution must be merge or verified');
28
+ console.log(JSON.stringify(await relayControlCommand(args, {
29
+ command: 'blocker.ensure',
30
+ jobId: dependentJobId,
31
+ request: {
32
+ requestId, targetRepository, dependentRepository, dependentJobId, dependentTaskId, reason,
33
+ title, objective, resolutionMode: modeValue, origin, authorized: true,
34
+ projectPath: arg(args, '--project-path') || undefined,
35
+ },
36
+ }), null, 2));
37
+ return;
38
+ }
6
39
  repository(args);
7
40
  const id = arg(args, '--id');
8
41
  if (!id)
package/dist/cli-help.js CHANGED
@@ -258,6 +258,12 @@ The blocker Job owns reverse \`unblocks\` references. \`add\` registers a failed
258
258
  Blocker: --repo OWNER/REPO --id JOB_ID.
259
259
  Dependent: --dependent-repo OWNER/REPO --dependent-pr NUMBER --dependent-job JOB_ID --dependent-task TASK_ID.
260
260
  Common: --resolution merge|verified (default merge).`,
261
+ 'blocker ensure': `Create or reuse an authorized cross-repository blocker Job and register its reverse relation.
262
+
263
+ Dependent: --repo OWNER/REPO --id DEPENDENT_JOB_ID --dependent-task TASK_ID.
264
+ Target: --target-repo OWNER/REPO --title TITLE --reason TEXT --objective-file PATH|-.
265
+ Identity: --request-id STABLE_REQUEST_ID --origin planner|troubleshooter --resolution merge|verified --authorized.
266
+ Target repositories must be configured in the current trusted workspace; target projects must use a normalized repository-relative path.`,
261
267
  'blocker resolve': `Resolve a verified blocker and safely requeue matching dependents.
262
268
 
263
269
  Required: --repo OWNER/REPO --id JOB_ID. This explicit path is required for blockers configured with --resolution verified.`,
@@ -6,18 +6,23 @@ const repositoryPattern = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,36}[A-Za-z0-9])?)\/([A
6
6
  const workflowDirectory = fileURLToPath(new URL('../workflow/', import.meta.url));
7
7
  export const DASHBOARD_JOB_RESULT_LIMIT = 20;
8
8
  export const DEFAULT_DASHBOARD_JOB_STATUSES = ['DRAFT', 'ACTIVE', 'COMPLETED'];
9
- function compareDashboardJobs(a, b) {
10
- const timestamp = (job) => {
11
- const updated = Date.parse(job.updatedAt ?? '');
12
- if (Number.isFinite(updated))
13
- return updated;
14
- const created = Date.parse(job.createdAt ?? '');
15
- return Number.isFinite(created) ? created : 0;
16
- };
17
- return timestamp(b) - timestamp(a)
9
+ function dashboardJobTimestamp(job) {
10
+ const updated = Date.parse(job.updatedAt ?? '');
11
+ if (Number.isFinite(updated))
12
+ return updated;
13
+ const created = Date.parse(job.createdAt ?? '');
14
+ return Number.isFinite(created) ? created : 0;
15
+ }
16
+ function compareDashboardJobInventory(a, b) {
17
+ return dashboardJobTimestamp(b) - dashboardJobTimestamp(a)
18
18
  || a.repository.localeCompare(b.repository)
19
19
  || a.id.localeCompare(b.id);
20
20
  }
21
+ function compareDashboardJobs(a, b) {
22
+ const lifecycleGroup = (job) => job.state === 'COMPLETED' || job.state === 'CANCELLED' ? 1 : 0;
23
+ return lifecycleGroup(a) - lifecycleGroup(b)
24
+ || compareDashboardJobInventory(a, b);
25
+ }
21
26
  export async function dashboardWorkflowGraphs() {
22
27
  const names = (await readdir(workflowDirectory)).filter(name => name.endsWith('.mmd')).sort();
23
28
  return Promise.all(names.map(async (name) => {
@@ -59,7 +64,7 @@ export async function eventHistory(jobId, taskId, limit) {
59
64
  }
60
65
  /** CLI inventory is complete, including CANCELLED; only the dashboard list is capped. */
61
66
  export function listDashboardJobInventory(jobs, repository = '') {
62
- const selected = jobs.filter(job => !repository || job.repository === repository).sort(compareDashboardJobs);
67
+ const selected = jobs.filter(job => !repository || job.repository === repository).sort(compareDashboardJobInventory);
63
68
  return {
64
69
  jobs: selected,
65
70
  repositories: [...new Set(jobs.map(job => job.repository).filter(Boolean))].sort(),
@@ -85,9 +90,9 @@ export function searchDashboardJobs(jobs, query) {
85
90
  || String(job.id || '').toLowerCase().includes(search)
86
91
  || Boolean(normalizedPr) && String(job.prNumber || '').includes(normalizedPr);
87
92
  };
88
- const matching = jobs.filter(job => matchesStatus(job) && matchesRepository(job) && matchesSearch(job)).sort(compareDashboardJobs);
93
+ const matching = jobs.filter(job => matchesStatus(job) && matchesRepository(job) && matchesSearch(job)).sort(compareDashboardJobInventory);
89
94
  return {
90
- jobs: matching.slice(0, DASHBOARD_JOB_RESULT_LIMIT),
95
+ jobs: matching.slice(0, DASHBOARD_JOB_RESULT_LIMIT).sort(compareDashboardJobs),
91
96
  repositories: [...new Set(jobs.map(job => job.repository).filter(Boolean))].sort(),
92
97
  total: matching.length,
93
98
  };
@@ -262,7 +262,7 @@ function iconSvg(name){const paths={close:'M5 5l14 14M19 5 5 19',detail:'M7 3h7l
262
262
  function showDetailsDialog(title,sections){const dialog=element('dialog','details-dialog');dialog.setAttribute('aria-label',title);const head=element('div','details-dialog-head');const name=element('strong','',text(title));const close=element('button','icon-button');close.append(iconSvg('close'));close.type='button';close.setAttribute('aria-label','Close details');close.title='Close details';close.addEventListener('click',()=>dialog.close());head.append(name,close);dialog.append(head);for(const [label,value] of sections){if(value===undefined||value===null||value==='')continue;dialog.append(element('h3','',text(label)));const content=element('pre');content.textContent=typeof value==='string'?value:JSON.stringify(value,null,2);dialog.append(content);}dialog.addEventListener('close',()=>dialog.remove());document.body.append(dialog);dialog.showModal();}function openJobDetails(){const job=selected();if(!job)return;showDetailsDialog('Job '+job.id+' · '+value(job.title),[['Objective',job.objective],['Description',job.description],['State',job.state],['Plans',job.plans?.map(p=>({id:p.id,status:p.status,assessment:p.assessment,error:p.error,generatedTaskIds:p.generatedTaskIds}))],['Review',job.review],['Outcome',job.result],['Publication',job.publication],['Failure',job.error]]);}function openTaskDetails(task){const result=task.result?.data??task.result;showDetailsDialog('Task '+task.id+' · '+value(task.title),[['Input / task objective',task.input],['State',task.state],['Conclusion',result],['Result summary',task.result?.summary],['Planner assessment',task.plannerResult?.assessment],['Resolution',task.resolution],['Resolution classification',task.resolutionClassification],['Failure',task.failureReason||task.error],['Dependencies',task.dependencies]]);}document.querySelector('#job-content-open').addEventListener('click',openJobDetails);function renderTaskDetail(task){taskDetailRoot.replaceChildren();if(!task){taskDetailRoot.append(element('p','empty',text('Select a task to inspect execution details.')));return;}const routing=task.routing||{};const groups=element('div','detail-groups');groups.append(field('Title',task.title||'—'),field('Task ID',task.id),field('Kind',task.kind||'work'),taskStateField(task),...(task.state==='FAILED'&&task.resolution?.state?[field('Resolution state',task.resolution.state),field('Resolution path',task.resolution.path||'—'),field('Resolution target',task.resolution.targetTaskId||'—')]:[]),manualOverrideField(task),field('Planning decision',task.planningDecisionId||'—'),field('Planning source',task.planningSource||'—'),field('Planning round',task.planningRound===undefined?'—':String(task.planningRound)),field('Project / agent',value(task.projectName)+' / '+value(task.agentName)),field('Parent task',task.parentTaskId||'root'),...(task.resolutionClassification?[field('Resolution classification',task.resolutionClassification.kind),field('Resolution target',task.resolutionClassification.targetTaskId),field('Resolution evidence',task.resolutionClassification.evidence),field('Resolution reason',task.resolutionClassification.reason)]:[]),field('Adapter',task.adapter),field('Provider / model',value(routing.provider)+' / '+value(routing.model)),field('Reasoning / profile',value(routing.reasoning||routing.profile)),field('Attempt',attemptBudget(task)),field('Dependencies',Array.isArray(task.dependencies)&&task.dependencies.length?task.dependencies.join(', '):'none'),taskCommentField(task),chatField(task));const job=selected();if(task.reviewHeadSha&&job)groups.append(commitField('HEAD commit',job,task.reviewHeadSha));const graph=agentGraphField(task);if(graph)groups.append(graph);if(task.plannerResult)groups.append(field('Objective status',task.plannerResult.objective_status),markdownField('Assessment',task.plannerResult.assessment));if(task.error)groups.append(field('Error',task.error));const result=task.result?.data??task.result;if(result){groups.append(field('Conclusion',result.verdict||result.outcome?.verdict||task.result?.summary||'Available'));}taskDetailRoot.append(groups);const details=element('button','icon-button');details.append(iconSvg('detail'));details.type='button';details.setAttribute('aria-label','Task details and conclusion');details.title='Task details and conclusion';details.addEventListener('click',()=>openTaskDetails(task));taskDetailRoot.append(details);}
263
263
  function reviewStatus(job){const review=job?.review;if(!review)return 'Not started';if(review.outcome==='approved'&&review.headSha===job.headSha)return 'MERGE READY · approved';const stale=Array.isArray(job?.tasks)&&job.tasks.some(task=>['reviewer','job-acceptance-reviewer'].includes(task.agentName)&&task.reviewHeadSha&&job.headSha&&task.reviewHeadSha!==job.headSha);if(stale)return 'STALE · awaiting review';return String(review.outcome||'pending').replace('_',' ').toUpperCase();}function renderSelectedJob(){jobDetail.replaceChildren();const job=selected();if(!job){selectedJobTitle.textContent='';jobContentButton.disabled=true;jobContentButton.dataset.state='IDLE';jobDetail.append(element('div','empty',text('No durable jobs discovered.')));buildTree([]);renderTaskDetail(null);return;}selectedJobTitle.textContent=value(job.title||job.id);jobContentButton.disabled=false;jobContentButton.dataset.state=JOB_STATES.includes(job.state)?job.state:'IDLE';jobContentButton.setAttribute('aria-label','Job details · '+value(job.state));jobContentButton.title='Job details · '+value(job.state);if(jobSelectionKey(job)!==selectedJob){selectedJob=jobSelectionKey(job);selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}const summary=element('div','job-summary');summary.append(field('PR state',job.githubState||'UNKNOWN'),jobStateField(job),field('Runtime status',job.runtimeStatus||'IDLE'),field('Review',reviewStatus(job)),field('Creator thread',job.creatorThreadId||'—'),threadField('Implementation thread',job.implementationThreadId),threadField('Reviewer thread',job.reviewerThreadId),commitField('Review head SHA',job,job.review?.headSha||job.headSha||''),prField(job),field('Repository',job.repository||'—'),field('Last activity',relativeTime(job.updatedAt)),field('Task states',compactCounts(job.tasks)),chatShortcutField(job));jobDetail.append(summary);const selectedTask=(job.tasks||[]).find(task=>task.id===selectedTaskId)||null;if(selectedTaskId&&!selectedTask){selectedTaskId=null;eventTaskId=null;clearEvents();rememberSelection();}buildTree(job.tasks||[]);renderTaskDetail(selectedTask);renderEventScope();}function renderAll(){jobs.sort(compareJobs);syncFilters();renderJobList();renderSelectedJob();syncMobileJobsView();}
264
264
  function isCompleteUnmerged(job){return job.runtimeStatus==='MERGE_PENDING';}
265
- function compareJobs(a,b){const timestamp=job=>{const updated=Date.parse(job.updatedAt||'');if(Number.isFinite(updated))return updated;const created=Date.parse(job.createdAt||'');return Number.isFinite(created)?created:0;};return timestamp(b)-timestamp(a)||String(a.repository||'').localeCompare(String(b.repository||''))||String(a.id||'').localeCompare(String(b.id||''));}
265
+ function compareJobs(a,b){const lifecycleGroup=job=>job.state==='COMPLETED'||job.state==='CANCELLED'?1:0;const timestamp=job=>{const updated=Date.parse(job.updatedAt||'');if(Number.isFinite(updated))return updated;const created=Date.parse(job.createdAt||'');return Number.isFinite(created)?created:0;};return lifecycleGroup(a)-lifecycleGroup(b)||timestamp(b)-timestamp(a)||String(a.repository||'').localeCompare(String(b.repository||''))||String(a.id||'').localeCompare(String(b.id||''));}
266
266
  async function loadJSON(url){const response=await fetch(url);if(!response.ok)throw new Error(response.status+' '+response.statusText);return response.json();}
267
267
  async function refreshVersion(){try{const live=await loadJSON('/api/version');if(live?.version&&live.version!==DASHBOARD_VERSION)location.reload();}catch{}}
268
268
  function renderRateLimitStatus(status){
@@ -64,7 +64,7 @@ export async function inspectWorkflowSymbol(graphId, kind, name) {
64
64
  const matchingLine = source.split('\n').findIndex(line => pattern.test(line));
65
65
  if (matchingLine < 0)
66
66
  return null;
67
- const contracts = ['skills/agents-relay/contracts/event-contract.md', 'skills/agents-relay/contracts/task-recovery-flows.md'];
67
+ const contracts = ['skills/agents-relay/contracts/event-contract.md', 'skills/agents-relay/contracts/task-recovery-flows.md', 'skills/agents-relay/contracts/blocker-job-recovery.md'];
68
68
  const contractRefs = (await Promise.all(contracts.map(async (path) => {
69
69
  try {
70
70
  return matches(await readFile(join(ROOT, path), 'utf8'), name, path, 2);
@@ -43,6 +43,12 @@ export async function managedWorkerInput(job, task, context, mode = 'production'
43
43
  ...(eventProtocol && existsSync(eventProtocol) ? [eventProtocol] : []),
44
44
  join(packageRoot, 'skills/agents-relay/contracts/task-job-contract.md'),
45
45
  join(packageRoot, 'skills/agents-relay/contracts/event-contract.md'),
46
+ ...(role === 'troubleshooter' ? [
47
+ join(packageRoot, 'skills/agents-relay/contracts/task-recovery-flows.md'),
48
+ join(packageRoot, 'skills/agents-relay/contracts/blocker-job-recovery.md'),
49
+ ] : []),
50
+ ...(role === 'worker' && context.skills.find(skill => skill.name === 'ponytail')
51
+ ? [context.skills.find(skill => skill.name === 'ponytail').path] : []),
46
52
  ...(role === 'worker' && !task.review && task.agentName !== 'review-chair'
47
53
  ? [join(packageRoot, 'skills/agents-relay/contracts/worker-self-review.md')] : []),
48
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,11 +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: [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'),
508
+ join(dirname(fileURLToPath(import.meta.url)), '..', 'skills/agents-relay/contracts/blocker-job-recovery.md'),
509
+ ...(ctx?.skills.find(skill => skill.name === 'ponytail')?.path ? [ctx.skills.find(skill => skill.name === 'ponytail').path] : [])],
500
510
  contexts: ctx?.instructions.filter(item => item.path.endsWith('/AGENTS.md')) ?? [],
501
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,
502
- taskId: context.planExecution.planId, executionId: context.planExecution.executionId,
503
- });
512
+ taskId: context.planExecution.planId, executionId: context.planExecution.executionId, });
504
513
  }
505
514
  export class AgentObjectivePlanner {
506
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)))