agents-relay 2.0.68 → 2.0.70

package/dist/service-publication.js

@@ -1,9 +1,7 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { eventFor } from './events.js';
-import { SQLiteRelayStore, relayStorePath } from './relay-store.js';
+import { SQLiteRelayStore, relayStoreDirectory, relayStorePath } from './relay-store.js';
 /** Single-Job service uses the same durable publish facts as the repository daemon. */
-export async function handleServicePublication(job, wake, bus, directory = join(homedir(), '.agents-relay', 'stores')) {
+export async function handleServicePublication(job, wake, bus, directory = relayStoreDirectory()) {
     if (!wake.publication && !wake.publishFailure)
         return;
     const sqlite = new SQLiteRelayStore(relayStorePath(directory, job.repository, job.prNumber));

package/dist/task-actions.js

@@ -1,6 +1,7 @@
 import { extendRetryBudget, transitionTaskEvent, tryTransitionTaskEvent } from './scheduler.js';
 import { selectRelatedTaskMutations } from './workflow/task-action-policy.js';
 export const TASK_RETRY_ACTION = 'task.retry';
+export const TASK_RECOVER_ACTION = 'task.recover';
 export const TASK_UNBLOCK_RETRY_ACTION = 'task.unblock.retry';
 export const TASK_CANCEL_ACTION = 'task.cancel';
 export const TASK_RELEASE_ACTION = 'task.release';
@@ -28,6 +29,24 @@ function clearExecution(task) {
     task.leaseExpiresAt = null;
     task.executionId = null;
 }
+function applyTaskRetrySnapshot(task, policy = {}) {
+    if (task.kind === 'planner')
+        throw new Error(`Legacy planner Task ${task.id} is read-only; retry the Plan instead`);
+    const decision = tryTransitionTaskEvent(task, 'retry');
+    if (!decision.accepted)
+        throw lifecycleRejection(task, 'restartable');
+    if (policy.extendBudget)
+        task.maxAttempts = extendRetryBudget(task);
+    clearExecution(task);
+}
+/** Fixed-job authoritative unblock continuation, applied inside one Job snapshot mutation. */
+export function applyTaskUnblockRetrySnapshot(task) {
+    if (!tryTransitionTaskEvent(task, 'retry').accepted)
+        throw lifecycleRejection(task, 'retryable after unblock');
+    task.maxAttempts = extendRetryBudget(task);
+    clearExecution(task);
+    delete task.blockedBy;
+}
 /** Shared task.retry mutation. The canonical lifecycle graph is the sole legality authority. */
 export async function applyTaskRetryAction(task, policy = {}) {
     if (task.kind === 'planner')
@@ -130,13 +149,48 @@ async function applySelectedRelatedTaskMutations(job, mutations) {
 }
 /** Compatibility bridge: domain mutation only; adapters own wake/reconcile/output behavior. */
 export async function dispatchTaskAction(store, request) {
+    if (store.mutateJob && [TASK_RETRY_ACTION, TASK_RECOVER_ACTION, TASK_CANCEL_ACTION].includes(request.id)) {
+        let updatedTask;
+        const updated = await store.mutateJob(request.jobId, current => {
+            const task = current.tasks.find(item => item.id === request.taskId);
+            if (!task)
+                throw new Error(`Task ${request.taskId} not found`);
+            if (request.id === TASK_RECOVER_ACTION) {
+                const recovery = request.recoveryTaskId ? current.tasks.find(item => item.id === request.recoveryTaskId) : undefined;
+                if (!recovery || recovery.agentName !== 'troubleshooter' || recovery.parentTaskId !== task.id || !['QUEUED', 'RUNNING'].includes(recovery.state))
+                    throw new Error(`task recover requires an active Troubleshooter recovery for ${task.id}`);
+            }
+            const relatedMutations = request.id === TASK_RECOVER_ACTION ? [] : selectRelatedTaskMutations(current, task, request.id);
+            if (request.id === TASK_RETRY_ACTION || request.id === TASK_RECOVER_ACTION)
+                applyTaskRetrySnapshot(task, { extendBudget: true });
+            else if (request.id === TASK_CANCEL_ACTION)
+                cancelTaskSnapshot(task);
+            for (const mutation of relatedMutations) {
+                const related = current.tasks.find(item => item.id === mutation.taskId);
+                if (!related)
+                    throw new Error(`Related task ${mutation.taskId} not found`);
+                cancelTaskSnapshot(related, mutation.reason);
+            }
+            updatedTask = structuredClone(task);
+            return current;
+        });
+        if (!updatedTask)
+            throw new Error(`Task ${request.taskId} was not updated`);
+        return { job: updated, task: updatedTask };
+    }
     const job = await store.load(request.jobId);
     const task = job.tasks.find(item => item.id === request.taskId);
     if (!task)
         throw new Error(`Task ${request.taskId} not found`);
-    const relatedMutations = selectRelatedTaskMutations(job, task, request.id);
+    const relatedMutations = request.id === TASK_RECOVER_ACTION ? [] : selectRelatedTaskMutations(job, task, request.id);
     if (request.id === TASK_RETRY_ACTION)
         await applyTaskRetryAction(task, { extendBudget: true });
+    else if (request.id === TASK_RECOVER_ACTION) {
+        const recovery = request.recoveryTaskId ? job.tasks.find(item => item.id === request.recoveryTaskId) : undefined;
+        if (!recovery || recovery.agentName !== 'troubleshooter' || recovery.parentTaskId !== task.id || !['QUEUED', 'RUNNING'].includes(recovery.state))
+            throw new Error(`task recover requires an active Troubleshooter recovery for ${task.id}`);
+        await applyTaskRetryAction(task, { extendBudget: true });
+    }
     else if (request.id === TASK_UNBLOCK_RETRY_ACTION)
         await applyTaskUnblockRetryAction(task);
     else if (request.id === TASK_CANCEL_ACTION)
@@ -157,3 +211,7 @@ export async function dispatchTaskAction(store, request) {
         await store.saveTask(related);
     return { job, task };
 }
+function cancelTaskSnapshot(task, reason = 'Cancelled by user') {
+    if (!tryApplyTaskCancelAction(task, reason))
+        throw lifecycleRejection(task, 'cancellable');
+}

package/dist/troubleshooter.js

@@ -26,7 +26,7 @@ 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. 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. Do not manually choose a provider/model or create a replacement task. 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. 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. 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;
@@ -79,7 +79,7 @@ export function pendingTroubleshooterTasks(job) {
             continuation: null,
             continuationDeliveredAt: null,
             attempt: 0,
-            maxAttempts: 1,
+            maxAttempts: 3,
             leaseOwner: null,
             leaseExpiresAt: null,
             executionId: null,
@@ -94,3 +94,22 @@ export function pendingTroubleshooterTasks(job) {
     }
     return recoveries;
 }
+export function exhaustedTroubleshooterRecoveries(job) {
+    const results = [];
+    for (const recovery of job.tasks) {
+        if (recovery.agentName !== 'troubleshooter' || recovery.state !== 'FAILED' || recovery.attempt < recovery.maxAttempts || !recovery.parentTaskId)
+            continue;
+        const original = job.tasks.find(task => task.id === recovery.parentTaskId);
+        if (!original || !['FAILED', 'BLOCKED'].includes(original.state))
+            continue;
+        const alreadyRecorded = job.recoveryFailures?.some(item => item.taskId === original.id && item.recoveryTaskId === recovery.id);
+        if (alreadyRecorded)
+            continue;
+        results.push({
+            original,
+            recovery,
+            reason: recovery.error ?? recovery.failureReason ?? `Troubleshooter ${recovery.id} ${recovery.state.toLowerCase()}`,
+        });
+    }
+    return results;
+}

package/dist/unblock.js

@@ -1,5 +1,5 @@
-import { transitionTaskEvent } from './scheduler.js';
-import { applyTaskUnblockRetryAction } from './task-actions.js';
+import { applyTaskUnblockRetrySnapshot } from './task-actions.js';
+import { tryTransitionTaskEvent } from './scheduler.js';
 import { dispatchAuthoritativeUnblock } from './workflow/authoritative-unblock-v2.js';
 export function isEffectivelyBlocked(task) { return task.kind !== 'planner' && task.state === 'BLOCKED'; }
 function baselineFor(task) {
@@ -53,14 +53,29 @@ export async function unblockAutonomousTasks(options) {
     const now = options.now ?? new Date().toISOString();
     const currentHeadSha = await store.headSha?.() ?? job.headSha ?? null;
     const facts = unblockFacts(job, tasks, currentHeadSha, trigger.reason);
-    for (const task of tasks) {
-        const baseline = baselineFor(task);
-        task.blockedBaseline = baseline;
-        task.unblock = { at: now, source: trigger.source, reason: trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: trigger.blockerJobId, resolution: trigger.resolution };
-        await transitionTaskEvent(task, 'task.unblocked');
-        task.updatedAt = now;
-        delete task.blockedBy;
-        await store.saveTask(task);
+    const apply = (current) => {
+        for (const requested of tasks) {
+            const task = current.tasks.find(item => item.id === requested.id);
+            if (!task || !isEffectivelyBlocked(task))
+                throw new Error(`Task ${requested.id} changed before authoritative unblock`);
+            const baseline = baselineFor(task);
+            if (!tryTransitionTaskEvent(task, 'task.unblocked').accepted)
+                throw new Error(`Task ${task.id} cannot be authoritatively unblocked`);
+            task.blockedBaseline = baseline;
+            task.unblock = { at: now, source: trigger.source, reason: trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: trigger.blockerJobId, resolution: trigger.resolution };
+            task.updatedAt = now;
+            delete task.blockedBy;
+        }
+        current.updatedAt = now;
+    };
+    if (store.mutateJob) {
+        const committed = await store.mutateJob(job.id, current => { apply(current); return current; });
+        Object.assign(job, structuredClone(committed));
+    }
+    else {
+        apply(job);
+        for (const task of tasks)
+            await store.saveTask(task);
     }
     const planTrigger = unconsumedUnblockTrigger(job) ?? {
         source: 'unblock', taskIds: tasks.map(task => task.id), reason: trigger.reason,
@@ -84,11 +99,28 @@ export async function unblockTask(options) {
             options.task.blockedBaseline = baseline;
             const facts = unblockFacts(options.job, [options.task], currentHeadSha, options.trigger.reason);
             options.task.unblock = { at: now, source: options.trigger.source, reason: options.trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: options.trigger.blockerJobId, resolution: options.trigger.resolution };
-            await transitionTaskEvent(options.task, 'task.unblocked');
-            await options.store.saveTask(options.task);
-            await applyTaskUnblockRetryAction(options.task);
-            options.task.updatedAt = now;
-            await options.store.saveTask(options.task);
+            const apply = (current) => {
+                const task = current.tasks.find(item => item.id === options.task.id);
+                if (!task || !isEffectivelyBlocked(task))
+                    throw new Error(`Task ${options.task.id} changed before authoritative unblock`);
+                if (!tryTransitionTaskEvent(task, 'task.unblocked').accepted)
+                    throw new Error(`Task ${task.id} cannot be authoritatively unblocked`);
+                const baseline = baselineFor(task);
+                task.blockedBaseline = baseline;
+                task.unblock = { at: now, source: options.trigger.source, reason: options.trigger.reason, baseline, currentHeadSha: currentHeadSha ?? undefined, facts, blockerJobId: options.trigger.blockerJobId, resolution: options.trigger.resolution };
+                applyTaskUnblockRetrySnapshot(task);
+                task.updatedAt = now;
+                delete task.blockedBy;
+                current.updatedAt = now;
+            };
+            if (options.store.mutateJob) {
+                const committed = await options.store.mutateJob(options.job.id, current => { apply(current); return current; });
+                Object.assign(options.job, structuredClone(committed));
+            }
+            else {
+                apply(options.job);
+                await options.store.saveTask(options.task);
+            }
             result = { replanning: false };
             return {};
         }

package/dist/worker-rejection.js

@@ -0,0 +1,11 @@
+/** Classify genuine worker-process rejection text, regardless of E2E mode. */
+export function classifyWorkerRejection(message) {
+    if (/rate[_ .-]?limit[_ .-]?exceeded|usage limit reached|quota[_ .-]?exceeded|insufficient[_ .-]?quota/i.test(message))
+        return 'rate_limit_exceeded';
+    if (/model[_ .-]?not[_ .-]?found|model (?:is )?(?:unavailable|not found|unsupported)|unsupported model/i.test(message))
+        return 'model_not_found';
+    if (/provider[_ .-]?unavailable|provider (?:is )?(?:unavailable|refused)|service unavailable/i.test(message))
+        return 'provider_unavailable';
+    return 'worker_process_failed';
+}
+export const reroutableWorkerRejections = new Set(['rate_limit_exceeded', 'model_not_found', 'provider_unavailable']);

package/dist/workflow-effect-failures.js

@@ -0,0 +1,30 @@
+import { transitionJobEvent, transitionTaskEvent } from './scheduler.js';
+import { workflowEffectFailureEvent } from './workflow/contracts.js';
+import { eventFor } from './events.js';
+export async function applyJobEffectOutcomes(store, emit, job, outcomes) {
+    for (const outcome of outcomes.filter(item => item.status === 'failed')) {
+        const eventName = workflowEffectFailureEvent(outcome.effect);
+        try {
+            await transitionJobEvent(job, eventName);
+            await store.saveJob(job);
+        }
+        catch {
+            // Some effects are observational for a given state; failure is still emitted below.
+        }
+        await emit(eventFor(job.id, 'job', null, 'workflow.effect.failed', 'failed', `${outcome.effect} failed: ${outcome.error ?? 'unknown error'}`, 'orchestrator', { effect: outcome.effect, idempotencyKey: outcome.key, workflowEvent: eventName }, { agent: 'relay', component: 'agents-relay' }));
+    }
+}
+export async function applyTaskEffectOutcomes(store, emit, job, task, outcomes) {
+    for (const outcome of outcomes.filter(item => item.status === 'failed')) {
+        const eventName = workflowEffectFailureEvent(outcome.effect);
+        try {
+            await transitionTaskEvent(task, eventName);
+            task.error = outcome.error ?? `${outcome.effect} failed`;
+            await store.saveTask(task);
+        }
+        catch {
+            // The effect failure remains observable even if this state has no feedback transition.
+        }
+        await emit(eventFor(job.id, task.id, task.parentTaskId, 'workflow.effect.failed', 'failed', `${outcome.effect} failed: ${outcome.error ?? 'unknown error'}`, 'orchestrator', { effect: outcome.effect, idempotencyKey: outcome.key, workflowEvent: eventName }, { agent: 'relay', component: 'agents-relay' }));
+    }
+}

package/dist/workspace.js

@@ -1,6 +1,7 @@
 import { lstat, mkdir, readdir, realpath, stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
 import { spawnOwnedProcess } from './owned-process.js';
 async function gitOutput(args) {
     return await new Promise((resolve, reject) => {
@@ -181,6 +182,88 @@ export function managedJobWorktreePath(repository, prNumber, workspaceRoot = def
         throw new Error('Invalid managed Job checkout identity');
     return join(workspaceRoot, '.worktrees', 'agents-relay', `${repository.replace('/', '-')}-pr-${prNumber}`, 'job');
 }
+export function managedLocalJobWorktreePath(repository, jobId, workspaceRoot = defaultWorkspaceRoot()) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || !jobId.trim())
+        throw new Error('Invalid local Job checkout identity');
+    const safeJob = jobId.replace(/[^A-Za-z0-9_.-]+/g, '-').slice(0, 72) || 'job';
+    const digest = createHash('sha256').update(jobId).digest('hex').slice(0, 12);
+    return join(workspaceRoot, '.worktrees', 'agents-relay', `${repository.replace('/', '-')}-job-${safeJob}-${digest}`, 'job');
+}
+/** Bind an ordinary SQLite Job to one deterministic local work branch.
+ * The target is always main, and branch creation never switches the user's checkout.
+ * This is a Git-local operation and never needs GitHub credentials.
+ */
+export async function ensureLocalJobSourceBranch(projectPath, job) {
+    if (job.localMerge?.sourceRef) {
+        if (job.localMerge.targetRef !== 'refs/heads/main')
+            throw new Error('Local Job target must be main');
+        return job.localMerge.sourceRef;
+    }
+    const safe = job.id.replace(/[^A-Za-z0-9_.-]+/g, '-').slice(0, 48);
+    const digest = createHash('sha256').update(job.id).digest('hex').slice(0, 12);
+    const sourceRef = `refs/heads/relay/job-${safe}-${digest}`;
+    const primary = (await git(projectPath, ['rev-parse', '--show-toplevel'])).trim();
+    await git(primary, ['rev-parse', '--verify', 'refs/heads/main']);
+    const exists = await gitOutput(['-C', primary, 'show-ref', '--verify', '--quiet', sourceRef]).then(() => true, () => false);
+    if (!exists) {
+        // A concurrent caller may create the same ref; git update-ref is idempotent
+        // when the target already exists, and must never reset it.
+        const sha = (await git(primary, ['rev-parse', '--verify', 'refs/heads/main'])).trim();
+        await gitOutput(['-C', primary, 'update-ref', sourceRef, sha, '0000000000000000000000000000000000000000']).catch(async (error) => {
+            if (!(await gitOutput(['-C', primary, 'show-ref', '--verify', sourceRef]).then(() => true, () => false)))
+                throw error;
+        });
+    }
+    return sourceRef;
+}
+export async function prepareLocalJobExecutionWorktree(projectPath, job, workspaceRoot = defaultWorkspaceRoot()) {
+    if (job.prNumber !== 0 || !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'))
+        throw new Error('Local Job execution requires a valid refs/heads sourceRef');
+    const primary = await git(projectPath, ['rev-parse', '--show-toplevel']);
+    const projectRelative = (await git(projectPath, ['rev-parse', '--show-prefix'])).replace(/\/$/, '');
+    let remote = '';
+    try {
+        remote = await git(primary, ['config', '--get', 'remote.origin.url']);
+    }
+    catch { /* Local-only repositories may have no origin. */ }
+    const remoteRepository = remote ? githubRepositoryFromRemote(remote) : null;
+    if (remoteRepository && remoteRepository !== job.repository)
+        throw new Error(`Primary checkout ${primary} does not match ${job.repository}`);
+    const sourceSha = await git(primary, ['rev-parse', '--verify', sourceRef]);
+    const worktree = managedLocalJobWorktreePath(job.repository, job.id, workspaceRoot);
+    await mkdir(dirname(worktree), { recursive: true });
+    try {
+        const existingRoot = await git(worktree, ['rev-parse', '--show-toplevel']);
+        if (await realpath(existingRoot) !== await realpath(worktree))
+            throw new Error(`Worktree ownership mismatch: ${worktree}`);
+        const branch = await git(worktree, ['symbolic-ref', 'HEAD']);
+        if (branch !== sourceRef)
+            throw new Error(`Local Job worktree is bound to ${branch}, expected ${sourceRef}`);
+        const existingHead = await git(worktree, ['rev-parse', 'HEAD']);
+        if (existingHead !== sourceSha) {
+            if (await git(worktree, ['status', '--porcelain']))
+                throw new Error(`Local Job worktree has changes while source ref advanced: ${worktree}`);
+            const ancestor = await gitOutput(['-C', worktree, 'merge-base', '--is-ancestor', existingHead, sourceSha]).then(() => true, () => false);
+            if (!ancestor)
+                throw new Error(`Local Job worktree has non-fast-forward history; preserve commits: ${worktree}`);
+            await git(worktree, ['merge', '--ff-only', sourceSha]);
+        }
+        return projectRelative ? join(worktree, projectRelative) : worktree;
+    }
+    catch (error) {
+        try {
+            await stat(worktree);
+        }
+        catch {
+            await git(primary, ['worktree', 'add', worktree, sourceRef.slice('refs/heads/'.length)]);
+            return projectRelative ? join(worktree, projectRelative) : worktree;
+        }
+        throw error;
+    }
+}
 /**
  * Graph-owned eligibility: called only after authoritative MERGED -> COMPLETED.
  * This function only performs the mechanical, conservative cleanup effect.
@@ -188,13 +271,14 @@ export function managedJobWorktreePath(repository, prNumber, workspaceRoot = def
 export async function cleanupCompletedJobWorktree(projectPath, job, workspaceRoot = defaultWorkspaceRoot()) {
     if (job.state !== 'COMPLETED')
         return { status: 'blocked', reason: 'Job is not completed' };
-    if (!job.headSha)
-        return { status: 'blocked', reason: 'No durable PR head SHA' };
+    const expectedHead = job.prNumber === 0 ? (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 = managedJobWorktreePath(job.repository, job.prNumber, workspaceRoot);
+    const worktree = job.prNumber === 0 ? managedLocalJobWorktreePath(job.repository, job.id, workspaceRoot) : managedJobWorktreePath(job.repository, job.prNumber, workspaceRoot);
     let metadata;
     try {
         metadata = await lstat(worktree);
@@ -207,8 +291,13 @@ export async function cleanupCompletedJobWorktree(projectPath, job, workspaceRoo
     if (!metadata.isDirectory() || metadata.isSymbolicLink())
         return { status: 'blocked', reason: 'Worktree path is not an owned directory' };
     const primary = await git(projectPath, ['rev-parse', '--show-toplevel']);
-    const origin = await git(primary, ['config', '--get', 'remote.origin.url']);
-    if (githubRepositoryFromRemote(origin) !== job.repository)
+    let origin = '';
+    try {
+        origin = await git(primary, ['config', '--get', 'remote.origin.url']);
+    }
+    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))
         return { status: 'blocked', reason: 'Canonical repository identity mismatch' };
     const registered = await git(primary, ['worktree', 'list', '--porcelain']);
     const ownedRoot = await realpath(worktree);
@@ -224,7 +313,7 @@ export async function cleanupCompletedJobWorktree(projectPath, job, workspaceRoo
     if (!matching.includes(true))
         return { status: 'blocked', reason: 'Worktree is not registered with the canonical repository' };
     const head = await git(worktree, ['rev-parse', 'HEAD']);
-    if (head !== job.headSha)
+    if (head !== expectedHead)
         return { status: 'blocked', reason: 'Worktree contains unique or stale commits' };
     if (await git(worktree, ['status', '--porcelain']))
         return { status: 'blocked', reason: 'Worktree has uncommitted or untracked changes' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.68",
+  "version": "2.0.70",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {
@@ -12,9 +12,10 @@
     "test": "npm run test:full",
     "test:chatgpt-temp-quality": "AGENTS_RELAY_RUN_CHATGPT_TEMP_QUALITY=1 sh -c \"npm run build && node test/quality/run-temporary-chat.mjs\"",
     "dev": "tsx src/cli.ts",
-    "test:publish": "npm run build && node --test --test-force-exit test/*.test.js",
-    "test:fast": "npm run build && node --test --test-concurrency=2 test/workflow-lifecycle.test.js test/workflow-v2-lifecycle-parity.test.js test/workflow-effects.test.js test/relay-store.test.js test/local-authority.test.js test/local-jobid-routing.test.js test/local-sqlite-jobid.test.js test/no-github.test.js test/scheduled-jobs.test.js test/reconcile-coordinator.test.js test/service-publication.test.js test/github-webhook.test.js",
-    "test:full": "npm run build && node --test --test-concurrency=1 test/*.test.js"
+    "test:publish": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 --test-force-exit test/*.test.js",
+    "test:fast": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=2 test/workflow-lifecycle.test.js test/workflow-v2-lifecycle-parity.test.js test/workflow-effects.test.js test/relay-store.test.js test/local-authority.test.js test/local-jobid-routing.test.js test/local-sqlite-jobid.test.js test/no-github.test.js test/scheduled-jobs.test.js test/reconcile-coordinator.test.js test/service-publication.test.js test/github-webhook.test.js",
+    "test:full": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/*.test.js",
+    "e2e": "node e2e/runner/run.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

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

@@ -81,6 +81,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - Treat durable Job/Task state as authoritative.
 - Discover visible agents from the resolved execution context before selecting an agent. Choose an existing visible agent only when it is appropriate for the Task; otherwise leave `agentName` unset. Agent discovery is runtime/context-specific, not a hardcoded global list.
 - Build `agentGraph` nodes only from agents in the discovered visible-agent catalog. Every named graph agent must be visible in the resolved planning/execution context.
+- `agentGraph` is optional. For a single agent use `flowchart LR\n  implementation[agent:implementation]` (replace with the actual visible agent); do **not** create an edge from an agent/node to itself. Every edge must connect distinct nodes, and all edges must form an acyclic directed graph. If no multi-agent orchestration is needed, omit `agentGraph` entirely.
 - Never invent completed work or evidence.
 - First decide whether the objective is already satisfied.
 - If satisfied, return `objective_status: "satisfied"` and `next_tasks: []`.
@@ -98,6 +99,8 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - Every child Task must declare exactly one output: `task_pr` or `file`.
 - Every child Task must include `storySize` (`S`, `M`, or `L`); use `M` when uncertain.
 - Do not create bookkeeping, waiting, status-checking, wrapper, or planning Tasks. Your response itself is the planning round.
+- Relay owns lifecycle delivery for local-first Jobs. Never create a worker Task whose job is to perform the local Git merge, mark the Job `COMPLETED`, merge the projected GitHub PR, or wait/check for those Relay-owned effects. After implementation and required review are satisfied, return no lifecycle-completion Task; let the canonical Review/Local-Merge/Job Graph advance the Job.
+- When all executable implementation work is complete and the only remaining steps are Relay-owned final review, local merge, Job completion, or projected PR convergence, return `objective_status: "satisfied"` with `next_tasks: []`. Do not return `in_progress` with an empty task list before final review; that would leave the Job with no executable progress path.
 - Return no prose outside the JSON result.
 
 ## Output

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

@@ -8,22 +8,19 @@ This contract defines orchestrator-owned exception workflows that sit above norm
 
 ## Normal managed Job start workflow
 
-For a normal managed Job, `job create` or `job adopt` establishes durable Job/PR state only. Unless the user explicitly requested **create-only / no execution**, the orchestrator must immediately start the Job by invoking the first-class Planner command for that exact Job:
+For a normal managed Job, the preferred bootstrap is one command:
 
 ```text
-job create|adopt
-  -> agents-relay plan --repo <owner/repo> --pr <number> --id <job_id>
+job create --initial-plan
   -> durable plan-N
   -> Planner next_tasks
   -> Relay materializes Tasks
   -> normal routing, execution, and reconciliation
 ```
 
-The initial decomposition for a normal managed Job belongs to that durable Planner round. The orchestrator must not hand-author the initial child Task batch as a substitute for `agents-relay plan`, and it must not leave a newly created executable Job with zero Plans and zero Tasks. If the Planner command fails, the Job is blocked at startup and the orchestrator must report the failure rather than silently inventing Tasks.
+Without `--initial-plan`, `job create` remains create-only and establishes durable Job/PR state without execution. `agents-relay plan` remains available for an existing create-only/adopted Job. Unless the user explicitly requested **create-only / no execution**, the orchestrator should use `job create --initial-plan` rather than issuing two separate commands.
 
-This rule applies regardless of whether the Job uses `fixed` or `autonomous` execution mode; execution mode does not replace the required initial Planner invocation. Later replanning continues to follow Relay's normal Planner/reconciliation rules.
-
-The explicit exception is the P0/self-job workflow below: a self job is synchronous orchestrator-owned execution, so it creates orchestrator-owned Tasks directly and terminalizes them in the same turn instead of invoking the normal initial Planner round.
+The initial decomposition belongs to that durable Planner round. The orchestrator must not hand-author the initial child Task batch as a substitute. If initial planning fails, the create command fails visibly after preserving the durable Job/Plan evidence; the orchestrator must not silently invent Tasks. This applies regardless of whether the Job uses `fixed` or `autonomous` execution mode. Later replanning continues to follow Relay's normal Planner/reconciliation rules.
 
 ## P0 / self job workflow
 

package/workflow/review-lifecycle.mmd

@@ -39,6 +39,7 @@ cancelChanges["action: review.cancelStale"]
 cancelBlocked["action: review.cancelStale"]
 fixPending["action: review.createFix"]
 fixStarted["action: review.createFix"]
+fixChanges["action: review.createFix"]
 mergePending["action: review.requestMerge"]
 mergeStarted["action: review.requestMerge"]
 
@@ -105,6 +106,8 @@ autoMergeStarted -->|false| approved
 started -->|on: review.changes_required| fixStarted
 fixStarted --> changes
 started -->|on: review.blocked| blocked
+changes -->|on: review.changes_required| fixChanges
+fixChanges --> changes
 
 pending -->|on: head.changed| cancelPending
 cancelPending --> stale