agents-relay 2.0.55 → 2.0.57

package/README.md

@@ -247,6 +247,8 @@ GitHub PR state is authoritative for terminal lifecycle: a merged PR reconciles
 
 `adapter: orchestrator` is reserved for synchronous self-work by the exact orchestrator turn that creates the Task. Relay deliberately does not auto-start these Tasks during reconciliation. The creator must perform the work before ending the turn and terminalize the same Task with `npx agents-relay task complete --task-id <id> --summary <summary> ...`. If work should continue asynchronously or in a later turn, use a real worker adapter instead.
 
+As a narrow recovery exception, reconciliation converts a `QUEUED` work Task that still has `adapter: orchestrator`, no execution identity, and is at least 30 minutes past `createdAt` into a normal ChatGPT-routable Task. This preserves the Task identity, intent, dependencies, output, lineage, priority, and story size while clearing stale routing state. `RUNNING` and terminal Tasks are never converted; the 30-minute rescue does not weaken the synchronous self-task contract for newly created work.
+
 For work that was completed outside the relay but must be represented truthfully in durable history, use `npx agents-relay record --task-id <id> --summary <summary> --commit <sha>`. Recorded tasks use the `orchestrator` adapter and terminal `SUCCEEDED` state; they do not pretend a shell/model worker executed the work. This is a repair/backfill mechanism—normal work should be created as a durable Task before execution. For managed jobs, the GitHub PR body is the canonical Job surface: hidden Job metadata marker plus the visible Markdown objective.
 
 ### Automatic task troubleshooting

package/dist/cli-escalation.js

@@ -1,37 +1,62 @@
 import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { textOption, arg } from './cli-support.js';
 import { runEscalationGraph } from './workflow/escalation.js';
