agents-relay 2.0.141 → 2.0.143

package/dist/workflow/conditions.js

@@ -0,0 +1,32 @@
+export class ConditionRegistry {
+    conditions = new Map();
+    constructor(specs) {
+        for (const spec of specs) {
+            if (this.conditions.has(spec.id))
+                throw new Error(`duplicate condition: ${spec.id}`);
+            this.conditions.set(spec.id, spec);
+        }
+    }
+    discover() { return [...this.conditions.keys()].sort(); }
+    inspect(id) {
+        const result = this.conditions.get(id);
+        if (!result)
+            throw new Error(`unknown condition: ${id}`);
+        return result;
+    }
+    check(id, facts) {
+        return this.inspect(id).check(facts);
+    }
+    guard(id) {
+        return ({ durableFacts }) => this.check(id, durableFacts) === 'Verified';
+    }
+}
+export function booleanCondition(id) {
+    return { id, check: facts => facts[id] === true ? 'Verified' : facts[id] === false ? 'Failed' : 'Unknown' };
+}
+export function verifyActionEffect(registry, actionId, conditionId, facts) {
+    return { actionId, conditionId, outcome: registry.check(conditionId, facts) };
+}
+export function safeRetryAllowed(outcome) {
+    return outcome === 'Failed';
+}

package/dist/workflow/definitions-v2.js

@@ -1,9 +1,14 @@
+import { ConditionRegistry, booleanCondition } from './conditions.js';
 import { readFileSync } from 'node:fs';
 import { GraphRuntime } from './graph-v2.js';
 import { WORKFLOW_EFFECT_NAMES, WORKFLOW_EVENT_NAMES, WORKFLOW_MUTATION_NAMES, } from './contracts.js';
 const TASK_STATES = ['DRAFT', 'QUEUED', 'RUNNING', 'BLOCKED', 'SUCCEEDED', 'FAILED', 'CANCELLED'];
 const JOB_STATES = ['DRAFT', 'ACTIVE', 'COMPLETED', 'CANCELLED'];
-const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+const conditionRegistry = new ConditionRegistry([
+    ...new Set(['dependenciesSatisfied', 'dependenciesUnsatisfied', 'runnable', 'dispatchable', 'recoverableExecution', 'troubleshooterRecovery', 'retryAvailable', 'autonomousJob', 'platformFallbackSafe', 'notMerged', 'autoMerge', 'prOpen', 'reviewDisabled', 'implementationComplete', 'headAvailable', 'mergeCapable', 'localCompletionAllowed', 'localMergeReady'])
+].map(booleanCondition));
+const boolGuard = (name) => conditionRegistry.guard(name);
+export const lifecycleConditions = conditionRegistry;
 function eventRegistry() {
     return Object.fromEntries(WORKFLOW_EVENT_NAMES.map(id => [id, { id }]));
 }

package/dist/workflow/dispatcher.js

