agents-relay 1.0.163 → 1.0.165

package/README.md

@@ -201,6 +201,13 @@ For work that was completed outside the relay but must be represented truthfully
 
 ### Automatic task troubleshooting
 
-When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
+When an ACTIVE Job contains a current-run `FAILED` task, reconciliation may create one P0-priority `troubleshooter` recovery task for that exact failed attempt. `BLOCKED` work is not troubleshooter-owned: it remains blocked until authoritative unblock transitions it to `UNBLOCKED`. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
 
-The Troubleshooter diagnoses before retrying. A task-local or transient blocker is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the blocker is removed does it retry the original task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.
+The Troubleshooter diagnoses before retrying. A task-local or transient execution cause is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the failure cause is repaired does it retry the original FAILED task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.
+
+
+### Authoritative unblock and Planner history
+
+Dependency release and runtime unblock are separate concepts. Dependency completion simply releases DAG work. A runtime/external blocker remains `BLOCKED` until `task unblock`, `job unblock`, or blocker-Job resolution records the blocked baseline/current evidence and emits `task.unblocked`, transitioning the Task to `UNBLOCKED`.
+
+For autonomous Jobs, `UNBLOCKED` is historical: Relay does not retry that old Task. The unblock evidence becomes the trigger/context of the next Planner round. Every Planner round is a first-class `agents-relay:plan:v1` PR comment. Relay creates that Plan comment before generated Task comments, then updates the same comment with the Planner assessment and generated Task IDs, preserving causal order in the PR timeline. Fixed Jobs may transition `UNBLOCKED -> QUEUED` through retry after the authoritative unblock record exists. Legacy Job `changeCycle` data is accepted only as compatibility input and is not written by the current model.

package/dist/cli-help.js

@@ -75,7 +75,7 @@ Example:
     'job merge': `Merge the backing pull request and complete the durable Job.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. The current PR head SHA is pinned into the merge request.`,
-    'job unblock': `Authoritatively unblock the effective BLOCKED work Tasks in one Job.\n\nRequired: --repo OWNER/REPO --pr NUMBER --id JOB_ID --reason TEXT. Autonomous Jobs persist a Change Cycle and wake Planner; fixed Jobs resume the blocked Tasks directly.`,
+    'job unblock': `Authoritatively unblock the effective BLOCKED work Tasks in one Job.\n\nRequired: --repo OWNER/REPO --pr NUMBER --id JOB_ID --reason TEXT. Autonomous Jobs transition blocked work to historical UNBLOCKED state and wake Planner with unblock facts as Plan trigger/context; fixed Jobs record UNBLOCKED first and then resume according to fixed-job retry semantics.`,
     'job cancel': `Cancel the durable Job and close its backing pull request.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID. Nonterminal Tasks are cancelled before the PR is closed.`,

package/dist/cli.js

@@ -18,7 +18,7 @@ import { decisionMode, LayaCliDecisionEngine } from './decision.js';
 import { discoverAgents } from './registry.js';
 import { AgentObjectivePlanner, CommandObjectivePlanner } from './planner.js';
 import { extendRetryBudget, transitionJobEvent, transitionTaskEvent } from './scheduler.js';
