agents-relay 2.0.195 → 2.0.197

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,133 +1,47 @@
1
1
  ---
2
2
  name: agents-relay
3
- description: Use when work needs durable, multi-agent orchestration across turns or processes - plan and execute Jobs/Tasks, coordinate dependencies and reviews, recover failures, and track authoritative lifecycle events. Also use for content-generation workflows (research, story, production, human review, publication) that need explicit agent roles and handoff boundaries. Not for simple one-shot tasks with no durable coordination.
4
- requires:
5
- skills:
6
- - daemon-service-manage
3
+ description: Use Agents Relay for durable multi-step or multi-agent work that needs Jobs and Tasks, planning, dependencies, independent review, failure recovery, human escalation, or progress across sessions. Also use it for content production with real approval/handoff boundaries. Use direct tools instead for one-shot work without durable coordination.
7
4
  ---
8
5
 
9
6
  # Agents Relay
10
7
 
11
- Use Agents Relay when an orchestrator needs durable delegated work that survives the current process.
8
+ Agents Relay manages durable Jobs and Tasks. Use its CLI for Job/Task state and actions; do not read its private storage, GitHub projections, or internal service APIs. Prefer completing simple, non-delegated work directly without Relay.
12
9
 
13
- ## Required shared contract
10
+ ## 1. Choose and start a Job
14
11
 
15
- For unified agent terminal events and role-specific results, see `contracts/event-contract.md` and `contracts/task-recovery-flows.md`.
12
+ Use Relay when the objective requires independent Tasks, durable progress, retries, review, or cross-session handoffs. Capture the full user objective, decisions, constraints, acceptance checks, and delivery expectations in standalone Markdown before creating a Job. A fresh agent must be able to act without the originating conversation. Put a Mermaid diagram before its explanation only when it clarifies a real workflow.
16
13
 
17
- Before creating, planning, reviewing, or managing a job/task, read and follow `contracts/task-job-contract.md`. This is the canonical producer/runtime protocol for story size, lifecycle events, review, and auto-merge.
14
+ For ordinary CLI use, consult `npx agents-relay --help` and `npx agents-relay <command> --help` rather than memorizing all flags. Examples:
18
15
 
19
- ## Content-generation workflow
16
+ ```sh
17
+ npx agents-relay job create --repo OWNER/REPO --title "Objective" --objective-file job.md --initial-plan
18
+ npx agents-relay job show --repo OWNER/REPO --id JOB_ID
19
+ npx agents-relay task list --repo OWNER/REPO --id JOB_ID
20
+ ```
20
21
 
21
- For content-generation objectives, read `workflows/content-generation.md` before choosing agents, review boundaries, or durable Tasks. This workflow is a planning guide; the shared task/job contract remains authoritative.
22
+ Use the **Job ID returned by create**; do not invent an ID, PR number, or Task. Omit `--initial-plan` only for explicitly create-only work. For an existing GitHub PR, use `job adopt`; do not create a managed PR through raw GitHub commands. For local-only work, consult the CLI's `--no-github` option.
22
23
 
23
- ## Core task contract
24
+ Read `contracts/task-job-contract.md` before authoring or changing Jobs or Tasks and `contracts/orchestrator-workflows.md` when handling initial planning, P0/self Jobs, or merge/delivery boundaries. For content work, load the active Neo Project rules, its Agent Graph if present, and the relevant stage contracts—not a presumed universal production sequence.
24
25
 
25
- A managed child task is always a descriptive unit of work. It says what an agent must accomplish; it is never a shell command.
26
+ ## 2. Plan and execute
26
27
 
27
- Normal worker tasks use an agent runtime:
28
- - `codex` for a local Codex-compatible agent.
29
- - `chatgpt` for the one-shot Browser ChatGPT worker.
28
+ Usually let `job create --initial-plan` establish the first Planner round; use `plan` for an existing create-only Job. Direct `task create` is for deliberately orchestrator-authored work. Tasks describe verifiable outcomes, **not shell commands**. Declare exactly one durable result (`task_pr` or `file`), meaningful dependencies, and `storySize`; Relay chooses worker/model routes unless the task truly needs a specific capability.
30
29
 
31
- Shell commands, tests, Markad Vision, ffmpeg, build tools, and similar CLIs are tools used inside an agent or directly by the orchestrator. They are not Agents Relay worker tasks.
30
+ An assigned **execution Prompt** pins a specific Skill version and supplies Role, Bootstrap, Contracts, Contexts, and Task/Plan identity. Preserve these references. Resolve the matching CLI as `../../dist/cli.js` relative to the pinned Skill directory; do **not** substitute an unrelated globally installed CLI. Before acting, load the exact execution-bound context:
32
31
 
33
- Every model-backed task producer normally declares:
34
- - its descriptive `input`;
35
- - semantic requirements such as capabilities/runtime only when known;
36
- - exactly one durable output contract:
37
- - `task_pr`: the managed task/PR is the authoritative result; or
38
- - `file`: an exact file path is the authoritative result.
32
+ ```sh
33
+ node <matching-absolute-dist/cli.js> task context --id JOB --task-id TASK --execution-id EXECUTION
34
+ node <matching-absolute-dist/cli.js> plan context --id JOB --plan-id PLAN --execution-id EXECUTION
35
+ ```
39
36
 
40
- Relay then runs one Execution Router decision over complete worker+model routes and persists the selected worker/adapter and model routing before launch. Explicit adapter/provider/model values are compatibility/debug constraints, not normal producer requirements.
37
+ These are alternative commands for Task and Planner executions. Both fail closed for stale identities. Optional `--repo` further constrains Job identity. Do not reconstruct task content from PR comments or guessed local files. The Planner submits its candidate through the returned `apply_cli`; only the exact `PLAN_APPLIED:<plan-id>:<execution-id>` receipt proves application. Follow the assigned Role and independent Contracts; load optional context only when the work requires it. Authorized delegation creates durable Relay child Tasks, not untracked agent processes.
41
38
 
42
- ## Lifecycle contract
39
+ ## 3. Verify, review, and recover
43
40
 
44
- Events are authoritative for model-backed task state.
41
+ Use the pinned CLI to inspect authoritative status, Task events, comments, and review evidence. A worker's process exit, browser submission receipt, or emitted event is **not** proof of durable completion. Task agents publish `task.started`, optional `task.progress`, and exactly one correlated terminal `task.completed` or `task.failed` via the canonical `events-bus` capability. Never emit `task.blocked` as a worker terminal outcome. Read `contracts/event-contract.md` for exact identity, event semantics, and reviewer verdict payloads; implementation agents also follow `contracts/worker-self-review.md`.
45
42
 
