agents-relay 2.0.32 → 2.0.33

package/README.md

@@ -189,6 +189,8 @@ events, durable-thread reuse, resume, or retry behavior.
 
 Open the dashboard on localhost port 8787. The marker format is intentionally public and append-friendly. Daemon/workspace operation uses `ProjectedDurableStore` over SQLite RelayStore plus the authenticated GitHub projection adapter; GitHubStore is not the daemon operational state database.
 
+Deterministic projection conflicts are safe and observable. A same-id/different-definition `append_task`/`append_plan` is classified once into a durable `conflict` state, stops consuming retry budget, keeps structured divergence evidence, and is never auto-overwritten. Inspect with `agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER` and repair explicitly with `agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local`. See [docs/architecture-v2.md](docs/architecture-v2.md).
+
 External product feedback uses the reusable `src/feedback.ts` contract. See [docs/feedback-intake.md](docs/feedback-intake.md) for the schema, attachment limits, privacy rules, materialization path, and provenance envelope for later Jobs/Tasks/PRs.
 
 reconcile leases and launches ready tasks without waiting inside the runtime scheduler; the CLI waits only long enough for its launched workers to persist results. agents-relayd (or the equivalent npx agents-relay serve) is the watchdog/dashboard mode. Model-backed workers require --events nats; the event transport carries authoritative terminal worker events as well as wake/progress traffic. See [docs/service.md](docs/service.md). --file PATH is explicit local demo/test mode only.

package/dist/cli-help.js

