agents-relay 2.0.149 → 2.0.151

package/dist/workflow/projection-conflict-v2.js

@@ -3,19 +3,36 @@ 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;
+const guards = {
+    deterministicDefinitionConflict: boolGuard('deterministicDefinitionConflict'),
+    'projection.recoveryInProgress': boolGuard('recoveryInProgress'),
+    'projection.recoveryEligible': (facts) => {
+        const values = facts.durableFacts;
+        return values.jobState === 'COMPLETED' && values.mergeSucceeded === true
+            && values.projectionStrategy === 'target_ref_push' && values.divergenceConfirmed === true
+            && values.remoteShaAvailable === true
+            && values.sameIdempotencyKey !== true && values.recoveryInProgress !== true
+            && Number(values.attempts ?? 0) < Number(values.maxAttempts ?? 0);
+    },
+    'projection.recoveryExhausted': (facts) => {
+        const values = facts.durableFacts;
+        return values.jobState === 'COMPLETED' && values.divergenceConfirmed === true && values.remoteShaAvailable === true
+            && values.sameIdempotencyKey !== true && values.recoveryInProgress !== true
+            && Number(values.attempts ?? 0) >= Number(values.maxAttempts ?? 0);
+    },
+    'projection.retryAvailable': (facts) => facts.durableFacts.taskRetryAvailable === true
+        && Number(facts.durableFacts.attempts ?? 0) < Number(facts.durableFacts.maxAttempts ?? 0),
+    'projection.repairReviewed': (facts) => facts.durableFacts.repairTaskState === 'SUCCEEDED' && facts.durableFacts.reviewOutcome === 'approved',
+    'projection.repairFailed': (facts) => facts.durableFacts.repairTaskState === 'FAILED' || facts.durableFacts.repairTaskState === 'BLOCKED'
+        || facts.durableFacts.reviewOutcome === 'blocked' || facts.durableFacts.reviewTaskState === 'FAILED',
+};
 export const projectionConflictV2 = new GraphRuntime(source, {
-    states: new Set(['classify', 'retry', 'conflict']),
-    guards: { deterministicDefinitionConflict: boolGuard('deterministicDefinitionConflict') },
-    actions: {},
-    events: { 'projection.failed': { id: 'projection.failed' } },
+    states: new Set(['classify', 'repairing', 'retry', 'conflict', 'escalated', 'projected']),
+    guards,
+    actions: Object.fromEntries(['projection.createRecoveryTask', 'effect.projectLocalMerge', 'projection.escalate'].map(id => [id, { id }])),
+    events: Object.fromEntries(['projection.failed', 'projection.delivery_failed', 'projection.delivered', 'reconcile'].map(id => [id, { id }])),
 });