46
- Agents Relay may launch a Codex process or submit a one-shot ChatGPT browser task, but runtime/process completion is only delivery/runtime evidence. It never means the task completed.
43
+ For a failed Task, diagnose before retrying. Read `contracts/task-recovery-flows.md` for recovery and human escalation boundaries. Troubleshooter inspects the original Task and its complete relevant lifecycle history through Relay CLI, repairs or registers a blocker, and verifies recovery. Only a genuinely human-required decision justifies escalation. Only Relay can block/unblock a Troubleshooter; a human response does not itself complete the original Task. Do not silently treat missing or stale evidence as success.
47
44
 
48
- A running agent MUST use the canonical Neo `events-bus` protocol and publish exactly one correlated terminal event before stopping:
49
- - `task.completed` after the declared output is durable;
50
- - `task.failed` when the task cannot complete;
51
- - Progress is optional; `task.blocked` and `task.unblocked` are Relay-owned lifecycle facts, never agent terminal events.
45
+ ## 4. Manage services when needed
52
46
 
53
- Event publishing is not an Agents Relay CLI responsibility. Sandboxed Codex and hosted ChatGPT workers use the federated `events__publish` MCP tool from `events-bus`; direct non-sandbox local workers may use the caller-provided `NEO_EVENTS_EMIT`. Agents Relay subscribes to the canonical `neo.events.job.<job_id>.>` stream and maps terminal events into durable task state. Relay resolves its native NATS endpoint and subject prefix from the canonical events-bus runtime configuration (with explicit Relay CLI flags remaining authoritative). The same runtime configuration supplies the events-bus HTTP API used for replay/history. Relay and its dashboard must not read the events-bus private history file or maintain a second event-history backend.
54
-
55
- The event must carry the exact durable `job_id` and `task_id`. Progress events are optional.
56
-
57
- Agents Relay maps those terminal events to durable state:
58
- - `task.completed` → `SUCCEEDED`
59
- - `task.failed` → `FAILED`
60
- 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.
61
-
62
- A model-backed task must not launch without an event bus. If no accepted `task.started` or newer current-execution `task.progress` arrives within `Task.timeoutMs`, Relay records an inactivity timeout failure. A Codex process exit or ChatGPT submission receipt alone never changes the task to a terminal state.
63
-
64
- Worker process exit is observational only. Relay does not perform an exit-time terminal check or synthesize task failure from process exit; for synchronous workers it caps the remaining inactivity wait at the shorter post-exit terminal grace.
65
-
66
- ## Managed GitHub jobs
67
-
68
- For repository work, create/adopt/repair the PR-backed job through the Agents Relay CLI. Do not create the managed PR through a parallel raw GitHub path.
69
-
70
- Example:
71
-
72
- ~~~sh
73
- npx agents-relay job create --repo OWNER/REPO --id JOB_ID --title "Objective" --objective-file job.md --initial-plan
74
-
75
- npx agents-relay task create --repo OWNER/REPO --pr 12 --id JOB_ID --task-id implement --output task-pr --input "Implement the requested change, validate it, and update the managed task/PR."
76
-
77
- npx agents-relayd --repo OWNER/REPO --events nats
78
- ~~~
79
-
80
- Use `--output file --output-path PATH` when the authoritative result is a file.
81
-
82
- ## Worker prompt
83
-
84
- For Codex and ChatGPT workers, Agents Relay adds only durable execution identity and contracts around the stored descriptive task input:
85
- - PR URL
86
- - job ID
87
- - task ID
88
- - parent task ID
89
- - project name
90
- - declared output
91
- - mandatory terminal-event contract
92
-
93
- The job/task descriptions remain the durable source of intent. Adapters do not invent task meaning.
94
-
95
- ## Shared execution context
96
-
97
- Before planner, reviewer, normal worker, or nested-worker execution, resolve one execution context from the bound project path. The shared resolver owns project instructions, skills, visible agents, and runtime capabilities with project-local > Neo shared > global `~/.agents` precedence. Concrete paths are execution-time data and must not be persisted into durable task records.
98
-
99
- Leaf workers consume the resolved instruction/skill/agent paths, not the full top-level XChat orchestrator contract. Nested workers may inspect visible agents, but any delegation must be represented as an Agents Relay durable child task preserving `parentTaskId`, output contract, routing, leases/retries, events, and review gates.
100
-
101
- ## ChatGPT worker
102
-
103
- The ChatGPT adapter uses Relay's `chatgpt-worker` agent contract and Browser Workspace ChatGPT platform; it does not depend on a Neo worker skill. It opens a fresh regular ChatGPT thread so the worker can use Neo MCP, submits the task with the account defaults, verifies the durable thread ID and submission receipt, and closes its caller-owned WebHelm Session after submission. File inputs are passed as explicit local paths for Neo MCP reading, not browser uploads.
104
-
105
- ChatGPT thread identity is diagnostic only. It is not persisted as a resumable task handle, and Relay does not poll, resume, retrieve a result from, or delete a ChatGPT conversation as part of task lifecycle.
106
-
107
- ## Objective-driven Planner
108
-
109
- Direct orchestrator-created Tasks do not require a Plan. The orchestrator may create the initial batch with `task create`; those Tasks remain top-level unless the orchestrator explicitly gives them normal task parentage. When planner-driven decomposition is desired instead, use `agents-relay plan --repo OWNER/REPO --pr N --id JOB_ID [--prompt TEXT | --prompt-file PATH|-]`.
110
-
111
- For explicit `plan` and automatic continuation, Relay invokes the same planner agent as a pure decision function. The planner receives durable Job/Task state, previous planner rounds, and resolved execution context, then returns structured `{ objective_status, assessment, next_tasks }` output. The planner does not call Relay CLI and does not persist Tasks itself.
112
-
113
- Each successful planner invocation is one real `plan-N` planning round. Relay persists that planner result, then creates returned work Tasks with provenance back to that planning round. `parentTaskId` expresses semantic ownership among work Tasks; it is not inherited from the Plan and must never point to a `plan-N` record. `dependencies` independently express execution prerequisites. Historical `planner-N` records remain readable. Only planner execution creates planner rounds; Relay never manufactures synthetic `plan-*` records for direct Task creation. In the dashboard, planner rounds remain provenance/grouping metadata, not semantic parents.
114
-
115
- A zero-task DRAFT Job remains idle until explicit first planning or direct Task creation. After initial work settles, every Job automatically replans until the latest successful Plan is `satisfied`; there is no fixed/autonomous mode or Job scheduler.
116
-
117
- Planner-created child Tasks remain descriptive agent work and must include the output contract and `storySize`; worker requirements are optional soft routing facts unless an explicit runtime constraint is known. Execution Router chooses the complete runtime route afterward.
118
-
119
- ## Durable truth
120
-
121
- SQLite is the sole local durable lifecycle authority. GitHub PR/Job/Task markers are collaboration projections. Correlated model-worker events are inputs to Graph-selected, SQLite-committed transitions; runtime events, process exits, browser receipts, and conversation text are not themselves completion proof.
122
-
123
- Keep secrets, credentials, private prompts, and large private payloads out of durable markers and events.
124
-
125
- ### Automatic task troubleshooting
126
-
127
- When an ACTIVE Job contains a current-run `FAILED` task, reconciliation may create one P0-priority `troubleshooter` recovery task for that exact failed attempt. `BLOCKED` is resolved only through authoritative unblock, which records evidence and transitions the Task to `UNBLOCKED`. The recovery task is routed to a local Codex-capable worker with repository/tool access and runs under the bundled Troubleshooter agent contract. Historical ordinary unblock evidence is Planner recovery context; only an effectively blocked Troubleshooter can be authoritatively resumed. Each Planner round is durably represented by an `agents-relay:plan:v1` PR comment created before generated Task comments and updated in place with its assessment and generated Task IDs. Troubleshooter diagnosis is event-first: it must inspect the failed task's task-scoped lifecycle event history (including ordering, duplicate/missing/late events, source and phase data) before classifying root cause or retrying.
128
-
129
- The Troubleshooter diagnoses before retrying. A task-local or transient blocker is repaired narrowly; a shared worker/runtime/tool defect is repaired through the owning repository's P0/self-job workflow. Only after the blocker is removed does it retry the original task and verify durable progress. Historical resolved failures do not spawn duplicate recovery work, and deterministic reconciliation does not duplicate a Troubleshooter task for the same failed attempt.
130
-
131
- ## Persistent service bootstrap
132
-
133
- This Skill owns `agents-relay/daemon`, `agents-relay/dashboard-tunnel`. The `daemon-service-manage` Skill is required. Run `node skills/agents-relay/bin/services.mjs setup` for idempotent registration through `serviceman`; run `status` to inspect or `doctor` to fail if a service is not online. Existing process configuration is preserved. Do not create unqualified legacy PM2 names.
47
+ For setup, outages, or persistent service health checks, load the separate `daemon-service-manage` Skill. The Relay Skill provides `bin/services.mjs`: run `node <pinned-skill-dir>/bin/services.mjs setup|status|doctor` as applicable. Do not start or restart services for ordinary Job operations, or create legacy unqualified PM2 names.
@@ -2,7 +2,6 @@
2
2
  name: implementation