@@ -1,4 +1,4 @@
-export const usage = 'agents-relay <job|task|plan|blocker|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
+export const usage = 'agents-relay <job|task|plan|blocker|projection|context|init|record|agent-register|agent-discover|status|reconcile|serve> [options]';
 const help = {
     root: `Agents Relay coordinates durable asynchronous agent jobs through GitHub pull requests.
 
@@ -10,6 +10,7 @@ Commands:
   task create|update|show|list|complete|retry|unblock|cancel  Manage durable tasks
   plan                     Invoke the Planner for an existing managed Job
   blocker add|resolve|show  Manage cross-Job blocker dependencies
+  projection conflicts|resolve  Inspect and repair deterministic GitHub projection conflicts
   context resolve          Resolve shared project instructions, skills, agents, and runtimes
   init                     Create a local demo job or initialize a GitHub job
   record                   Backfill a completed task into durable history
@@ -203,6 +204,17 @@ Common: --capabilities a,b, --runtime shell|codex|chatgpt, --provider NAME, --mo
 
 Example:
   npx agents-relay agent-register --file .agents-relay.json --name builder --responsibility "Build code" --role engineer --endpoint shell`,
+    projection: `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.
+
+Usage:
+  npx agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER [--store PATH]
+  npx agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local
+
+A deterministic same-id/different-definition append conflict is classified once, stops
+consuming retry budget, and retains structured diagnostic evidence. It is never
+auto-overwritten: an operator resolves it after reconciling the divergent definition.
+  requeue        Re-arm the recorded projection after the divergent side is reconciled
+  discard-local  Drop the blocked local mutation so a fresh one can be enqueued`,
     'agent-discover': `Find registered agents using hard filters.
 
 Required: --file PATH or managed GitHub options.
@@ -220,5 +232,7 @@ export function helpText(command, action) {
         return action ? help[`context ${action}`] ?? help.context : help.context;
     if (command === 'blocker')
         return action ? help[`blocker ${action}`] ?? help.blocker : help.blocker;
+    if (command === 'projection')
+        return help.projection;
     return command ? help[command] ?? help.root : help.root;
 }

package/dist/cli-projection.js

@@ -0,0 +1,61 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { SQLiteRelayStore, relayStorePath } from './relay-store.js';
+import { arg, integerArg, pullRequest, repository } from './cli-support.js';
+const DEFAULT_STORE_DIR = join(homedir(), '.agents-relay', 'stores');
+function storePath(args) {
+    const explicit = arg(args, '--store');
+    if (explicit)
+        return explicit;
+    return relayStorePath(arg(args, '--store-dir', DEFAULT_STORE_DIR), repository(args), pullRequest(args));
+}
+export async function runProjectionCommand(action, args) {
+    const store = new SQLiteRelayStore(storePath(args));
+    try {
+        if (action === 'conflicts' || action === 'list') {
+            const conflicts = await store.listProjectionConflicts();
+            console.log(JSON.stringify(conflicts, null, 2));
+            return;
+        }
+        if (action === 'resolve') {
+            const id = integerArg(args, '--projection-id', 0);
+            if (id <= 0)
+                throw new Error('projection resolve requires --projection-id ID');
+            const raw = arg(args, '--action', 'requeue');
+            if (raw !== 'requeue' && raw !== 'discard-local' && raw !== 'discard_local')
+                throw new Error('--action must be requeue or discard-local');
+            const resolution = raw === 'requeue' ? 'requeue' : 'discard_local';
+            const note = arg(args, '--note') || undefined;
+            const resolved = await store.resolveProjectionConflict(id, { action: resolution, ...(note ? { note } : {}) });
+            if (!resolved)
+                throw new Error(`Projection ${id} is not in a resolvable conflict state`);
+            console.log(`Resolved projection ${id} with ${resolution}`);
+            return;
+        }
+        throw new Error(`projection ${action || '<action>'} is not supported; use conflicts or resolve`);
+    }
+    finally {
+        store.close();
+    }
+}
+export function projectionHelp(action) {
+    if (action === 'resolve') {
+        return `Explicitly repair one classified projection conflict.
+
+Required: --projection-id ID --action requeue|discard-local, plus --store PATH or --repo OWNER/REPO --pr NUMBER.
+Actions:
+  requeue        Re-arm the recorded projection after the divergent side is reconciled
+  discard-local  Drop the blocked local mutation so a fresh one can be enqueued
+
+Never silently overwrites either side. The recorded diagnostic remains until resolution.`;
+    }
+    return `Inspect and explicitly repair deterministic V2 GitHub projection conflicts.
+
+Usage:
+  npx agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER [--store PATH]
+  npx agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local
+
+A deterministic same-id/different-definition append conflict is classified once, stops
+consuming retry budget, and retains structured diagnostic evidence. It is never
+auto-overwritten: an operator resolves it after reconciling the divergent definition.`;
+}

package/dist/cli.js

@@ -23,6 +23,7 @@ import { applyJobActivateAction, applyJobCancelAction } from './job-actions.js';
 import { resolveExecutionContext } from './execution-context.js';
 import { defaultWorkspaceRoot, resolveManagedProjectPath, resolveRepositoryProjectPath } from './workspace.js';
 import { runBlockerCommand } from './cli-blocker.js';
+import { runProjectionCommand } from './cli-projection.js';
 import { helpText, usage } from './cli-help.js';
 import { parseAgentGraph } from './agent-graph.js';
 import { runJobUnblockCommand, runTaskUnblockCommand } from './cli-unblock.js';
@@ -571,6 +572,11 @@ async function main() {
         await runBlockerCommand(action ?? '', blockerArgs);
         return;
     }
+    if (command === 'projection') {
+        const [action, ...projectionArgs] = args;
+        await runProjectionCommand(action ?? '', projectionArgs);
+        return;
+    }
     if (command === 'init') {
         const now = new Date().toISOString();
         const initialSchedule = scheduleFromArgs(args);

package/dist/projected-store.js

@@ -1,5 +1,6 @@
 import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
-import { sameTaskDefinition } from './store-task-definition.js';
+import { DurableDefinitionConflictError, isDurableDefinitionConflict, sameTaskDefinition } from './store-task-definition.js';
+import { decideProjectionFailure } from './workflow/projection-conflict-v2.js';
 function taskKey(task) { return `task:${task.jobId ?? ''}:${task.id}`; }
 function planKey(plan) { return `plan:${plan.jobId}:${plan.id}`; }
 function retryHeader(error, name) {
@@ -27,17 +28,60 @@ export function githubProjectionRetryAt(error, attempt, now = new Date()) {
     const backoffMs = Math.min(300_000, 1_000 * (2 ** Math.min(8, Math.max(0, attempt))));
     return new Date(now.getTime() + backoffMs);
 }
+const DEFINITION_CONFLICT_MESSAGE = /already exists with a different definition$/;
+/**
+ * Core deterministic-conflict classifier.
+ *
+ * A structured {@link DurableDefinitionConflictError} is authoritative; a plain error
+ * whose message matches the canonical GitHub marker conflict text is classified the
+ * same way so remote stores and legacy callers converge on one behavior.
+ */
 export function isTerminalProjectionFailure(item, error) {
+    if (item.operation !== 'append_task' && item.operation !== 'append_plan')
+        return false;
     const message = error instanceof Error ? error.message : String(error);
-    return (item.operation === 'append_task' || item.operation === 'append_plan')
-        && /already exists with a different definition$/.test(message);
+    return isDurableDefinitionConflict(error) || DEFINITION_CONFLICT_MESSAGE.test(message);
+}
+/** Builds durable diagnostic evidence even when a plain error carries no structured fields. */
+function conflictDiagnostic(item, error, detectedAt) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof DurableDefinitionConflictError) {
+        return {
+            kind: error.kind,
+            jobId: error.jobId,
+            subjectId: error.subjectId,
+            operation: item.operation,
+            operationKey: item.operationKey,
+            localDefinition: error.local,
+            remoteDefinition: error.remote,
+            divergingFields: [...error.divergingFields],
+            detectedAt,
+            message,
+        };
+    }
+    const payload = item.payload;
+    const kind = item.operation === 'append_plan' ? 'plan' : 'task';
+    return {
+        kind,
+        jobId: typeof payload?.value?.jobId === 'string' ? payload.value.jobId : '',
+        subjectId: typeof payload?.value?.id === 'string' ? payload.value.id : '',
+        operation: item.operation,
+        operationKey: item.operationKey,
+        localDefinition: payload?.value ?? item.payload ?? null,
+        remoteDefinition: null,
+        divergingFields: [],
+        detectedAt,
+        message,
+    };
 }
 export class GitHubProjectionWriter {
     relay;
     github;
-    constructor(relay, github) {
+    onConflict;
+    constructor(relay, github, onConflict) {
         this.relay = relay;
         this.github = github;
+        this.onConflict = onConflict;
     }
     async flushOnce(limit = 50, now = new Date()) {
         const items = await this.relay.claimDueProjections(limit, now);
@@ -51,8 +95,13 @@ export class GitHubProjectionWriter {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                if (isTerminalProjectionFailure(item, error))
-                    await this.relay.deadLetterProjection(item.id, message);
+                const deterministic = isTerminalProjectionFailure(item, error);
+                const decision = decideProjectionFailure({ deterministicDefinitionConflict: deterministic });
+                if (decision.accepted && decision.target === 'conflict') {
+                    const diagnostic = conflictDiagnostic(item, error, now.toISOString());
+                    await this.relay.recordProjectionConflict(item.id, diagnostic);
+                    await this.notifyConflict(diagnostic, message);
+                }
                 else {
                     await this.relay.retryProjection(item.id, message, githubProjectionRetryAt(error, item.attempts, now));
                     deferred += 1;
@@ -61,6 +110,16 @@ export class GitHubProjectionWriter {
         }
         return { projected, deferred };
     }
+    async notifyConflict(diagnostic, message) {
+        if (!this.onConflict)
+            return;
+        try {
+            await this.onConflict({ type: 'projection.conflict', status: 'conflict', visibility: 'orchestrator', message, data: diagnostic });
+        }
+        catch (error) {
+            process.stderr.write(`warning: projection conflict event unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
     async apply(item) {
         const payload = item.payload;
         switch (payload.operation) {
@@ -106,11 +165,11 @@ export class ProjectedDurableStore {
     relatedStore;
     projection;
     seededFacts;
-    constructor(relay, github, seed = null, relatedStore) {
+    constructor(relay, github, seed = null, relatedStore, onConflict) {
         this.relay = relay;
         this.github = github;
         this.relatedStore = relatedStore;
-        this.projection = new GitHubProjectionWriter(relay, github);
+        this.projection = new GitHubProjectionWriter(relay, github, onConflict);
         this.seededFacts = pullRequestFactsFromSeed(seed);
         if (this.seededFacts)
             void this.relay.savePullRequestFacts(this.seededFacts).catch(() => { });

package/dist/projection-outbox.js

@@ -0,0 +1,268 @@
+export const SCHEMA_VERSION = 5;
+const UNSAFE_QUEUED_KEY_SUFFIX = /:(?:queued|lost):\d+$/;
+/** Logical operation key recovered from a possibly queued/lost idempotency key. */
+export function logicalOperationKey(idempotencyKey) {
+    return idempotencyKey.replace(UNSAFE_QUEUED_KEY_SUFFIX, '');
+}
+export function rowToProjection(row) {
+    return {
+        id: Number(row.id),
+        idempotencyKey: row.idempotency_key,
+        operationKey: row.operation_key ?? logicalOperationKey(row.idempotency_key),
+        coalesceKey: row.coalesce_key,
+        operation: row.operation,
+        payload: JSON.parse(row.payload_json),
+        priority: Number(row.priority),
+        attempts: Number(row.attempts),
+        nextAttemptAt: row.next_attempt_at,
+        lastError: row.last_error,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function rowToConflict(row) {
+    const evidence = row.conflict_evidence_json ? JSON.parse(row.conflict_evidence_json) : {};
+    const resolution = row.conflict_resolution_json ? JSON.parse(row.conflict_resolution_json) : null;
+    const operationKey = row.operation_key ?? logicalOperationKey(row.idempotency_key);
+    return {
+        id: Number(row.id),
+        status: (row.status ?? 'conflict'),
+        operation: row.operation,
+        operationKey,
+        attempts: Number(row.attempts),
+        diagnostic: {
+            kind: evidence.kind ?? 'task',
+            jobId: String(evidence.jobId ?? ''),
+            subjectId: String(evidence.subjectId ?? ''),
+            operation: row.operation,
+            operationKey,
+            localDefinition: row.conflict_definition_json ? JSON.parse(row.conflict_definition_json) : null,
+            remoteDefinition: evidence.remoteDefinition ?? null,
+            divergingFields: Array.isArray(evidence.divergingFields) ? evidence.divergingFields.map(String) : [],
+            detectedAt: row.conflict_detected_at ?? row.updated_at,
+            message: String(evidence.message ?? row.last_error ?? 'projection definition conflict'),
+        },
+        resolution,
+    };
+}
+const OUTBOX_COLUMNS = 'id,idempotency_key,operation_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at,conflict_definition_json,conflict_evidence_json,conflict_detected_at,conflict_disposition,conflict_resolution_json';
+/**
+ * Durable projection outbox persistence.
+ *
+ * Owns the schema, pending/processing/conflict/dead state machine storage, coalescing,
+ * claiming, retry/backoff bookkeeping, deterministic-conflict diagnostics, and explicit repair.
+ * It is deliberately independent of Job/Task/Plan semantics: callers persist domain state
+ * separately and enqueue one projection request.
+ */
+export class ProjectionOutbox {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static createTableSql(table = 'projection_outbox') {
+        return `CREATE TABLE IF NOT EXISTS ${table} (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        operation_key TEXT,
+        coalesce_key TEXT,
+        operation TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        priority INTEGER NOT NULL DEFAULT 0,
+        status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','processing','conflict','dead')),
+        attempts INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at TEXT,
+        last_error TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        conflict_definition_json TEXT,
+        conflict_evidence_json TEXT,
+        conflict_detected_at TEXT,
+        conflict_disposition TEXT,
+        conflict_resolution_json TEXT
+      );`;
+    }
+    static createIndexSql() {
+        return `
+      CREATE INDEX IF NOT EXISTS projection_due_idx ON projection_outbox(status, next_attempt_at, priority DESC, id);
+      CREATE INDEX IF NOT EXISTS projection_coalesce_idx ON projection_outbox(coalesce_key, status);
+    `;
+    }
+    /** Rebuild a pre-v5 outbox, backfill logical operation keys, and classify legacy dead conflicts. */
+    static upgrade(db, previousVersion) {
+        const schema = db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='projection_outbox'").get();
+        const sql = schema?.sql ?? '';
+        const needsRebuild = sql.length > 0 && (!sql.includes("'conflict'") || !sql.includes('operation_key'));
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            if (needsRebuild) {
+                db.exec(`
+          DROP INDEX IF EXISTS projection_due_idx;
+          DROP INDEX IF EXISTS projection_coalesce_idx;
+          ALTER TABLE projection_outbox RENAME TO projection_outbox_legacy;
+          ${ProjectionOutbox.createTableSql()}
+          INSERT INTO projection_outbox(id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at)
+          SELECT id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at FROM projection_outbox_legacy;
+          DROP TABLE projection_outbox_legacy;
+        `);
+            }
+            db.exec(ProjectionOutbox.createIndexSql());
+            db.prepare(`
+        UPDATE projection_outbox
+        SET operation_key = CASE
+          WHEN operation_key IS NOT NULL AND operation_key<>'' THEN operation_key
+          WHEN idempotency_key GLOB '*:queued:*' THEN substr(idempotency_key, 1, instr(idempotency_key, ':queued:') - 1)
+          ELSE idempotency_key END
+        WHERE operation_key IS NULL OR operation_key=''
+      `).run();
+            const diagnostics = db.prepare(`
+        SELECT id,operation,idempotency_key,last_error,attempts,updated_at FROM projection_outbox
+        WHERE status='dead' AND last_error LIKE '%already exists with a different definition%'
+      `).all();
+            const promote = db.prepare(`
+        UPDATE projection_outbox
+        SET status='conflict', conflict_detected_at=?, conflict_disposition='classified_on_migration',
+            conflict_evidence_json=?, conflict_definition_json=COALESCE(conflict_definition_json, payload_json)
+        WHERE id=?
+      `);
+            for (const row of diagnostics) {
+                const evidence = JSON.stringify({ kind: row.operation === 'append_plan' ? 'plan' : 'task', subjectId: '', jobId: '', divergingFields: [], message: row.last_error ?? 'legacy deterministic projection conflict', migratedFromAttempts: Number(row.attempts), recoveredFromSchema: previousVersion });
+                promote.run(row.updated_at, evidence, row.id);
+            }
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    resetProcessing(now) {
+        this.db.prepare("UPDATE projection_outbox SET status='pending', updated_at=? WHERE status='processing'").run(now);
+    }
+    enqueue(request, now) {
+        const operationKey = logicalOperationKey(request.idempotencyKey);
+        if (request.coalesceKey) {
+            this.db.prepare(`
+        DELETE FROM projection_outbox
+        WHERE coalesce_key=? AND status='pending' AND operation_key<>?
+      `).run(request.coalesceKey, operationKey);
+        }
+        const existing = this.db.prepare('SELECT status FROM projection_outbox WHERE operation_key=? ORDER BY id DESC LIMIT 1')
+            .get(operationKey);
+        // A writer may be applying this key outside the transaction, or a deterministic
+        // conflict may already be recorded for it. Never rewrite that row's payload: its
+        // completion must only remove its own row, and a recorded conflict must stay the
+        // classification evidence until explicitly repaired. New mutations queue beside it.
+        const nextId = Number(this.db.prepare('SELECT COALESCE(MAX(id),0)+1 AS next_id FROM projection_outbox').get().next_id ?? 1);
+        const collides = existing?.status === 'processing' || existing?.status === 'conflict' || existing?.status === 'dead';
+        const idempotencyKey = collides ? `${operationKey}:queued:${nextId}` : operationKey;
+        this.db.prepare(`
+      INSERT INTO projection_outbox(
+        idempotency_key,operation_key,coalesce_key,operation,payload_json,priority,status,
+        attempts,next_attempt_at,last_error,created_at,updated_at
+      ) VALUES(?,?,?,?,?,?,'pending',0,NULL,NULL,?,?)
+      ON CONFLICT(idempotency_key) DO UPDATE SET
+        operation_key=excluded.operation_key,
+        coalesce_key=excluded.coalesce_key,
+        operation=excluded.operation,
+        payload_json=excluded.payload_json,
+        priority=MAX(projection_outbox.priority,excluded.priority),
+        status='pending',
+        next_attempt_at=NULL,
+        last_error=NULL,
+        updated_at=excluded.updated_at
+    `).run(idempotencyKey, operationKey, request.coalesceKey ?? null, request.operation, JSON.stringify(request.payload), request.priority ?? 0, now, now);
+    }
+    claimDue(limit, now) {
+        const observedAt = now.toISOString();
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const rows = this.db.prepare(`
+        SELECT ${OUTBOX_COLUMNS}
+        FROM projection_outbox
+        WHERE status='pending' AND (next_attempt_at IS NULL OR next_attempt_at<=?)
+        ORDER BY priority DESC, id ASC
+        LIMIT ?
+      `).all(observedAt, Math.max(1, Math.floor(limit)));
+            const mark = this.db.prepare("UPDATE projection_outbox SET status='processing', updated_at=? WHERE id=? AND status='pending'");
+            const claimed = [];
+            for (const row of rows) {
+                const result = mark.run(observedAt, row.id);
+                if (Number(result.changes) === 1)
+                    claimed.push({ ...row, updated_at: observedAt });
+            }
+            this.db.exec('COMMIT');
+            return claimed.map(rowToProjection);
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    complete(id) {
+        this.db.prepare('DELETE FROM projection_outbox WHERE id=?').run(id);
+    }
+    retry(id, error, nextAttemptAt) {
+        this.db.prepare(`
+      UPDATE projection_outbox
+      SET status='pending', attempts=attempts+1, next_attempt_at=?, last_error=?, updated_at=?
+      WHERE id=?
+    `).run(nextAttemptAt.toISOString(), error, new Date().toISOString(), id);
+    }
+    deadLetter(id, error) {
+        this.db.prepare(`
+      UPDATE projection_outbox
+      SET status='dead', attempts=attempts+1, next_attempt_at=NULL, last_error=?, updated_at=?
+      WHERE id=?
+    `).run(error, new Date().toISOString(), id);
+    }
+    recordConflict(id, diagnostic) {
+        const evidence = JSON.stringify({
+            kind: diagnostic.kind,
+            jobId: diagnostic.jobId,
+            subjectId: diagnostic.subjectId,
+            remoteDefinition: diagnostic.remoteDefinition,
+            divergingFields: diagnostic.divergingFields,
+            message: diagnostic.message,
+        });
+        this.db.prepare(`
+      UPDATE projection_outbox
+      SET status='conflict', attempts=attempts+1, next_attempt_at=NULL, last_error=?,
+          conflict_definition_json=?, conflict_evidence_json=?, conflict_detected_at=?,
+          conflict_disposition='awaiting_repair', conflict_resolution_json=NULL, updated_at=?
+      WHERE id=? AND status NOT IN ('conflict','dead')
+    `).run(diagnostic.message, JSON.stringify(diagnostic.localDefinition), evidence, diagnostic.detectedAt, diagnostic.detectedAt, id);
+    }
+    listConflicts() {
+        const rows = this.db.prepare(`
+      SELECT ${OUTBOX_COLUMNS} FROM projection_outbox WHERE status='conflict' ORDER BY id ASC
+    `).all();
+        return rows.map(rowToConflict);
+    }
+    /** Explicit repair: requeue the original projection, or discard the blocked local mutation for a fresh one. */
+    resolveConflict(id, resolution) {
+        const now = new Date().toISOString();
+        const record = this.db.prepare('SELECT status FROM projection_outbox WHERE id=?').get(id);
+        if (!record || record.status !== 'conflict')
+            return false;
+        const resolutionJson = JSON.stringify({ action: resolution.action, resolvedAt: now, ...(resolution.note ? { note: resolution.note } : {}) });
+        if (resolution.action === 'requeue') {
+            this.db.prepare(`
+        UPDATE projection_outbox
+        SET status='pending', attempts=0, next_attempt_at=NULL, conflict_disposition='requeued',
+            conflict_resolution_json=?, updated_at=?
+        WHERE id=? AND status='conflict'
+      `).run(resolutionJson, now, id);
+        }
+        else {
+            this.db.prepare('DELETE FROM projection_outbox WHERE id=? AND status=?').run(id, 'conflict');
+        }
+        return true;
+    }
+    conflictCount() { return this.count("status='conflict'"); }
+    pendingCount() { return this.count("status IN ('pending','processing')"); }
+    terminalCount() { return this.count("status='dead'"); }
+    count(where) {
+        const row = this.db.prepare(`SELECT COUNT(*) AS count FROM projection_outbox WHERE ${where}`).get();
+        return Number(row?.count ?? 0);
+    }
+}

package/dist/relay-store.js

@@ -2,7 +2,7 @@ import { DatabaseSync } from 'node:sqlite';
 import { dirname } from 'node:path';
 import { mkdirSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
-const SCHEMA_VERSION = 4;
+import { ProjectionOutbox, SCHEMA_VERSION, } from './projection-outbox.js';
 function newerRecord(local, remote) {
     if (!local)
         return structuredClone(remote);
@@ -30,24 +30,10 @@ export function mergeInboundJobSnapshot(local, remote) {
     }
     return base;
 }
-function rowToProjection(row) {
-    return {
-        id: Number(row.id),
-        idempotencyKey: row.idempotency_key,
-        coalesceKey: row.coalesce_key,
-        operation: row.operation,
-        payload: JSON.parse(row.payload_json),
-        priority: Number(row.priority),
-        attempts: Number(row.attempts),
-        nextAttemptAt: row.next_attempt_at,
-        lastError: row.last_error,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-    };
-}
 export class SQLiteRelayStore {
     path;
     db;
+    outbox;
     constructor(path) {
         this.path = path;
         if (path !== ':memory:')
@@ -55,8 +41,8 @@ export class SQLiteRelayStore {
         this.db = new DatabaseSync(path);
         this.db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON;');
         this.migrate();
-        this.db.prepare("UPDATE projection_outbox SET status='pending', updated_at=? WHERE status='processing'")
-            .run(new Date().toISOString());
+        this.outbox = new ProjectionOutbox(this.db);
+        this.outbox.resetProcessing(new Date().toISOString());
     }
     migrate() {
         this.db.exec(`
@@ -87,60 +73,15 @@ export class SQLiteRelayStore {
         sequence INTEGER,
         received_at TEXT NOT NULL
       );
-      CREATE TABLE IF NOT EXISTS projection_outbox (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        idempotency_key TEXT NOT NULL UNIQUE,
-        coalesce_key TEXT,
-        operation TEXT NOT NULL,
-        payload_json TEXT NOT NULL,
-        priority INTEGER NOT NULL DEFAULT 0,
-        status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','processing','dead')),
-        attempts INTEGER NOT NULL DEFAULT 0,
-        next_attempt_at TEXT,
-        last_error TEXT,
-        created_at TEXT NOT NULL,
-        updated_at TEXT NOT NULL
-      );
-      CREATE INDEX IF NOT EXISTS projection_due_idx
-        ON projection_outbox(status, next_attempt_at, priority DESC, id);
-      CREATE INDEX IF NOT EXISTS projection_coalesce_idx
-        ON projection_outbox(coalesce_key, status);
+      ${ProjectionOutbox.createTableSql()}
+      ${ProjectionOutbox.createIndexSql()}
     `);
         const current = this.db.prepare("SELECT value FROM relay_meta WHERE key='schema_version'").get();
         const version = current?.value ? Number(current.value) : 0;
         if (version > SCHEMA_VERSION)
             throw new Error(`Relay store schema ${version} is newer than supported ${SCHEMA_VERSION}`);
-        if (version < 4) {
-            const schema = this.db.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='projection_outbox'").get();
-            if (schema?.sql && !schema.sql.includes("'dead'")) {
-                this.db.exec(`
-          BEGIN IMMEDIATE;
-          DROP INDEX IF EXISTS projection_due_idx;
-          DROP INDEX IF EXISTS projection_coalesce_idx;
-          ALTER TABLE projection_outbox RENAME TO projection_outbox_v3;
-          CREATE TABLE projection_outbox (
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            idempotency_key TEXT NOT NULL UNIQUE,
-            coalesce_key TEXT,
-            operation TEXT NOT NULL,
-            payload_json TEXT NOT NULL,
-            priority INTEGER NOT NULL DEFAULT 0,
-            status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending','processing','dead')),
-            attempts INTEGER NOT NULL DEFAULT 0,
-            next_attempt_at TEXT,
-            last_error TEXT,
-            created_at TEXT NOT NULL,
-            updated_at TEXT NOT NULL
-          );
-          INSERT INTO projection_outbox(id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at)
-          SELECT id,idempotency_key,coalesce_key,operation,payload_json,priority,status,attempts,next_attempt_at,last_error,created_at,updated_at FROM projection_outbox_v3;
-          DROP TABLE projection_outbox_v3;
-          CREATE INDEX projection_due_idx ON projection_outbox(status, next_attempt_at, priority DESC, id);
-          CREATE INDEX projection_coalesce_idx ON projection_outbox(coalesce_key, status);
-          COMMIT;
-        `);
-            }
-        }
+        if (version < SCHEMA_VERSION)
+            ProjectionOutbox.upgrade(this.db, version);
         this.db.prepare("INSERT INTO relay_meta(key,value) VALUES('schema_version',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value")
             .run(String(SCHEMA_VERSION));
     }
@@ -257,11 +198,14 @@ export class SQLiteRelayStore {
     `).run(eventId, stream, sequence, new Date().toISOString());
         return Number(result.changes) === 1;
     }
+    enqueueProjectionInTransaction(request, now) {
+        this.outbox.enqueue(request, now);
+    }
     async enqueueProjection(request) {
         const now = new Date().toISOString();
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            this.enqueueProjectionInTransaction(request, now);
+            this.outbox.enqueue(request, now);
             this.db.exec('COMMIT');
         }
         catch (error) {
@@ -269,90 +213,24 @@ export class SQLiteRelayStore {
             throw error;
         }
     }
-    enqueueProjectionInTransaction(request, now) {
-        if (request.coalesceKey) {
-            this.db.prepare(`
-        DELETE FROM projection_outbox
-        WHERE coalesce_key=? AND status='pending' AND idempotency_key<>?
-      `).run(request.coalesceKey, request.idempotencyKey);
-        }
-        const existing = this.db.prepare('SELECT status FROM projection_outbox WHERE idempotency_key=?').get(request.idempotencyKey);
-        // A writer may be applying this key outside the transaction. Never rewrite its
-        // payload: its completion must only remove its own row, not a newer mutation.
-        const nextId = Number(this.db.prepare('SELECT COALESCE(MAX(id),0)+1 AS next_id FROM projection_outbox').get().next_id ?? 1);
-        const idempotencyKey = existing?.status === 'processing' || existing?.status === 'dead'
-            ? `${request.idempotencyKey}:queued:${nextId}`
-            : request.idempotencyKey;
-        this.db.prepare(`
-      INSERT INTO projection_outbox(
-        idempotency_key,coalesce_key,operation,payload_json,priority,status,
-        attempts,next_attempt_at,last_error,created_at,updated_at
-      ) VALUES(?,?,?,?,?,'pending',0,NULL,NULL,?,?)
-      ON CONFLICT(idempotency_key) DO UPDATE SET
-        coalesce_key=excluded.coalesce_key,
-        operation=excluded.operation,
-        payload_json=excluded.payload_json,
-        priority=MAX(projection_outbox.priority,excluded.priority),
-        status='pending',
-        next_attempt_at=NULL,
-        last_error=NULL,
-        updated_at=excluded.updated_at
-    `).run(idempotencyKey, request.coalesceKey ?? null, request.operation, JSON.stringify(request.payload), request.priority ?? 0, now, now);
-    }
     async claimDueProjections(limit = 50, now = new Date()) {
-        const observedAt = now.toISOString();
-        this.db.exec('BEGIN IMMEDIATE');
-        try {
-            const rows = this.db.prepare(`
-        SELECT id,idempotency_key,coalesce_key,operation,payload_json,priority,
-               attempts,next_attempt_at,last_error,created_at,updated_at
-        FROM projection_outbox
-        WHERE status='pending' AND (next_attempt_at IS NULL OR next_attempt_at<=?)
-        ORDER BY priority DESC, id ASC
-        LIMIT ?
-      `).all(observedAt, Math.max(1, Math.floor(limit)));
-            const mark = this.db.prepare("UPDATE projection_outbox SET status='processing', updated_at=? WHERE id=? AND status='pending'");
-            const claimed = [];
-            for (const row of rows) {
-                const result = mark.run(observedAt, row.id);
-                if (Number(result.changes) === 1)
-                    claimed.push({ ...row, updated_at: observedAt });
-            }
-            this.db.exec('COMMIT');
-            return claimed.map(rowToProjection);
-        }
-        catch (error) {
-            this.db.exec('ROLLBACK');
-            throw error;
-        }
-    }
-    async completeProjection(id) {
-        this.db.prepare('DELETE FROM projection_outbox WHERE id=?').run(id);
-    }
-    async retryProjection(id, error, nextAttemptAt) {
-        this.db.prepare(`
-      UPDATE projection_outbox
-      SET status='pending', attempts=attempts+1, next_attempt_at=?, last_error=?, updated_at=?
-      WHERE id=?
-    `).run(nextAttemptAt.toISOString(), error, new Date().toISOString(), id);
-    }
-    async deadLetterProjection(id, error) {
-        this.db.prepare(`
-      UPDATE projection_outbox
-      SET status='dead', attempts=attempts+1, next_attempt_at=NULL, last_error=?, updated_at=?
-      WHERE id=?
-    `).run(error, new Date().toISOString(), id);
-    }
-    async pendingProjectionCount() {
-        const row = this.db.prepare("SELECT COUNT(*) AS count FROM projection_outbox WHERE status IN ('pending','processing')").get();
-        return Number(row?.count ?? 0);
-    }
-    async terminalProjectionCount() {
-        const row = this.db.prepare("SELECT COUNT(*) AS count FROM projection_outbox WHERE status='dead'").get();
-        return Number(row?.count ?? 0);
+        return this.outbox.claimDue(limit, now);
     }
+    async completeProjection(id) { this.outbox.complete(id); }
+    async retryProjection(id, error, nextAttemptAt) { this.outbox.retry(id, error, nextAttemptAt); }
+    async deadLetterProjection(id, error) { this.outbox.deadLetter(id, error); }
+    async recordProjectionConflict(id, diagnostic) { this.outbox.recordConflict(id, diagnostic); }
+    async listProjectionConflicts() { return this.outbox.listConflicts(); }
+    async resolveProjectionConflict(id, resolution) { return this.outbox.resolveConflict(id, resolution); }
+    async conflictProjectionCount() { return this.outbox.conflictCount(); }
+    async pendingProjectionCount() { return this.outbox.pendingCount(); }
+    async terminalProjectionCount() { return this.outbox.terminalCount(); }
     close() { this.db.close(); }
 }
+/** Canonical on-disk Relay Store location for one managed GitHub pull request. */
+export function relayStorePath(directory, repository, prNumber) {
+    return directory + '/' + `${repository.replace('/', '_')}-${prNumber}.db`;
+}
 export async function discoverLocalRelayStoreSnapshots(directory) {
     let names;
     try {

package/dist/relayd.js

@@ -10,10 +10,11 @@ import { RepositoryWorkerPool, aggregateManagedGitHubJobs } from './pool.js';
 import { Reconciler } from './reconciler.js';
 import { dashboardManagedJobs, GitHubStore, InMemoryStore, loadManagedGitHubPullRequestSnapshotGraphql, withGitHubRequestContext } from './store.js';
 import { ProjectedDurableStore } from './projected-store.js';
-import { discoverLocalRelayStoreSnapshots, SQLiteRelayStore } from './relay-store.js';
+import { discoverLocalRelayStoreSnapshots, relayStorePath, SQLiteRelayStore } from './relay-store.js';
 import { githubAuthContext } from './github-auth.js';
 import { dashboardJobAction, isEntrypoint, runtimePlanner, runtimeReviewer, startService, SERVICE_DEFAULTS } from './cli.js';
 import { eventBusResolutionMessage, publishOrchestratorTaskCompletion, resolveEventBus } from './cli-support.js';
+import { eventFor } from './events.js';
 import { applyJobActivateAction } from './job-actions.js';
 import { applyOrchestratorCompleteAction } from './task-actions.js';
 import { dashboardJobSetState, dashboardTaskAction, dashboardTaskSetState } from './dashboard-actions.js';
@@ -147,11 +148,17 @@ export async function runDaemon(argv) {
         const key = `${repository}#${prNumber}`;
         let relay = relayStores.get(key);
         if (!relay) {
-            relay = new SQLiteRelayStore(join(homedir(), '.agents-relay', 'stores', `${repository.replace('/', '_')}-${prNumber}.db`));
+            relay = new SQLiteRelayStore(relayStorePath(join(homedir(), '.agents-relay', 'stores'), repository, prNumber));
             relayStores.set(key, relay);
         }
         const github = new GitHubStore(client, repository, prNumber, trusted, seed);
-        const projected = new ProjectedDurableStore(relay, github, seed ?? null, (relatedRepository, relatedPrNumber) => runtimeStore(relatedRepository, relatedPrNumber));
+        const projected = new ProjectedDurableStore(relay, github, seed ?? null, (relatedRepository, relatedPrNumber) => runtimeStore(relatedRepository, relatedPrNumber), conflict => {
+            process.stderr.write(`projection conflict for ${repository}#${prNumber}: ${conflict.message} (fields: ${conflict.data.divergingFields.join(', ') || 'unknown'}; repair with agents-relay projection resolve)\n`);
+            if (bus) {
+                const jobId = conflict.data.jobId || conflictJobId(repository, prNumber);
+                void Promise.resolve().then(() => bus.publish(eventFor(jobId, 'projection', null, 'projection.conflict', 'blocked', conflict.message, 'orchestrator', { ...conflict.data, repository, prNumber }))).catch(() => undefined);
+            }
+        });
         projectionWriters.set(key, projected.projection);
         return projected;
     };
@@ -483,3 +490,6 @@ export async function runDaemon(argv) {
 }
 if (isEntrypoint(import.meta.url))
     runDaemon(process.argv.slice(2)).catch(error => { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; });
+function conflictJobId(repository, prNumber) {
+    return `${repository}#${prNumber}`;
+}

package/dist/store-github.js

@@ -1,5 +1,5 @@
 import { parseAgent, parseJob, parsePlan, parseTask, renderAgentComment, renderJobBody, renderPlanComment, renderTaskComment, JOB_MARKER } from './markers.js';
-import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
+import { DurableDefinitionConflictError, isTaskForJob, planDefinitionDivergence, samePlanDefinition, sameTaskDefinition, taskDefinitionDivergence } from './store-task-definition.js';
 import { registerBlockerDependency, resolveBlockerDependencies } from './blockers.js';
 const TASK_WRITE_OVERLAY = new Map();
 const PLAN_WRITE_OVERLAY = new Map();
@@ -322,8 +322,8 @@ export class GitHubStore {
             return;
         }
         const existing = parsePlan(matches[0].body);
-        if (!existing || JSON.stringify({ ...existing, planUrl: undefined }) !== JSON.stringify({ ...plan, planUrl: undefined }))
-            throw new Error(`Plan ${plan.id} already exists with a different definition`);
+        if (!existing || !samePlanDefinition(existing, plan))
+            throw new DurableDefinitionConflictError('plan', 'append_plan', plan.jobId, plan.id, plan, existing ?? null, existing ? planDefinitionDivergence(existing, plan) : []);
         for (const duplicate of matches.slice(1))
             await this.deleteComment(duplicate);
     }
@@ -357,8 +357,9 @@ export class GitHubStore {
             return;
         }
         const parsed = matches.map(comment => ({ comment, task: parseTask(comment.body) }));
-        if (parsed.some(item => !sameTaskDefinition(item.task, task)))
-            throw new Error(`Task ${task.id} already exists with a different definition`);
+        const divergent = parsed.find(item => !sameTaskDefinition(item.task, task));
+        if (divergent)
+            throw new DurableDefinitionConflictError('task', 'append_task', task.jobId ?? '', task.id, task, divergent.task, taskDefinitionDivergence(divergent.task, task));
         for (const duplicate of parsed.slice(1))
             await this.deleteComment(duplicate.comment);
     }

package/dist/store-task-definition.js

@@ -1,3 +1,37 @@
+/**
+ * Deterministic conflict between two different definitions that claim the same durable id.
+ *
+ * This is not a transient projection failure: the same id is already occupied by a
+ * different immutable definition, so retrying the same append can never succeed.
+ * Callers classify it once, stop consuming retry budget, and record diagnostic evidence.
+ */
+export class DurableDefinitionConflictError extends Error {
+    kind;
+    operation;
+    jobId;
+    subjectId;
+    local;
+    remote;
+    divergingFields;
+    deterministic = true;
+    constructor(kind, operation, jobId, subjectId, local, remote, divergingFields) {
+        super(kind === 'task'
+            ? `Task ${subjectId} already exists with a different definition`
+            : `Plan ${subjectId} already exists with a different definition`);
+        this.kind = kind;
+        this.operation = operation;
+        this.jobId = jobId;
+        this.subjectId = subjectId;
+        this.local = local;
+        this.remote = remote;
+        this.divergingFields = divergingFields;
+        this.name = 'DurableDefinitionConflictError';
+    }
+}
+export function isDurableDefinitionConflict(error) {
+    return error instanceof DurableDefinitionConflictError
+        || (typeof error === 'object' && error !== null && error.name === 'DurableDefinitionConflictError');
+}
 function immutableTaskDefinition(task) {
     const routing = task.routing ? {
         provider: task.routing.provider, model: task.routing.model, profile: task.routing.profile,
@@ -12,6 +46,35 @@ function immutableTaskDefinition(task) {
 export function sameTaskDefinition(left, right) {
     return JSON.stringify(immutableTaskDefinition(left)) === JSON.stringify(immutableTaskDefinition(right));
 }
+/** Plan identity ignores the resolved comment URL, which is projection metadata rather than definition. */
+export function planDefinition(plan) {
+    const { planUrl: _planUrl, ...rest } = plan;
+    return rest;
+}
+export function samePlanDefinition(left, right) {
+    return JSON.stringify(planDefinition(left)) === JSON.stringify(planDefinition(right));
+}
+function observableDefinition(kind, definition) {
+    if (typeof definition !== 'object' || definition === null)
+        return {};
+    if (kind === 'task')
+        return immutableTaskDefinition(definition);
+    const { planUrl: _planUrl, ...rest } = definition;
+    return rest;
+}
+/** Top-level field names whose definition values diverge; enough to diagnose a conflicted id. */
+export function divergingDefinitionFields(kind, left, right) {
+    const observed = observableDefinition(kind, left);
+    const other = observableDefinition(kind, right);
+    const keys = [...new Set([...Object.keys(observed), ...Object.keys(other)])].sort();
+    return keys.filter(key => JSON.stringify(observed[key]) !== JSON.stringify(other[key]));
+}
+export function taskDefinitionDivergence(left, right) {
+    return divergingDefinitionFields('task', left, right);
+}
+export function planDefinitionDivergence(left, right) {
+    return divergingDefinitionFields('plan', left, right);
+}
 export function isTaskForJob(task, jobId, soleTrustedJob) {
     if (task.jobId === jobId)
         return true;

package/dist/store.js

@@ -1,5 +1,5 @@
 import { parseAgent, parseJob, parsePlan, parseTask, renderAgentComment, renderJobComment, renderPlanComment, renderTaskComment, AGENT_MARKER, JOB_MARKER, PLAN_MARKER, TASK_MARKER } from './markers.js';
-import { isTaskForJob, sameTaskDefinition } from './store-task-definition.js';
+import { DurableDefinitionConflictError, isTaskForJob, planDefinitionDivergence, samePlanDefinition, sameTaskDefinition, taskDefinitionDivergence } from './store-task-definition.js';
 import { parsePackagePublicationMarker } from './github-webhook.js';
 function publicationFromComments(rows, trustedAuthors) {
     const allowed = rows.filter(item => {
@@ -95,9 +95,9 @@ export class InMemoryStore {
     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);
-        if (current && JSON.stringify(current) === JSON.stringify(plan))
+        if (current && samePlanDefinition(current, plan))
             return;
-        throw new Error(`Plan ${plan.id} already exists with a different definition`);
+        throw new DurableDefinitionConflictError('plan', 'append_plan', plan.jobId, plan.id, plan, current ?? null, current ? planDefinitionDivergence(current, plan) : []);
     } this.values.set(key, renderPlanComment(plan)); }
     async savePlan(plan) { this.values.set(`${PLAN_MARKER}:${plan.jobId}:${plan.id}`, renderPlanComment(plan)); }
     async appendTask(task) {
@@ -107,7 +107,7 @@ export class InMemoryStore {
             const current = parseTask(existing);
             if (current && sameTaskDefinition(current, task))
                 return;
-            throw new Error(`Task ${task.id} already exists with a different definition`);
+            throw new DurableDefinitionConflictError('task', 'append_task', task.jobId ?? '', task.id, task, current ?? null, current ? taskDefinitionDivergence(current, task) : []);
         }
         this.values.set(key, renderTaskComment(task));
     }

package/dist/workflow/projection-conflict-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/projection-conflict.mmd', import.meta.url), 'utf8');
+const boolGuard = (name) => (facts) => facts.durableFacts[name] === true;
+export const projectionConflictV2 = new GraphRuntime(source, {
+    states: new Set(['classify', 'retry', 'conflict']),
+    guards: { deterministicDefinitionConflict: boolGuard('deterministicDefinitionConflict') },
+    actions: {},
+    events: { 'projection.failed': { id: 'projection.failed' } },
+});
+/**
+ * Core projection-failure disposition policy.
+ *
+ * A deterministic same-id/different-definition conflict stops consuming retry budget;
+ * any other failure keeps the normal backoff/retry path. This branch is owned by the
+ * canonical Mermaid graph, not by a procedural `if` in the projection writer.
+ */
+export function decideProjectionFailure(facts) {
+    return dispatchWorkflowGraphSync(projectionConflictV2, {
+        initialState: 'classify',
+        input: { transport: 'event', id: 'projection.failed', payload: {} },
+        durableFacts: facts,
+        maxSteps: 1,
+    });
+}

package/package.json

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

package/workflow/projection-conflict.mmd

@@ -0,0 +1,11 @@
+flowchart LR
+%% relay: initial classify
+classify["state: classify"]
+retry["state: retry"]
+conflict["state: conflict"]
+
+deterministic["guard: deterministicDefinitionConflict"]
+
+classify -->|on: projection.failed| deterministic
+deterministic -->|true| conflict
+deterministic -->|false| retry