@@ -58,16 +58,66 @@ export async function dispatchWorkflowGraph(runtime, options) {
     let current = options.initialState;
     const maxSteps = options.maxSteps ?? 1;
     for (let step = 0; step < maxSteps; step += 1) {
+        let deferredTransition = null;
+        const deferredEvents = [];
         const dispatcher = new GraphDispatcher(runtime, {
-            persistTransition: async (transition) => { await options.persistTransition?.(transition.source, transition.target); },
-            executeAction: options.executeAction ? async (actionId) => await options.executeAction(actionId) : undefined,
-            publishEvent: async (event) => { await options.publishEvent?.(event.id, event.payload); },
+            persistTransition: async (transition) => {
+                if (options.actionVerification)
+                    deferredTransition = transition;
+                else
+                    await options.persistTransition?.(transition.source, transition.target);
+            },
+            executeAction: options.executeAction ? async (actionId) => {
+                const verification = options.actionVerification;
+                if (verification) {
+                    const identity = verification.identity(actionId);
+                    const decision = runtime.evaluateSync({ currentState: current, input: options.input, durableFacts: options.durableFacts ?? {} });
+                    if (!verification.ledger.reserveForRunningTask(identity, decision, verification.conditionId(actionId))) {
+                        throw new Error('action attempt already reserved: reconcile outcome; never repeat side effect');
+                    }
+                }
+                const receipt = await options.executeAction(actionId);
+                if (receipt.ok === false)
+                    throw new Error('action returned failure receipt: reconciliation required');
+                if (verification) {
+                    const identity = verification.identity(actionId);
+                    const trace = verification.ledger.verify(identity.attemptKey, verification.conditions, await verification.observedFacts(actionId));
+                    if (trace.outcome !== 'Verified')
+                        throw new Error('action postcondition ' + trace.outcome + ': reconciliation required');
+                }
+                return receipt;
+            } : undefined,
+            publishEvent: async (event) => {
+                if (options.actionVerification)
+                    deferredEvents.push(event);
+                else
+                    await options.publishEvent?.(event.id, event.payload);
+            },
         });
         const result = await dispatcher.dispatch({
             currentState: current,
             input: options.input,
             durableFacts: options.durableFacts ?? {},
         });
+        if (options.actionVerification && result.decision.accepted) {
+            if (result.receipts.some(receipt => receipt.ok === false))
+                throw new Error('action failed: reconciliation required; transition withheld');
+            const transition = deferredTransition;
+            const publication = options.actionVerification.publication;
+            const persist = options.actionVerification.persistSqliteTransition;
+            if (!publication || !persist || transition === null)
+                throw new Error('atomic SQLite transition and outbox required');
+            const events = deferredEvents.map((event, index) => {
+                const action = result.decision.accepted ? result.decision.actions[0] : undefined;
+                if (!action)
+                    throw new Error('missing durable action event identity');
+                const identity = options.actionVerification.identity(action.id);
+                return { key: `${identity.attemptKey}/emit/${index}`, eventId: event.id, payload: event.payload };
+            });
+            publication.commitTransitionAndEvents(() => persist(transition.source, transition.target), events);
+            if (options.publishEvent)
+                await publication.replay(async (event) => options.publishEvent(event.eventId, event.payload));
+        }
         if (options.observe !== false)
             observeDecision(options.graphName, options.input, result.decision);
         if (!result.decision.accepted)

package/dist/workflow/durable-publication.js

@@ -0,0 +1,85 @@
+export class DurableWorkflowPublication {
+    db;
+    constructor(db) {
+        this.db = db;
+        db.exec(`CREATE TABLE IF NOT EXISTS workflow_event_outbox (
+      event_key TEXT PRIMARY KEY, event_id TEXT NOT NULL, payload_json TEXT NOT NULL,
+      state TEXT NOT NULL DEFAULT 'pending' CHECK(state IN ('pending','published')),
+      created_at TEXT NOT NULL, published_at TEXT
+    )`);
+    }
+    /** State mutation callback MUST use this.db synchronously; rollback covers both writes. */
+    commitTransitionAndEvents(transition, events) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            transition();
+            for (const event of (typeof events === 'function' ? events() : events))
+                this.enqueue(event.key, event.eventId, event.payload);
+            this.db.exec('COMMIT');
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    enqueue(key, eventId, payload) {
+        if (!key || !eventId)
+            throw new Error('event identity required');
+        const encoded = JSON.stringify(payload ?? null);
+        this.db.prepare(`INSERT OR IGNORE INTO workflow_event_outbox(event_key,event_id,payload_json,created_at) VALUES(?,?,?,?)`)
+            .run(key, eventId, encoded, new Date().toISOString());
+        const existing = this.db.prepare('SELECT event_id,payload_json FROM workflow_event_outbox WHERE event_key=?').get(key);
+        if (existing.event_id !== eventId || existing.payload_json !== encoded)
+            throw new Error('workflow event key collision');
+    }
+    pending() {
+        return this.db.prepare("SELECT event_key,event_id,payload_json FROM workflow_event_outbox WHERE state='pending' ORDER BY created_at,event_key").all().map(row => ({ key: row.event_key, eventId: row.event_id, payload: JSON.parse(row.payload_json) }));
+    }
+    async replay(publish) {
+        let delivered = 0;
+        for (const event of this.pending()) {
+            await publish(event);
+            this.db.prepare("UPDATE workflow_event_outbox SET state='published',published_at=? WHERE event_key=? AND state='pending'").run(new Date().toISOString(), event.key);
+            delivered++;
+        }
+        return delivered;
+    }
+}
+/** Atomic SQLite inbox for event consumers. The callback MUST mutate the same DB
+ * synchronously; duplicate deliveries return false without repeating the mutation.
+ * Consumers with external side effects must use their own idempotency protocol. */
+export class DurableWorkflowConsumer {
+    db;
+    constructor(db) {
+        this.db = db;
+        db.exec(`CREATE TABLE IF NOT EXISTS workflow_event_inbox (
+      consumer_id TEXT NOT NULL, event_key TEXT NOT NULL, event_id TEXT NOT NULL,
+      payload_json TEXT NOT NULL, consumed_at TEXT NOT NULL,
+      PRIMARY KEY(consumer_id,event_key)
+    )`);
+    }
+    consume(consumerId, event, apply) {
+        if (!consumerId || !event.key || !event.eventId)
+            throw new Error('consumer and event identity required');
+        const payload = JSON.stringify(event.payload ?? null);
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const previous = this.db.prepare('SELECT event_id,payload_json FROM workflow_event_inbox WHERE consumer_id=? AND event_key=?').get(consumerId, event.key);
+            if (previous) {
+                if (previous.event_id !== event.eventId || previous.payload_json !== payload)
+                    throw new Error('consumer event key collision');
+                this.db.exec('COMMIT');
+                return false;
+            }
+            apply();
+            this.db.prepare('INSERT INTO workflow_event_inbox(consumer_id,event_key,event_id,payload_json,consumed_at) VALUES(?,?,?,?,?)')
+                .run(consumerId, event.key, event.eventId, payload, new Date().toISOString());
+            this.db.exec('COMMIT');
+            return true;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}

package/dist/workflow/durable-transition.js

@@ -26,11 +26,20 @@ export class DurableTaskTransitionRuntime {
                 return null;
             }
             const from = task.state;
+            const previousUpdatedAt = task.updatedAt;
             const decision = tryTransitionTaskEvent(task, event, options.facts?.(job, task) ?? {});
             if (!decision.accepted || !decision.target) {
                 return { job, task, from, decision };
             }
             await options.mutate?.(job, task, decision);
+            // The local SQLite writer rejects stale snapshots. Wall-clock timestamps may
+            // collide or move backwards across rapid start/terminal events; ensure the
+            // graph-selected transition has a strictly newer version before saving.
+            const previous = Date.parse(previousUpdatedAt);
+            const proposed = Date.parse(task.updatedAt);
+            if (Number.isFinite(previous) && (!Number.isFinite(proposed) || proposed <= previous)) {
+                task.updatedAt = new Date(previous + 1).toISOString();
+            }
             await this.store.saveTask(task);
             observability().record({
                 stage: 'transition',

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

@@ -6,13 +6,16 @@ const source = readFileSync(new URL('../../workflow/planner-orchestration.mmd',
 const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
 export const plannerOrchestrationV2 = new GraphRuntime(source, {
     states: new Set([
-        'idle', 'check_legacy_pending', 'check_recover', 'check_seed', 'check_planner', 'check_resolution_ownership',
+        'idle', 'check_legacy_pending', 'check_recover', 'check_plan_failure', 'check_plan_recovery', 'check_plan_recovery_exists', 'check_seed', 'check_planner', 'check_resolution_ownership',
         'check_blocked', 'check_work', 'check_materialized', 'check_objective', 'wait', 'recovered', 'created',
     ]),
     guards: {
         autonomousJob: boolGuard('autonomousJob'),
         legacyPlanningPending: boolGuard('legacyPlanningPending'),
         recoverablePendingPlan: boolGuard('recoverablePendingPlan'),
+        terminalPlanFailure: boolGuard('terminalPlanFailure'),
+        planRecoveryExists: boolGuard('planRecoveryExists'),
+        planRecoveryVerified: boolGuard('planRecoveryVerified'),
         hasSeedWork: boolGuard('hasSeedWork'),
         noActivePlanner: boolGuard('noActivePlanner'),
         resolutionOwnedByTroubleshooter: boolGuard('resolutionOwnedByTroubleshooter'),
@@ -22,6 +25,7 @@ export const plannerOrchestrationV2 = new GraphRuntime(source, {
         objectiveUnsatisfied: boolGuard('objectiveUnsatisfied'),
     },
     actions: {
+        'planner.createRecovery': { id: 'planner.createRecovery' },
         'planner.recoverPending': { id: 'planner.recoverPending' },
         'planner.createRound': { id: 'planner.createRound' },
     },
@@ -39,6 +43,12 @@ export function plannerOrchestrationFacts(job, recoverablePendingPlan) {
     const scopedPlans = (job.plans ?? []).filter(plan => !Number.isFinite(slot) || Date.parse(plan.createdAt) >= slot)
         .sort((a, b) => a.round - b.round || a.createdAt.localeCompare(b.createdAt));
     const latestPlan = scopedPlans.at(-1);
+    const failedPlan = latestPlan?.status === 'FAILED' ? latestPlan : null;
+    const recovery = failedPlan ? job.tasks.find(task => task.agentName === 'troubleshooter' && task.recoveryPlanId === failedPlan.id) : undefined;
+    const recoveryVerified = recovery?.state === 'SUCCEEDED'
+        && recovery.result?.data?.verified === true
+        && typeof recovery.result?.data?.evidence === 'string'
+        && recovery.result.data.evidence.trim().length > 0;
     const legacyLatest = scopedPlans.length === 0
         ? scopedTasks.filter(task => task.kind === 'planner' && task.state === 'SUCCEEDED' && task.plannerResult)
             .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)).at(-1)
@@ -49,8 +59,11 @@ export function plannerOrchestrationFacts(job, recoverablePendingPlan) {
         autonomousJob: job.executionMode === 'autonomous',
         legacyPlanningPending: job.initialPlanning?.status === 'pending',
         recoverablePendingPlan,
+        terminalPlanFailure: Boolean(failedPlan && !failedPlan.manualPlanning && failedPlan.trigger.source !== 'unblock'),
+        planRecoveryExists: Boolean(recovery),
+        planRecoveryVerified: recoveryVerified,
         hasSeedWork: !((job.plans?.length ?? 0) === 0 && job.tasks.filter(task => task.kind !== 'planner').length === 0),
-        noActivePlanner: unblockNeedsNewPlan(job) || !unconsumedUnblockTrigger(job) ? !scopedPlans.some(plan => plan.status === 'PLANNING') : false,
+        noActivePlanner: failedPlan?.manualPlanning ? false : unblockNeedsNewPlan(job) || !unconsumedUnblockTrigger(job) ? !scopedPlans.some(plan => plan.status === 'PLANNING') : false,
         noBlockedWork: Boolean(unconsumedUnblockTrigger(job)) || !scopedTasks.some(task => task.kind !== 'planner' && isEffectivelyBlocked(task)),
         noActiveImplementation: !scopedTasks.some(task => task.kind !== 'planner' && (['QUEUED', 'RUNNING'].includes(task.state) || (task.state === 'DRAFT' && !task.unblock))),
         resolutionOwnedByTroubleshooter: scopedTasks.some(task => task.kind !== 'planner' && task.resolution?.owner === 'troubleshooter' && ['active', 'waiting'].includes(task.resolution.state)),

package/dist/workflow/usage-index.js

@@ -0,0 +1,35 @@
+/** Derived, read-only reverse usage index. Graph topology remains the only transition authority. */
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
+import { parseGraphV2 } from './graph-v2.js';
+const EXECUTABLE_GRAPH = /^[a-z][a-z0-9-]*\.mmd$/;
+export function executableGraphs(directory) {
+    const output = new Map();
+    for (const filename of readdirSync(directory).sort()) {
+        if (!EXECUTABLE_GRAPH.test(filename) || filename === 'main.mmd')
+            continue;
+        output.set(filename, parseGraphV2(readFileSync(join(directory, filename), 'utf8')));
+    }
+    return output;
+}
+export function buildWorkflowUsageIndex(graphs) {
+    const usages = [];
+    for (const [graphName, graph] of graphs) {
+        for (const node of graph.nodes.values()) {
+            usages.push({ graph: graphName, kind: node.kind, id: node.semanticId, line: node.line, node: node.id });
+        }
+        for (const edge of graph.edges) {
+            if ((edge.kind === 'on' || edge.kind === 'emit' || edge.kind === 'request') && edge.semanticId) {
+                usages.push({ graph: graphName, kind: edge.kind === 'request' ? 'request' : 'event', id: edge.semanticId, line: edge.line });
+            }
+        }
+    }
+    return usages.sort((a, b) => a.id.localeCompare(b.id) || a.graph.localeCompare(b.graph) || a.line - b.line);
+}
+export function whereWorkflowSymbol(index, id, kind) {
+    return index.filter(item => item.id === id && (!kind || item.kind === kind));
+}
+export function defaultWorkflowDirectory() {
+    return resolve(fileURLToPath(new URL('../../workflow/', import.meta.url)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.141",
+  "version": "2.0.143",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",
@@ -19,10 +19,14 @@
     "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": "node --test test/verification/harness.test.mjs",
-    "test:verification:l3": "npm run build && node --test 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": "npm run test:verification:l1 && npm run test:verification:l3",
-    "e2e": "node e2e/runner/run.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:l3": "npm run build && node --test 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-planner-round.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.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",
+    "test:verification:matrix": "node test/verification/recovery-report.mjs /tmp/agents-relay-job481-evidence",
+    "test:verification:l2": "npm run build && node --test test/verification/l2/*.test.mjs",
+    "test:verification:l2:live": "node test/verification/l2/live-provider.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/workflow/main.mmd

@@ -1,29 +1,56 @@
-%% dashboard: presentation-only; not an executable workflow
+%% dashboard: presentation-only — not registered with GraphRuntime or the executable Graph DSL.
+%% Nodes link to the canonical executable workflow graphs. SQLite remains authoritative.
 flowchart LR
-objective["START: Job Objective"] --> planner["Planner"] --> worker["Worker"] --> reviewer["Reviewer"] --> merge["Merge / Delivery"] --> achieved["Objective Achieved"] --> completed["Job Completed"]
-reviewer -->|Changes Required| fix["Fix Task"] --> worker
-planner -->|Failed| troubleshooter["Troubleshooter"]
-worker -->|Failed| troubleshooter
-reviewer -->|Failed| troubleshooter
-merge -->|Failed| troubleshooter
-troubleshooter --> resolution["Resolution"]
-resolution -->|Recovered| planner
-resolution -->|Recovered| worker
-resolution -->|Recovered| reviewer
-resolution -->|Recovered| merge
-resolution -->|Needs human action| escalator["Escalator workflow"] -->|Resolved| resolution
-classDef failure fill:#ffe4e4,stroke:#be3030,color:#7c1818
-class troubleshooter,resolution,escalator failure
-linkStyle 8,9,10,11,12,13,14,15,16,17,18 stroke:#be3030,stroke-width:2px
+    objective["START: Job Objective"]
+    planner["Planner"]
+    worker["Worker"]
+    reviewer["Reviewer"]
+    delivery["Merge / Delivery"]
+    verify["Objective Verification"]
+    completed["Completed"]
+    trouble["Troubleshooter"]
+    recover{"Recovery conditions verified?"}
+    escalation["Escalation: human action only"]
+    fix["Changes Required: fix and review again"]
 
-click objective href "job-lifecycle.mmd"
-click planner href "planner-orchestration.mmd"
-click worker href "task-lifecycle.mmd"
-click reviewer href "review-lifecycle.mmd"
-click merge href "job-lifecycle.mmd"
-click achieved href "job-lifecycle.mmd"
-click completed href "job-lifecycle.mmd"
-click fix href "review-lifecycle.mmd"
-click troubleshooter href "troubleshooter.mmd"
-click resolution href "blocker-resolution.mmd"
-click escalator href "escalation.mmd"
+    objective --> planner
+    planner --> worker
+    worker --> reviewer
+    reviewer -->|approved| delivery
+    reviewer -->|changes required| fix
+    fix --> worker
+    delivery --> verify
+    verify -->|verified| completed
+
+    planner -->|failure| trouble
+    worker -->|failure| trouble
+    reviewer -->|failure| trouble
+    delivery -->|failure| trouble
+    verify -->|unknown / failed| trouble
+    trouble --> recover
+    recover -->|guarded retry to exact failed step| planner
+    recover -->|guarded retry to exact failed step| worker
+    recover -->|guarded retry to exact failed step| reviewer
+    recover -->|guarded retry to exact failed step| delivery
+    recover -->|unknown: reconcile first| trouble
+    recover -->|human action required| escalation
+    escalation -->|resolved: reconcile and resume| trouble
+
+    click objective href "job-lifecycle.mmd" "Job lifecycle"
+    click planner href "planner-orchestration.mmd" "Planner orchestration"
+    click worker href "task-lifecycle.mmd" "Task lifecycle"
+    click reviewer href "review-lifecycle.mmd" "Review lifecycle"
+    click delivery href "job-lifecycle.mmd" "Job completion"
+    click verify href "job-lifecycle.mmd" "Objective completion gate"
+    click trouble href "troubleshooter.mmd" "Troubleshooter"
+    click recover href "task-resolution.mmd" "Task resolution"
+    click escalation href "escalation.mmd" "Escalation"
+    click fix href "review-lifecycle.mmd" "Review fixes"
+
+    classDef exception fill:#fee2e2,stroke:#b91c1c,color:#991b1b
+    classDef normal fill:#eff6ff,stroke:#2563eb,color:#1e40af
+    class trouble,recover,escalation exception
+    class objective,planner,worker,reviewer,delivery,verify,completed,fix normal
+
+    %% Failed/unknown transitions are red; verified retries remain blue.
+    linkStyle 8,9,10,11,12,18 stroke:#be3030,stroke-width:2px

package/workflow/planner-orchestration.mmd

@@ -3,6 +3,9 @@ flowchart LR
 idle["state: idle"]
 checkLegacy["state: check_legacy_pending"]
 checkRecover["state: check_recover"]
+checkPlanFailure["state: check_plan_failure"]
+checkPlanRecovery["state: check_plan_recovery"]
+checkPlanRecoveryExists["state: check_plan_recovery_exists"]
 checkSeed["state: check_seed"]
 checkPlanner["state: check_planner"]
 checkResolution["state: check_resolution_ownership"]
@@ -17,6 +20,9 @@ created["state: created"]
 autonomous["guard: autonomousJob"]
 legacyPending["guard: legacyPlanningPending"]
 recoverablePending["guard: recoverablePendingPlan"]
+terminalFailure["guard: terminalPlanFailure"]
+recoveryVerified["guard: planRecoveryVerified"]
+recoveryExists["guard: planRecoveryExists"]
 hasSeed["guard: hasSeedWork"]
 noActivePlanner["guard: noActivePlanner"]
 resolutionOwned["guard: resolutionOwnedByTroubleshooter"]
@@ -26,6 +32,7 @@ materialized["guard: continuationMaterialized"]
 unsatisfied["guard: objectiveUnsatisfied"]
 
 recoverAction["action: planner.recoverPending"]
+createRecovery["action: planner.createRecovery"]
 createAction["action: planner.createRound"]
 
 idle -->|on: planner.reconcile| autonomous
@@ -39,7 +46,20 @@ legacyPending -->|false| checkRecover
 checkRecover -->|on: planner.reconcile| recoverablePending
 recoverablePending -->|true| recoverAction
 recoverAction --> recovered
-recoverablePending -->|false| checkSeed
+recoverablePending -->|false| checkPlanFailure
+
+checkPlanFailure -->|on: planner.reconcile| terminalFailure
+terminalFailure -->|false| checkSeed
+terminalFailure -->|true| checkPlanRecovery
+
+checkPlanRecovery -->|on: planner.reconcile| recoveryVerified
+recoveryVerified -->|true| checkPlanner
+recoveryVerified -->|false| checkPlanRecoveryExists
+
+checkPlanRecoveryExists -->|on: planner.reconcile| recoveryExists
+recoveryExists -->|true| wait
+recoveryExists -->|false| createRecovery
+createRecovery --> created
 
 checkSeed -->|on: planner.reconcile| hasSeed
 hasSeed -->|false| wait

package/workflow/review-lifecycle.mmd

@@ -101,6 +101,10 @@ autoMergePending -->|false| approved
 pending -->|on: review.changes_required| fixPending
 fixPending --> changes
 
+%% A failed Reviewer execution may recover with a new Execution ID while
+%% the Review lifecycle remains STARTED. This is a legal re-start event;
+%% Reconciler still fences stale execution generations and immutable head SHA.
+started -->|on: review.started| started
 started -->|on: review.approved| autoMergeStarted
 autoMergeStarted -->|true| mergeStarted
 mergeStarted --> approved