-function runNeoEscalation(request) {
-    const args = ['escalation', '--intent', request.intent, '--blocked-on', request.blockedOn];
-    if (request.context)
-        args.push('--context', request.context);
-    if (request.onNeedsUser)
-        args.push('--on-needs-user', request.onNeedsUser);
-    if (request.cwd)
-        args.push('--cwd', request.cwd);
-    return new Promise((resolve, reject) => {
-        const child = spawn('neo', args, { cwd: request.cwd ?? process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
-        let stdout = '';
-        let stderr = '';
-        child.stdout.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
-        child.stderr.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
-        child.on('error', reject);
-        child.on('close', code => {
-            let parsed;
-            try {
-                parsed = JSON.parse(stdout.trim());
-            }
-            catch {
-                reject(new Error(`neo escalation returned invalid JSON (exit ${code ?? 'unknown'}): ${stderr || stdout}`));
-                return;
-            }
-            if (!['resolved', 'failed', 'needs_user'].includes(parsed.status)) {
-                reject(new Error(`neo escalation returned invalid status ${String(parsed.status)}`));
-                return;
-            }
-            resolve(parsed);
+export function neoEscalationArgs(handoffPath, policyPath, cwd) {
+    return [
+        'escalation', '--handoff-file', handoffPath,
+        ...(policyPath ? ['--on-needs-user-file', policyPath] : []),
+        ...(cwd ? ['--cwd', cwd] : []),
+    ];
+}
+function handoffText(request) {
+    return [
+        '# Intent', request.intent.trim(),
+        '', '# Blocked on', request.blockedOn.trim(),
+        ...(request.context?.trim() ? ['', '# Context', request.context.trim()] : []),
+        '',
+    ].join('\n');
+}
+export async function runNeoEscalation(request) {
+    const tempRoot = await mkdtemp(join(tmpdir(), 'agents-relay-escalation-'));
+    try {
+        const handoffPath = join(tempRoot, 'handoff.md');
+        await writeFile(handoffPath, handoffText(request), { encoding: 'utf8', mode: 0o600 });
+        let policyPath;
+        if (request.onNeedsUser) {
+            policyPath = join(tempRoot, 'on-needs-user.md');
+            await writeFile(policyPath, request.onNeedsUser, { encoding: 'utf8', mode: 0o600 });
+        }
+        const args = neoEscalationArgs(handoffPath, policyPath, request.cwd);
+        return await new Promise((resolve, reject) => {
+            const child = spawn('neo', args, { cwd: request.cwd ?? process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8').on('data', chunk => { stdout += chunk; });
+            child.stderr.setEncoding('utf8').on('data', chunk => { stderr += chunk; });
+            child.on('error', reject);
+            child.on('close', code => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(stdout.trim());
+                }
+                catch {
+                    reject(new Error(`neo escalation returned invalid JSON (exit ${code ?? 'unknown'}): ${stderr || stdout}`));
+                    return;
+                }
+                if (!['resolved', 'failed', 'needs_user'].includes(parsed.status)) {
+                    reject(new Error(`neo escalation returned invalid status ${String(parsed.status)}`));
+                    return;
+                }
+                resolve(parsed);
+            });
         });
-    });
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true });
+    }
 }
 export async function runEscalationCommand(args) {
     const intent = await textOption(args, '--intent', '--intent-file');

package/dist/reconciler.js

@@ -19,6 +19,7 @@ import { createReviewChairExecutionPlan } from './review-chair.js';
 import { taskTagWorkerPrompt } from './task-tag.js';
 import { recoverExpiredExecutions, recoverStartupOrphans as recoverStartupExecutionOrphans } from './execution-recovery.js';
 import { dispatchJobReconcile } from './workflow/job-reconcile-v2.js';
+import { applyOrchestratorRescue } from './workflow/orchestrator-rescue.js';
 import { launchPlanExecution } from './planner-runtime.js';
 import { classifyFailure, errorMessage, observability, withObservabilityCorrelation } from './observability.js';
 const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3 };
@@ -154,6 +155,13 @@ export class Reconciler extends ReconcilerReviewBase {
             if (job.state !== 'ACTIVE')
                 return job;
             await recoverExpiredExecutions(job, now, this.executionRecoveryPorts(job));
+            for (const task of (await this.store.load(jobId)).tasks) {
+                const rescue = applyOrchestratorRescue(task, now);
+                if (!rescue.rescued)
+                    continue;
+                await this.store.saveTask(task);
+                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.orchestrator_rescued', 'queued', `Stale orchestrator task ${task.id} converted to ChatGPT execution`, 'orchestrator', { ageMs: rescue.ageMs, adapter: 'chatgpt' }, { agent: 'relay', component: 'agents-relay' }));
+            }
             await this.recoverPlannerChildren(job);
             for (const recovery of pendingTroubleshooterTasks(await this.store.load(jobId))) {
                 await this.store.appendTask(recovery);

package/dist/workflow/orchestrator-rescue.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { dispatchWorkflowGraphSync } from './dispatcher.js';
+import { GraphRuntime } from './graph-v2.js';
+export const STALE_ORCHESTRATOR_TASK_MS = 30 * 60 * 1000;
+const source = readFileSync(new URL('../../workflow/orchestrator-rescue.mmd', import.meta.url), 'utf8');
+const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+export const orchestratorRescueV2 = new GraphRuntime(source, {
+    states: new Set(['idle', 'check', 'skip', 'rescued']),
+    guards: { rescuable: boolGuard('rescuable') },
+    actions: { 'task.rescueOrchestrator': { id: 'task.rescueOrchestrator' } },
+    events: { 'orchestrator.rescue.reconcile': { id: 'orchestrator.rescue.reconcile' } },
+});
+export function orchestratorRescueFacts(task, now) {
+    const createdAt = Date.parse(task.createdAt);
+    const oldEnough = Number.isFinite(createdAt) && now - createdAt >= STALE_ORCHESTRATOR_TASK_MS;
+    return { rescuable: task.kind !== 'planner' && task.adapter === 'orchestrator' && task.state === 'QUEUED' && task.executionId === null && oldEnough };
+}
+export function decideOrchestratorRescue(task, now) {
+    return dispatchWorkflowGraphSync(orchestratorRescueV2, {
+        initialState: 'idle', input: { transport: 'event', id: 'orchestrator.rescue.reconcile', payload: {} },
+        durableFacts: orchestratorRescueFacts(task, now), graphName: 'orchestrator-rescue',
+        isTransientState: state => state === 'check', maxSteps: 2,
+    });
+}
+export function applyOrchestratorRescue(task, now) {
+    const decision = decideOrchestratorRescue(task, now);
+    const rescued = decision.accepted && decision.actions.some(action => action.id === 'task.rescueOrchestrator');
+    const ageMs = now - Date.parse(task.createdAt);
+    if (!rescued)
+        return { rescued: false, ageMs };
+    task.adapter = 'chatgpt';
+    task.workerRequirements = { capabilities: [...task.capabilities], runtime: 'chatgpt' };
+    task.workerSelection = undefined;
+    task.routing = undefined;
+    task.timeoutMs = 0;
+    task.updatedAt = new Date(now).toISOString();
+    return { rescued: true, ageMs };
+}

package/package.json

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

package/skills/agents-relay/contracts/orchestrator-workflows.md

@@ -36,6 +36,8 @@ A **P0 job** (alias: **self job**) is executed directly by the current active or
 5. P0/self jobs do not require the normal reviewer gate unless the user explicitly asks for review.
 6. After implementation and local verification, the orchestrator merges the job itself and completes normal post-merge reconciliation.
 
+Recovery exception: reconciliation may rescue only a `QUEUED` work Task with `adapter: orchestrator` that has no execution identity and is at least 30 minutes past `createdAt`. It converts that Task in place to a normal ChatGPT-routable Task, preserving its durable intent and Task identity while clearing stale routing state. `RUNNING` and terminal Tasks are not rescued. This is a stale-task safety net, not an asynchronous handoff mechanism for newly created self-work.
+
 `job create` still only creates durable job state; the P0 workflow requires the orchestrator to follow it immediately with task creation and execution.
 
 ## Merge completion vs deployment evidence

package/workflow/orchestrator-rescue.mmd

@@ -0,0 +1,13 @@
+flowchart LR
+%% relay: initial idle
+idle["state: idle"]
+check["state: check"]
+skip["state: skip"]
+rescued["state: rescued"]
+rescuable["guard: rescuable"]
+rescue["action: task.rescueOrchestrator"]
+idle -->|on: orchestrator.rescue.reconcile| check
+check -->|on: orchestrator.rescue.reconcile| rescuable
+rescuable -->|false| skip
+rescuable -->|true| rescue
+rescue -->|to: rescued| rescued