agents-relay 2.0.81 → 2.0.82

package/dist/workflow/entity-creation.js

@@ -1,17 +1,27 @@
 import { dispatchJobLifecycleSync, dispatchTaskLifecycleSync } from './lifecycle.js';
+import { deriveTaskTitle } from '../task-title.js';
 function dependenciesSatisfied(job, dependencies) {
     if (dependencies.length === 0)
         return true;
     const byId = new Map(job.tasks.map(task => [task.id, task]));
     return dependencies.every(id => byId.get(id)?.state === 'SUCCEEDED');
 }
+function validateTaskRequirements(value) {
+    if (value.adapter === 'orchestrator') {
+        throw new Error('New Tasks cannot use the Relay-internal orchestrator adapter; declare worker requirements and let Execution Router select the route');
+    }
+    if (value.workerRequirements && !Array.isArray(value.workerRequirements.capabilities)) {
+        throw new Error(`Task ${value.id} workerRequirements.capabilities must be an array`);
+    }
+}
 /**
  * Canonical creation boundary for new Task entities.
  * Constructors provide metadata/facts only; the Task lifecycle graph derives
  * whether a fresh Task remains DRAFT or becomes QUEUED.
  */
 export function createTaskEntity(job, value, options = {}) {
-    const task = { ...value, state: 'DRAFT' };
+    validateTaskRequirements(value);
+    const task = { ...value, title: value.title?.trim() || deriveTaskTitle(value.input, value.agentName ? `${value.agentName} task` : 'Task'), state: 'DRAFT' };
     if (!options.defer) {
         dispatchTaskLifecycleSync(task, 'reconcile', {
             dependenciesSatisfied: dependenciesSatisfied(job, task.dependencies),

package/dist/workflow/orchestrator-rescue.js

@@ -1,42 +1,86 @@
 import { readFileSync } from 'node:fs';
 import { dispatchWorkflowGraphSync } from './dispatcher.js';
 import { GraphRuntime } from './graph-v2.js';
+import { tryTransitionTaskEvent } from '../scheduler.js';
+import { taskOverallTimeoutMs } from '../types.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' } },
+    states: new Set(['idle', 'check', 'external_completed', 'blocked', 'skip', 'rescued']),
+    guards: {
+        legacyActive: boolGuard('legacyActive'),
+        verifiedExternalCompletion: boolGuard('verifiedExternalCompletion'),
+        unknownStartedOutcome: boolGuard('unknownStartedOutcome'),
+        rescuable: boolGuard('rescuable'),
+    },
+    actions: {
+        'task.applyExternalCompletion': { id: 'task.applyExternalCompletion' },
+        'task.blockLegacyOrchestrator': { id: 'task.blockLegacyOrchestrator' },
+        '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;
-    const urgentRepair = task.priority === 'P0' && task.agentName === 'troubleshooter';
-    return { rescuable: task.kind !== 'planner' && task.adapter === 'orchestrator' && task.state === 'QUEUED'
-            && task.executionId === null && (oldEnough || urgentRepair) };
+    const legacyActive = task.kind !== 'planner' && task.adapter === 'orchestrator'
+        && (task.state === 'QUEUED' || task.state === 'RUNNING');
+    const verifiedExternalCompletion = legacyActive && task.result !== null
+        && task.result.data?.externalCompletionVerified === true;
+    return {
+        legacyActive,
+        verifiedExternalCompletion,
+        unknownStartedOutcome: legacyActive && task.state === 'RUNNING' && !verifiedExternalCompletion
+            && (!task.leaseExpiresAt || Date.parse(task.leaseExpiresAt) <= now),
+        rescuable: legacyActive && task.state === 'QUEUED' && !verifiedExternalCompletion
+            && (!task.leaseExpiresAt || Date.parse(task.leaseExpiresAt) <= now),
+    };
 }
 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,
+        isTransientState: state => state === 'check', maxSteps: 4,
     });
 }
