agents-relay 2.0.67 → 2.0.69

package/dist/workflow/job-reconcile-v2.js

@@ -1,65 +1,14 @@
 import { decideJobLifecycle, dispatchJobLifecycle } from './lifecycle.js';
-import { implementationComplete } from '../runtime-status.js';
-import { applyHistoricalJobCompatibilityRepair } from './runtime.js';
-function lifecycleInput(facts) {
-    if (facts.prState === 'MERGED')
-        return { event: 'pr.merged', context: {} };
-    if (facts.prState === 'CLOSED')
-        return { event: 'pr.closed', context: { notMerged: true } };
-    return {
-        event: 'reconcile',
-        context: {
-            prOpen: true,
-            headAvailable: Boolean(facts.headSha),
-            mergeCapable: facts.mergeCapable,
-        },
-    };
-}
-function graphFacts(job, facts) {
-    const input = lifecycleInput(facts);
-    if (input.event !== 'reconcile')
-        return input.context;
-    return {
-        ...input.context,
-        reviewDisabled: job.reviewEnabled === false,
-        implementationComplete: implementationComplete(job),
-        autoMerge: job.autoMerge !== false,
-    };
-}
-/**
- * Historical compatibility only. Normal Job lifecycle is always decided by
- * workflow/job-lifecycle.mmd from the PR fact-derived event.
- */
-function repairHistoricalTerminalState(job, facts) {
-    if (['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'].includes(job.state))
-        return null;
-    if (facts.prState === 'MERGED')
-        applyHistoricalJobCompatibilityRepair(job, 'COMPLETED');
-    else if (facts.prState === 'CLOSED')
-        applyHistoricalJobCompatibilityRepair(job, 'CANCELLED');
-    else
-        return null;
-    return job.state;
-}
+const localFacts = (_job, facts) => ({
+    jobActive: facts.jobActive,
+    implementationComplete: facts.implementationComplete,
+    headAvailable: facts.headAvailable,
+    deliveryReady: facts.deliveryReady,
+});
+/** Local reconciliation cannot invent a completion event; local Git delivery owns it. */
 export function decideJobReconcile(job, facts) {
-    const input = lifecycleInput(facts);
-    return decideJobLifecycle(job, input.event, graphFacts(job, facts));
+    return decideJobLifecycle(job, 'reconcile', localFacts(job, facts));
 }
 export async function dispatchJobReconcile(job, facts, executeEffect, persist) {
-    const repaired = repairHistoricalTerminalState(job, facts);
-    if (repaired) {
-        await persist?.();
-        await executeEffect?.('effect.cancelActiveTasks');
-        return {
-            accepted: true,
-            target: repaired,
-            guard: null,
-            actions: ['effect.cancelActiveTasks'],
-            mutations: [],
-            effects: ['effect.cancelActiveTasks'],
-            reason: 'accepted',
-        };
-    }
-    const input = lifecycleInput(facts);
-    return dispatchJobLifecycle(job, input.event, graphFacts(job, facts), executeEffect, persist);
+    return dispatchJobLifecycle(job, 'reconcile', localFacts(job, facts), executeEffect, persist);
 }

package/dist/workflow/runtime.js

@@ -35,15 +35,30 @@ export function applyTaskMutation(task, mutation) {
     if (mutation === 'mutation.markPlannerUnavailable')
         task.error = 'No objective planner configured';
 }