-/**
- * 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.
- */
+/** The decision is graph-owned; callers supply SQLite and inspected Git facts. */
 export function decideProjectionFailure(facts) {
     return dispatchWorkflowGraphSync(projectionConflictV2, {
         initialState: 'classify',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-relay",
-  "version": "2.0.149",
+  "version": "2.0.151",
   "description": "Durable async agent jobs coordinated through GitHub pull requests",
   "repository": {
     "type": "git",
@@ -20,13 +20,14 @@
     "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: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-cli-actions.test.mjs test/verification/l3-planner-round.test.mjs test/verification/full-recovery-gates.test.mjs test/verification/production-wiring.test.mjs",
+    "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/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",
     "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"
+    "test:verification:l2:live": "node test/verification/l2/live-provider.mjs",
+    "test:l2:agents": "npm run build && node test/l2-agent-prompts/evaluate.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/skills/agents-relay/SKILL.md

@@ -54,7 +54,7 @@ The event must carry the exact durable `job_id` and `task_id`. Progress events a
 Agents Relay maps those terminal events to durable state:
 - `task.completed` → `SUCCEEDED`
 - `task.failed` → `FAILED`
-Relay may authoritatively move a Task to `BLOCKED` for an external condition and may resume it only through an authorized unblock operation. A human response resumes the blocked Troubleshooter, not the failed original Task.
+Relay may authoritatively move a Task to `BLOCKED` for an external condition and may resume it only through an authorized unblock operation. A human response is an append-only Task Comment and resumes the blocked Troubleshooter, not the failed original Task. Task input remains stable; recovery agents receive current authoritative state and relevant comments as execution context.
 
 A model-backed task must not launch without an event bus. If no terminal event arrives before the task timeout, Relay records an explicit timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
 

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

@@ -17,7 +17,7 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
 
 ## Recovery loop
 
-1. Retrieve the durable original Job and failed/blocked Task from GitHub.
+1. Retrieve the durable original Job and Task from the authoritative Relay store with `agents-relay task context`; GitHub is only an optional projection and is never lifecycle authority.
 2. **Mandatory before diagnosis:** retrieve the failed Task's task-scoped lifecycle event history. When the local Relay dashboard is available, use `GET http://127.0.0.1:8787/api/events?job=<job_id>&task=<task_id>&limit=200`. Inspect event order, type/status, source, data/phase, execution IDs, duplicates, missing expected lifecycle events, and late events. Then inspect task error/failureReason, worker selection, routing, attempt count, task input/output contract, PR state, and relevant runtime/service logs.
 3. Classify the blocker:
    - transient execution/delivery/lease failure;
@@ -32,8 +32,8 @@ Read and follow the shared Task / Job contract and orchestrator P0/self-job work
    - For task-local failure, make the smallest durable repair in the original Job/PR when that is within scope.
    - For a shared platform/runtime defect, first create or reuse the owning blocker P0/self-job. If it can be completed inside this recovery execution, fix/verify it and retry the original Task. If it cannot be completed now, register the original Task with `agents-relay blocker add` on that blocker Job and finish this Troubleshooter task; do not stay running while waiting for another Job.
    - For a suspected genuine human/external blocker, do not publish `task.blocked` and do not branch on Neo's result yourself. Invoke `agents-relay escalation` with the original intent, blocker, and relevant context. The canonical graph owns the `resolved`, `failed`, and `needs_user` outcomes. When it returns `needs_user`, call Relay's `task escalate` operation with the concrete required action, resolution condition, and diagnostic context. Relay records the escalation and blocks this Troubleshooter; no worker remains running while waiting.
-7. For an immediate repair, only after the blocker is removed run `agents-relay task recover` for the original Task with this Troubleshooter's recovery Task ID and reconcile its Job. An authorized human response resumes this same Troubleshooter with its diagnostic context; verify the action before requesting original-task recovery. For deferred repair, rely on the durable blocker relation: merge-mode blockers wake matching dependents after merge; release/deploy/runtime blockers use `--resolution verified` and `agents-relay blocker resolve` only after verification.
-8. Verify durable evidence that the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
+7. For an immediate repair, only after the blocker is removed request `agents-relay task recover` with this Troubleshooter's recovery Task ID, then reconcile the original Job. Verify the SQLite postcondition: original Task state QUEUED, expected resolution and recovery correlation. An authorized human response is a Task Comment, not a rewrite of Task input. Retain historical conditions as provenance, independently verify the original failing execution context, and do not submit an identical escalation with no new evidence. Deferred repair uses the durable blocker relation: merge-mode blockers wake dependents after merge; release/deploy/runtime blockers require `--resolution verified` and `agents-relay blocker resolve` only after verification.
+8. Verify durable evidence the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
 9. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.
 
 ## Rules

package/skills/agents-relay/contracts/event-contract.md

@@ -25,7 +25,7 @@ A Reviewer must **not** publish unstructured `task.completed`: missing verdict o
 
 Only a real user action merits escalation. Troubleshooter invokes the Relay escalation operation, specifying the required action, resolution condition, and diagnostic context. Relay durably records the human action and blocks **the Troubleshooter Task**, leaving the original failed Task `FAILED`. This is a Relay state transition, not a third agent terminal event.
 
-When the human responds, the **Troubleshooter Task** is authoritatively unblocked and resumed with its prior context plus the response. Troubleshooter independently verifies resolution, requests an authorized original Task recovery, and only then publishes its own `task.completed`. If unresolved, it continues diagnosis or escalates again; human assertion alone is not technical verification.
+When the human responds, Relay records the response as an append-only Task Comment and authoritatively unblocks the **Troubleshooter Task**. The stable Task input is unchanged. Troubleshooter receives current authoritative state and relevant comments, independently verifies the response against the original failing execution context, requests an authorized original Task recovery, and only then publishes its own `task.completed`. A repeated identical escalation without new evidence is idempotent. If unresolved, it continues diagnosis or escalates again; human assertion alone is not technical verification.
 
 See [task-recovery-flows.md](task-recovery-flows.md) for unified architecture, overall flow, failure recovery, and post-blocked resumption.
 

package/skills/agents-relay/contracts/task-job-contract.md

@@ -32,6 +32,13 @@ A later Planner round must inspect the existing semantic tree and attach review,
 
 A Task input records **what is known and what has already been decided before execution**. A Task result records **what execution discovered and what was actually done**.
 
+After creation, keep `Task.input` stable as the objective and initial evidence.
+Responses, resolution changes, and escalation history belong in append-only
+Task Comments. SQLite atomically records typed comments with authoritative
+resolution/escalation mutations; PR-bound Jobs project those comments through
+the durable idempotent projection outbox. Comments supplement current state and
+never replace `Task.resolution` or `Task.escalation`.
+
 Task input should include, as applicable:
 
 - goal and observed behavior;

package/skills/agents-relay/contracts/task-recovery-flows.md

@@ -1,6 +1,6 @@
 # Task Failure Recovery and Human Escalation — Agreed Target Design
 
-**Status:** Design agreement; not an assertion of current implementation. This document describes two flows. Existing runtime, workflow graphs, and agent instructions may need changes to conform.
+**Status:** Current recovery contract. SQLite Task snapshots retain append-only typed comments alongside authoritative state.
 
 ## Principles and ownership
 
@@ -133,3 +133,20 @@ flowchart TD
 - Align escalation graph, CLI, reconciler, and unblock commands so human intervention blocks **Troubleshooter**, not the original failed Task; preserve the original failure and correlated recovery context.
 - Ensure the blocked Troubleshooter can resume after an authorized human unblock rather than being treated as a finished terminal execution.
 - Add integrated checks: technical retry, blocker-Job handoff, human request/block, human unblock/resume, failed verification/re-escalation, stale/duplicate responses, and correct original-Task retry.
+
+## Durable recovery history
+
+`Task.input` remains the stable objective and original evidence. `Task.resolution` and
+`Task.escalation` remain the current authoritative states; comments are append-only
+history, not a second state authority. SQLite mutation transactions compare the
+before/after authoritative values and append typed comments with Job, Task,
+execution, transition, and idempotency identity in the same commit. Do not add a
+`resolutionHistory` field.
+
+Human responses are comments. Resuming a Troubleshooter must not rewrite its
+input or append a stale “Required resolution condition” as new objective text.
+The condition remains in escalation provenance. Reviewer and Troubleshooter
+prompts receive current authoritative state and relevant task comments as runtime
+context; Troubleshooters independently verify a response against evidence from
+the original failing execution. Repeating an identical escalation with unchanged
+evidence is idempotent.

package/workflow/projection-conflict.mmd

@@ -1,15 +1,66 @@
 ---
 title: Projection Conflict
-description: Detects and resolves conflicting workflow state projections against authoritative facts.
+description: Recover local-main and origin-main divergence after a completed Job's GitHub projection fails.
+name: projection-conflict
+authority: SQLite Relay Job snapshot
+trigger: projection.delivery_failed
+idempotency: job-id plus observed origin/main SHA
+actions:
+  - projection.createRecoveryTask
+  - projection.escalate
+effects:
+  - effect.projectLocalMerge
+guards:
+  - deterministicDefinitionConflict
+  - projection.recoveryEligible
+  - projection.recoveryExhausted
+  - projection.recoveryInProgress
+  - projection.retryAvailable
+  - projection.repairReviewed
+  - projection.repairFailed
 ---
 flowchart LR
 %% relay: initial classify
 classify["state: classify"]
-retry["state: retry"]
 conflict["state: conflict"]
+repairing["state: repairing"]
+retry["state: retry"]
+escalated["state: escalated"]
+projected["state: projected"]
 
+eligible["guard: projection.recoveryEligible"]
+inProgress["guard: projection.recoveryInProgress"]
 deterministic["guard: deterministicDefinitionConflict"]
+exhausted["guard: projection.recoveryExhausted"]
+retryAvailable["guard: projection.retryAvailable"]
+reviewed["guard: projection.repairReviewed"]
+repairFailed["guard: projection.repairFailed"]
+createTask["action: projection.createRecoveryTask"]
+retryProjection["action: effect.projectLocalMerge"]
+escalate["action: projection.escalate"]
 
+classify -->|on: projection.delivery_failed| inProgress
+inProgress -->|true| classify
+inProgress -->|false| eligible
 classify -->|on: projection.failed| deterministic
 deterministic -->|true| conflict
 deterministic -->|false| retry
+eligible -->|true| createTask
+eligible -->|false| exhausted
+exhausted -->|true| escalate
+exhausted -->|false| classify
+createTask --> repairing
+
+repairing -->|on: reconcile| reviewed
+retry -->|on: reconcile| retryAvailable
+reviewed -->|true| retryAvailable
+retryAvailable -->|true| retryProjection
+retryAvailable -->|false| escalate
+reviewed -->|false| repairFailed
+repairFailed -->|true| escalate
+repairFailed -->|false| repairing
+retryProjection --> retry
+escalate --> escalated
+
+retry -->|on: projection.delivered| projected
+retry -->|on: projection.delivery_failed| eligible