-import { dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
+import { assertScheduledAutonomousRepositoryCapability, dueBuckets, processDueScheduledJobs, syncScheduleLabels } from './scheduled-jobs.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { runBlockerCommand } from './cli-blocker.js';
@@ -35,6 +35,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
     const store = new GitHubStore(client, repositoryName, pr.number, trustedAuthors);
     try {
         const existing = await store.load(options.id);
+        await assertScheduledAutonomousRepositoryCapability(client, repositoryName, existing);
         if (existing.schedule)
             await syncScheduleLabels(client, repositoryName, existing);
         return { job: existing, pr };
@@ -65,6 +66,7 @@ export async function ensureManagedGitHubJob(client, repositoryName, trustedAuth
     };
     if (options.schedule)
         job.schedule = options.schedule;
+    await assertScheduledAutonomousRepositoryCapability(client, repositoryName, job);
     await store.saveJob(job);
     if (job.schedule)
         await syncScheduleLabels(client, repositoryName, job);
@@ -448,6 +450,7 @@ async function runJobCommand(action, args) {
             throw new Error('--continue-kind and --continue-target must be supplied together');
         job.continuation = next;
     }
+    await assertScheduledAutonomousRepositoryCapability(auth.client, repo, job);
     job.updatedAt = new Date().toISOString();
     await store.saveJob(job);
     if (hasArg(args, '--schedule') && job.schedule)

package/dist/reconciler.js

@@ -228,9 +228,17 @@ export class Reconciler extends ReconcilerReviewBase {
         }
     }
     async recoverLostExecutions(job, now) {
-        for (const task of job.tasks.filter(item => item.state === 'RUNNING' || (item.state === 'QUEUED' && item.executionId !== null))) {
-            const expired = task.leaseExpiresAt !== null && new Date(task.leaseExpiresAt).getTime() <= now;
-            if (!expired)
+        const candidates = job.tasks.filter(item => item.state === 'RUNNING' || (item.state === 'QUEUED' && item.executionId !== null));
+        for (const staleTask of candidates) {
+            if (staleTask.leaseExpiresAt === null || new Date(staleTask.leaseExpiresAt).getTime() > now)
+                continue;
+            // Re-read durable state before applying lease recovery: another reconciler may have accepted a terminal event or launched a newer execution.
+            const task = (await this.store.load(job.id)).tasks.find(item => item.id === staleTask.id);
+            if (!task)
+                continue;
+            const sameGeneration = task.executionId === staleTask.executionId && task.leaseOwner === staleTask.leaseOwner && task.leaseExpiresAt === staleTask.leaseExpiresAt;
+            const recoverable = task.state === 'RUNNING' || (task.state === 'QUEUED' && task.executionId !== null);
+            if (!sameGeneration || !recoverable || task.leaseExpiresAt === null || new Date(task.leaseExpiresAt).getTime() > now)
                 continue;
             this.live.get(task.id)?.execution.cancel();
             const planner = this.plannerLive.get(task.id);
@@ -239,8 +247,7 @@ export class Reconciler extends ReconcilerReviewBase {
                 planner.controller.abort();
                 this.plannerLive.delete(task.id);
             }
-            const failedEvent = task.state === 'RUNNING' ? 'task.failed' : 'fail';
-            await transitionTaskEvent(task, failedEvent);
+            await transitionTaskEvent(task, task.state === 'RUNNING' ? 'task.failed' : 'fail');
             task.error = 'Lease expired';
             task.leaseOwner = null;
             task.leaseExpiresAt = null;
@@ -248,12 +255,11 @@ export class Reconciler extends ReconcilerReviewBase {
             if (task.attempt < task.maxAttempts) {
                 await transitionTaskEvent(task, 'retry');
                 await this.store.saveTask(task);
+                continue;
             }
-            else {
-                task.error += ' after maximum attempts';
-                await this.store.saveTask(task);
-                await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.failed', 'failed', task.error, 'user', { reason: 'lease_expired' }));
-            }
+            task.error += ' after maximum attempts';
+            await this.store.saveTask(task);
+            await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'task.failed', 'failed', task.error, 'user', { reason: 'lease_expired' }));
         }
     }
     async planJob(jobId, guidance) {

package/dist/scheduled-jobs.js

@@ -1,6 +1,7 @@
 import { GitHubStore, loadManagedGitHubPullRequestGraphql } from './store.js';
 import { bucketStart, nextScheduleRun, parseRunBucketLabel, runBucketLabel, scheduleBucket } from './scheduler.js';
 export const AUTONOMOUS_LABEL = 'agents-relay:autonomous';
+export const AUTONOMOUS_SCHEDULER_WORKFLOW = '.github/workflows/autonomous-scheduler.yml';
 function searchPath(query, page) {
     return `search/issues?q=${encodeURIComponent(query)}&sort=created&order=asc&per_page=100&page=${page}`;
 }
@@ -17,6 +18,21 @@ export function indexedDueQuery(repository, bucket) {
     const label = runBucketLabel(bucket);
     return `repo:${repository} is:open is:pr label:"${AUTONOMOUS_LABEL}" label:"${label}"`;
 }
+export async function assertScheduledAutonomousRepositoryCapability(client, repository, job) {
+    if (job.executionMode !== 'autonomous' || !job.schedule)
+        return;
+    const metadata = await client.request(`repos/${repository}`);
+    const defaultBranch = typeof metadata.default_branch === 'string' && metadata.default_branch ? metadata.default_branch : 'main';
+    try {
+        await client.request(`repos/${repository}/contents/${AUTONOMOUS_SCHEDULER_WORKFLOW}?ref=${encodeURIComponent(defaultBranch)}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/404|Not Found/i.test(message))
+            throw error;
+        throw new Error(`SCHEDULED_AUTONOMOUS_UNAVAILABLE: ${repository} default branch ${defaultBranch} must contain ${AUTONOMOUS_SCHEDULER_WORKFLOW} before creating or enabling a scheduled autonomous Job`);
+    }
+}
 async function issueLabels(client, repository, prNumber) {
     const labels = [];
     let page = 1;

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -115,6 +115,6 @@ Keep secrets, credentials, private prompts, and large private payloads out of du
 
 ### Automatic task troubleshooting
 
-When an ACTIVE Job contains a current-run `FAILED` or `BLOCKED` task, reconciliation creates one P0-priority `troubleshooter` recovery task for that exact failed attempt. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
+When an ACTIVE Job contains a current-run `FAILED` task, reconciliation may create one P0-priority `troubleshooter` recovery task for that exact failed attempt. `BLOCKED` is resolved only through authoritative unblock, which records evidence and transitions the Task to `UNBLOCKED`. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Autonomous `UNBLOCKED` Tasks are historical and feed the next Planner round instead of being retried or sent through Troubleshooter. Each Planner round is durably represented by an `agents-relay:plan:v1` PR comment created before generated Task comments and updated in place with its assessment and generated Task IDs. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
 
 The Troubleshooter diagnoses before retrying. A task-local or transient blocker is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the blocker is removed does it retry the original task and verify durable progress. Historical failures from older scheduled autonomous runs do not spawn recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.

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

@@ -1,6 +1,6 @@
 ---
 name: troubleshooter
-description: Recover failed or blocked Agents Relay tasks by diagnosing the root cause, repairing recoverable blockers, and retrying the original task only after the blocker is removed.
+description: Recover FAILED Agents Relay tasks by diagnosing runtime/execution faults and repairing recoverable causes. BLOCKED tasks require authoritative unblock and are not resumed by Troubleshooter.
 capabilities: [troubleshoot, recovery, orchestration, local_repo, iterative_tools]
 runtime: codex
 delegation: [p0-self-job, relay-task-retry]
@@ -9,7 +9,7 @@ restrictions: [preserve-failure-evidence, no-blind-retry, no-human-blocker-bypas
 
 # Troubleshooter Agent
 
-You are the recovery orchestrator for a failed or blocked Agents Relay task.
+You are the recovery orchestrator for a FAILED Agents Relay task. Do not authoritatively clear BLOCKED work; that requires `task unblock`, `job unblock`, or blocker-Job resolution.
 
 Your goal is not to explain the failure. Your goal is to make the original task move again when it is safe and technically possible.
 

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

@@ -109,7 +109,9 @@ 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.
+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 target repository's default branch **must** contain `.github/workflows/autonomous-scheduler.yml`; this repository-level heartbeat is a required capability, not optional deployment glue. Job creation or update that would result in an autonomous Job with a schedule must fail loudly when that workflow is absent instead of persisting a schedule that can never advance. Unscheduled autonomous Jobs and fixed Jobs do not require this workflow.
+
+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.
 
 
 ## Task evidence and head identity
@@ -122,7 +124,7 @@ This does not weaken immutable review semantics: final review and specialist rev
 
 ## Dependency vs block and authoritative unblock
 
-`dependencies` describe normal DAG ordering. Dependency completion does not create an unblock event or a planning change cycle; Relay simply releases dependent work when its prerequisites succeed. `BLOCKED` is different: it records that execution reached a runtime/external condition that invalidates normal progress.
+`dependencies` describe normal DAG ordering. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; Relay simply releases dependent work when its prerequisites succeed. `BLOCKED` is different: it records that execution reached a runtime/external condition that invalidates normal progress.
 
 A BLOCKED Task cannot be resumed through retry, queue, dashboard state editing, PR push, webhook, ordinary task update, or troubleshooter inference. Except for blocker-Job resolution, the authoritative entry points are `task unblock --reason ...` and `job unblock --reason ...`. Authoritative unblock records the blocked baseline and current evidence, then transitions `BLOCKED -> UNBLOCKED` through the durable `task.unblocked` lifecycle event. `BLOCKED` therefore always means the blocker is still effective; `UNBLOCKED` means the old blocked attempt is historical and its blocker was explicitly cleared.