-export function applyTaskGraphTarget(task, target, timestamp = new Date().toISOString()) { task.state = target; task.updatedAt = timestamp; }
-export function applyJobGraphTarget(job, target, timestamp = new Date().toISOString()) { job.state = target; job.updatedAt = timestamp; }
+export function applyTaskGraphTarget(task, target, timestamp = new Date().toISOString()) {
+    const previous = Date.parse(task.updatedAt), candidate = Date.parse(timestamp);
+    task.state = target;
+    task.updatedAt = Number.isFinite(previous)
+        ? new Date(Math.max(Number.isFinite(candidate) ? candidate : Date.now(), previous + 1)).toISOString()
+        : timestamp;
+}
+export function applyJobGraphTarget(job, target, timestamp = new Date().toISOString()) {
+    const previous = Date.parse(job.updatedAt), candidate = Date.parse(timestamp);
+    job.state = target;
+    job.updatedAt = Number.isFinite(previous)
+        ? new Date(Math.max(Number.isFinite(candidate) ? candidate : Date.now(), previous + 1)).toISOString()
+        : timestamp;
+}
 export function applyTaskWorkflowDecision(task, decision, timestamp = new Date().toISOString()) {
     if (!decision.accepted || !decision.target)
         throw new Error(`Cannot apply rejected workflow decision to task ${task.id}`);
     task.state = decision.target;
     for (const mutation of decision.mutations)
         applyTaskMutation(task, mutation);
-    task.updatedAt = timestamp;
+    const previous = Date.parse(task.updatedAt), candidate = Date.parse(timestamp);
+    task.updatedAt = Number.isFinite(previous)
+        ? new Date(Math.max(Number.isFinite(candidate) ? candidate : Date.now(), previous + 1)).toISOString()
+        : timestamp;
 }
 export function applyJobWorkflowDecision(job, decision, timestamp = new Date().toISOString()) {
     if (!decision.accepted || !decision.target)

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.67",
+  "version": "2.0.69",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "type": "module",
   "bin": {
@@ -9,10 +9,13 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/cli.js dist/relayd.js dist/relayd-main.js",
-    "test": "npm run build && node --test test/*.test.js",
+    "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:publish": "npm run build && node --test --test-concurrency=1 --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",
+    "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/job-lifecycle.mmd

@@ -4,73 +4,32 @@ draft["state: DRAFT"]
 active["state: ACTIVE"]
 completed["state: COMPLETED"]
 cancelled["state: CANCELLED"]
-notMergedDraft["guard: notMerged"]
-notMergedActive["guard: notMerged"]
-autoMergeReview["guard: autoMerge"]
-autoMergeImplementation["guard: autoMerge"]
-prOpenReconcile["guard: prOpen"]
-reviewDisabledReconcile["guard: reviewDisabled"]
-implementationCompleteReconcile["guard: implementationComplete"]
-autoMergeReconcile["guard: autoMerge"]
-headAvailableReconcile["guard: headAvailable"]
-mergeCapableReconcile["guard: mergeCapable"]
-mergeReconcile["action: effect.mergePullRequest"]
-cancelDraftMerge["action: effect.cancelActiveTasks"]
-cancelDraftClose["action: effect.cancelActiveTasks"]
-mergeReview["action: effect.mergePullRequest"]
-mergeImplementation["action: effect.mergePullRequest"]
-cancelActiveMerge["action: effect.cancelActiveTasks"]
-cancelActiveClose["action: effect.cancelActiveTasks"]
-cancelCancelledMerge["action: effect.cancelActiveTasks"]
+
+cancelDraft["action: effect.cancelActiveTasks"]
+cancelActive["action: effect.cancelActiveTasks"]
+localCompletionGuard["guard: localCompletionAllowed"]
+localMergeReadyGuard["guard: localMergeReady"]
+localMergeDelivery["action: effect.deliverLocalMerge"]
 
 draft -->|on: activate| active
-draft -->|on: pr.merged| cancelDraftMerge
-cancelDraftMerge --> completed
 draft -->|on: cancel| cancelDraft
-cancelDraft["action: effect.cancelActiveTasks"]
 cancelDraft --> cancelled
-draft -->|on: pr.closed| notMergedDraft
-notMergedDraft -->|true| cancelDraftClose
-cancelDraftClose --> cancelled
-
-active -->|on: reconcile| prOpenReconcile
-prOpenReconcile -->|true| reviewDisabledReconcile
-prOpenReconcile -->|false| active
-reviewDisabledReconcile -->|true| implementationCompleteReconcile
-reviewDisabledReconcile -->|false| active
-implementationCompleteReconcile -->|true| autoMergeReconcile
-implementationCompleteReconcile -->|false| active
-autoMergeReconcile -->|true| headAvailableReconcile
-autoMergeReconcile -->|false| active
-headAvailableReconcile -->|true| mergeCapableReconcile
-headAvailableReconcile -->|false| active
-mergeCapableReconcile -->|true| mergeReconcile
-mergeCapableReconcile -->|false| active
-mergeReconcile --> active
 
-active -->|on: review.approved| autoMergeReview
-autoMergeReview -->|true| mergeReview
-mergeReview --> active
-active -->|on: implementation.completed| autoMergeImplementation
-autoMergeImplementation -->|true| mergeImplementation
-mergeImplementation --> active
-active -->|on: effect.mergePullRequest.failed| active
-active -->|on: pr.merged| cancelActiveMerge
-cancelActiveMerge --> completed
+active -->|on: reconcile| active
+active -->|on: review.approved| active
+active -->|on: implementation.completed| active
 active -->|on: cancel| cancelActive
-cancelActive["action: effect.cancelActiveTasks"]
 cancelActive --> cancelled
-active -->|on: pr.closed| notMergedActive
-notMergedActive -->|true| cancelActiveClose
-cancelActiveClose --> cancelled
 
-cancelled -->|on: pr.merged| cancelCancelledMerge
-cancelCancelledMerge --> completed
-cancelled -->|on: effect.cancelActiveTasks.failed| cancelled
-completed -->|on: effect.cancelActiveTasks.failed| completed
+active -->|on: local.completed| localCompletionGuard
+localCompletionGuard -->|true| completed
+localCompletionGuard -->|false| active
 
-%% Cleanup eligibility belongs to the lifecycle graph and is retryable after restart.
-cleanupCompletedWorktree["action: effect.cleanupJobWorktree"]
-completed -->|on: pr.merged| cleanupCompletedWorktree
-cleanupCompletedWorktree --> completed
+active -->|on: local.merge.requested| localMergeReadyGuard
+localMergeReadyGuard -->|true| localMergeDelivery
+localMergeDelivery --> active
+localMergeReadyGuard -->|false| active
+active -->|on: effect.deliverLocalMerge.failed| active
+
+cancelled -->|on: effect.cancelActiveTasks.failed| cancelled
 completed -->|on: effect.cleanupJobWorktree.failed| completed

package/workflow/review-lifecycle.mmd

@@ -10,7 +10,6 @@ stale["state: STALE"]
 
 unscheduledNone["guard: unscheduled"]
 reviewEnabledNone["guard: reviewEnabled"]
-prOpenNone["guard: prOpen"]
 jobActiveNone["guard: jobActive"]
 implementationCompleteNone["guard: implementationComplete"]
 headAvailableNone["guard: headAvailable"]
@@ -19,7 +18,6 @@ noActiveReviewNone["guard: noActiveReviewTask"]
 noApprovedReviewNone["guard: noApprovedCurrentReview"]
 unscheduledStale["guard: unscheduled"]
 reviewEnabledStale["guard: reviewEnabled"]
-prOpenStale["guard: prOpen"]
 jobActiveStale["guard: jobActive"]
 implementationCompleteStale["guard: implementationComplete"]
 headAvailableStale["guard: headAvailable"]
@@ -41,16 +39,15 @@ 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"]
 
 none -->|on: reconcile| unscheduledNone
 unscheduledNone -->|true| reviewEnabledNone
 unscheduledNone -->|false| none
-reviewEnabledNone -->|true| prOpenNone
+reviewEnabledNone -->|true| jobActiveNone
 reviewEnabledNone -->|false| none
-prOpenNone -->|true| jobActiveNone
-prOpenNone -->|false| none
 jobActiveNone -->|true| implementationCompleteNone
 jobActiveNone -->|false| none
 implementationCompleteNone -->|true| headAvailableNone
@@ -68,10 +65,8 @@ createNone --> pending
 stale -->|on: reconcile| unscheduledStale
 unscheduledStale -->|true| reviewEnabledStale
 unscheduledStale -->|false| stale
-reviewEnabledStale -->|true| prOpenStale
+reviewEnabledStale -->|true| jobActiveStale
 reviewEnabledStale -->|false| stale
-prOpenStale -->|true| jobActiveStale
-prOpenStale -->|false| stale
 jobActiveStale -->|true| implementationCompleteStale
 jobActiveStale -->|false| stale
 implementationCompleteStale -->|true| headAvailableStale
@@ -111,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