agents-relay 1.0.160 → 1.0.162

package/dist/blockers.js

@@ -1,4 +1,5 @@
 import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
+import { isEffectivelyBlocked, unblockAutonomousTasks } from './unblock.js';
 function dependentKey(value) {
     return `${value.repository}#${value.prNumber}:${value.jobId}:${value.taskId}:a${value.blockedAttempt}`;
 }
@@ -91,6 +92,31 @@ export async function resolveBlockerDependencies(options) {
             obsolete += 1;
             continue;
         }
+        if (targetJob.executionMode === 'autonomous') {
+            if (isEffectivelyBlocked(task)) {
+                await unblockAutonomousTasks({
+                    store,
+                    job: targetJob,
+                    tasks: [task],
+                    trigger: { source: 'blocker_job', reason: `Blocker Job ${blocker.id} resolved (${options.resolution})`, blockerJobId: blocker.id, resolution: options.resolution },
+                    now,
+                });
+                relation.state = 'resumed';
+                relation.resolvedAt = now;
+                relation.resolution = options.resolution;
+                relation.note = 'dependent task unblocked for replanning';
+                resumed += 1;
+                continue;
+            }
+            if (task.state === 'BLOCKED' && task.unblock) {
+                relation.state = 'resumed';
+                relation.resolvedAt = now;
+                relation.resolution = options.resolution;
+                relation.note = 'dependent Job already unblocked for replanning';
+                resumed += 1;
+                continue;
+            }
+        }
         if (task.state === 'DRAFT') {
             await transitionTaskEvent(task, 'release');
         }

package/dist/cli-help.js

@@ -6,8 +6,8 @@ Usage:
   npx agents-relay <command> [options]
 
 Commands:
-  job create|update|show|list|merge|cancel  Manage durable GitHub-backed jobs
-  task create|update|show|list|complete|retry|cancel  Manage durable tasks
+  job create|update|show|list|merge|unblock|cancel  Manage durable GitHub-backed jobs
+  task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
   plan                     Invoke the Planner for an existing managed Job
   blocker add|resolve|show  Manage cross-Job blocker dependencies
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
@@ -25,7 +25,7 @@ Use 'node dist/cli.js' only for explicit local development/demo mode.`,
     job: `Manage GitHub-backed durable jobs.
 
 Usage:
-  npx agents-relay job <create|update|show|list|merge|cancel> [options]
+  npx agents-relay job <create|update|show|list|merge|unblock|cancel> [options]
 
 Actions:
   create  Create a durable Job, optionally binding an existing unmanaged PR
@@ -33,6 +33,7 @@ Actions:
   show    Show one durable Job
   list    List managed Jobs in a repository
   merge   Merge the backing PR and complete the Job
+  unblock Authoritatively invalidate current BLOCKED decisions and trigger replanning/resume
   cancel  Close the backing PR and cancel the Job
 
 Common options:
@@ -74,6 +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 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.`,
@@ -86,14 +88,15 @@ Returns the same summary used by the dashboard header plus a running array with
     task: `Manage durable tasks.
 
 Usage:
-  npx agents-relay task <create|update|show|list|retry|cancel> [options]
+  npx agents-relay task <create|update|show|list|retry|unblock|cancel> [options]
 
 Actions:
   create  Create one durable Task under an existing Job
   update  Update mutable Task fields
   show    Show one Task
   list    List Tasks for a Job
-  retry   Retry a failed or blocked Task
+  retry   Retry a FAILED Task
+  unblock Authoritatively invalidate a BLOCKED decision
   complete Complete an orchestrator-owned Task
   cancel  Cancel a Task`,
     'task create': `Create one durable Task under an existing Job.

package/dist/cli-unblock.js

