agents-relay 2.0.87 → 2.0.89

package/dist/adapters.js

@@ -274,7 +274,7 @@ async function findExistingReviewTurn(cli, sessionId, delivery, signal) {
         verified_by: 'existing-user-turn', user_message_id: typeof observation.user_message_id === 'string' ? observation.user_message_id : null };
 }
 async function runBrowserWorker(cli, configFile, signal, action = 'temporary-submit', delivery) {
-    const session = parseWorkspaceJson(await browserWorkspaceCommand(cli, ['session', 'start'], undefined, signal));
+    const session = parseWorkspaceJson(await browserWorkspaceCommand(cli, ['session', 'start', '--workspace', CHATGPT_BROWSER_WORKSPACE], undefined, signal));
     const sessionId = session.session_id;
     if (typeof sessionId !== 'string' || !sessionId)
         throw new Error('browser-workspace session start returned no session_id');

package/dist/planner-task-title.js

@@ -0,0 +1,10 @@
+/** Validate freshly proposed planner titles; legacy persisted Plans are not re-parsed. */
+export function requiredPlannerTaskTitle(value, index) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`Planner next_tasks[${index}].title is required`);
+    const title = value.trim();
+    const words = title.split(/\s+/);
+    if (words.length < 5 || words.length > 8)
+        throw new Error(`Planner next_tasks[${index}].title must contain 5–8 words (got ${words.length})`);
+    return title;
+}

package/dist/planner.js

@@ -11,6 +11,7 @@ import { dispatchPlannerTrigger } from './workflow/planner-trigger-v2.js';
 import { createTaskEntity } from './workflow/entity-creation.js';
 import { prepareReviewerThreadDelivery, chatgptThreadRequirements } from './reviewer-thread.js';
 import { spawnOwnedProcess } from './owned-process.js';