-export function applyOrchestratorRescue(task, now) {
+export function prepareOrchestratorRepair(task, now) {
     const decision = decideOrchestratorRescue(task, now);
-    const rescued = decision.accepted && decision.actions.some(action => action.id === 'task.rescueOrchestrator');
+    const externallyCompleted = decision.accepted
+        && decision.actions.some(action => action.id === 'task.applyExternalCompletion');
+    const blocked = decision.accepted
+        && decision.actions.some(action => action.id === 'task.blockLegacyOrchestrator');
+    const rescued = externallyCompleted || blocked
+        || (decision.accepted && decision.actions.some(action => action.id === 'task.rescueOrchestrator'));
     const ageMs = now - Date.parse(task.createdAt);
+    if (decision.accepted && externallyCompleted) {
+        tryTransitionTaskEvent(task, 'task.completed');
+        task.leaseOwner = null;
+        task.leaseExpiresAt = null;
+        task.executionId = null;
+        task.threadId = null;
+        task.updatedAt = new Date(now).toISOString();
+        return { repaired: true, externallyCompleted: true, blocked: false, ageMs };
+    }
     if (!rescued)
-        return { rescued: false, ageMs };
-    const urgentRepair = task.priority === 'P0' && task.agentName === 'troubleshooter';
-    task.adapter = urgentRepair ? 'codex' : 'chatgpt';
-    task.workerRequirements = { capabilities: [...task.capabilities, ...(urgentRepair ? ['local_repo'] : [])],
-        runtime: urgentRepair ? 'codex' : 'chatgpt' };
+        return { repaired: false, externallyCompleted: false, blocked: false, ageMs };
+    if (blocked) {
+        tryTransitionTaskEvent(task, 'task.blocked');
+        task.error = 'Legacy orchestrator execution outcome is unknown; automatic replay is unsafe. Verify external effects and create replacement validation/recovery work before unblocking.';
+        task.leaseOwner = null;
+        task.leaseExpiresAt = null;
+        task.executionId = null;
+        task.threadId = null;
+        task.updatedAt = new Date(now).toISOString();
+        return { repaired: true, externallyCompleted: false, blocked: true, ageMs };
+    }
+    task.adapter = 'codex';
+    task.workerRequirements = { capabilities: [...task.capabilities] };
     task.workerSelection = undefined;
     task.routing = undefined;
-    task.timeoutMs = 0;
+    task.leaseOwner = null;
+    task.leaseExpiresAt = null;
+    task.executionId = null;
+    task.threadId = null;
+    task.timeoutMs = taskOverallTimeoutMs(task.storySize ?? 'M');
     task.updatedAt = new Date(now).toISOString();
-    return { rescued: true, ageMs };
+    return { repaired: true, externallyCompleted: false, blocked: false, ageMs };
 }

package/dist/workflow/troubleshooter-v2.js

@@ -6,7 +6,7 @@ const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const troubleshooterV2 = new GraphRuntime(source, {
     states: new Set(['idle', 'check_ordinary', 'check_run', 'check_needs', 'check_id', 'check_barrier', 'skip', 'create']),
     guards: {
-        failedOrBlocked: boolGuard('failedOrBlocked'),
+        failedWork: boolGuard('failedWork'),
         ordinaryWork: boolGuard('ordinaryWork'),
         currentRun: boolGuard('currentRun'),
         needsRecovery: boolGuard('needsRecovery'),

package/dist/workspace.js

@@ -217,7 +217,7 @@ export async function ensureLocalJobSourceBranch(projectPath, job) {
     return sourceRef;
 }
 export async function prepareLocalJobExecutionWorktree(projectPath, job, workspaceRoot = defaultWorkspaceRoot()) {
-    if (job.prNumber !== 0 || !job.localMerge?.sourceRef)
+    if (!job.localMerge?.sourceRef)
         return resolveRepositoryProjectPath(projectPath, job.projectPath);
     const sourceRef = job.localMerge.sourceRef;
     if (!/^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(sourceRef) || sourceRef.includes('..') || sourceRef.endsWith('.lock'))
@@ -285,14 +285,15 @@ export async function prepareLocalJobExecutionWorktree(projectPath, job, workspa
 export async function cleanupCompletedJobWorktree(projectPath, job, workspaceRoot = defaultWorkspaceRoot()) {
     if (job.state !== 'COMPLETED')
         return { status: 'blocked', reason: 'Job is not completed' };
-    const expectedHead = job.prNumber === 0 ? (job.localMerge?.sourceSha ?? job.review?.headSha ?? job.headSha) : job.headSha;
+    const isLocalJob = Boolean(job.localMerge?.sourceRef);
+    const expectedHead = isLocalJob ? (job.localMerge?.sourceSha ?? job.review?.headSha ?? job.headSha) : job.headSha;
     if (!expectedHead)
         return { status: 'blocked', reason: 'No durable Job head SHA' };
     if (job.tasks.some(task => task.executionId !== null || task.leaseOwner !== null))
         return { status: 'blocked', reason: 'Task still owns an execution or lease' };
     if ((job.plans ?? []).some(plan => plan.executionId !== null || plan.leaseOwner !== null))
         return { status: 'blocked', reason: 'Planner still owns an execution or lease' };
-    const worktree = job.prNumber === 0 ? managedLocalJobWorktreePath(job.repository, job.id, workspaceRoot) : managedJobWorktreePath(job.repository, job.prNumber, workspaceRoot);
+    const worktree = isLocalJob ? managedLocalJobWorktreePath(job.repository, job.id, workspaceRoot) : managedJobWorktreePath(job.repository, job.prNumber, workspaceRoot);
     let metadata;
     try {
         metadata = await lstat(worktree);
@@ -311,7 +312,7 @@ export async function cleanupCompletedJobWorktree(projectPath, job, workspaceRoo
     }
     catch { /* Local-only repositories may have no origin. */ }
     const originRepository = origin ? githubRepositoryFromRemote(origin) : null;
-    if ((job.prNumber > 0 && originRepository !== job.repository) || (job.prNumber === 0 && originRepository && originRepository !== job.repository))
+    if ((job.prNumber > 0 && !isLocalJob && originRepository !== job.repository) || (isLocalJob && originRepository && originRepository !== job.repository))
         return { status: 'blocked', reason: 'Canonical repository identity mismatch' };
     const registered = await git(primary, ['worktree', 'list', '--porcelain']);
     const ownedRoot = await realpath(worktree);

package/package.json

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

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

@@ -24,18 +24,19 @@ The initial decomposition belongs to that durable Planner round. The orchestrato
 
 ## P0 / self job workflow
 
-A **P0 job** (alias: **self job**) is executed directly by the current active orchestrator thread:
-
-1. The orchestrator creates the durable job.
-2. The orchestrator immediately creates the required orchestrator-owned task(s); do not leave the P0 job idle.
-3. The current orchestrator thread starts executing those tasks immediately rather than delegating them to another worker. Creating an `adapter: orchestrator` Task is never a handoff: the exact creator owns it for this turn.
-4. The orchestrator must terminalize every orchestrator-owned Task it created before ending the turn. It must not return to the user with one of its self-tasks left `QUEUED` or `RUNNING`; successful work uses `task complete` on that same durable Task.
-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.
+P0/self work is ordinary durable Relay work. The orchestrator may choose normal
+Task requirements, but every newly created work Task is executable by a
+worker/model route selected by Execution Router. Relay has no privileged
+orchestrator-worker lifecycle, and new Task creation rejects
+`adapter: orchestrator`. P0/self jobs do not require the normal reviewer gate
+unless the user explicitly asks for review; Relay-owned merge and completion
+lifecycle remain in their canonical graphs.
+
+Legacy recovery: existing `adapter: orchestrator` work Tasks may be repaired only
+through the canonical rescue graph. The repair converts only never-started QUEUED records in place to declarative worker requirements and lets Execution Router select the route. A legacy RUNNING record with an unknown outcome is quarantined as BLOCKED instead of replayed; only explicit durable external-completion verification may complete it without execution. Process reclamation is attempted only after the record is proven eligible for this legacy path, so normal live workers are never touched by the migration scan.
+
+`job create --initial-plan` remains the normal way to create durable planning
+state and hand subsequent execution to Relay.
 
 ## Merge completion vs deployment evidence
 

package/workflow/orchestrator-rescue.mmd

@@ -2,12 +2,27 @@ flowchart LR
 %% relay: initial idle
 idle["state: idle"]
 check["state: check"]
+external["state: external_completed"]
+blocked["state: blocked"]
 skip["state: skip"]
 rescued["state: rescued"]
+legacyActive["guard: legacyActive"]
+verifiedExternalCompletion["guard: verifiedExternalCompletion"]
+unknownStartedOutcome["guard: unknownStartedOutcome"]
 rescuable["guard: rescuable"]
 rescue["action: task.rescueOrchestrator"]
+externalCompletion["action: task.applyExternalCompletion"]
+quarantine["action: task.blockLegacyOrchestrator"]
 idle -->|on: orchestrator.rescue.reconcile| check
-check -->|on: orchestrator.rescue.reconcile| rescuable
+check -->|on: orchestrator.rescue.reconcile| legacyActive
+legacyActive -->|false| skip
+legacyActive -->|true| verifiedExternalCompletion
+verifiedExternalCompletion -->|true| externalCompletion
+externalCompletion -->|to: external_completed| external
+verifiedExternalCompletion -->|false| unknownStartedOutcome
+unknownStartedOutcome -->|true| quarantine
+quarantine -->|to: blocked| blocked
+unknownStartedOutcome -->|false| rescuable
 rescuable -->|false| skip
 rescuable -->|true| rescue
 rescue -->|to: rescued| rescued

package/workflow/troubleshooter.mmd

@@ -9,7 +9,7 @@ checkBarrier["state: check_barrier"]
 skip["state: skip"]
 create["state: create"]
 
-failedOrBlocked["guard: failedOrBlocked"]
+failed["guard: failedWork"]
 ordinary["guard: ordinaryWork"]
 currentRun["guard: currentRun"]
 needsRecovery["guard: needsRecovery"]
@@ -17,9 +17,9 @@ idUnused["guard: idUnused"]
 noBarrier["guard: noRecoveryBarrier"]
 createAction["action: troubleshooter.create"]
 
-idle -->|on: troubleshooter.reconcile| failedOrBlocked
-failedOrBlocked -->|false| skip
-failedOrBlocked -->|true| checkOrdinary
+idle -->|on: troubleshooter.reconcile| failed
+failed -->|false| skip
+failed -->|true| checkOrdinary
 
 checkOrdinary -->|on: troubleshooter.reconcile| ordinary
 ordinary -->|false| skip