3
3
  description: Implement the assigned Agents Relay task in the managed checkout and verify the durable result.
4
4
  capabilities: [implementation, local_repo, iterative_tools]
5
- runtime: codex
6
5
  delegation: [relay-child-task]
7
6
  restrictions: [preserve-user-changes, no-unrelated-refactors]
8
7
  ---
@@ -10,7 +9,7 @@ restrictions: [preserve-user-changes, no-unrelated-refactors]
10
9
  # Implementation Agent
11
10
 
12
11
  Implement the assigned Task in the current managed checkout. Treat the durable
13
- Job objective and Task input retrieved from GitHub as authoritative. Inspect the
12
+ Job objective and Task input retrieved from the execution-bound `task context` returned by the Prompt-pinned Relay CLI as authoritative. Inspect the
14
13
  existing design before editing, keep the change narrowly scoped, and preserve
15
14
  unrelated user work.
16
15
 
@@ -2,15 +2,15 @@
2
2
 
3
3
  You are the default objective planner for all Agents Relay Jobs.
4
4
 
5
- Before producing tasks, read and follow `../contracts/task-job-contract.md`.
5
+ Before producing tasks, read the Task/Job Contract listed by the Relay Prompt. The merged Agent snapshot can live outside the repository, so do not resolve contracts relative to the Agent file.
6
6
 
7
7
  You own end-to-end objective convergence. Relay invokes you with the durable Job, existing Tasks, previous planner rounds, and resolved project context. Investigate the actual objective and execution evidence, decide whether it is satisfied, and otherwise produce safe executable progress or an evidence-backed block. A Task Tree is a means to that outcome, not the outcome itself.
8
8
 
9
- Every proposal MUST be committed with the provided `agents-relay plan apply` CLI command. Write the proposed JSON to a temporary file and run that command with the exact Plan and execution IDs from `plan_execution` / `apply_cli`. If it exits unsuccessfully with a JSON error whose code is `PLAN_APPLY_VALIDATION_FAILED`, read its `phase` and every `issues` entry, correct the candidate, and retry within this SAME Planner execution using the same Plan and execution IDs, up to three corrections. This is an actionable candidate rejection: it does not persist the Plan or any Task/history mutation, and the CLI output is the evidence for the correction. Keep the original evidence and intent; change only what the reported issues require. For `phase: "fencing"`, refresh the durable context and stop if the active execution no longer owns the Plan; never bypass the fence. For any other CLI failure, diagnose it from its actual output and do not claim validation feedback that was not returned.
9
+ Every proposal MUST be committed with the execution-bound `apply_cli` returned by `plan context` through the Prompt-pinned Relay CLI. Write the proposed JSON to a temporary file and run the returned command with the exact Plan and execution IDs from `plan_execution` / `apply_cli`. If it exits unsuccessfully with a JSON error whose code is `PLAN_APPLY_VALIDATION_FAILED`, read its `phase` and every `issues` entry, correct the candidate, and retry within this SAME Planner execution using the same Plan and execution IDs, up to three corrections. This is an actionable candidate rejection: it does not persist the Plan or any Task/history mutation, and the CLI output is the evidence for the correction. Keep the original evidence and intent; change only what the reported issues require. For `phase: "fencing"`, refresh the durable context and stop if the active execution no longer owns the Plan; never bypass the fence. For any other CLI failure, diagnose it from its actual output and do not claim validation feedback that was not returned.
10
10
 
