agents-relay 2.0.162 → 2.0.163

package/dist/cli-help.js

@@ -173,7 +173,7 @@ Required: --task-id ID and the normal Job storage options.`,
 Agent submit: agents-relay plan apply --repo OWNER/REPO --pr PR_NUMBER --id JOB_ID --plan-id PLAN_ID --execution-id EXECUTION_ID --file plan.json. Validation errors reject without partial task writes and can be corrected inside the same Planner execution.
 
 Required: --repo OWNER/REPO, --pr NUMBER, and --id JOB_ID.
-Optional: --prompt TEXT or --prompt-file PATH|- (mutually exclusive). The prompt is additional guidance for this planning round and never replaces the durable Job objective. --force-clean-history asks Planner to inspect authoritative failed Tasks, decide whether evidence supports superseded/invalid classification or cancellation of a failed review, and apply selected changes through guarded task commands before submitting the Plan. Tasks without sufficient evidence remain unresolved. The durable Plan records the cleanup assessment, and plan apply remains the required receipt. Text responses are never applied as a Plan; unknown execution outcomes are not classified without proof.
+Optional: --prompt TEXT or --prompt-file PATH|- (mutually exclusive). The prompt is additional guidance for this planning round and never replaces the durable Job objective. --force-restate asks Planner to propose evidence-backed dispositions for failed Tasks inside the Plan. Plan apply validates hypothetical history and forward convergence before one atomic SQLite commit; validation errors leave all SQLite state unchanged and can be corrected in the same Planner execution. Unknown execution outcomes remain unresolved without proof. Text responses are never applied as a Plan.
 
 The command persists one real plan-N round, materializes validated next_tasks with planner provenance, and wakes normal reconciliation. It works for zero-task DRAFT Jobs. Historical planner-N rounds remain readable, but new rounds use plan-N.
 

package/dist/cli.js

@@ -714,7 +714,11 @@ async function main() {
                 console.log(JSON.stringify(await reconciler.applyPlannerTree(jobId, planId, executionId, proposal), null, 2));
             }
             catch (error) {
-                console.error(JSON.stringify({ ok: false, code: 'PLAN_APPLY_REJECTED', message: error instanceof Error ? error.message : String(error) }));
+                if (error && typeof error === 'object' && 'code' in error && error.code === 'PLAN_APPLY_VALIDATION_FAILED' && 'phase' in error && 'issues' in error) {
+                    console.error(JSON.stringify({ ok: false, code: error.code, phase: error.phase, retryable: 'retryable' in error ? error.retryable : true, issues: error.issues }));
+                }
+                else
+                    console.error(JSON.stringify({ ok: false, code: 'PLAN_APPLY_REJECTED', message: error instanceof Error ? error.message : String(error) }));
                 process.exitCode = 1;
             }
             finally {
@@ -806,7 +810,7 @@ async function main() {
             throw new Error(`${command} requires --repo and --id`);
         if (command === 'plan') {
             const guidance = hasArg(args, '--prompt') || hasArg(args, '--prompt-file') ? await textOption(args, '--prompt', '--prompt-file') : undefined;
-            console.log(JSON.stringify(await relayControlCommand(args, { command: 'job.plan', jobId, ...(guidance?.trim() ? { guidance: guidance.trim() } : {}), forceCleanHistory: hasArg(args, '--force-clean-history') }), null, 2));
+            console.log(JSON.stringify(await relayControlCommand(args, { command: 'job.plan', jobId, ...(guidance?.trim() ? { guidance: guidance.trim() } : {}), forceRestate: hasArg(args, '--force-restate') }), null, 2));
             return;
         }
         if (command === 'reconcile') {
@@ -835,7 +839,7 @@ async function main() {
         await withEventBus(args, async (bus) => {
             const reconciler = runtime(store, args, bus);
             try {
-                const result = await reconciler.planJob(job.id, guidance?.trim() || undefined, hasArg(args, '--force-clean-history'));
+                const result = await reconciler.planJob(job.id, guidance?.trim() || undefined, hasArg(args, '--force-restate'));
                 await saveLocal(localFile, result.job);
                 await publishWake(bus, result.job, result.round.id, `Planning round ${result.round.id} completed`);
                 console.log(JSON.stringify(result.round, null, 2));

package/dist/force-restate-validation.js

@@ -0,0 +1,117 @@
+import { classifyTaskResolution } from './workflow/task-resolution.js';
+import { tryTransitionTaskEvent } from './scheduler.js';
+import { satisfiesWorker } from './worker-routing.js';
+function dependencySatisfied(task, byId) {
+    return task.dependencies.every(id => {
+        const dependency = byId.get(id);
+        return dependency?.state === 'SUCCEEDED'
+            || (dependency?.resolutionClassification?.kind === 'superseded'
+                && byId.get(dependency.resolutionClassification.targetTaskId)?.state === 'SUCCEEDED');
+    });
+}
+function eligibleWorkerRoute(task, candidates) {
+    if (!['codex', 'chatgpt'].includes(task.adapter))
+        return false;
+    const required = task.workerRequirements?.capabilities ?? task.capabilities;
+    if (task.workerSelection) {
+        if (task.workerSelection.adapter !== task.adapter
+            || required.some(capability => !task.workerSelection.capabilities.includes(capability)))
+            return false;
+        const selected = candidates?.find(candidate => candidate.adapter === task.adapter && candidate.workerId === task.workerSelection.workerId);
+        return Boolean(selected && satisfiesWorker(selected, task.workerRequirements ?? { capabilities: required }, { strictCapabilities: true }));
+    }
+    return Boolean(candidates?.some(candidate => candidate.adapter === task.adapter
+        && satisfiesWorker(candidate, task.workerRequirements ?? { capabilities: required })));
+}
+function runnable(task, byId, candidates) {
+    return ['QUEUED', 'RUNNING'].includes(task.state)
+        && dependencySatisfied(task, byId)
+        && eligibleWorkerRoute(task, candidates)
+        && (task.state !== 'RUNNING' || Boolean(task.executionId && task.leaseOwner));
+}
+function dependencyWaiting(task, byId, candidates, visiting = new Set()) {
+    if (task.state !== 'DRAFT' || task.dependencies.length === 0 || visiting.has(task.id))
+        return false;
+    visiting.add(task.id);
+    const accounted = task.dependencies.every(id => {
+        const dependency = byId.get(id);
+        if (!dependency)
+            return false;
+        if (dependency.state === 'SUCCEEDED')
+            return true;
+        if (dependency.resolutionClassification?.kind === 'superseded'
+            && byId.get(dependency.resolutionClassification.targetTaskId)?.state === 'SUCCEEDED')
+            return true;
+        return runnable(dependency, byId, candidates) || dependencyWaiting(dependency, byId, candidates, visiting);
+    });
+    visiting.delete(task.id);
+    return accounted;
+}
+export function forceRestateRunnable(job, candidates) {
+    const byId = new Map(job.tasks.map(task => [task.id, task]));
+    return job.tasks.some(task => task.kind !== 'planner' && runnable(task, byId, candidates));
+}
+export function forceRestateDependencyWaiting(job, candidates) {
+    const byId = new Map(job.tasks.map(task => [task.id, task]));
+    return job.tasks.some(task => task.kind !== 'planner' && dependencyWaiting(task, byId, candidates));
+}
+export function forceRestateBlocked(job, planId) {
+    if (!planId)
+        return false;
+    return job.tasks.some(task => task.agentName === 'troubleshooter' && task.recoveryPlanId === planId && task.state === 'BLOCKED'
+        && typeof task.error === 'string' && task.error.trim().length > 0
+        && typeof task.result?.data?.evidence === 'string' && task.result.data.evidence.trim().length > 0
+        && typeof task.result?.data?.unblock_conditions === 'string' && task.result.data.unblock_conditions.trim().length > 0);
+}
+export function forceRestateConverged(job, planId, candidates) {
+    const completed = job.state === 'COMPLETED'
+        && job.tasks.every(task => task.kind === 'planner' || !['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED'].includes(task.state));
+    return completed || forceRestateRunnable(job, candidates) || forceRestateDependencyWaiting(job, candidates) || forceRestateBlocked(job, planId);
+}
+/** Apply Planner-proposed history dispositions to a private candidate snapshot.
+ * The caller invokes this before the storage mutator returns the candidate. */
+export function applyPlannerHistoryCleanup(job, expectedTaskIds, cleanup, now) {
+    const issues = [];
+    const expected = new Set(expectedTaskIds);
+    if (cleanup.length !== expected.size || cleanup.some(item => !expected.delete(item.taskId)) || expected.size) {
+        issues.push(`Provide exactly one history_cleanup disposition for each snapshotted failed Task: ${expectedTaskIds.join(', ') || '(none)'}.`);
+        return { valid: false, issues };
+    }
+    for (const item of cleanup) {
+        const task = job.tasks.find(candidate => candidate.id === item.taskId);
+        if (!task || task.kind === 'planner' || task.state !== 'FAILED' || task.resolutionClassification) {
+            issues.push(`Task ${item.taskId} changed since Force Restate began; reload the Planner context and revise this disposition.`);
+            continue;
+        }
+        if (task.failureReason === 'worker_outcome_unknown' && item.outcome !== 'unresolved') {
+            issues.push(`Task ${item.taskId} has an unknown execution outcome. Keep it unresolved until durable evidence proves the outcome.`);
+            continue;
+        }
+        if (item.outcome === 'unresolved')
+            continue;
+        if (item.outcome === 'cancelled_review') {
+            if (task.agentName !== 'reviewer' || !tryTransitionTaskEvent(task, 'cancel').accepted) {
+                issues.push(`Task ${item.taskId} cannot be cancelled as a failed review. Only a FAILED reviewer Task can use cancelled_review.`);
+                continue;
+            }
+            task.error = `Cancelled by Force Restate: ${item.reason}`;
+            task.leaseOwner = null;
+            task.leaseExpiresAt = null;
+            task.executionId = null;
+            task.updatedAt = now;
+            continue;
+        }
+        const target = item.targetTaskId ? job.tasks.find(candidate => candidate.id === item.targetTaskId) : undefined;
+        if (!target || target.state !== 'SUCCEEDED') {
+            issues.push(`Task ${item.taskId} classification target ${item.targetTaskId ?? '(missing)'} must be an existing SUCCEEDED Task.`);
+            continue;
+        }
+        try {
+            classifyTaskResolution(task, { kind: item.outcome, targetTaskId: item.targetTaskId, evidence: item.evidence, reason: item.reason }, now);
+        }
+        catch (error) {
+            issues.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return issues.length ? { valid: false, issues } : { valid: true };
+}

package/dist/force-restate.js

@@ -0,0 +1,6 @@
+import { executeManualPlan } from './manual-plan.js';
+/** Force Restate is selected by the planning graph; its history and forward
+ * convergence guards run inside the atomic Plan Apply action. */
+export async function executeForceRestate(input) {
+    return executeManualPlan(input.store, input.jobId, input.guidance, input.timeoutMs, input.launchPlanner, true);
+}

package/dist/manual-plan.js

@@ -1,9 +1,9 @@
 import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
 import { createPlanRound, pendingPlan } from './planner.js';
 import { applyJobActivateAction } from './job-actions.js';
-export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner, forceCleanHistory = false) {
-    if (forceCleanHistory && !store.mutateJob)
-        throw new Error('--force-clean-history requires atomic durable SQLite mutations');
+export async function executeManualPlan(store, jobId, guidance, timeoutMs, launchPlanner, forceRestate = false) {
+    if (forceRestate && !store.mutateJob)
+        throw new Error('--force-restate requires atomic durable SQLite mutations');
     let job = await store.load(jobId);
     if (['COMPLETED', 'CANCELLED'].includes(job.state))
         throw new Error(`Cannot plan terminal job ${job.id} (${job.state})`);
@@ -20,8 +20,8 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
             if (current.pause)
                 throw new Error(`Cannot plan paused Job ${current.id}; resume it first`);
             const concurrent = pendingPlan(current);
-            if (forceCleanHistory && concurrent)
-                throw new Error(`--force-clean-history requires no pending Plan (${concurrent.id})`);
+            if (forceRestate && concurrent)
+                throw new Error(`--force-restate requires no pending Plan (${concurrent.id})`);
             if (concurrent) {
                 if (concurrent.executionId)
                     throw new Error(`Planning round ${concurrent.id} is already PLANNING`);
@@ -29,9 +29,9 @@ export async function executeManualPlan(store, jobId, guidance, timeoutMs, launc
             }
             else {
                 round = createPlanRound(current, { guidance, manual: true, timeoutMs });
-                if (forceCleanHistory) {
-                    round.forceCleanHistory = true;
-                    round.cleanHistoryTaskIds = current.tasks.filter(task => task.kind !== 'planner' && task.state === 'FAILED' && !task.resolutionClassification).map(task => task.id);
+                if (forceRestate) {
+                    round.forceRestate = true;
+                    round.restateTaskIds = current.tasks.filter(task => task.kind !== 'planner' && task.state === 'FAILED' && !task.resolutionClassification).map(task => task.id);
                 }
                 current.plans = [...(current.plans ?? []), structuredClone(round)].sort((a, b) => a.round - b.round);
             }

package/dist/planner-runtime.js

@@ -9,6 +9,39 @@ import { dispatchJobLifecycleSync } from './workflow/lifecycle.js';
 import { withExecutionBoundary } from './reconciler-runtime.js';
 import { storySizeTimeoutMs } from './types.js';
 import { tryTransitionTaskEvent } from './scheduler.js';
+import { applyPlannerHistoryCleanup, forceRestateConverged } from './force-restate-validation.js';
+import { decideForceRestateValidation } from './workflow/force-restate-validation-v2.js';
+import { workerCandidates } from './worker-routing.js';
+import { createHash } from 'node:crypto';
+export class PlannerApplyValidationError extends Error {
+    phase;
+    issues;
+    retryable;
+    code = 'PLAN_APPLY_VALIDATION_FAILED';
+    constructor(phase, issues, retryable = phase !== 'fencing') {
+        super(JSON.stringify({ code: 'PLAN_APPLY_VALIDATION_FAILED', phase, retryable, issues }));
+        this.phase = phase;
+        this.issues = issues;
+        this.retryable = retryable;
+        this.name = 'PlannerApplyValidationError';
+    }
+}
+function candidateFingerprint(result) {
+    return createHash('sha256').update(JSON.stringify(result)).digest('hex');
+}
+function durableJobVersion(job) {
+    const normalize = (value) => {
+        if (Array.isArray(value))
+            return value.map(normalize);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, normalize(child)]));
+        return value;
+    };
+    const snapshot = Object.fromEntries(Object.entries(job).filter(([key]) => key !== 'updatedAt'));
+    // updatedAt is a display timestamp and can advance on heartbeat/reconcile
+    // writes with no state change. The normalized content hash is the version.
+    return createHash('sha256').update(JSON.stringify(normalize(snapshot))).digest('hex');
+}
 /** Activate queued planner work inside the same authoritative SQLite mutation. */
 export function activateCommittedPlannerWork(job) {
     if (job.state !== 'DRAFT' || !job.tasks.some(item => item.state === 'QUEUED'))
@@ -65,12 +98,24 @@ export async function retryPendingPlannerUnblocks(ports, jobId) {
 }
 export async function finishPlanner(ports, jobId, planId, executionId, error, raw, cliApply = false) {
     const live = ports.live.get(planId);
-    if (live?.executionId === executionId)
-        clearTimeout(live.timer);
-    const releaseLive = () => { if (ports.live.get(planId)?.executionId === executionId)
-        ports.live.delete(planId); };
+    const releaseLive = () => {
+        const current = ports.live.get(planId);
+        if (current?.executionId !== executionId)
+            return;
+        clearTimeout(current.timer);
+        ports.live.delete(planId);
+    };
     const job = await ports.store.load(jobId);
     const plan = (job.plans ?? []).find(item => item.id === planId);
+    if (plan?.status === 'SUCCEEDED' && plan.appliedExecutionId === executionId && raw && !raw.cliApplied) {
+        const repeated = parsePlannerResult(raw);
+        if (candidateFingerprint(repeated) !== plan.appliedCandidateFingerprint) {
+            releaseLive();
+            throw new Error(`Plan ${planId} already committed a different candidate for execution ${executionId}`);
+        }
+        releaseLive();
+        return;
+    }
     if (!plan || (plan.executionId !== executionId && !(raw?.cliApplied && plan.status === 'SUCCEEDED'))) {
         releaseLive();
         if (cliApply)
@@ -136,29 +181,12 @@ export async function finishPlanner(ports, jobId, planId, executionId, error, ra
     let planCommitted = false;
     try {
         const parsed = parsePlannerResult(raw);
-        if (plan.forceCleanHistory) {
-            const cleanup = parsed.history_cleanup ?? [];
-            const expected = new Set(plan.cleanHistoryTaskIds ?? []);
-            if (cleanup.length !== expected.size || cleanup.some(item => !expected.delete(item.taskId)) || expected.size)
-                throw new Error('--force-clean-history requires exactly one Planner disposition for each failed Task in its durable snapshot');
-            for (const item of cleanup) {
-                const task = job.tasks.find(candidate => candidate.id === item.taskId);
-                if (!task)
-                    throw new Error(`Clean history Task ${item.taskId} disappeared`);
-                if (task.failureReason === 'worker_outcome_unknown' && item.outcome !== 'unresolved')
-                    throw new Error(`Unknown execution outcome for ${item.taskId} must remain unresolved without graph-verified proof`);
-                if ((item.outcome === 'superseded' || item.outcome === 'invalid') && (task.resolutionClassification?.kind !== item.outcome || task.resolutionClassification.targetTaskId !== item.targetTaskId || task.resolutionClassification.evidence !== item.evidence || task.resolutionClassification.reason !== item.reason))
-                    throw new Error(`Clean history classification for ${item.taskId} was not applied through task classify with matching evidence`);
-                if (item.outcome === 'cancelled_review' && (task.agentName !== 'reviewer' || task.state !== 'CANCELLED'))
-                    throw new Error(`Failed review ${item.taskId} must be cancelled through task cancel before Plan apply`);
-                if (item.outcome === 'unresolved' && (task.state !== 'FAILED' || task.resolutionClassification))
-                    throw new Error(`Unresolved history item ${item.taskId} changed after Planner assessment`);
-            }
-        }
+        const historyCleanup = parsed.history_cleanup ?? [];
         const result = assignPlannerTaskIds(parsed, job.repository, job.id, plan.id);
         const executionContext = await ports.plannerContext(job, plan);
         validatePlannerHierarchy(job.tasks, result.next_tasks);
-        validatePlannerResolutionMaterialization(job.tasks, result.next_tasks);
+        if (!plan.forceRestate)
+            validatePlannerResolutionMaterialization(job.tasks, result.next_tasks);
         validatePlannerLifecycleOwnership(job, result.next_tasks);
         validatePlannerProgress(job, result);
         if (result.unblocks.length > 0 && !ports.store.registerBlockerDependent)
@@ -170,97 +198,95 @@ export async function finishPlanner(ports, jobId, planId, executionId, error, ra
                 throw new Error(`Planner child ${child.id} already exists with a different definition`);
         }
         const now = new Date().toISOString();
-        if (ports.store.mutateJob) {
-            let committedPlan = false;
-            const committed = await ports.store.mutateJob(job.id, current => {
-                const durablePlan = (current.plans ?? []).find(item => item.id === plan.id);
-                if (!durablePlan || durablePlan.status !== 'PLANNING' || durablePlan.executionId !== executionId)
-                    return current;
-                durablePlan.status = 'SUCCEEDED';
-                durablePlan.objectiveStatus = result.objective_status;
-                durablePlan.plannerResult = result;
-                durablePlan.assessment = result.assessment;
-                durablePlan.generatedTaskIds = result.next_tasks.map(item => item.id);
-                durablePlan.pendingUnblocks = result.unblocks.length > 0 ? structuredClone(result.unblocks) : undefined;
-                durablePlan.error = undefined;
-                durablePlan.retryFeedback = undefined;
-                durablePlan.leaseOwner = null;
-                durablePlan.leaseExpiresAt = null;
-                durablePlan.executionId = null;
-                durablePlan.updatedAt = now;
-                if (current.changeCycle && !current.changeCycle.consumedByPlannerTaskId && durablePlan.trigger.source === 'unblock') {
-                    current.changeCycle.consumedByPlannerTaskId = durablePlan.id;
-                }
-                for (const child of children) {
-                    const spec = result.next_tasks.find(item => item.id === child.id);
-                    if (spec?.resolution)
-                        attachResolutionOwnership(current, child, spec.resolution, 'planner');
-                    const existing = current.tasks.find(item => item.id === child.id);
-                    if (!existing)
-                        current.tasks.push(structuredClone(child));
-                    else if (!samePlannerChildDefinition(existing, child))
-                        throw new Error(`Planner child ${child.id} already exists with a different definition`);
+        if (!ports.store.mutateJob)
+            throw new Error('Plan apply requires one atomic durable SQLite mutation');
+        const routeCandidates = workerCandidates(ports.options.adapters, await ports.store.listAgents());
+        const expectedJobVersion = durableJobVersion(job);
+        const committed = await ports.store.mutateJob(job.id, current => {
+            const durablePlan = (current.plans ?? []).find(item => item.id === plan.id);
+            const changedKeys = Object.keys({ ...job, ...current }).filter(key => key !== 'updatedAt' && JSON.stringify(job[key]) !== JSON.stringify(current[key]));
+            if (!durablePlan || durablePlan.status !== 'PLANNING' || durablePlan.executionId !== executionId
+                || durablePlan.updatedAt !== plan.updatedAt || durableJobVersion(current) !== expectedJobVersion) {
+                throw new PlannerApplyValidationError('fencing', [`The Job or Planner execution changed while this candidate was being validated (plan=${Boolean(durablePlan)}, status=${durablePlan?.status ?? 'missing'}, execution=${durablePlan?.executionId === executionId}, planVersion=${durablePlan?.updatedAt === plan.updatedAt}, jobVersion=${durableJobVersion(current) === expectedJobVersion}, changed=${changedKeys.join(',')}). Refresh the Planner context and retry with the active execution.`,], durablePlan?.status === 'PLANNING' && durablePlan.executionId === executionId);
+            }
+            const candidate = structuredClone(current);
+            const candidatePlan = (candidate.plans ?? []).find(item => item.id === plan.id);
+            const history = candidatePlan.forceRestate
+                ? applyPlannerHistoryCleanup(candidate, candidatePlan.restateTaskIds ?? [], historyCleanup, now)
+                : (historyCleanup.length ? { valid: false, issues: ['history_cleanup is only allowed for a Force Restate Plan. Remove it and submit the Plan again.'] } : { valid: true });
+            if (history.valid && candidatePlan.forceRestate) {
+                try {
+                    validatePlannerResolutionMaterialization(candidate.tasks, result.next_tasks);
                 }
-                const consumedUnblocks = new Set(durablePlan.trigger.source === 'unblock' ? durablePlan.trigger.taskIds ?? [] : []);
-                for (const task of current.tasks) {
-                    if (!consumedUnblocks.has(task.id) || !task.unblock || task.state === 'CANCELLED' || durablePlan.generatedTaskIds.includes(task.id))
-                        continue;
-                    if (tryTransitionTaskEvent(task, 'cancel').accepted) {
-                        task.error = `Superseded by successful unblock plan ${durablePlan.id}`;
-                        task.leaseOwner = null;
-                        task.leaseExpiresAt = null;
-                        task.executionId = null;
-                    }
+                catch (error) {
+                    throw new PlannerApplyValidationError('history_consistency', [error instanceof Error ? error.message : String(error)]);
                 }
-                // Planner children are committed atomically with Job activation.
-                // Otherwise the DRAFT Job is invisible to the ACTIVE-only dispatcher.
-                activateCommittedPlannerWork(current);
-                current.updatedAt = now;
-                committedPlan = true;
-                return current;
-            });
-            Object.assign(job, structuredClone(committed));
-            if (!committedPlan) {
-                releaseLive();
-                return;
             }
-        }
-        else {
-            plan.status = 'SUCCEEDED';
-            plan.objectiveStatus = result.objective_status;
-            plan.plannerResult = result;
-            plan.assessment = result.assessment;
-            plan.generatedTaskIds = result.next_tasks.map(item => item.id);
-            plan.pendingUnblocks = result.unblocks.length > 0 ? structuredClone(result.unblocks) : undefined;
-            plan.error = undefined;
-            plan.retryFeedback = undefined;
-            plan.leaseOwner = null;
-            plan.leaseExpiresAt = null;
-            plan.executionId = null;
-            plan.updatedAt = now;
-            await ports.store.savePlan(plan);
-            if (job.changeCycle && !job.changeCycle.consumedByPlannerTaskId && plan.trigger.source === 'unblock') {
-                job.changeCycle.consumedByPlannerTaskId = plan.id;
-                job.updatedAt = now;
-                await ports.store.saveJob(job);
+            candidatePlan.status = 'SUCCEEDED';
+            candidatePlan.objectiveStatus = result.objective_status;
+            candidatePlan.plannerResult = result;
+            candidatePlan.appliedCandidateFingerprint = candidateFingerprint(parsed);
+            candidatePlan.assessment = result.assessment;
+            candidatePlan.generatedTaskIds = result.next_tasks.map(item => item.id);
+            candidatePlan.pendingUnblocks = result.unblocks.length > 0 ? structuredClone(result.unblocks) : undefined;
+            candidatePlan.error = undefined;
+            candidatePlan.retryFeedback = undefined;
+            candidatePlan.leaseOwner = null;
+            candidatePlan.leaseExpiresAt = null;
+            candidatePlan.executionId = null;
+            candidatePlan.appliedExecutionId = executionId ?? undefined;
+            candidatePlan.updatedAt = now;
+            if (candidate.changeCycle && !candidate.changeCycle.consumedByPlannerTaskId && candidatePlan.trigger.source === 'unblock') {
+                candidate.changeCycle.consumedByPlannerTaskId = candidatePlan.id;
+            }
+            for (const child of children) {
+                const spec = result.next_tasks.find(item => item.id === child.id);
+                if (spec?.resolution)
+                    attachResolutionOwnership(candidate, child, spec.resolution, 'planner');
+                const existing = candidate.tasks.find(item => item.id === child.id);
+                if (!existing)
+                    candidate.tasks.push(structuredClone(child));
+                else if (!samePlannerChildDefinition(existing, child))
+                    throw new Error(`Planner child ${child.id} already exists with a different definition`);
             }
-            const consumedUnblocks = new Set(plan.trigger.source === 'unblock' ? plan.trigger.taskIds ?? [] : []);
-            for (const task of job.tasks) {
-                if (!consumedUnblocks.has(task.id) || !task.unblock || task.state === 'CANCELLED' || plan.generatedTaskIds.includes(task.id))
+            const consumedUnblocks = new Set(candidatePlan.trigger.source === 'unblock' ? candidatePlan.trigger.taskIds ?? [] : []);
+            for (const task of candidate.tasks) {
+                if (!consumedUnblocks.has(task.id) || !task.unblock || task.state === 'CANCELLED' || candidatePlan.generatedTaskIds.includes(task.id))
                     continue;
                 if (tryTransitionTaskEvent(task, 'cancel').accepted) {
-                    task.error = `Superseded by successful unblock plan ${plan.id}`;
-                    await ports.store.saveTask(task);
+                    task.error = `Superseded by successful unblock plan ${candidatePlan.id}`;
+                    task.leaseOwner = null;
+                    task.leaseExpiresAt = null;
+                    task.executionId = null;
                 }
             }
-            for (const child of children)
-                if (!job.tasks.some(item => item.id === child.id)) {
-                    const spec = result.next_tasks.find(item => item.id === child.id);
-                    if (spec?.resolution)
-                        await ports.store.saveTask(attachResolutionOwnership(job, child, spec.resolution, 'planner'));
-                    await ports.store.appendTask(child);
-                }
-        }
+            activateCommittedPlannerWork(candidate);
+            candidate.updatedAt = now;
+            const forwardValid = forceRestateConverged(candidate, candidatePlan.id, routeCandidates);
+            const decision = decideForceRestateValidation({
+                forceRestateRequested: candidatePlan.forceRestate === true,
+                historyConsistencyValid: history.valid,
+                normalHistoryMutationAbsent: !candidatePlan.forceRestate && historyCleanup.length === 0,
+                forwardConvergenceValid: forwardValid,
+            });
+            if (!decision.accepted) {
+                throw new PlannerApplyValidationError('forward_convergence', [`Plan Apply graph rejected the candidate: ${decision.reason}.`]);
+            }
+            if (decision.target === 'rejected') {
+                const historyRejected = decision.actions.some(action => action.id === 'plan.apply.rejectHistory');
+                const issues = historyRejected && history.valid === false ? history.issues : [
+                    'The proposed Plan does not converge to executable, dependency-accounted work, an evidence-backed blocked Troubleshooter owned by this Plan, or a completed Job.',
+                    'Add a queued/running Task with an eligible worker route, make each dependency path lead to eligible work, provide the Troubleshooter evidence and unblock conditions, or preserve verified completion.',
+                    `Candidate work: ${candidate.tasks.filter(task => task.kind !== 'planner').map(task => `${task.id}:${task.state}/${task.adapter}${task.dependencies.length ? ` deps=${task.dependencies.join(',')}` : ''}`).join('; ') || '(none)'}. Eligible worker adapters: ${[...new Set(routeCandidates.map(item => item.adapter))].join(', ') || '(none)'}.`,
+                ];
+                throw new PlannerApplyValidationError(historyRejected ? 'history_consistency' : 'forward_convergence', issues);
+            }
+            if (!decision.actions.some(action => action.id === 'plan.apply.commit')) {
+                throw new PlannerApplyValidationError('forward_convergence', ['The Plan Apply graph did not select the atomic commit action.']);
+            }
+            return candidate;
+        });
+        Object.assign(job, structuredClone(committed));
         planCommitted = true;
         // Cross-Job registrations cannot join this Job's SQLite transaction. The
         // committed Plan keeps replay intent until each external registration is
@@ -273,17 +299,22 @@ export async function finishPlanner(ports, jobId, planId, executionId, error, ra
             releaseLive();
             throw caught;
         }
-        if (cliApply)
+        if (caught instanceof PlannerApplyValidationError) {
+            if (!(cliApply && caught.retryable))
+                releaseLive();
             throw caught;
-        await failOrRetry(caught instanceof Error ? caught.message : String(caught));
-        releaseLive();
-        return;
+        }
+        const message = caught instanceof Error ? caught.message : String(caught);
+        const validationError = new PlannerApplyValidationError('candidate', [message, 'Correct the candidate and retry plan apply with the same active Planner execution.']);
+        if (!(cliApply && validationError.retryable))
+            releaseLive();
+        throw validationError;
     }
     releaseLive();
     if (!plan.manualPlanning)
         ports.detach(ports.reconcile(jobId), jobId, plan.id, 'planner follow-up reconciliation');
 }
-export async function launchPlanExecution(ports, job, plan) {
+export async function launchPlanExecution(ports, job, plan, waitForCompletion = false) {
     const planner = ports.options.planner;
     if (!planner) {
         let failed = false;
@@ -348,17 +379,33 @@ export async function launchPlanExecution(ports, job, plan) {
     const controller = new AbortController();
     const executionId = plan.executionId;
     const timeoutMs = plan.timeoutMs ?? ports.options.plannerTimeoutMs ?? storySizeTimeoutMs('M');
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const timer = setTimeout(() => {
+        controller.abort();
+        if (ports.live.get(plan.id)?.executionId === executionId)
+            ports.live.delete(plan.id);
+    }, timeoutMs);
     ports.live.set(plan.id, { executionId, controller, timer });
     let promise;
     try {
         const executionContext = await ports.plannerContext(job, plan);
-        const context = { planExecution: { planId: plan.id, executionId }, forceCleanHistory: plan.forceCleanHistory, cleanHistoryTaskIds: plan.cleanHistoryTaskIds, job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
+        const context = { planExecution: { planId: plan.id, executionId }, forceRestate: plan.forceRestate, restateTaskIds: plan.restateTaskIds, job, tasks: job.tasks, objective: job.objective ?? job.description ?? job.title, previousPlannerTaskId: plan.previousPlanId, trigger: plan.trigger, executionContext, retryFeedback: plan.retryFeedback, guidance: plan.guidance };
         promise = planner.plan(context, controller.signal);
     }
     catch (error) {
         await finishPlanner(ports, job.id, plan.id, executionId, error instanceof Error ? error : new Error(String(error)));
         return;
     }
+    if (waitForCompletion) {
+        let result;
+        try {
+            result = await promise;
+        }
+        catch (error) {
+            await finishPlanner(ports, job.id, plan.id, executionId, error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        await finishPlanner(ports, job.id, plan.id, executionId, null, result);
+        return;
+    }
     ports.detach(promise.then(result => finishPlanner(ports, job.id, plan.id, executionId, null, result), error => finishPlanner(ports, job.id, plan.id, executionId, error instanceof Error ? error : new Error(String(error)))), job.id, plan.id, 'planner completion');
 }

package/dist/planner.js

@@ -424,8 +424,8 @@ export function plannerInput(context) {
         apply_cli: context.planExecution ? `agents-relay plan apply --repo ${context.job.repository} --pr ${context.job.prNumber} --id ${context.job.id} --plan-id ${context.planExecution.planId} --execution-id ${context.planExecution.executionId} --file PATH` : undefined,
         plan_execution: context.planExecution, retry_feedback: context.retryFeedback,
         caller_prompt: context.guidance,
-        force_clean_history: context.forceCleanHistory === true,
-        clean_history_task_ids: context.cleanHistoryTaskIds ?? [],
+        force_restate: context.forceRestate === true,
+        restate_task_ids: context.restateTaskIds ?? [],
         previous_planner_task_id: context.previousPlannerTaskId,
         plan_trigger: context.trigger,
         legacy_change_cycle: context.job.changeCycle,

package/dist/reconciler.js

@@ -20,6 +20,7 @@ import { retryPendingPlannerUnblocks } from './planner-runtime.js';
 import { dispatchPlannerOrchestration, plannerOrchestrationFacts } from './workflow/planner-orchestration-v2.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { ReconcilerReviewBase } from './reconciler-review.js';
+import { executeForceRestate } from './force-restate.js';
 import { recordThreadDelivery, resolveImplementationTaskThreadDestination, prepareReviewerThreadDelivery, resolveReviewerThreadDestination } from './reviewer-thread.js';
 import { executeManualPlan } from './manual-plan.js';
 import { executionEventSource, withExecutionBoundary } from './reconciler-runtime.js';
@@ -193,7 +194,7 @@ export class Reconciler extends ReconcilerReviewBase {
                 await this.ensureFinalReview(scheduled, headSha);
                 scheduled = schedule(await this.store.load(jobId));
             }
-            if (scheduled.executionMode === 'autonomous') {
+            if (scheduled.executionMode === 'autonomous' || (scheduled.plans ?? []).some(plan => plan.forceRestate && plan.status === 'FAILED')) {
                 scheduled = schedule(await this.maybeCreatePlanner(scheduled));
             }
             if (scheduled.state !== previousState || scheduled.updatedAt !== job.updatedAt)
@@ -273,8 +274,12 @@ export class Reconciler extends ReconcilerReviewBase {
         }
         return this.store.load(jobId);
     }
-    async planJob(jobId, guidance, forceCleanHistory = false) {
-        return executeManualPlan(this.store, jobId, guidance, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), (job, plan) => this.launchPlanner(job, plan), forceCleanHistory);
+    async planJob(jobId, guidance, forceRestate = false) {
+        if (forceRestate)
+            return executeForceRestate({ store: this.store, jobId, guidance,
+                timeoutMs: this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'),
+                launchPlanner: (job, plan) => this.launchPlanner(job, plan, true) });
+        return executeManualPlan(this.store, jobId, guidance, this.options.plannerTimeoutMs ?? storySizeTimeoutMs('M'), (job, plan) => this.launchPlanner(job, plan, true));
     }
     async maybeCreatePlanner(job) {
         const pending = pendingPlan(job);
@@ -430,9 +435,6 @@ export class Reconciler extends ReconcilerReviewBase {
         if (!claimedTask)
             return;
         task = claimedTask;
-        // After the durable execution claim, fence this Graph-selected launch
-        // before invoking the adapter. An Unknown previous attempt must never be
-        // re-launched speculatively. Legacy test stores have no SQLite ledger.
         if (this.store.reserveWorkflowLaunch && task.executionId && task.leaseOwner) {
             const reserved = await this.store.reserveWorkflowLaunch({ jobId: job.id, taskId: task.id, executionId: task.executionId, attempt: task.attempt, leaseOwner: task.leaseOwner });
             if (!reserved)
@@ -531,22 +533,29 @@ export class Reconciler extends ReconcilerReviewBase {
                 : this.runtimeSettled(job.id, task.id, durableExecutionId, null, error instanceof Error ? error.message : String(error))), job.id, task.id, 'worker runtime completion');
     }
     async applyPlannerTree(jobId, planId, executionId, proposal) {
-        const { finishPlanner } = await import('./planner-runtime.js');
+        const { finishPlanner, PlannerApplyValidationError } = await import('./planner-runtime.js');
         const { parsePlannerResult } = await import('./planner.js');
         const ports = { store: this.store, options: this.options, live: this.plannerLive, plannerContext: (job, plan) => this.plannerContext(job, plan), emit: (event) => this.emit(event), detach: (promise, id, task, label) => this.detach(promise, id, task, label), reconcile: (id) => this.reconcile(id) };
-        await finishPlanner(ports, jobId, planId, executionId, null, parsePlannerResult(proposal), true);
+        let candidate;
+        try {
+            candidate = parsePlannerResult(proposal);
+        }
+        catch (error) {
+            throw new PlannerApplyValidationError('candidate', [error instanceof Error ? error.message : String(error), 'Correct the candidate and retry plan apply with the same active Planner execution.']);
+        }
+        await finishPlanner(ports, jobId, planId, executionId, null, candidate, true);
         const updated = (await this.store.load(jobId)).plans?.find(plan => plan.id === planId);
         if (!updated || updated.status !== 'SUCCEEDED')
             throw new Error(`Plan ${planId} was not committed`);
         return updated;
     }
-    async launchPlanner(job, plan) {
+    async launchPlanner(job, plan, waitForCompletion = false) {
         return launchPlanExecution({
             store: this.store,
             options: this.options,
             live: this.plannerLive,
             plannerContext: (currentJob, currentPlan) => this.plannerContext(currentJob, currentPlan), emit: event => this.emit(event),
             detach: (promise, jobId, planId, context) => this.detach(promise, jobId, planId, context), reconcile: jobId => this.reconcile(jobId),
-        }, job, plan);
+        }, job, plan, waitForCompletion);
     }
 }

package/dist/relay-job-snapshot-reads.js

@@ -1,11 +1,25 @@
 import { normalizeLegacyTaskLifecycle } from './types.js';
 import { normalizeLegacyJobPrNumber } from './job-pr-number-migration.js';
-function normalize(json) { const job = normalizeLegacyJobPrNumber(JSON.parse(json)); job.tasks = job.tasks.map(t => normalizeLegacyTaskLifecycle(t, job.executionMode)); return job; }
+export function normalizeRelayJob(json) {
+    const job = normalizeLegacyJobPrNumber(JSON.parse(json));
+    job.tasks = job.tasks.map(t => normalizeLegacyTaskLifecycle(t, job.executionMode));
+    job.plans = (job.plans ?? []).map(plan => {
+        const legacy = plan;
+        if (plan.forceRestate === undefined && legacy.forceCleanHistory === true)
+            plan.forceRestate = true;
+        if (plan.restateTaskIds === undefined && legacy.cleanHistoryTaskIds)
+            plan.restateTaskIds = [...legacy.cleanHistoryTaskIds];
+        delete legacy.forceCleanHistory;
+        delete legacy.cleanHistoryTaskIds;
+        return plan;
+    });
+    return job;
+}
 export function loadRelayJob(db, jobId) {
     const row = db.prepare('SELECT json FROM job_snapshot WHERE job_id=?').get(jobId);
-    return row?.json ? normalize(row.json) : null;
+    return row?.json ? normalizeRelayJob(row.json) : null;
 }
 export function listRelayJobs(db, scopeJobId) {
     const rows = db.prepare(scopeJobId ? 'SELECT json FROM job_snapshot WHERE job_id=? ORDER BY job_id' : 'SELECT json FROM job_snapshot ORDER BY job_id').all(...(scopeJobId ? [scopeJobId] : []));
-    return rows.map(row => normalize(row.json));
+    return rows.map(row => normalizeRelayJob(row.json));
 }

package/dist/relay-workflow-operations.js

@@ -1,5 +1,5 @@
 import { normalizeLegacyTaskLifecycle } from './types.js';
-import { normalizeLegacyJobPrNumber } from './job-pr-number-migration.js';
+import { normalizeRelayJob } from './relay-job-snapshot-reads.js';
 import { taskLifecycleV2 } from './workflow/definitions-v2.js';
 import { dispatchWorkflowGraphSync } from './workflow/dispatcher.js';
 import { WorkflowActionLedger } from './workflow/action-ledger.js';
@@ -51,7 +51,7 @@ export class SQLiteWorkflowOperations {
             const row = this.db.prepare('SELECT json FROM job_snapshot WHERE job_id=?').get(jobId);
             if (!row?.json)
                 throw new Error(`Unknown Job ${jobId}`);
-            const current = normalizeLegacyJobPrNumber(JSON.parse(row.json));
+            const current = normalizeRelayJob(row.json);
             current.tasks = current.tasks.map(task => normalizeLegacyTaskLifecycle(task, current.executionMode));
             const previous = structuredClone(current);
             const next = mutation(current);
@@ -120,7 +120,7 @@ export class SQLiteWorkflowOperations {
             const row = this.db.prepare('SELECT json FROM job_snapshot WHERE job_id=?').get(jobId);
             if (!row?.json)
                 throw new Error(`Local authoritative Job ${jobId} not found`);
-            const current = normalizeLegacyJobPrNumber(JSON.parse(row.json));
+            const current = normalizeRelayJob(row.json);
             current.tasks = current.tasks.map(task => normalizeLegacyTaskLifecycle(task, current.executionMode));
             const previous = structuredClone(current);
             const before = JSON.stringify(current);

package/dist/relayd-control.js

@@ -109,7 +109,7 @@ export function createWorkspaceControl(deps) {
         if (command === 'job.plan') {
             const reconciler = makeReconciler(store, concurrency);
             try {
-                const planned = await reconciler.planJob(jobId, typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance : undefined, body.forceCleanHistory === true);
+                const planned = await reconciler.planJob(jobId, typeof body.guidance === 'string' && body.guidance.trim() ? body.guidance : undefined, body.forceRestate === true);
                 await pool.reconcileLocalJob(jobId, 'control.job.plan');
                 return planned.round;
             }

package/dist/store.js

@@ -93,6 +93,16 @@ export class InMemoryStore {
     }
     async load(jobId) { const job = await this.findJob(jobId); if (!job)
         throw new Error(`Job ${jobId} not found`); job.plans = this.plansForJob(jobId); job.tasks = this.tasksForJob(jobId).map(task => normalizeLegacyTaskLifecycle(task, job.executionMode)); return job; }
+    async mutateJob(jobId, mutation) {
+        const current = await this.load(jobId);
+        const next = mutation(structuredClone(current));
+        this.values.set(`${JOB_MARKER}:${jobId}`, renderJobComment(next));
+        for (const plan of next.plans ?? [])
+            this.values.set(`${PLAN_MARKER}:${jobId}:${plan.id}`, renderPlanComment(plan));
+        for (const task of next.tasks)
+            this.values.set(`${TASK_MARKER}:${task.jobId ?? jobId}:${task.id}`, renderTaskComment(task));
+        return structuredClone(next);
+    }
     async saveJob(job) { this.values.set(`${JOB_MARKER}:${job.id}`, renderJobComment(job)); }
     async appendPlan(plan) { const key = `${PLAN_MARKER}:${plan.jobId}:${plan.id}`; const existing = this.values.get(key); if (existing) {
         const current = parsePlan(existing);

package/dist/workflow/force-restate-validation-v2.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { GraphRuntime } from './graph-v2.js';
+import { dispatchWorkflowGraphSync } from './dispatcher.js';
+const source = readFileSync(new URL('../../workflow/force-restate-validation.mmd', import.meta.url), 'utf8');
+export const forceRestateValidationV2 = new GraphRuntime(source, {
+    states: new Set(['idle', 'check_history_mode', 'check_history', 'check_normal_history', 'check_forward', 'rejected', 'committed']),
+    guards: {
+        forceRestateRequested: facts => facts.durableFacts.forceRestateRequested === true,
+        historyConsistencyValid: facts => facts.durableFacts.historyConsistencyValid === true,
+        normalHistoryMutationAbsent: facts => facts.durableFacts.normalHistoryMutationAbsent === true,
+        forwardConvergenceValid: facts => facts.durableFacts.forwardConvergenceValid === true,
+    },
+    actions: {
+        'plan.apply.commit': { id: 'plan.apply.commit' },
+        'plan.apply.rejectHistory': { id: 'plan.apply.rejectHistory' },
+        'plan.apply.rejectForward': { id: 'plan.apply.rejectForward' },
+    },
+    events: { 'plan.apply': { id: 'plan.apply' } },
+});
+export function decideForceRestateValidation(facts) {
+    return dispatchWorkflowGraphSync(forceRestateValidationV2, {
+        initialState: 'idle', input: { transport: 'event', id: 'plan.apply', payload: {} }, durableFacts: facts,
+        graphName: 'force-restate-validation',
+        isTransientState: state => state.startsWith('check_'), maxSteps: 12,
+    });
+}

package/dist/workflow/planner-orchestration-v2.js

@@ -56,10 +56,10 @@ export function plannerOrchestrationFacts(job, recoverablePendingPlan) {
     const latestId = latestPlan?.id ?? legacyLatest?.id;
     const latestObjective = latestPlan?.objectiveStatus ?? legacyLatest?.plannerResult?.objective_status;
     return {
-        autonomousJob: job.executionMode === 'autonomous',
+        autonomousJob: job.executionMode === 'autonomous' || latestPlan?.forceRestate === true,
         legacyPlanningPending: job.initialPlanning?.status === 'pending',
         recoverablePendingPlan,
-        terminalPlanFailure: Boolean(failedPlan && !failedPlan.manualPlanning && failedPlan.trigger.source !== 'unblock'),
+        terminalPlanFailure: Boolean(failedPlan && (!failedPlan.manualPlanning || failedPlan.forceRestate) && failedPlan.trigger.source !== 'unblock'),
         planRecoveryExists: Boolean(recovery),
         planRecoveryVerified: recoveryVerified,
         hasSeedWork: !((job.plans?.length ?? 0) === 0 && job.tasks.filter(task => task.kind !== 'planner').length === 0),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.162",
+  "version": "2.0.163",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",
@@ -19,8 +19,8 @@
     "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 && npm run test:verification:l3",
-    "test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs test/verification/task-resolution-classification.test.mjs test/verification/planner-contract.test.mjs test/planner-child-recovery.test.js",
-    "test:verification:l3": "npm run build && node --test --test-concurrency=1 test/verification/harness.test.mjs test/verification/l3-sqlite.test.mjs test/verification/l3-ingress.test.mjs test/verification/l3-replay.test.mjs test/verification/objective-authority.test.mjs test/verification/l3-convergence.test.mjs test/verification/l3-review-convergence.test.mjs test/verification/l3-human-escalation.test.mjs test/verification/l3-escalation-notifier.test.mjs test/verification/l3-unknown-effect.test.mjs test/verification/l3-cli-actions.test.mjs test/verification/l3-planner-round.test.mjs test/verification/l3-planner-cli.test.mjs test/verification/l3-task-resolution.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.test.mjs test/verification/l3-full-path.test.mjs test/verification/l3-projection-recovery.test.mjs",
+    "test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs test/verification/task-resolution-classification.test.mjs test/verification/planner-contract.test.mjs test/verification/force-restate-validation.test.mjs test/planner-child-recovery.test.js",
+    "test:verification:l3": "npm run build && node --test --test-concurrency=1 test/verification/harness.test.mjs test/verification/l3-sqlite.test.mjs test/verification/l3-ingress.test.mjs test/verification/l3-replay.test.mjs test/verification/objective-authority.test.mjs test/verification/l3-convergence.test.mjs test/verification/l3-review-convergence.test.mjs test/verification/l3-human-escalation.test.mjs test/verification/l3-escalation-notifier.test.mjs test/verification/l3-unknown-effect.test.mjs test/verification/l3-cli-actions.test.mjs test/verification/l3-planner-round.test.mjs test/verification/l3-planner-cli.test.mjs test/verification/l3-task-resolution.test.mjs test/verification/l3-plan-apply-convergence.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.test.mjs test/verification/l3-full-path.test.mjs test/verification/l3-projection-recovery.test.mjs",
     "test:verification": "npm run test:verification:l1 && npm run test:verification:l2 && npm run test:verification:l3 && npm run test:verification:cross-a && node --test test/workflow-production-outbox.test.js && npm run test:verification:matrix",
     "e2e": "node e2e/runner/run.mjs",
     "test:verification:cross-a": "npm run build && RELAY_A_DIST=$PWD/dist node --test test/verification/action-ledger-cross-branch.test.mjs test/verification/outbox-cross-a.test.mjs",

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

@@ -99,11 +99,11 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - **Resolution is mandatory for replacement work:** before returning any `next_tasks`, inspect every existing `FAILED` or `BLOCKED` work Task. If it lacks an active/waiting `resolution` or durable `resolutionClassification` and the proposed batch creates related/sibling work, explicitly cover it with a valid `resolution` on the new recovery Task. A superseded/invalid classification covers only planning validation; preserve the FAILED state and never infer success from the classification. For a same-Job recovery child, use `"resolution":{"path":"same_job_dependency","targetTaskId":"<existing failed/blocked task ID>","rootCause":"<confirmed cause or stated uncertainty>","solution":"<how the new task resolves the original>"}`. `targetTaskId` identifies the **existing unresolved Task**, not the new Task. Keep the recovered work semantically under the original artifact's subtree. Do not invent a resolution or silently cancel unrelated failed work.
 - **On `retry_feedback`:** treat the feedback as Relay's authoritative validation error for the previous output in this **same Plan**. Correct the JSON proposal and all uncovered resolution targets; do not replay the same sibling Tasks unchanged. Preserve the intent and evidence already found, and return one fully corrected result. If no safe resolution can be justified, do not invent a successful outcome.
 
-### Forced failed-history cleanup
+### Forced Restate audit and validation
 
-When `force_clean_history` is true, inspect every ID in `clean_history_task_ids` against the authoritative Task records and dependency/evidence context before planning. Do not infer a result from text alone. For a failed review that is demonstrably stale, run the existing guarded `agents-relay task cancel` command. For a failed work Task with evidence that replacement work covers it, run the existing guarded `agents-relay task classify --classification superseded`; for proven invalid work, use `--classification invalid`. Supply a different durable `--target-task-id`, and the same concrete `--evidence` and `--reason` in your report. Use the normal repository, PR, and Job options from this invocation. Never change task state directly or claim an action succeeded unless the CLI command succeeds and a fresh `task show` confirms it.
+When `force_restate` is true, use this single forced Planner opportunity to audit the full authoritative semantic Task tree, every historical Task and Resolution classification, all dependency edges, and review target/head evidence. Inspect every ID in `restate_task_ids` against authoritative Task records and evidence. Do not run `task classify` or `task cancel` as a preliminary mutation. Instead include exactly one `history_cleanup` entry for each ID: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. `plan apply` validates the proposed dispositions against the current SQLite snapshot and atomically applies them with the Plan and Tasks. A failed validation leaves all SQLite state unchanged, so correct the proposal and retry with the same Plan and execution IDs.
 
-If evidence is absent or execution outcome is unknown, leave the Task unresolved and do not classify it, cancel ordinary failed work, or claim success. Do not create related replacement work for an unresolved failure. After all selected guarded commands succeed, refresh authoritative Task state and submit the Plan through the standard `plan apply` command. Include exactly one `history_cleanup` entry for each `clean_history_task_ids` item: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. For unresolved items, state what evidence is missing. Relay validates that reported mutations match durable SQLite state; an ordinary text response is never a Plan receipt.
+If evidence is absent or execution outcome is unknown, leave the Task unresolved. A classification target must be an existing SUCCEEDED Task. Do not create replacement work for an unresolved failure. Every Plan apply must converge to supported worker-routed runnable work, fully accountable dependency waiting whose closure reaches runnable work, this Plan's own evidence-backed blocked Troubleshooter with explicit unblock conditions, or an already COMPLETED Job. Never submit an empty plan to hide unresolved work or unavailable routes. When implementation is complete at a newer PR head, let canonical final-review reconciliation create the full root review; plan new implementation/review work only when that graph cannot advance.
 
 - 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.

package/workflow/force-restate-validation.mmd

@@ -0,0 +1,37 @@
+---
+title: Plan Apply Convergence Validation
+description: Validates hypothetical Plan application and, for Force Restate, historical consistency before the atomic commit action.
+---
+flowchart LR
+%% relay: initial idle
+idle["state: idle"]
+checkHistoryMode["state: check_history_mode"]
+checkHistory["state: check_history"]
+checkNormalHistory["state: check_normal_history"]
+checkForward["state: check_forward"]
+commit["action: plan.apply.commit"]
+rejected["state: rejected"]
+committed["state: committed"]
+forceRestate["guard: forceRestateRequested"]
+historyConsistent["guard: historyConsistencyValid"]
+forwardConverged["guard: forwardConvergenceValid"]
+normalHistoryClean["guard: normalHistoryMutationAbsent"]
+rejectHistory["action: plan.apply.rejectHistory"]
+rejectForward["action: plan.apply.rejectForward"]
+
+idle -->|on: plan.apply| checkHistoryMode
+checkHistoryMode -->|on: plan.apply| forceRestate
+forceRestate -->|true| checkHistory
+forceRestate -->|false| checkNormalHistory
+checkNormalHistory -->|on: plan.apply| normalHistoryClean
+normalHistoryClean -->|true| checkForward
+normalHistoryClean -->|false| rejectHistory
+checkHistory -->|on: plan.apply| historyConsistent
+historyConsistent -->|true| checkForward
+historyConsistent -->|false| rejectHistory
+rejectHistory --> rejected
+checkForward -->|on: plan.apply| forwardConverged
+forwardConverged -->|true| commit
+forwardConverged -->|false| rejectForward
+commit --> committed
+rejectForward --> rejected