agents-relay 1.0.140 → 1.0.142

package/dist/planner-child.js

@@ -0,0 +1,3 @@
+export function samePlannerChildDefinition(left, right) {
+    return JSON.stringify({ id: left.id, input: left.input, output: left.output, review: left.review ?? null, priority: left.priority, storySize: left.storySize ?? 'M', projectName: left.projectName, agentName: left.agentName, agentGraph: left.agentGraph, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, output: right.output, review: right.review ?? null, priority: right.priority, storySize: right.storySize ?? 'M', projectName: right.projectName, agentName: right.agentName, agentGraph: right.agentGraph, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
+}

package/dist/planner.js

@@ -47,7 +47,7 @@ export function planningSpec(task) {
         throw new Error(`Initial task ${task.id} requires an output contract`);
     if (!['codex', 'chatgpt', 'orchestrator'].includes(task.adapter))
         throw new Error(`Initial task ${task.id} requires a supported adapter`);
-    return { id: task.id, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
+    return { id: task.id, input: task.input, priority: task.priority, storySize: task.storySize, projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph, review: task.review, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, adapter: task.adapter, output: task.output ?? { kind: 'task_pr' }, routing: task.routing, continuation: task.continuation, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs };
 }
 function record(value, field = 'result') {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -88,6 +88,27 @@ function workerRequirements(value, field) {
     }
     return { capabilities, runtime: optional('runtime'), taskKind: optional('taskKind'), trustDomain: optional('trustDomain'), region: optional('region'), labels };
 }
+function reviewMetadata(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    const root = record(value, field);
+    if (root.role !== 'chair' && root.role !== 'specialist')
+        throw new Error(`Planner ${field}.role must be chair or specialist`);
+    const targetValue = record(root.target, `${field}.target`);
+    const artifact = optionalString(targetValue.artifact, `${field}.target.artifact`);
+    const version = optionalString(targetValue.version, `${field}.target.version`);
+    if (!artifact || !version)
+        throw new Error(`Planner ${field}.target requires artifact and version`);
+    const dimension = optionalString(root.dimension, `${field}.dimension`);
+    const selectionReason = optionalString(root.selectionReason, `${field}.selectionReason`);
+    if (root.role === 'specialist' && (!dimension || !selectionReason)) {
+        throw new Error(`Planner ${field} specialist tasks require dimension and selectionReason`);
+    }
+    const round = root.round === undefined ? undefined : root.round;
+    if (round !== undefined && (!Number.isInteger(round) || Number(round) < 1))
+        throw new Error(`Planner ${field}.round must be a positive integer`);
+    return { role: root.role, target: { artifact, version }, dimension, selectionReason, round: round === undefined ? undefined : Number(round) };
+}
 function rawValue(value) {
     if (typeof value === 'string')
         return JSON.stringify(value);
@@ -185,6 +206,7 @@ export function parsePlannerResult(value) {
         const route = routing(task.routing, 'next_tasks[' + index + '].routing');
         const requirements = workerRequirements(task.workerRequirements ?? task.requirements, 'next_tasks[' + index + '].workerRequirements');
         const agentGraph = optionalString(task.agentGraph, `next_tasks[${index}].agentGraph`);
+        const review = reviewMetadata(task.review, `next_tasks[${index}].review`);
         if (agentGraph) {
             try {
                 parseAgentGraph(agentGraph);
@@ -200,7 +222,7 @@ export function parsePlannerResult(value) {
             throw new Error(`Planner next_tasks[${index}].timeoutMs is invalid`);
         return {
             id, input: task.input, priority, storySize,
-            projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'), agentGraph,
+            projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'), agentGraph, review,
             dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'), workerRequirements: requirements,
             adapter: adapter, output: output, routing: route,
             continuation: task.continuation, maxAttempts, timeoutMs

package/dist/reconciler-runtime.js

@@ -153,6 +153,15 @@ export class ReconcilerRuntimeBase {
     registerExecutionOwner(jobId, taskId, executionId) {
         activeExecutionOwners.set(executionEventSource(jobId, taskId, executionId), this);
     }
+    clearTerminalTimer(taskId, executionId) {
+        const live = this.live.get(taskId);
+        if (!live || live.executionId !== executionId)
+            return;
+        const timer = this.terminalTimers.get(taskId);
+        if (timer)
+            clearTimeout(timer);
+        this.terminalTimers.delete(taskId);
+    }
     clearExecution(taskId, executionId) {
         const live = this.live.get(taskId);
         if (!executionId || live?.executionId === executionId) {
@@ -243,6 +252,8 @@ export class ReconcilerRuntimeBase {
         const task = job.tasks.find(item => item.id === taskId);
         if (!task || task.executionId !== executionId)
             return;
+        if (task.adapter !== 'chatgpt')
+            this.clearTerminalTimer(taskId, executionId);
         await this.emit(eventFor(jobId, taskId, task.parentTaskId, task.adapter === 'chatgpt' ? 'task.process.async_exited' : 'task.process.exited', error ? 'failed' : 'succeeded', error ?? result?.summary ?? 'Worker runtime exited', 'orchestrator', { authoritative: false, waitingForTerminalEvent: true, processError: error }, { agent: 'relay', component: 'agents-relay' }));
     }
     async timeoutTask(jobId, taskId, executionId) {

package/dist/reconciler.js

@@ -15,6 +15,8 @@ import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
 import { applyHistoricalJobCompatibilityRepair } from './workflow/runtime.js';
 import { pendingTroubleshooterTasks } from './troubleshooter.js';
 import { prepareManagedExecutionWorktree } from './workspace.js';
+import { createReviewChairExecutionPlan } from './review-chair.js';
+import { samePlannerChildDefinition } from './planner-child.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
 export function compareTaskPriority(a, b, jobPriority = 'P2') { const ar = PRIORITY_RANK[a.priority ?? jobPriority]; const br = PRIORITY_RANK[b.priority ?? jobPriority]; return ar - br || a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id); }
 export async function managedWorkerInput(job, task, context) {
@@ -22,6 +24,9 @@ export async function managedWorkerInput(job, task, context) {
         return task.input;
     const selectedAgent = task.agentName && context ? await agentContractPrompt(context, task.agentName) : '';
     const selectedGraph = task.agentGraph && context ? await agentGraphPrompt(context, task.agentGraph) : '';
+    const chairPlan = task.review?.role === 'chair' && context
+        ? createReviewChairExecutionPlan(context.agents, task.review.target)
+        : null;
     if (!task.output)
         throw new Error(`Task ${task.id} requires an explicit output contract`);
     if (!task.executionId)
@@ -41,7 +46,7 @@ Project: ${task.projectName ?? context?.project.name ?? 'unspecified'}
 
 Retrieve the durable job and task from GitHub before doing the work. Use whatever GitHub access this environment provides: the URLs, a GitHub integration/tool, or GitHub CLI/API. GitHub is the source of truth for task intent and declared output.
 
-${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? selectedAgent + '\n\n' : ''}${selectedGraph ? selectedGraph + '\n\n' : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
+${context ? executionContextPrompt(context) + '\n\n' : ''}${selectedAgent ? selectedAgent + '\n\n' : ''}${selectedGraph ? selectedGraph + '\n\n' : ''}${chairPlan ? `[Review Chair execution plan]\n${JSON.stringify(chairPlan, null, 2)}\n\nUse this runtime-discovered panel to create sibling durable specialist Tasks. Preserve each specialistTasks entry as review metadata, keep the target immutable, and synthesize structured results with synthesizeReview semantics before returning the unified revision plan.\n\n` : ''}Follow the resolved project instructions and Agents Relay/events-bus worker contracts.
 
 [Output contract]
 ${output}
@@ -542,9 +547,6 @@ export class Reconciler extends ReconcilerReviewBase {
     plannerChild(job, planner, spec, executionContext) {
         validateAgentSelection(executionContext, spec.agentName, spec.agentGraph);
         const now = new Date().toISOString();
-        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, agentGraph: spec.agentGraph, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: (spec.dependencies?.length ?? 0) > 0 ? 'DRAFT' : 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
+        return { jobId: job.id, id: spec.id, kind: 'work', priority: spec.priority ?? job.priority, storySize: spec.storySize ?? 'M', projectName: spec.projectName, agentName: spec.agentName, agentGraph: spec.agentGraph, review: spec.review, parentTaskId: planner.id, dependencies: spec.dependencies ?? [], capabilities: spec.capabilities ?? [], workerRequirements: spec.workerRequirements, adapter: 'codex', input: spec.input, output: spec.output, continuation: spec.continuation ?? null, continuationDeliveredAt: null, state: (spec.dependencies?.length ?? 0) > 0 ? 'DRAFT' : 'QUEUED', attempt: 0, maxAttempts: spec.maxAttempts ?? 3, leaseOwner: null, leaseExpiresAt: null, executionId: null, threadId: null, result: null, plannerResult: null, error: null, timeoutMs: spec.timeoutMs ?? taskOverallTimeoutMs(spec.storySize ?? 'M'), createdAt: now, updatedAt: now, planningDecisionId: planner.id, planningSource: planner.planningSource ?? 'model-planner', planningRound: planner.planningRound ?? 1 };
     }
 }
-function samePlannerChildDefinition(left, right) {
-    return JSON.stringify({ id: left.id, input: left.input, output: left.output, priority: left.priority, storySize: left.storySize ?? 'M', projectName: left.projectName, agentName: left.agentName, agentGraph: left.agentGraph, dependencies: left.dependencies, capabilities: left.capabilities, adapter: left.adapter, routing: left.routing, continuation: left.continuation ?? null, maxAttempts: left.maxAttempts, timeoutMs: left.timeoutMs }) === JSON.stringify({ id: right.id, input: right.input, output: right.output, priority: right.priority, storySize: right.storySize ?? 'M', projectName: right.projectName, agentName: right.agentName, agentGraph: right.agentGraph, dependencies: right.dependencies, capabilities: right.capabilities, adapter: right.adapter, routing: right.routing, continuation: right.continuation ?? null, maxAttempts: right.maxAttempts, timeoutMs: right.timeoutMs });
-}

package/dist/review-chair.js

@@ -0,0 +1,134 @@
+function text(value, field) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error(`Review ${field} must be a non-empty string`);
+    return value.trim();
+}
+function target(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Review target must be an object');
+    const record = value;
+    return { artifact: text(record.artifact, 'target.artifact'), version: text(record.version, 'target.version') };
+}
+function severity(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || !/^P[0-3]$/.test(value))
+        throw new Error('Review finding severity must be P0, P1, P2, or P3');
+    return value;
+}
+export function parseReviewFinding(value, index = 0) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`Review finding ${index} must be an object`);
+    const record = value;
+    const verdict = record.verdict;
+    if (verdict !== 'pass' && verdict !== 'concern' && verdict !== 'fail' && verdict !== 'blocked')
+        throw new Error(`Review finding ${index}.verdict is invalid`);
+    return {
+        id: record.id === undefined ? undefined : text(record.id, `finding ${index}.id`),
+        reviewer: text(record.reviewer, `finding ${index}.reviewer`),
+        dimension: text(record.dimension, `finding ${index}.dimension`),
+        verdict,
+        summary: text(record.summary, `finding ${index}.summary`),
+        severity: severity(record.severity),
+        location: record.location === undefined ? undefined : text(record.location, `finding ${index}.location`),
+        recommendation: record.recommendation === undefined ? undefined : text(record.recommendation, `finding ${index}.recommendation`),
+        evidence: record.evidence === undefined ? undefined : text(record.evidence, `finding ${index}.evidence`),
+    };
+}
+export function parseSpecialistReview(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Specialist review must be an object');
+    const record = value;
+    const verdict = record.verdict;
+    if (verdict !== 'pass' && verdict !== 'concern' && verdict !== 'fail' && verdict !== 'blocked')
+        throw new Error('Specialist review verdict is invalid');
+    if (!Array.isArray(record.findings))
+        throw new Error('Specialist review findings must be an array');
+    const parsedTarget = target(record.target);
+    const findings = record.findings.map((item, index) => parseReviewFinding(item, index));
+    for (const finding of findings) {
+        if (finding.reviewer !== text(record.reviewer, 'reviewer') || finding.dimension !== text(record.dimension, 'dimension')) {
+            throw new Error('Specialist review findings must preserve reviewer and dimension attribution');
+        }
+    }
+    return { reviewer: text(record.reviewer, 'reviewer'), dimension: text(record.dimension, 'dimension'), target: parsedTarget, verdict, findings };
+}
+function candidateFromAgent(agent) {
+    return { agent: agent.name, dimensions: [...agent.capabilities], description: agent.description };
+}
+/** Selects roles from the resolved visible catalog; it never selects workers or models. */
+export function selectReviewPanel(candidates, dimensions, max = 5) {
+    if (!Number.isInteger(max) || max < 1)
+        throw new Error('Review panel max must be a positive integer');
+    const normalized = candidates.map(candidate => 'name' in candidate ? candidateFromAgent(candidate) : candidate);
+    const selected = [];
+    const usedAgents = new Set();
+    for (const dimension of [...dimensions].map((item, index) => ({ item, index })).sort((a, b) => (a.item.priority ?? 99) - (b.item.priority ?? 99) || a.index - b.index).map(item => item.item)) {
+        const match = normalized
+            .filter(candidate => !usedAgents.has(candidate.agent))
+            .map(candidate => ({ candidate, score: candidate.dimensions.some(item => item.toLowerCase() === dimension.name.toLowerCase()) ? 0 : 1 }))
+            .sort((a, b) => a.score - b.score)[0];
+        if (!match || match.score > 0)
+            continue;
+        selected.push({ agent: match.candidate.agent, dimension: dimension.name, reason: `Visible agent capability matches the ${dimension.name} review dimension${match.candidate.description ? `: ${match.candidate.description}` : ''}.` });
+        usedAgents.add(match.candidate.agent);
+        if (selected.length >= max)
+            break;
+    }
+    return selected;
+}
+export function specialistReviewTaskMetadata(targetValue, member, round = 1) {
+    return { role: 'specialist', target: { ...targetValue }, dimension: member.dimension, selectionReason: member.reason, round };
+}
+export function createSpecialistReviewTasks(tasks, targetValue, panel, round = 1) {
+    const existing = new Set(tasks.filter(task => task.review?.role === 'specialist').map(task => `${task.review?.target.artifact}@${task.review?.target.version}:${task.review?.dimension}:${task.agentName ?? ''}`));
+    return panel
+        .filter(member => !existing.has(`${targetValue.artifact}@${targetValue.version}:${member.dimension}:${member.agent}`))
+        .map(member => specialistReviewTaskMetadata(targetValue, member, round));
+}
+/** Builds the durable-task inputs used by the live Review Chair worker path. */
+export function createReviewChairExecutionPlan(agents, targetValue, max = 5) {
+    const dimensions = [...new Set(agents.flatMap(agent => agent.capabilities))]
+        .map(name => ({ name }))
+        .filter(dimension => dimension.name !== 'model');
+    const panel = selectReviewPanel(agents, dimensions, max);
+    return { target: { ...targetValue }, panel, specialistTasks: createSpecialistReviewTasks([], targetValue, panel) };
+}
+function findingKey(finding) { return `${finding.location ?? ''}|${finding.summary.toLowerCase().replace(/\s+/g, ' ').trim()}`; }
+function priority(finding) { return finding.severity ?? (finding.verdict === 'blocked' ? 'P0' : finding.verdict === 'fail' ? 'P1' : 'P2'); }
+/** Deterministically merges independent specialist output into one executor-facing plan. */
+export function synthesizeReview(targetValue, panel, reviews) {
+    const mismatched = reviews.find(review => review.target.artifact !== targetValue.artifact || review.target.version !== targetValue.version);
+    if (mismatched)
+        throw new Error(`Specialist review ${mismatched.reviewer} targets ${mismatched.target.artifact}@${mismatched.target.version}, expected ${targetValue.artifact}@${targetValue.version}`);
+    const byKey = new Map();
+    for (const review of reviews)
+        for (const finding of review.findings) {
+            const key = findingKey(finding);
+            const group = byKey.get(key) ?? [];
+            group.push(finding);
+            byKey.set(key, group);
+        }
+    const usedIds = new Set();
+    const mergedGroups = [...byKey.values()].map((group, index) => {
+        const preferredId = group[0].id ?? `finding-${index + 1}`;
+        let id = preferredId;
+        let suffix = 2;
+        while (usedIds.has(id))
+            id = `${preferredId}-${suffix++}`;
+        usedIds.add(id);
+        return { group, id };
+    });
+    const findings = mergedGroups.map(({ group, id }) => ({
+        ...group[0],
+        id,
+        attributions: group.map(item => ({ reviewer: item.reviewer, dimension: item.dimension, ...(item.id ? { findingId: item.id } : {}) })),
+    }));
+    const conflicts = mergedGroups.filter(({ group }) => new Set(group.map(item => item.verdict)).size > 1).map(({ group, id }) => ({ findingIds: [id], resolution: `Prioritize the more severe disposition and preserve all specialist attribution: ${group.map(item => `${item.reviewer}=${item.verdict}`).join(', ')}.` }));
+    const actions = findings.filter(finding => finding.verdict !== 'pass').map(finding => ({ priority: priority(finding), action: finding.recommendation ?? `Address: ${finding.summary}`, findingIds: [finding.id ?? findingKey(finding)], rationale: finding.evidence ?? `Raised by ${finding.reviewer} for ${finding.dimension}.` })).sort((a, b) => a.priority.localeCompare(b.priority) || a.action.localeCompare(b.action));
+    const covered = new Set(reviews.map(review => review.dimension));
+    const missingDimensions = panel.map(member => member.dimension).filter(dimension => !covered.has(dimension));
+    const unresolved = findings.filter(finding => finding.verdict === 'blocked');
+    return { target: { ...targetValue }, panel: panel.map(member => ({ ...member })), findings, conflicts, actions, unresolved, needsAdditionalSpecialist: missingDimensions.length > 0, missingDimensions };
+}
+function findingsIndex(group) { return group.map(item => item.reviewer).sort().join('-').toLowerCase().replace(/[^a-z0-9-]+/g, '-') || 'unknown'; }

package/dist/store-task-definition.js

@@ -6,7 +6,7 @@ function immutableTaskDefinition(task) {
     return {
         jobId: task.jobId, id: task.id, priority: task.priority, storySize: task.storySize ?? 'M', projectName: task.projectName, agentName: task.agentName, agentGraph: task.agentGraph,
         kind: task.kind ?? 'work', planningDecisionId: task.planningDecisionId, planningSource: task.planningSource, planningRound: task.planningRound, plannerGuidance: task.plannerGuidance, manualPlanning: task.manualPlanning, parentTaskId: task.parentTaskId, dependencies: task.dependencies, capabilities: task.capabilities, workerRequirements: task.workerRequirements, workerSelection: task.workerSelection, adapter: task.adapter,
-        input: task.input, attachments: task.attachments, output: task.output, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
+        input: task.input, attachments: task.attachments, output: task.output, review: task.review, routing, chatgptTabClosePolicy: task.chatgptTabClosePolicy ?? 'after-start', continuation: task.continuation ?? null, maxAttempts: task.maxAttempts, timeoutMs: task.timeoutMs
     };
 }
 export function sameTaskDefinition(left, right) {

package/package.json

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

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

@@ -66,6 +66,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - Otherwise return only the next useful executable batch from the graph-derived Task boundaries.
 - Do not repeat completed work or recreate an existing Task unless replacement work is explicitly needed.
 - Prefer independently verifiable Tasks with stable IDs, but do not split work solely to make Tasks smaller.
+- When a Job needs multi-perspective review, use the visible `review-chair` agent or an Agent Graph to select specialist roles dynamically. Keep specialist Tasks as independent siblings against the same immutable target/version, and leave worker/model/provider routing to Relay.
 - A Task describes what an agent must accomplish; never emit a shell command as a worker Task.
 - Use dependencies only for Task IDs inside the current Job, and only when execution order actually matters. Never encode cross-Job or cross-repository dependencies in `dependencies`.
 - When the current Job is a prerequisite for another durable Job/Task, emit that dependent in top-level `unblocks`. The current blocker Job owns this authoritative reverse relation. Dependent-side `blockedBy` is optional observability metadata and is not the source of truth. Use `resolutionMode: "merge"` when blocker PR merge is sufficient; use `"verified"` when publication, deployment, runtime health, human approval, or another post-merge fact must be verified.

package/skills/agents-relay/agents/review-chair.agent.md

@@ -0,0 +1,49 @@
+---
+name: review-chair
+description: Select a non-redundant specialist review panel for one immutable target and synthesize one attributed revision plan.
+capabilities: review-orchestration, structured-synthesis
+delegation: relay-child-task
+restrictions: no-artifact-edits, no-worker-model-provider-selection, preserve-final-review
+runtime: codex
+---
+
+# Review Chair Agent
+
+You own the review panel for exactly one declared immutable target/version. You
+are a review orchestrator, not an artifact editor and not the final approval
+gate.
+
+## Contract
+
+1. Read the Job objective, acceptance criteria, audience/platform, context, and
+   the exact target `{ artifact, version }`. Reject or report any specialist
+   result that targets a different version.
+2. Derive only the review dimensions that matter for this target. Discover
+   candidates from the resolved visible-agent catalog at execution time; never
+   use a hard-coded reviewer list. Select a small non-redundant panel (normally
+   2-5 agents) and record each agent, dimension, and evidence-based reason.
+3. Create normal durable specialist Tasks with `parentTaskId` lineage. Every
+   specialist Task must carry the same immutable target/version. Independent
+   specialists may be siblings and may run in parallel when dependencies allow.
+   Select agent identities/roles only; worker, adapter, provider, and model
+   routing remains Relay's responsibility.
+4. Require structured specialist results with reviewer, dimension, verdict,
+   findings, severity/priority, target location when useful, recommendation,
+   and evidence/rationale. Preserve attribution.
+5. Deduplicate overlapping findings, make disagreements explicit, resolve them
+   against the Job objective, and produce one prioritized P0/P1/P2/P3 revision
+   plan. The executor receives this unified plan, never competing edit lists.
+6. If a missing expertise dimension or unresolved blocker remains, record it and
+   request an additional specialist Task before declaring synthesis complete.
+   Preserve prior trade-off rationale across revision rounds when available.
+
+## Output
+
+Return a structured synthesis containing: target; selected panel and reasons;
+merged findings; conflicts and resolutions; prioritized actions with attribution;
+unresolved/blocking issues; and whether another specialist round is needed.
+
+The Review Chair must not modify the reviewed artifact, select a worker/model/
+provider, merge or approve the Job, or replace the existing SHA-bound final
+reviewer. A revised artifact is a new target/version and starts a new review
+round.

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

@@ -150,4 +150,17 @@ A zero-task autonomous Job stays idle under ordinary reconciliation, but an expl
 
 Planner-produced Tasks obey this same contract, including explicit `storySize`.
 
+### Optional Review Chair Tasks
+
+Projects may use the shared `review-chair` agent as a normal Task or Agent
+Graph node. The chair discovers specialist agent roles from the resolved
+visible-agent catalog, records selection reasons, and creates sibling durable
+specialist Tasks carrying the same immutable review target/version. Their
+structured findings are synthesized into one attributed revision plan. A chair
+may add a specialist when synthesis exposes a missing dimension. It never
+chooses worker/model/provider, edits the artifact, or replaces the existing
+SHA-bound final reviewer. For example, `video-director + market + style ->
+review-chair -> unified revision plan` is a project pattern, not a hard-coded
+Relay reviewer list.
+
 A scheduled autonomous job adds cron/timezone/next-run and missed-run/concurrency policy to the trusted job marker, plus the `agents-relay:autonomous` label and one bounded time-of-day `agents-relay:next-run:*` index label. The GitHub heartbeat discovers only indexed due candidates, validates the marker's exact `nextRunAt`, claims the slot idempotently, advances the durable next run, and pulses `agents-relay:schedule-wake`. GitHub webhook delivery then wakes local Relay for planner/worker execution. While the schedule is active, the durable Job remains `ACTIVE`; between runs its derived runtime status is `WAITING`. Scheduled recurring Jobs do not enter one-shot final-review/auto-merge after each satisfied run; older-cycle failures are historical evidence and do not block a later slot.