11
- A CLI rejection (`PLAN_APPLY_VALIDATION_FAILED`) is distinct from a missing apply receipt. Only successful CLI output followed by the exact final message `PLAN_APPLIED:<plan-id>:<execution-id>` proves this execution committed. A missing, mismatched, or decorated receipt is not a validation failure and must never be fabricated or retried as though the apply were rejected. If the Plan may have committed but its receipt is unavailable, stop without claiming success; Relay/runtime must resolve the durable Plan state. The CLI prints the persisted Plan JSON on success; that output alone is not your final receipt. Do not edit SQLite or other durable storage directly. Do not treat a JSON/text proposal as a plan submission and do not return the proposal as your final answer. Never invent the receipt. If no live execution identity or CLI action is available, fail rather than returning a proposal.
11
+ A CLI rejection (`PLAN_APPLY_VALIDATION_FAILED`) is distinct from a missing apply receipt. Only successful CLI output followed by the exact final message `PLAN_APPLIED:<plan-id>:<execution-id>` proves this execution committed. A missing, mismatched, or decorated receipt is not a validation failure and must never be fabricated or retried as though the apply were rejected. If the Plan may have committed but its receipt is unavailable, stop without claiming success; Relay/runtime must resolve the durable Plan state. The CLI prints the persisted Plan JSON on success; that output alone is not your final receipt. Change Plan or Task state only through the version-matched Relay CLI. Do not treat a JSON/text proposal as a plan submission and do not return the proposal as your final answer. Never invent the receipt. If no live execution identity or CLI action is available, fail rather than returning a proposal.
12
12
 
13
- Relay persists each planning round as a first-class Plan PR comment/marker before generated Task comments. The Plan carries its trigger/context (including unblock/change facts when applicable), assessment, and generated Task IDs. Legacy `kind=planner` Task records may still exist as execution history, but they are not the durable semantic container for the planning decision. Returned work Tasks are not automatically children of the Plan; use `parentTaskId` only when the business Task graph needs hierarchy.
13
+ Read current Plan, prior rounds, and Task history through the execution-bound Relay `plan context` CLI response. Do not infer Plan status from GitHub or PR comments. A Plan records its trigger/context (including unblock/change facts), assessment, and generated Task IDs; Plan records are not semantic parents for work Tasks.
14
14
 
15
15
  ## Planning contract
16
16
 
@@ -25,10 +25,10 @@ For every non-satisfied objective:
25
25
 
26
26
  ### Objective decomposition and convergence
27
27
 
28
- - **Never bundle independently testable acceptance layers into one giant Task.** Break objectives into separately verifiable deliverables (for example, contract tests, real-provider compliance, L1 Graph branches, L2 role evidence, and L3 production-ingress SQLite replay, and integration evidence). Give each Task concrete acceptance checks and an observable output.
28
+ - **Never bundle independently testable acceptance layers into one giant Task.** Break objectives into separately verifiable deliverables (for example, contract tests, real-provider compliance, L1 Graph branches, L2 role evidence, and L3 production-ingress and recovery evidence). Give each Task concrete acceptance checks and an observable output.
29
29
  - Split a large Task when its remaining work spans distinct implementation areas, independently testable failure paths, or more than one meaningful review/recovery cycle. Put shared prerequisites in earlier Tasks and express true dependencies explicitly; independent work may run in parallel.
30
30
  - For a failed Task with repeated deterministic acceptance gaps, do not reissue the identical broad assignment. Identify the *missing acceptance cases*, create focused same-Job repair Tasks with valid `same_job_dependency` resolutions, and specify how their evidence unblocks the original Task. Preserve the original failed Task and failure history.
31
- - For event-driven workflows, separate basic ingress/persistence checks from L3 production Reconciler/Graph/SQLite multi-stage replay scenarios. Require negative-path, multi-failure recovery and no-false-completion evidence before claiming full objective coverage.
31
+ - For event-driven workflows, separate basic ingress/persistence checks from L3 full-path lifecycle and recovery scenarios. Require negative-path, multi-failure recovery and no-false-completion evidence before claiming full objective coverage.
32
32
  - In `assessment`, show the entire remaining objective as a dependency graph, clearly distinguishing already proven work, the executable batch, subsequent verification, and Relay-owned review/merge. Never report overall `satisfied` merely because one batch has passed.
33
33
 
34
34
 
@@ -74,7 +74,7 @@ Prefer:
74
74
 
75
75
  ```text
76
76
  Task: Create and publish today's vlog
77
- internal graph: collect media -> select story -> script -> edit -> captions -> QA -> publish
77
+ production flow: collect media -> select story -> script -> edit -> captions -> QA -> publish
78
78
  ```
79
79
 
80
80
  when nobody needs to separately review or discuss those intermediate outputs.
@@ -105,7 +105,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
105
105
 
106
106
  ### Forced Restate audit and validation
107
107
 
108
- When `force_restate` is true, use this single forced Planner opportunity to audit the full authoritative semantic Task tree, every historical Task and Resolution classification, all dependency edges, and review target/head evidence. Inspect every ID in `restate_task_ids` against authoritative Task records and evidence before constructing the candidate. Do not run `task classify` or `task cancel` as a preliminary mutation. Include exactly one `history_cleanup` entry for every ID in `restate_task_ids` in the first complete candidate you submit: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. Never defer a disposition or omit one while submitting partial work. `plan apply` validates the complete proposal against the current SQLite snapshot and atomically applies dispositions with the Plan and Tasks only after all validation succeeds. A failed validation leaves all SQLite state unchanged; use its exact phase and issues to correct the candidate and retry with the same Plan and execution IDs.
108
+ When `force_restate` is true, use this single forced Planner opportunity to audit the full authoritative semantic Task tree, every historical Task and Resolution classification, all dependency edges, and review target/head evidence. Inspect every ID in `restate_task_ids` against authoritative Task records and evidence before constructing the candidate. Do not run `task classify` or `task cancel` as a preliminary mutation. Include exactly one `history_cleanup` entry for every ID in `restate_task_ids` in the first complete candidate you submit: `{ "taskId", "outcome": "superseded"|"invalid"|"cancelled_review"|"unresolved", "evidence", "reason", "targetTaskId?" }`. Never defer a disposition or omit one while submitting partial work. `plan apply` validates the complete proposal against current Relay state and rejects invalid dispositions before accepting the Plan. If validation fails, use its exact phase and issues to correct the candidate and retry with the same Plan and execution IDs.
109
109
 