@@ -0,0 +1,32 @@
+import { arg, eventBus, publishWake, saveLocal } from './cli-support.js';
+import { isEffectivelyBlocked, unblockAutonomousTasks, unblockTask } from './unblock.js';
+export async function runTaskUnblockCommand(args, store, job, task, localFile) {
+    const reason = arg(args, '--reason');
+    if (!reason.trim())
+        throw new Error('task unblock requires --reason');
+    const result = await unblockTask({ store, job, task, trigger: { source: 'cli', reason } });
+    const refreshed = await store.load(job.id);
+    await saveLocal(localFile, refreshed);
+    await publishWake(eventBus(args), refreshed, task.id, `Task ${task.id} unblocked${result.replanning ? ' for replanning' : ''}`);
+    console.log(JSON.stringify({ taskId: task.id, ...result, task: refreshed.tasks.find(item => item.id === task.id) }, null, 2));
+}
+export async function runJobUnblockCommand(args, store, job) {
+    const reason = arg(args, '--reason');
+    if (!reason.trim())
+        throw new Error('job unblock requires --reason');
+    const blocked = job.tasks.filter(isEffectivelyBlocked);
+    if (blocked.length === 0)
+        throw new Error(`Job ${job.id} has no effective BLOCKED work task`);
+    if (job.executionMode === 'autonomous') {
+        const changeCycle = await unblockAutonomousTasks({ store, job, tasks: blocked, trigger: { source: 'cli', reason } });
+        const refreshed = await store.load(job.id);
+        await publishWake(eventBus(args), refreshed, 'job', `Job ${job.id} unblocked for replanning`);
+        console.log(JSON.stringify({ jobId: job.id, replanning: true, changeCycle }, null, 2));
+        return;
+    }
+    for (const task of blocked)
+        await unblockTask({ store, job, task, trigger: { source: 'cli', reason } });
+    const refreshed = await store.load(job.id);
+    await publishWake(eventBus(args), refreshed, 'job', `Job ${job.id} unblocked`);
+    console.log(JSON.stringify({ jobId: job.id, replanning: false, resumedTasks: blocked.map(task => task.id) }, null, 2));
+}

package/dist/cli.js