+import { requiredPlannerTaskTitle } from './planner-task-title.js';
 export function semanticTaskTree(tasks) {
     const work = tasks.filter(task => task.kind !== 'planner');
     const ids = new Set(work.map(task => task.id));
@@ -309,7 +310,7 @@ export function parsePlannerResult(value) {
         if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs < 0)
             throw new Error(`Planner next_tasks[${index}].timeoutMs is invalid`);
         return {
-            id, title: optionalString(task.title, `next_tasks[${index}].title`), parentTaskId, input: task.input, priority, storySize,
+            id, title: requiredPlannerTaskTitle(task.title, index), parentTaskId, input: task.input, priority, storySize,
             projectName: optionalString(task.projectName, 'projectName'), agentName: optionalString(task.agentName, 'agentName'), agentGraph, review,
             dependencies: stringArray(task.dependencies, 'dependencies'), capabilities: stringArray(task.capabilities, 'capabilities'), workerRequirements: requirements,
             testInjection: parseTestInjection(task.testInjection ?? task['--test-injection']) ?? optionalString(task.testInjection ?? task['--test-injection'], `next_tasks[${index}].--test-injection`),

package/dist/reconciler.js

@@ -18,7 +18,7 @@ import { executeManualPlan } from './manual-plan.js';
 import { executionEventSource, withExecutionBoundary } from './reconciler-runtime.js';
 export { executionEventSource } from './reconciler-runtime.js';
 import { CallbackWorkflowEffectHandler } from './workflow/effects.js';
-import { exhaustedTroubleshooterRecoveries, pendingTroubleshooterTasks } from './troubleshooter.js';
+import { exhaustedTroubleshooterRecoveries, pendingTroubleshooterTasks, pendingTroubleshooterReopens, refreshTroubleshooterInput } from './troubleshooter.js';
 import { taskUsesCanonicalProjectRun } from './workspace.js';
 import { cleanupMergedJobWorktree } from './job-worktree-cleanup.js';
 import { jobHasActiveExecution } from './job-execution-slot.js';
@@ -106,6 +106,12 @@ export class Reconciler extends ReconcilerReviewBase {
                 detach: (promise, currentJobId, planId, context) => this.detach(promise, currentJobId, planId, context),
                 reconcile: currentJobId => this.reconcile(currentJobId),
             }, jobId);
+            for (const { original, recovery } of pendingTroubleshooterReopens(await this.store.load(jobId))) {
+                await transitionTaskEvent(recovery, 'recovery.reopen', { troubleshooterRecovery: recovery.agentName === 'troubleshooter' });
+                refreshTroubleshooterInput(job, original, recovery);
+                await this.store.saveTask(recovery);
+                await this.emit(eventFor(job.id, recovery.id, original.id, 'troubleshooter.reopened', 'queued', `Reusing Troubleshooter ${recovery.id} for Task ${original.id} attempt ${original.attempt}`, 'orchestrator', { originalTaskId: original.id, attempt: original.attempt }));
+            }
             for (const recovery of pendingTroubleshooterTasks(await this.store.load(jobId))) {
                 await this.store.appendTask(recovery);
                 await this.emit(eventFor(job.id, recovery.id, null, "troubleshooter.created", "queued", "Troubleshooter task " + recovery.id + " created for failed/blocked work", "orchestrator", { agentName: "troubleshooter" }));

package/dist/troubleshooter.js

@@ -5,9 +5,9 @@ function slug(value) {
     return value.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 72) || 'task';
 }
 export function troubleshooterTaskId(task) {
-    return `troubleshoot-${slug(task.id)}-a${task.attempt}`;
+    return `troubleshoot-${slug(task.id)}`;
 }
-function failureInput(job, task) {
+function failureInput(job, task, recoveryId = troubleshooterTaskId(task)) {
     return `Recover the failed/blocked task below and make it move again if technically safe.
 
 Original repository: ${job.repository}
@@ -26,23 +26,51 @@ Retrieve this task's lifecycle event history before classifying the root cause o
 GET http://127.0.0.1:8787/api/events?job=${encodeURIComponent(job.id)}&task=${encodeURIComponent(task.id)}&limit=200
 Inspect event order, type/status, source, data/phase, duplicate events, missing expected lifecycle events, late events, and execution identifiers. If the event stream points to delivery/runtime failure, inspect the corresponding Relay/worker/tool logs too. Do not treat the final task.error string as the complete root cause.
 
-Follow the selected Troubleshooter agent contract. Diagnose root cause from durable task state + event history + relevant runtime logs before retry. The final task.error string alone is never sufficient. Classify the evidence as model/provider/runtime, worker/tool/infrastructure, semantic task failure, or timeout/unknown. Select exactly one graph-enabled resolution path: exact_original_retry, same_job_dependency, blocker_job_dependency (with merge or verified mode), escalation_gate, or cancel_supersede. Only model/provider/runtime evidence may call the narrow model re-decision action; that action gathers fresh usage, reloads current policy, updates this exact Task's routing, and does not retry it. Troubleshooter must then reactivate/retry this exact original task and verify progress. Use the dedicated agents-relay task recover path with --task-id ${task.id} and --recovery-task-id ${troubleshooterTaskId(task)}; never use ordinary task retry from a Troubleshooter because manual retry intentionally supersedes active recovery. Do not manually choose a provider/model or create a replacement task; no replacement_task action exists. If the blocker is a shared worker/runtime/tool defect, create and directly complete a P0/self-job in the owning repository, including required release/deploy verification. If diagnosis suggests a genuine human/external blocker, do not publish task.blocked directly and do not implement the result branch procedurally. Call agents-relay escalation with the original intent, blocker, and relevant context. Pass any caller-defined notification plan through --on-needs-user/--on-needs-user-file; do not hard-code a channel. The canonical escalation graph invokes Neo escalation and owns the resolved/failed/needs_user branch; follow its selected outcome. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
+Follow the selected Troubleshooter agent contract. Diagnose root cause from durable task state + event history + relevant runtime logs before retry. The final task.error string alone is never sufficient. Classify the evidence as model/provider/runtime, worker/tool/infrastructure, semantic task failure, or timeout/unknown. Select exactly one graph-enabled resolution path: exact_original_retry, same_job_dependency, blocker_job_dependency (with merge or verified mode), escalation_gate, or cancel_supersede. Only model/provider/runtime evidence may call the narrow model re-decision action; that action gathers fresh usage, reloads current policy, updates this exact Task's routing, and does not retry it. Troubleshooter must then reactivate/retry this exact original task and verify progress. Use the dedicated agents-relay task recover path with --task-id ${task.id} and --recovery-task-id ${recoveryId}; never use ordinary task retry from a Troubleshooter because manual retry intentionally supersedes active recovery. Do not manually choose a provider/model or create a replacement task; no replacement_task action exists. If the blocker is a shared worker/runtime/tool defect, create and directly complete a P0/self-job in the owning repository, including required release/deploy verification. If diagnosis suggests a genuine human/external blocker, do not publish task.blocked directly and do not implement the result branch procedurally. Call agents-relay escalation with the original intent, blocker, and relevant context. Pass any caller-defined notification plan through --on-needs-user/--on-needs-user-file; do not hard-code a channel. The canonical escalation graph invokes Neo escalation and owns the resolved/failed/needs_user branch; follow its selected outcome. Retry this exact original task only after the blocker is removed, reconcile the original job, and verify durable progress.`;
 }
 function belongsToCurrentRun(job, task) {
     const slot = job.schedule?.currentRunSlot;
     return !slot || task.createdAt >= slot;
 }
-const ACTIVE_RECOVERY_STATES = new Set(['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED']);
+const ACTIVE_RECOVERY_STATES = new Set(['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'UNBLOCKED']);
 function recoveryTargetsTask(recovery, original) {
     if (recovery.agentName !== 'troubleshooter')
         return false;
     if (recovery.parentTaskId)
         return recovery.parentTaskId === original.id;
-    return recovery.id.startsWith(`troubleshoot-${slug(original.id)}-a`);
+    return recovery.id === troubleshooterTaskId(original) || recovery.id.startsWith(`troubleshoot-${slug(original.id)}-a`);
 }
 function hasRecoveryBarrier(job, original) {
-    return job.tasks.some(task => recoveryTargetsTask(task, original)
-        && (ACTIVE_RECOVERY_STATES.has(task.state) || ['FAILED', 'CANCELLED'].includes(task.state)));
+    // Exactly one durable recovery identity per original Task, across all failures.
+    return job.tasks.some(task => recoveryTargetsTask(task, original));
+}
+function recoveryEpisode(recovery) {
+    return recovery.recoveryForAttempt ?? Number(/-a(\d+)$/.exec(recovery.id)?.[1] ?? -1);
+}
+/** Reuse the existing recovery rather than creating one child per worker retry. */
+export function pendingTroubleshooterReopens(job) {
+    const pending = [];
+    for (const original of job.tasks) {
+        if (original.kind === 'planner' || original.agentName === 'troubleshooter' || original.state !== 'FAILED')
+            continue;
+        if (!belongsToCurrentRun(job, original))
+            continue;
+        const recoveries = job.tasks.filter(candidate => recoveryTargetsTask(candidate, original));
+        if (!recoveries.length || recoveries.some(candidate => ACTIVE_RECOVERY_STATES.has(candidate.state)))
+            continue;
+        const recovery = recoveries.sort((a, b) => recoveryEpisode(b) - recoveryEpisode(a))[0];
+        if (!['SUCCEEDED', 'CANCELLED'].includes(recovery.state) || recoveryEpisode(recovery) >= original.attempt)
+            continue;
+        pending.push({ original, recovery });
+    }
+    return pending;
+}
+export function refreshTroubleshooterInput(job, original, recovery) {
+    recovery.input = failureInput(job, original, recovery.id);
+    recovery.recoveryForAttempt = original.attempt;
+    recovery.maxAttempts = Math.max(recovery.maxAttempts, recovery.attempt + 3);
+    recovery.routing = undefined;
+    recovery.workerSelection = undefined;
 }
 export function pendingTroubleshooterTasks(job) {
     const existing = new Set(job.tasks.filter(task => task.agentName === 'troubleshooter').map(task => task.id));
@@ -64,6 +92,8 @@ export function pendingTroubleshooterTasks(job) {
         recoveries.push(createTaskEntity(job, {
             jobId: job.id,
             id,
+            title: `Diagnose and recover failed task ${task.id}`,
+            recoveryForAttempt: task.attempt,
             kind: 'work',
             priority: 'P0',
             storySize: 'M',

package/dist/workflow/contracts.js

@@ -22,6 +22,7 @@ export const WORKFLOW_EVENT_NAMES = [
     'planner.failed',
     'planner.unavailable',
     'reconcile',
+    'recovery.reopen',
     'release',
     'retry',
     'review.started',

package/dist/workflow/definitions-v2.js

@@ -25,6 +25,7 @@ export const taskLifecycleV2 = load('task-lifecycle', TASK_STATES, {
     runnable: boolGuard('runnable'),
     dispatchable: boolGuard('dispatchable'),
     recoverableExecution: boolGuard('recoverableExecution'),
+    troubleshooterRecovery: boolGuard('troubleshooterRecovery'),
     retryAvailable: boolGuard('retryAvailable'),
 });
 export const jobLifecycleV2 = load('job-lifecycle', JOB_STATES, {

package/package.json

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

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

@@ -116,7 +116,7 @@ For `objective_status: "satisfied"`, `assessment` may be a concise evidence-base
 
 Each item in `next_tasks` MUST include a concise, meaningful `title` of **5–8 words** (separate from the detailed `input`). Do not use the input text as a title.
 
-Each item in next_tasks contains id, input, output, and storySize. `unblocks`, when present, is an array of `{repository, prNumber, jobId, taskId, resolutionMode?}` records identifying Tasks that must remain waiting until the current Job resolves their blocker. It may also contain parentTaskId, priority, projectName, agentName, dependencies, capabilities, workerRequirements, maxAttempts, and timeoutMs. Adapter/routing fields are selected by Relay after planning; do not invent them.
+Each item in `next_tasks` contains **required `title`**, id, input, output, and storySize. The planner parser rejects missing titles and titles outside 5–8 whitespace-separated words. `unblocks`, when present, is an array of `{repository, prNumber, jobId, taskId, resolutionMode?}` records identifying Tasks that must remain waiting until the current Job resolves their blocker. It may also contain parentTaskId, priority, projectName, agentName, dependencies, capabilities, workerRequirements, maxAttempts, and timeoutMs. Adapter/routing fields are selected by Relay after planning; do not invent them.
 
 ### Exact `next_tasks` serialization
 

package/workflow/task-lifecycle.mmd

@@ -18,6 +18,11 @@ recoverComplete["guard: recoverableExecution"]
 recoverBlocked["guard: recoverableExecution"]
 recoverFailed["guard: recoverableExecution"]
 recoverCancelled["guard: recoverableExecution"]
+troubleshooterRecovery["guard: troubleshooterRecovery"]
+recoveryReopenClearError["action: mutation.clearError"]
+recoveryReopenClearReason["action: mutation.clearFailureReason"]
+recoveryReopenClearLease["action: mutation.clearLease"]
+recoveryReopenClearExecution["action: mutation.clearExecution"]
 
 retryAvailableRunning["guard: retryAvailable"]
 plannerRetryAvailable["guard: retryAvailable"]
@@ -200,3 +205,12 @@ recoverFailed -->|true| failed
 failed -->|on: task.cancelled| recoverCancelled
 recoverCancelled -->|true| cancelled
 failed -->|on: cancel| cancelled
+
+%% Only a persistent Troubleshooter may reopen a terminal recovery for a new failure episode.
+succeeded -->|on: recovery.reopen| troubleshooterRecovery
+cancelled -->|on: recovery.reopen| troubleshooterRecovery
+troubleshooterRecovery -->|true| recoveryReopenClearError
+recoveryReopenClearError --> recoveryReopenClearReason
+recoveryReopenClearReason --> recoveryReopenClearLease
+recoveryReopenClearLease --> recoveryReopenClearExecution
+recoveryReopenClearExecution --> queued