110
110
  If evidence is absent or execution outcome is unknown, disposition that historical Task as `unresolved`; never classify, cancel, or imply success without proof. A classification target must be an existing SUCCEEDED Task. An unresolved failure may still need safe recovery: when the objective requires it, create executable recovery work with a valid `resolution` targeting the original unresolved Task, preserving the original failure and uncertainty. If no recovery can be justified from evidence, create this Plan's own evidence-backed blocked Troubleshooter with explicit unblock conditions. Do not use unresolved history as a reason to silently abandon the objective. Every Plan apply must converge to supported worker-routed runnable work, fully accountable dependency waiting whose closure reaches runnable work, this Plan's own evidence-backed blocked Troubleshooter with explicit unblock conditions, or an already COMPLETED Job. Never submit an empty plan to hide unresolved work or unavailable routes. When implementation is complete at a newer PR head, let canonical final-review reconciliation create the full root review; plan new implementation/review work only when that graph cannot advance.
111
111
 
@@ -123,11 +123,11 @@ If evidence is absent or execution outcome is unknown, disposition that historic
123
123
  - Do not create bookkeeping, waiting, status-checking, wrapper, or planning Tasks. Your response itself is the planning round.
124
124
  - Relay owns lifecycle delivery for local-first Jobs. Never create a worker Task whose job is to perform the local Git merge, mark the Job `COMPLETED`, merge the projected GitHub PR, or wait/check for those Relay-owned effects. After implementation and required review are satisfied, return no lifecycle-completion Task; let the canonical Review/Local-Merge/Job Graph advance the Job.
125
125
  - When all executable implementation work is complete and the only remaining steps are Relay-owned final review, local merge, Job completion, or projected PR convergence, return `objective_status: "satisfied"` with `next_tasks: []`. Do not return `in_progress` with an empty task list before final review; that would leave the Job with no executable progress path.
126
- - Return no prose outside the JSON result.
126
+ - Do not print the candidate JSON as the final reply. Write it to a temporary file, invoke the execution-bound `apply_cli` with that file, and only return the exact successful `PLAN_APPLIED:<plan-id>:<execution-id>` receipt.
127
127
 
128
128
  ## Output
129
129
 
130
- Return exactly one JSON object with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`. In forced cleanup mode, also return required `history_cleanup` as specified above.
130
+ Construct one **candidate Plan JSON object** with `objective_status`, `assessment`, `next_tasks`, and optional top-level `unblocks`. In forced cleanup mode, include the required `history_cleanup`. Submit this object as a file to `apply_cli`; it is not the terminal chat output.
131
131
 
132
132
  For `objective_status: "in_progress"`, `assessment` must be Markdown containing:
133
133
 
@@ -152,7 +152,7 @@ Use these exact serialized forms:
152
152
  - `storySize` is exactly `"S"`, `"M"`, or `"L"`.
153
153
  - `parentTaskId`, when present, is the durable parent work Task ID in the current Job. Never point it at a `plan-N` planner round.
154
154
 
155
- A valid non-satisfied response:
155
+ Example candidate JSON file for a non-satisfied Plan:
156
156
 
157
157
  ```json
158
158
  {
@@ -174,4 +174,4 @@ A valid non-satisfied response:
174
174
  }
175
175
  ```
176
176
 
177
- Return this JSON object directly. Do not wrap the whole result in another JSON string.
177
+ Save this candidate JSON to a file and pass it to the exact `apply_cli` command supplied by `plan context`. After successful apply, respond with only the exact `PLAN_APPLIED:<plan-id>:<execution-id>` receipt. If apply fails or its receipt is unknown, follow the failure/uncertainty rules above; never claim successful application or return unsubmitted JSON as the result.
@@ -26,4 +26,4 @@ negative verdict is a successful review, not `task.failed`. If review
26
26
  execution fails or required validation evidence is unavailable, publish `task.failed`.
27
27
  Never emit `review.*` as the agent's terminal event. The event source must
28
28
  match the execution identity supplied by Relay. See
29
- `../contracts/event-contract.md`.
29
+ the independently referenced Event Contract in the Relay Prompt (the cached Agent snapshot is not the repository directory).
@@ -13,14 +13,14 @@ You are the recovery orchestrator for a FAILED Agents Relay task. Ordinary Tasks
13
13
 
14
14
  Your goal is not to explain the failure. Your goal is to make the original task move again when it is safe and technically possible.
15
15
 
16
- Read and follow the shared Task / Job contract and orchestrator P0/self-job workflow before acting.
16
+ Read the independently pinned Task/Job Contract from the Relay Prompt. Only when a shared defect requires a P0/self-job, load `contracts/orchestrator-workflows.md` relative to the Prompt-pinned Relay Skill; do not add it to ordinary recovery startup Context.
17
17
 
18
- Read `skills/agents-relay/troubleshooter-qa.md` for user-editable best practices before diagnosis. Treat its answers as guidance only, below current evidence and authoritative contracts. After a verified recovery, add or refine a concise Q&A entry when it provides reusable knowledge; never include secrets or unverified claims.
18
+ Read `troubleshooter-qa.md` beside the Prompt-pinned Relay Skill for user-editable best practices before diagnosis. Treat its answers as guidance only, below current evidence and authoritative contracts. After a verified recovery, add or refine a concise Q&A entry when it provides reusable knowledge; never include secrets or unverified claims.
19
19
 
20
20
  ## Recovery loop
21
21
 
22
- 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.
23
- 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.
22
+ 1. Read this recovery execution through the Prompt-pinned Relay CLI `task context`; obtain the failed original Task through `task show` and relevant `task comments`. Do not retrieve Relay state from GitHub or PR comments.
23
+ 2. **Mandatory before diagnosis:** use the Prompt-pinned Relay CLI `task show --id JOB --task-id FAILED_TASK` and `task events --id JOB --task-id FAILED_TASK --limit 60 --order asc --after 0`. Repeat with `--after <nextCursor>` until a page has fewer than 60 events. Optional `--repo` fences the Job. Inspect event order, type/status, source, data/phase, execution IDs, duplicates, missing expected lifecycle events, and late events. Events pages are oldest-first with a durable cursor in ascending mode. If pagination cannot retrieve the needed history, report the evidence gap rather than pretending it is complete. Then inspect Task error/failureReason, worker selection, routing, attempt, input/output contract, and relevant worker/runtime logs. Never fetch Relay state or event history from internal HTTP endpoints or files.
24
24
  3. Classify the blocker:
25
25
  - transient execution/delivery/lease failure;
26
26
  - task-local implementation or validation failure;
@@ -33,10 +33,10 @@ Read `skills/agents-relay/troubleshooter-qa.md` for user-editable best practices
33
33
  - For a transient failure, verify the transient condition is gone.
34
34
  - For task-local failure, make the smallest durable repair in the original Job/PR when that is within scope.
35
35
  - 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.
36
- - For a suspected genuine human/external blocker, 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.
36
+ - For a suspected genuine human/external blocker, invoke `agents-relay escalation` with the original intent, blocker, and relevant context. Handle the CLI-reported `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.
37
37
  - After unblock, this same Troubleshooter must run with a new execution ID, re-check the blocking condition, and produce a fresh resolution bound to that execution. A previously resolved resolution record never authorizes retrying a new attempt.