@@ -24,6 +24,7 @@ import { defaultWorkspaceRoot, resolveManagedProjectPath, resolveRepositoryProje
 import { runBlockerCommand } from './cli-blocker.js';
 import { helpText, usage } from './cli-help.js';
 import { parseAgentGraph } from './agent-graph.js';
+import { runJobUnblockCommand, runTaskUnblockCommand } from './cli-unblock.js';
 export { helpText } from './cli-help.js';
 import { SERVICE_DEFAULTS, ServiceEventBus, arg, hasArg, textOption, integerArg, repository, storeFor, saveLocal, githubStore, eventBus, publishWake, priority, storySize, executionMode, chatGptTabClosePolicy, requestedExecutionMode, continuation, scheduleFromArgs, jobTagFromArgs, requestManagedReconciliation, } from './cli-support.js';
 export { SERVICE_DEFAULTS, eventBus, executionMode, chatGptTabClosePolicy } from './cli-support.js';
@@ -130,7 +131,7 @@ async function workerTaskFromArgs(job, args, now) {
     };
 }
 async function runTaskCommand(action, args) {
-    if (!['create', 'update', 'show', 'list', 'complete', 'retry', 'cancel'].includes(action))
+    if (!['create', 'update', 'show', 'list', 'complete', 'retry', 'unblock', 'cancel'].includes(action))
         throw new Error(usage);
     const { store, job, localFile } = await storeFor(args);
     if (action === 'list') {
@@ -165,6 +166,10 @@ async function runTaskCommand(action, args) {
         console.log(JSON.stringify(task, null, 2));
         return;
     }
+    if (action === 'unblock') {
+        await runTaskUnblockCommand(args, store, job, task, localFile);
+        return;
+    }
     if (action === 'complete') {
         if (task.adapter !== 'orchestrator')
             throw new Error('task complete is only valid for adapter=orchestrator self-tasks');
@@ -189,6 +194,8 @@ async function runTaskCommand(action, args) {
     }
     if (action === 'retry' || action === 'cancel') {
         if (action === 'retry') {
+            if (task.state === 'BLOCKED')
+                throw new Error(`Task ${id} is BLOCKED; use task unblock --reason instead of retry`);
             task.maxAttempts = extendRetryBudget(task);
             if (task.kind === 'planner' && task.error)
                 task.plannerRetryFeedback = task.error;
@@ -255,8 +262,10 @@ async function runTaskCommand(action, args) {
             throw new Error('Task dependencies must succeed before queueing');
         if (task.state === 'DRAFT')
             await transitionTaskEvent(task, 'release');
-        else if (task.state === 'FAILED' || task.state === 'BLOCKED')
+        else if (task.state === 'FAILED')
             await transitionTaskEvent(task, 'retry');
+        else if (task.state === 'BLOCKED')
+            throw new Error(`Task ${id} is BLOCKED; use task unblock --reason instead of --queue`);
     }
     if (hasArg(args, '--max-attempts') && task.maxAttempts < task.attempt)
         throw new Error('--max-attempts cannot be less than the current attempt count');
@@ -306,7 +315,7 @@ async function runContextCommand(action, args) {
     console.log(JSON.stringify(context, null, 2));
 }
 async function runJobCommand(action, args) {
-    if (!['create', 'update', 'show', 'list', 'merge', 'cancel'].includes(action))
+    if (!['create', 'update', 'show', 'list', 'merge', 'unblock', 'cancel'].includes(action))
         throw new Error(usage);
     const repo = repository(args);
     let createObjective;
@@ -359,6 +368,10 @@ async function runJobCommand(action, args) {
         throw new Error(`job ${action} requires --pr`);
     const store = new GitHubStore(auth.client, repo, prNumber, auth.trustedAuthors);
     const job = await store.load(id);
+    if (action === 'unblock') {
+        await runJobUnblockCommand(args, store, job);
+        return;
+    }
     if (action === 'show') {
         console.log(JSON.stringify(job, null, 2));
         return;

package/dist/dashboard-actions.js

@@ -7,7 +7,9 @@ export function dashboardTaskAction(store, reconciler, action) {
         if (!task)
             throw new Error(`Task ${taskId} not found`);
         if (action === 'retry') {
-            if (!['FAILED', 'BLOCKED'].includes(task.state))
+            if (task.state === 'BLOCKED')
+                throw new Error(`Task ${task.id} is BLOCKED; use the unblock CLI with a reason`);
+            if (task.state !== 'FAILED')
                 throw new Error(`Task ${task.id} is not restartable (${task.state})`);
             task.maxAttempts = extendRetryBudget(task);
             await transitionTaskEvent(task, 'retry');
@@ -52,6 +54,8 @@ export function dashboardTaskSetState(store) {
             throw new Error(`Task ${taskId} not found`);
         if (task.state === state)
             return job;
+        if (task.state === 'BLOCKED' && state !== 'CANCELLED')
+            throw new Error(`Task ${task.id} is BLOCKED; only the unblock CLI may resume or replan it`);
         const now = new Date().toISOString();
         const from = task.state;
         applyTaskWorkflowDecision(task, {

package/dist/planner.js

@@ -281,6 +281,7 @@ export function plannerInput(context) {
         retry_feedback: context.retryFeedback,
         caller_prompt: context.guidance,
         previous_planner_task_id: context.previousPlannerTaskId,
+        change_cycle: context.job.changeCycle,
         project: project ? { name: project.name, path: project.path } : undefined,
         visible_agents: visibleAgents ?? [],
         tasks: context.tasks.map(task => ({
@@ -296,6 +297,8 @@ export function plannerInput(context) {
                 next_task_ids: task.plannerResult.next_tasks.map(item => item.id),
             } : undefined,
             error: boundedText(task.error, 2000),
+            blocked_baseline: task.blockedBaseline,
+            unblock: task.unblock,
         })),
     });
 }

package/dist/reconciler-runtime.js

@@ -353,6 +353,16 @@ export class ReconcilerRuntimeBase {
                 }
                 else if (event.type === 'task.blocked') {
                     task.error = event.message || `Task ${task.id} blocked`;
+                    const data = event.data ?? {};
+                    const head = ['candidate_head', 'candidate_head_sha', 'pr_head', 'head_sha']
+                        .map(key => data[key])
+                        .find(value => typeof value === 'string' && value.length > 0);
+                    task.blockedBaseline = {
+                        blockedAt: event.timestamp || task.updatedAt,
+                        headSha: typeof head === 'string' ? head : job.headSha,
+                        reason: task.error,
+                    };
+                    task.unblock = undefined;
                 }
                 else if (event.type === 'task.cancelled') {
                     task.error = event.message || `Task ${task.id} cancelled`;

package/dist/reconciler.js

@@ -17,6 +17,7 @@ import { pendingTroubleshooterTasks } from './troubleshooter.js';
 import { prepareManagedExecutionWorktree } from './workspace.js';
 import { createReviewChairExecutionPlan } from './review-chair.js';
 import { samePlannerChildDefinition } from './planner-child.js';
+import { consumeChangeCycle, isEffectivelyBlocked } from './unblock.js';
 import { taskTagWorkerPrompt } from './task-tag.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); }
@@ -271,13 +272,11 @@ export class Reconciler extends ReconcilerReviewBase {
         const slot = job.schedule?.currentRunSlot ? Date.parse(job.schedule.currentRunSlot) : Number.NaN;
         const scopedTasks = Number.isFinite(slot) ? job.tasks.filter(task => Date.parse(task.createdAt) >= slot) : job.tasks;
         const planners = scopedTasks.filter(task => task.kind === 'planner').sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
-        if (planners.some(task => ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
+        if (planners.some(task => ['DRAFT', 'QUEUED', 'RUNNING', 'FAILED'].includes(task.state)))
             return job;
-        if (scopedTasks.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
+        if (scopedTasks.some(isEffectivelyBlocked))
             return job;
-        if (planners.some(task => task.state === 'FAILED' || task.state === 'BLOCKED'))
-            return job;
-        if (scopedTasks.some(task => task.kind !== 'planner' && !['SUCCEEDED', 'CANCELLED'].includes(task.state)))
+        if (scopedTasks.some(task => task.kind !== 'planner' && ['DRAFT', 'QUEUED', 'RUNNING'].includes(task.state)))
             return job;
         if (planners.length > 0 && planners.at(-1)?.plannerResult?.objective_status === 'in_progress' && !job.tasks.some(task => task.planningDecisionId === planners.at(-1)?.id))
             return job;
@@ -286,6 +285,8 @@ export class Reconciler extends ReconcilerReviewBase {
             return job;
         const task = createPlannerRoundTask(job, { timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M') });
         await this.store.appendTask(task);
+        if (consumeChangeCycle(job, task.id))
+            await this.store.saveJob(job);
         await this.emit(eventFor(job.id, task.id, task.parentTaskId, 'planner.created', 'queued', `Planner task ${task.id} created`, 'orchestrator'));
         return this.store.load(job.id);
     }

package/dist/runtime-status.js

@@ -2,7 +2,10 @@ function isSuperseded(task) {
     return task.state === 'CANCELLED' && typeof task.error === 'string' && task.error.startsWith('Superseded ');
 }
 export function implementationTasks(job) {
-    return job.tasks.filter(task => task.agentName !== 'reviewer' && task.agentName !== 'troubleshooter' && !isSuperseded(task));
+    return job.tasks.filter(task => task.agentName !== 'reviewer'
+        && task.agentName !== 'troubleshooter'
+        && !isSuperseded(task)
+        && !(task.state === 'BLOCKED' && task.unblock));
 }
 export function implementationComplete(job) {
     const tasks = implementationTasks(job);
@@ -20,7 +23,7 @@ export function deriveJobRuntimeStatus(job, prState = 'OPEN') {
             return 'RUNNING';
         if (job.tasks.some(task => task.state === 'QUEUED'))
             return 'QUEUED';
-        if (job.tasks.some(task => task.state === 'BLOCKED'))
+        if (job.tasks.some(task => task.state === 'BLOCKED' && !task.unblock))
             return 'BLOCKED';
         if (job.tasks.some(task => task.state === 'FAILED'))
             return 'FAILED';
@@ -40,7 +43,7 @@ export function deriveJobRuntimeStatus(job, prState = 'OPEN') {
         return 'RUNNING';
     if (job.tasks.some(task => task.state === 'QUEUED'))
         return 'QUEUED';
-    if (job.tasks.some(task => task.state === 'BLOCKED'))
+    if (job.tasks.some(task => task.state === 'BLOCKED' && !task.unblock))
         return 'BLOCKED';
     if (job.tasks.some(task => task.state === 'FAILED'))
         return 'FAILED';

package/dist/troubleshooter.js

@@ -48,6 +48,8 @@ export function pendingTroubleshooterTasks(job) {
     for (const task of job.tasks) {
         if (!['FAILED', 'BLOCKED'].includes(task.state) || task.kind === 'planner' || task.agentName === 'troubleshooter' || !belongsToCurrentRun(job, task))
             continue;
+        if (task.state === 'BLOCKED' && task.unblock)
+            continue;
         const id = troubleshooterTaskId(task);
         if (existing.has(id) || hasRecoveryBarrier(job, task))
             continue;

package/dist/unblock.js

@@ -0,0 +1,74 @@
+import { extendRetryBudget, transitionTaskEvent } from './scheduler.js';
+export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.state === 'BLOCKED' && !task.unblock; }
+function baselineFor(task) {
+    return task.blockedBaseline ?? { blockedAt: task.updatedAt, reason: task.error ?? undefined };
+}
+function cycleFacts(job, tasks, currentHeadSha, reason) {
+    const facts = [`unblock: ${reason}`];
+    const baselines = tasks.map(task => baselineFor(task));
+    const heads = [...new Set(baselines.map(item => item.headSha).filter((item) => Boolean(item)))];
+    if (currentHeadSha && heads.some(head => head !== currentHeadSha))
+        facts.push(`PR head advanced from ${heads.join(', ')} to ${currentHeadSha}`);
+    const times = baselines.map(item => Date.parse(item.blockedAt)).filter(Number.isFinite).sort((a, b) => a - b);
+    const earliest = times[0];
+    if (earliest !== undefined) {
+        for (const task of job.tasks) {
+            if (tasks.some(item => item.id === task.id))
+                continue;
+            const changedAt = Date.parse(task.updatedAt);
+            if (!Number.isFinite(changedAt) || changedAt < earliest)
+                continue;
+            const detail = task.result?.summary ?? task.error ?? task.state;
+            facts.push(`task ${task.id} -> ${task.state}: ${detail}`);
+        }
+    }
+    return [...new Set(facts)];
+}
+export async function unblockAutonomousTasks(options) {
+    const { store, job, trigger } = options;
+    const tasks = options.tasks.filter(isEffectivelyBlocked);
+    if (tasks.length === 0)
+        throw new Error('No effective BLOCKED work task is available to unblock');
+    const now = options.now ?? new Date().toISOString();
+    const currentHeadSha = await store.headSha?.() ?? job.headSha ?? null;
+    for (const task of tasks) {
+        const baseline = baselineFor(task);
+        const record = { at: now, source: trigger.source, reason: trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, blockerJobId: trigger.blockerJobId, resolution: trigger.resolution };
+        task.blockedBaseline = baseline;
+        task.unblock = record;
+        task.updatedAt = now;
+        delete task.blockedBy;
+        await store.saveTask(task);
+    }
+    const baselineHeadShas = [...new Set(tasks.map(task => baselineFor(task).headSha).filter((item) => Boolean(item)))];
+    const cycle = { triggeredAt: now, source: trigger.source, reason: trigger.reason, taskIds: tasks.map(task => task.id), baselineHeadShas, currentHeadSha: currentHeadSha ?? undefined, facts: cycleFacts(job, tasks, currentHeadSha, trigger.reason) };
+    job.changeCycle = cycle;
+    job.updatedAt = now;
+    await store.saveJob(job);
+    return cycle;
+}
+export async function unblockTask(options) {
+    if (!isEffectivelyBlocked(options.task))
+        throw new Error(`Task ${options.task.id} is not an effective BLOCKED work task`);
+    if (options.job.executionMode === 'autonomous') {
+        const changeCycle = await unblockAutonomousTasks({ store: options.store, job: options.job, tasks: [options.task], trigger: options.trigger, now: options.now });
+        return { replanning: true, changeCycle };
+    }
+    options.task.maxAttempts = extendRetryBudget(options.task);
+    await transitionTaskEvent(options.task, 'retry');
+    options.task.error = null;
+    options.task.leaseOwner = null;
+    options.task.leaseExpiresAt = null;
+    options.task.executionId = null;
+    options.task.updatedAt = options.now ?? new Date().toISOString();
+    delete options.task.blockedBy;
+    await options.store.saveTask(options.task);
+    return { replanning: false };
+}
+export function consumeChangeCycle(job, plannerTaskId, now = new Date().toISOString()) {
+    if (!job.changeCycle || job.changeCycle.consumedByPlannerTaskId)
+        return false;
+    job.changeCycle.consumedByPlannerTaskId = plannerTaskId;
+    job.updatedAt = now;
+    return true;
+}

package/package.json

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

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

@@ -66,6 +66,8 @@ 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 Task depends on mutable repository or product state, distinguish a frozen evidence target from the current execution head. A SHA may freeze that Task's own review/source evidence, but do not copy an upstream SHA into a dependent release, deploy, publication, or other follow-on Task unless the objective explicitly requires that same frozen target. After dependencies complete, downstream Tasks must resolve and verify the current durable Job/PR head before acting.
+- When fresh UI, browser, store, runtime, or visual evidence is material to the Task outcome, say so explicitly in the Task input and require evidence from the real current state. Existing screenshots, prepared assets, or prior observations are not substitutes for fresh evidence unless the objective explicitly allows reuse.
 - 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`.

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

@@ -110,3 +110,22 @@ 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.
+
+
+## Task evidence and head identity
+
+Task inputs must make evidence freshness and target identity explicit when those facts affect correctness. A Task may bind its own review, audit, or source evidence to an immutable SHA/version. That frozen target belongs to that Task; it must not be propagated mechanically into later dependent work. A downstream release, deploy, publication, or other Task that runs after dependencies complete must resolve the current durable Job/PR head at execution time unless the Job objective explicitly requires the earlier immutable target.
+
+When success depends on the actual current UI, browser state, store listing, runtime state, or another externally observable surface, the Task contract must require fresh evidence from that real current surface. Reusing an existing screenshot, prepared asset, cached observation, or older evidence is valid only when the Job explicitly permits it.
+
+This does not weaken immutable review semantics: final review and specialist review Tasks should continue to declare and inspect one exact immutable target/version.
+
+## 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.
+
+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 ...`. For autonomous Jobs, unblock does not retry the old Task. Relay preserves its blocked baseline, records current head/change facts in a durable Job Change Cycle, marks that blocked decision as unblocked-for-planning, and wakes the next Planner round. The Planner then decides whether to retry, replace, split, wait, or otherwise re-plan the objective.
+
+A blocker Job owns reverse `unblocks` references. When it resolves, Relay checks the dependent Job. If that autonomous Job has an effective BLOCKED work Task, resolution uses the same Change Cycle/replanning primitive. If it does not have BLOCKED work (for example the registered Task is DRAFT or FAILED), existing release/retry behavior remains unchanged.
+
+Automatic Planner creation treats only an effective BLOCKED work Task as a block gate. FAILED history is not itself a Planner gate; active DRAFT/QUEUED/RUNNING work still prevents a competing planning round.