38
38
  - Unknown worker execution outcomes fail closed. Do not automatically reroute or retry the original task, and do not block the original task; diagnose it through the Troubleshooter.
39
- 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.
39
+ 7. For an immediate repair, only after the blocker is removed invoke the Prompt-pinned Relay CLI `task recover --id JOB --task-id ORIGINAL_FAILED_TASK --recovery-task-id THIS_TROUBLESHOOTER_TASK` (plus the normal Job binding and diagnosis flags), then check the original Job/Task through the same CLI. Verify the reported 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.
40
40
  8. Verify durable evidence the original Task moved: at minimum QUEUED after retry, preferably a new execution / task.started / observable progress.
41
41
  9. Publish this Troubleshooter Task's terminal event only after the recovery outcome is durable.
42
42
 
@@ -33,7 +33,7 @@ Every Implementation, Reviewer, and Troubleshooter execution publishes `task.sta
33
33
  | Reviewer | `verdict` (`approved` or `changes-required`), exact immutable `head_sha`, actionable `findings` as necessary | Validate current immutable review target and apply verdict; defects are a successful Reviewer execution, not `task.failed` |
34
34
  | Troubleshooter | Recovery action and durable evidence of verified original Task retry, blocker-Job handoff, or other authorized recovery | Complete recovery Task only; original Task state changes through separately authorized Relay operations |
35
35
 
36
- A Reviewer must **not** publish unstructured `task.completed`: missing verdict or immutable head is invalid. Relay normalizes an authenticated structured Reviewer terminal event into its internal Review decision; native `review.*` events may be accepted for backward compatibility.
36
+ A Reviewer must **not** publish unstructured `task.completed`: missing verdict or immutable head is invalid. Relay validates the Reviewer verdict; read the accepted review outcome through the matching Relay CLI.
37
37
 
38
38
  ## Troubleshooter human escalation
39
39
 
@@ -49,6 +49,9 @@ A host-mediated interactive invocation is a separate Relay-controlled wait. It r
49
49
 
50
50
  A legacy Job-level `review: blocked` gate is reset to `pending` only after authoritative `task.unblocked` metadata exists on its bound Reviewer Task and the immutable review head still matches. The same Reviewer Task then resumes without creating a duplicate.
51
51
 
52
- ## Local Git merge delivery history
52
+ ## Delivery outcome
53
53
 
54
- The Relay-owned merge effect persists the current `job.localMerge` receipt in SQLite. Every attempted delivery also emits `job.merge.failed` or `job.merge.succeeded` to the canonical events-bus, keyed by the Job and merge attempt. Failure `data` contains `reason`, exact `message`, `attempts`, `retryable`, and `nextAttemptAt`; success contains `mergedCommitSha` and `sourceSha`. A dirty checked-out target is `reason: dirty_target_worktree`. The dashboard displays the durable failure reason while `localMerge.status=failed`. After the retry deadline, periodic reconciliation must select ACTIVE Jobs with failed local merges even when all Tasks have succeeded. Historical failure events remain visible after successful recovery.
54
+ Relay owns merge and delivery. Workers must not emit `job.merge.*` or mark
55
+ the Job complete. Inspect delivery status and its failure reason/receipt through
56
+ the version-matched Relay CLI. A prior failed attempt or successful browser
57
+ submission is not proof of final delivery.
@@ -40,16 +40,18 @@ orchestrator-worker lifecycle, and new Task creation rejects
40
40
  unless the user explicitly asks for review; Relay-owned merge and completion
41
41
  lifecycle remain in their canonical graphs.
42
42
 
43
- Legacy recovery: existing `adapter: orchestrator` work Tasks may be repaired only
44
- through the canonical rescue graph. The repair converts only never-started QUEUED records in place to declarative worker requirements and lets Execution Router select the route. A legacy RUNNING record with an unknown outcome is quarantined as BLOCKED instead of replayed; only explicit durable external-completion verification may complete it without execution. Process reclamation is attempted only after the record is proven eligible for this legacy path, so normal live workers are never touched by the migration scan.
43
+ For legacy Tasks with an unsupported runtime or unknown execution outcome,
44
+ inspect the actual state and supported recovery options using the matching
45
+ Relay CLI. Do not edit task records, infer completion, or relaunch uncertain
46
+ executions directly. Report a concrete blocker if CLI recovery cannot proceed.
45
47
 
46
48
  `job create --initial-plan` remains the normal way to create durable planning
47
49
  state and hand subsequent execution to Relay.
48
50
 
49
51
  ## Merge completion vs deployment evidence
50
52
 
51
- For a managed Job, the canonical Job lifecycle Graph owns completion. A satisfied Plan, successful implementation evidence, applicable SHA-bound review, and a verified local merge/delivery receipt are required. Remote GitHub `pr.merged` facts are audit-only and never independently complete a local Job. Deployment code must not invent another completion gate after durable Job completion.
53
+ For a managed Job, Relay owns Job completion. A satisfied Plan, successful implementation evidence, applicable SHA-bound review, and a verified local merge/delivery receipt are required. A GitHub merge alone is not proof of Job completion; verify the outcome with the Relay CLI. Deployment code must not invent another completion gate after durable Job completion.
52
54
 
53
55
  Post-merge publication and deployment activity is separate from Job lifecycle. Events or evidence such as `package.published`, published version metadata, service restart, and deployment verification may be attached after the Job is already `COMPLETED`; they must not hold the Job open, reopen it, or redefine completion. If post-merge deployment needs remediation, record that as separate deployment/recovery work rather than mutating the completed implementation Job lifecycle.
54
56
 
55
- A PR closed without merge follows the same graph-owned rule through `pr.closed -> CANCELLED`.
57
+ If a PR closes without merge, check the Job state through Relay CLI; do not infer a successful completion.
@@ -6,7 +6,7 @@ This contract is the shared protocol for every component that creates, schedules
6
6
 
7
7
  Job objectives and Task inputs are **Markdown** and are durable execution context, not short labels. Use Mermaid where a diagram materially explains a workflow, state model, architecture, dependency graph, relationship, or other visual structure. **Mermaid-first applies to that explanation/section, not to the entire Job objective or Task input.** Put the diagram before the prose that explains that visual model, but keep normal document structure: start with the goal/context when that is what the reader needs first. Do not force a Mermaid block at the top of every objective/input, and do not add decorative or redundant diagrams when Markdown is clearer.
8
8
 
9
- The trusted machine-readable Job/Task marker stores lifecycle and execution metadata only. Do **not** duplicate the Job objective or Task input inside marker JSON. The Job marker lives in the PR body immediately before the human-readable Job objective; Task markers live in their Task comments immediately before the human-readable Task input/result. Readers reconstruct `objective` / `input` from that visible Markdown while remaining backward-compatible with legacy markers that embedded long-form content or stored the Job marker in a separate comment.
9
+ Create, update, and read Job objectives and Task inputs only through the version-matched Relay CLI. Do not parse or edit PR bodies, comments, hidden markers, or private files to obtain or alter Relay state.
10
10
 
11
11
  For long-form content, use files instead of shell-quoted arguments:
12
12
 
@@ -15,7 +15,7 @@ For long-form content, use files instead of shell-quoted arguments:
15
15
 
16
16
  When creating a new Job from an active discussion, the orchestrator must consolidate **all context needed to finish the Job without the originating thread** into the Job objective before creation. Include, as applicable: goal, relevant background, decisions already made, requirements, constraints, lifecycle/workflow semantics, non-goals, implementation boundaries, acceptance criteria, delivery/review instructions, and any important known issues. Do not create a Job whose objective is only a one-line summary when the discussion contains material implementation context.
17
17
 
18
- Ordinary `job create` requires standalone objective Markdown. An external display PR is projected after the first meaningful code commit; existing PRs are adopted with `job adopt`. The PR body is the single durable Job surface: one hidden `agents-relay:job:v1` marker followed by the objective Markdown. Updating Job metadata or objective updates that same body. New Jobs must not create a separate Job comment that repeats the objective. Readers must remain backward-compatible with legacy Job-comment markers, and a successful Job save may migrate such a legacy marker into the PR body only after validating the replacement before deleting the redundant legacy Job comment.
18
+ Use `job create` with standalone objective Markdown, or `job adopt` for an existing PR when authorized. Use Relay CLI for subsequent Job reads and updates; do not infer Job state or objective from GitHub.
19
19
 
20
20
  ## Task producers
21
21
 
@@ -34,12 +34,10 @@ A later Planner round must inspect the existing semantic tree and attach review,
34
34
 
35
35
  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**.
36
36
 
37
- After creation, keep `Task.input` stable as the objective and initial evidence.
38
- Responses, resolution changes, and escalation history belong in append-only
39
- Task Comments. SQLite atomically records typed comments with authoritative
40
- resolution/escalation mutations; PR-bound Jobs project those comments through
41
- the durable idempotent projection outbox. Comments supplement current state and
42
- never replace `Task.resolution` or `Task.escalation`.
37
+ After creation, keep `Task.input` stable as the objective and initial
38
+ evidence. Use the Relay CLI to read or append Task Comments and to request
39
+ resolution/escalation changes. Comments are history; the current
40
+ `Task.resolution` and `Task.escalation` are obtained through the CLI.
43
41
 
44
42
  Task input should include, as applicable:
45
43
 
@@ -62,7 +60,7 @@ Task results should also include, as applicable:
62
60
 
63
61
  - **deviations** from any proposed or required solution, with the reason;
64
62
  - **validation** showing how the result was verified;
65
- - relevant changed files, commits, PR comments, artifacts, or remaining issues.
63
+ - relevant changed files, commits, artifacts, CLI receipts, or remaining issues.
66
64
 
67
65
  This is a worker result-content contract, not a requirement for dedicated `rootCause` / `solution` schema fields. Workers may satisfy it in normal durable result prose unless a Job defines a stricter structured output contract.
68
66
 
@@ -76,12 +74,12 @@ Every artifact-changing implementation worker follows the shared [worker self-re
76
74
 
77
75
  `Task.state` is reserved for Relay lifecycle only: `DRAFT`, `QUEUED`, `RUNNING`, `BLOCKED`, `SUCCEEDED`, `FAILED`, and `CANCELLED`. `BLOCKED` is exclusive to Tasks whose `agentName` is exactly `troubleshooter`; ordinary Tasks never enter `BLOCKED` or an `UNBLOCKED` lifecycle state. A Job may additionally define one optional `tag` contract for a Job-specific result or classification that should be visible on each Task without changing its lifecycle state.
78
76
 
79
- The Job owns the meaning of the tag. Its trusted Job marker declares a human-readable `description` explaining what the tag means and when workers should set it, plus the allowed durable values and their dashboard display strings:
77
+ The Job owns the meaning of the tag. Its Job-defined tag contract declares a human-readable `description` explaining when workers should set it, allowed values, and their display strings:
80
78
 
81
79
  ```json
82
80
  {
83
81
  "tag": {
84
- "description": "L3 verification outcome. Set pass only after authoritative SQLite replay checks pass; set fail when a required check fails.",
82
+ "description": "L3 verification outcome. Set pass only after the required recovery checks pass; otherwise set fail.",
85
83
  "values": {
86
84
  "pass": "✅",
87
85
  "fail": "❌"
@@ -90,7 +88,7 @@ The Job owns the meaning of the tag. Its trusted Job marker declares a human-rea
90
88
  }
91
89
  ```
92
90
 
93
- A worker does **not** edit the Task marker directly. When the Job defines a tag and the tag applies to the work just performed, the worker reports one allowed durable value in the canonical terminal event as `data.tag`:
91
+ A worker does **not** edit Relay state or PR markers directly. When the Job defines a tag and the tag applies to the work just performed, the worker reports one allowed durable value in the canonical terminal event as `data.tag`:
94
92
 
95
93
  ```json
96
94
  {
@@ -102,7 +100,7 @@ A worker does **not** edit the Task marker directly. When the Job defines a tag
102
100
  }
103
101
  ```
104
102
 
105
- Relay validates `data.tag` against `Job.tag.values`. If the value is allowed, Relay persists it into the trusted Task marker as the Task's `tag`; undeclared or invalid values are ignored. The transport `data.tag` is not duplicated into `result.data`. The resulting Task metadata may therefore contain both independent concepts at once:
103
+ Relay validates `data.tag` against `Job.tag.values`. Check the accepted tag and Task state through the Relay CLI; lifecycle status and Job-defined tag are independent:
106
104
 
107
105
  ```json
108
106
  {
@@ -121,8 +119,7 @@ For a validation Job, for example, the Job defines `pass -> ✅` and `fail ->
121
119
  ### Task resolution classifications
122
120
 
123
121
  `Task.resolutionClassification` is durable diagnostic metadata, separate from
124
- `Task.state` and the recovery `Task.resolution` path. The canonical Task
125
- Resolution Graph and `task classify` CLI action may classify a known FAILED
122
+ `Task.state` and the recovery `Task.resolution` path. The `task classify` CLI action may classify a known FAILED
126
123
  work Task as `superseded` or `invalid`; each record requires a different
127
124
  durable target Task, evidence, and reason. Classification never changes the
128
125
  FAILED lifecycle state, execution history, or result and never proves success.
@@ -143,7 +140,11 @@ SHA-bound final reviewer. For example, `video-director + market + style ->
143
140
  review-chair -> unified revision plan` is a project pattern, not a hard-coded
144
141
  Relay reviewer list.
145
142
 
146
- Every Job is objective-driven. After a direct initial Task batch or a Planner-produced batch settles, reconciliation evaluates the canonical Planner Graph and creates the next durable `plan-N` round until the latest successful Plan returns `objective_status: satisfied`. There is no fixed/autonomous mode, no Job schedule, no cron slot, and no Scheduler entity. The daemon performs startup recovery and wake-driven reconciliation from SQLite. A satisfied Plan alone does not complete a Job: successful implementation evidence, SHA-bound review when enabled, and verified local merge/delivery remain mandatory.
143
+ Every Job is objective-driven. After a Task batch settles, Relay may create
144
+ further Plan rounds until the current Plan reports `objective_status: satisfied`.
145
+ A satisfied Plan alone is not Job completion: accepted implementation
146
+ evidence, immutable review when required, and verified delivery must still
147
+ be confirmed through the Relay CLI.
147
148
 
148
149
  A newly created zero-task DRAFT Job waits for explicit initial planning (`plan` or `--initial-plan`) or direct work creation; this is only a start gate, not a distinct execution mode. Failed or blocked Tasks require durable Troubleshooter/owner recovery and never allow a fabricated completion. Duplicate events and daemon restarts must not create duplicate Plan rounds.
149
150
 
@@ -164,7 +165,7 @@ This is a strong execution boundary:
164
165
 
165
166
  For example, a `neo-build-log` episode whose output is `runs/2026-10-02/package.md` executes in the canonical `neo/neo-build-log` project directory, and its review/render/publish descendants see the same `runs/2026-10-02/` tree.
166
167
 
167
- Task inputs must make evidence freshness and target identity explicit when those facts affect correctness. A Task may bind its own review, audit, or source evidence to an immutable SHA/version. That frozen target belongs to that Task; it must not be propagated mechanically into later dependent work. A downstream release, deploy, publication, or other Task that runs after dependencies complete must resolve the current durable Job/PR head at execution time unless the Job objective explicitly requires the earlier immutable target.
168
+ Task inputs must make evidence freshness and target identity explicit when those facts affect correctness. A Task may bind its own review, audit, or source evidence to an immutable SHA/version. That frozen target belongs to that Task; it must not be propagated mechanically into later dependent work. A downstream release, deploy, publication, or other Task must verify the current target/head at execution time using the Relay CLI and source evidence, unless the objective explicitly requires the earlier immutable target.
168
169
 
169
170
  When success depends on the actual current UI, browser state, store listing, runtime state, or another externally observable surface, the Task contract must require fresh evidence from that real current surface. Reusing an existing screenshot, prepared asset, cached observation, or older evidence is valid only when the Job explicitly permits it.
170
171
 
@@ -182,11 +183,13 @@ forbids it.
182
183
 
183
184
  `dependencies` describe normal DAG ordering. An unmet dependency keeps ordinary work in `DRAFT`; dispatchable work is `QUEUED`. Dependency completion does not create an unblock lifecycle event or Planner unblock trigger; Relay releases dependent work when its prerequisites succeed. Worker, platform, semantic, and unknown-outcome failures are `FAILED`. Unknown worker outcome fails closed and never justifies rerouting. Only a Troubleshooter waiting for an authoritative human response may become `BLOCKED`.
184
185
 
185
- A BLOCKED Troubleshooter cannot be resumed through retry, queue, dashboard state editing, PR push, webhook, ordinary task update, or Troubleshooter inference. The authoritative entry point records the response and transitions that same Troubleshooter `BLOCKED -> QUEUED` through `task.unblocked`. The queued Troubleshooter must execute again, verify the condition from fresh evidence, and issue a fresh resolution before Relay may retry or replan the original FAILED Task. Prior `resolved` metadata never authorizes another attempt. Historical ordinary BLOCKED snapshots migrate to FAILED while their append-only event history remains unchanged; they are never silently converted to success.
186
+ A BLOCKED Troubleshooter resumes only after an authorized Relay CLI unblock with a human response. The CLI must report that same Troubleshooter moving from `BLOCKED` to `QUEUED`. The queued Troubleshooter must execute again, verify the condition from fresh evidence, and issue a fresh resolution before Relay may retry or replan the original FAILED Task. Prior `resolved` metadata never authorizes another attempt. Historical failures must not be silently reclassified as success.
186
187
 
187
- The old `UNBLOCKED` state is compatibility-only input. It normalizes to QUEUED only for Troubleshooter Tasks and to FAILED for ordinary Tasks, pending diagnosis.
188
+ Do not create or infer an `UNBLOCKED` state for ordinary Tasks.
188
189
 
189
- Each Planner round is also a first-class durable Plan entity stored in its own `agents-relay:plan:v1` PR comment. Relay creates the Plan comment before the internal planner execution record and before any generated Task comments, then updates that same Plan comment with the final assessment and generated Task IDs. Unblock/change facts belong to the Plan trigger/context, not to new Job-level Change Cycle state. Historical `kind=planner` Task records and legacy Job `changeCycle` fields remain readable for compatibility only.
190
+ Read Plan rounds, current status, trigger/context, assessment and generated
191
+ Task IDs via the execution-bound `plan context` CLI command. PR comments are
192
+ not a source for Plan execution state.
190
193
 
191
194
  A blocker Job owns reverse `unblocks` references. When it resolves, Relay releases matching dependency-waiting Tasks through their ordinary DRAFT/QUEUED path. It cannot unblock ordinary work or resume a Troubleshooter without the authoritative response flow.
192
195