agents-relay 1.0.173 → 1.0.175

package/dist/planner.js

@@ -5,6 +5,15 @@ import { dirname, join } from 'node:path';
 import { storySizeTimeoutMs, taskOverallTimeoutMs } from './types.js';
 import { executionContextPrompt } from './execution-context.js';
 import { parseAgentGraph } from './agent-graph.js';
+/** Business-task ownership only; planner rounds remain provenance records. */
+export function semanticTaskTree(tasks) {
+    const work = tasks.filter(task => task.kind !== 'planner');
+    const ids = new Set(work.map(task => task.id));
+    return {
+        roots: work.filter(task => !task.parentTaskId || !ids.has(task.parentTaskId)).map(task => task.id),
+        tasks: work.map(task => ({ id: task.id, parent_task_id: task.parentTaskId, state: task.state, dependencies: [...task.dependencies], planning_decision_id: task.planningDecisionId, planning_round: task.planningRound, review: task.review })),
+    };
+}
 function plannerTrigger(job, manual = false) {
     if (manual)
         return { source: 'manual' };
@@ -329,6 +338,7 @@ export function plannerInput(context) {
         previous_planner_task_id: context.previousPlannerTaskId,
         plan_trigger: context.trigger,
         legacy_change_cycle: context.job.changeCycle,
+        semantic_task_tree: semanticTaskTree(context.tasks),
         project: project ? { name: project.name, path: project.path } : undefined,
         visible_agents: visibleAgents ?? [],
         tasks: context.tasks.map(task => ({

package/dist/reconciler.js

@@ -109,8 +109,10 @@ export class Reconciler extends ReconcilerReviewBase {
             const previousState = job.state;
             const prState = await this.store.pullRequestState?.() ?? 'OPEN';
             const headSha = prState === 'OPEN' ? await this.currentHeadSha(job) : null;
-            if (headSha)
+            if (headSha && job.headSha !== headSha) {
                 job.headSha = headSha;
+                await this.store.saveJob(job);
+            }
             await this.invalidateStaleReview(job, headSha);
             const now = (this.options.now ?? new Date()).getTime();
             if (prState !== 'OPEN') {

package/package.json

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

package/skills/agents-relay/SKILL.md

@@ -101,7 +101,7 @@ Direct orchestrator-created Tasks do not require a Plan. The orchestrator may cr
 
 For explicit `plan` and autonomous 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.
 
-Each successful planner invocation is one real `plan-N` planning round. Relay persists that planner result, then creates the returned Tasks with lineage back to that planning round. 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 are organizational/grouping nodes for the Tasks they produced.
+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.
 
 A zero-task autonomous Job remains idle. After a direct orchestrator-created initial batch completes, Relay may start the first real planner round. Fixed Jobs do not automatically create planner rounds.
 

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

@@ -34,6 +34,17 @@ Keep sibling Tasks at a comparable abstraction level. Do not mix a whole product
 
 The graph is the explanation for the decomposition: every emitted Task should map to a meaningful boundary in the graph, and important graph boundaries should not be omitted accidentally.
 
+### Semantic ownership vs execution flow
+
+The planning graph and the durable Task tree are two different views:
+
+- The graph and `dependencies` express execution flow and prerequisites.
+- `parentTaskId` expresses semantic ownership of an artifact or milestone.
+- A later planning round must inspect the existing Task tree and attach work to the existing artifact it changes. Do not turn a later round into a new root merely because its work follows an earlier Task.
+- `plan-N` records are planning provenance, not business milestones, and must never be used as `parentTaskId`.
+
+For example, produce `architecture-v2` as a root milestone, then place `architecture-review`, `architecture-revision-1`, and `architecture-rereview-1` under it. The revision may depend on the review, and the re-review may depend on the revision; those dependencies do not determine their semantic parent. An independent `graph-runtime-v2` milestone remains a root sibling. A troubleshooter belongs under the failed Task (or its artifact subtree), and specialist review work stays under its review/artifact context.
+
 ### Examples
 
 Prefer:
@@ -69,6 +80,7 @@ Do not create separate Tasks merely for "analyze", "format", "call tool", "check
 - When a Task depends on mutable repository or product state, distinguish a frozen evidence target from the current execution head. A SHA may freeze that Task's own review/source evidence, but do not copy an upstream SHA into a dependent release, deploy, publication, or other follow-on Task unless the objective explicitly requires that same frozen target. After dependencies complete, downstream Tasks must resolve and verify the current durable Job/PR head before acting.
 - When fresh UI, browser, store, runtime, or visual evidence is material to the Task outcome, say so explicitly in the Task input and require evidence from the real current state. Existing screenshots, prepared assets, or prior observations are not substitutes for fresh evidence unless the objective explicitly allows reuse.
 - When a Job needs multi-perspective review, use the visible `review-chair` agent or an Agent Graph to select specialist roles dynamically. Keep specialist Tasks as independent siblings against the same immutable target/version, and leave worker/model/provider routing to Relay.
+- Treat `parentTaskId` as semantic ownership, not execution order. Select an existing non-planner Task as the parent when a later-round revision, re-review, specialist review, or troubleshooting Task belongs to that artifact/milestone; a terminal parent remains valid historical ownership. Use `dependencies` independently for prerequisites, including cross-parent dependencies. Never use a `plan-N` Task as a parent, and never invent a synthetic parent merely to group a planning round.
 - A Task describes what an agent must accomplish; never emit a shell command as a worker Task.
 - Use dependencies only for Task IDs inside the current Job, and only when execution order actually matters. Never encode cross-Job or cross-repository dependencies in `dependencies`.
 - When the current Job is a prerequisite for another durable Job/Task, emit that dependent in top-level `unblocks`. The current blocker Job owns this authoritative reverse relation. Dependent-side `blockedBy` is optional observability metadata and is not the source of truth. Use `resolutionMode: "merge"` when blocker PR merge is sufficient; use `"verified"` when publication, deployment, runtime health, human approval, or another post-merge fact must be verified.

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

@@ -22,6 +22,34 @@ For a newly created PR (`job create --head`), standalone objective Markdown is r
 Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.
 Task producers choose semantic task properties such as objective, dependencies, worker requirements, priority, and `storySize`. They do not normally choose an adapter, provider/model, or raw timeout milliseconds.
 
+### Planning graph and semantic Task tree
+
+The planning graph expresses execution flow. The Task tree expresses semantic
+ownership. `dependencies` answer which durable outcomes must succeed before a
+Task can run; `parentTaskId` answers which durable artifact, milestone, or
+parent outcome the Task belongs to. These are independent relationships and
+must not be inferred from one another.
+
+For a multi-round artifact workflow, keep the business tree compact and
+milestone-oriented:
+
+```text
+Job
+├── Architecture v2
+│   ├── Review
+│   ├── Revision 1
+│   └── Re-review 1
+└── Graph Runtime v2
+```
+
+The revision may depend on Review and Re-review may depend on Revision 1, but
+both remain semantically owned by Architecture v2. A later Planner round must
+inspect existing Tasks and attach review, change, validation-rerun, release
+correction, or recovery work to the existing artifact subtree. An independent
+milestone is a root sibling. `plan-N` records are planning provenance/history,
+never semantic parents. Existing terminal Tasks are historical evidence and
+must not be rewritten merely to improve the tree.
+
 ### Task input vs result
 
 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**.
@@ -98,6 +126,33 @@ For the ChatGPT Browser Worker guardian, for example, the Job defines `pass ->
 
 ### Optional Review Chair Tasks
 
+### Semantic Task tree and planning provenance
+
+The planning graph, semantic Task tree, and dependency graph are separate:
+
+```text
+plan-2 (planning provenance only)
+  ├─ revision (parentTaskId: milestone, dependencies: [review])
+  └─ re-review (parentTaskId: milestone, dependencies: [revision])
+independent-milestone (parentTaskId: null, dependencies: [revision])
+```
+
+`parentTaskId` answers which durable artifact or milestone owns this work. It
+may point to an existing terminal work Task when a later planning round
+continues that artifact, or to another work Task in the same batch. It must
+never point to a `plan-N`/historical `planner-N` record and must not be used
+just to group a round. `dependencies` answer what must finish first and may
+cross semantic subtrees. Reviews, changes-required revisions, re-reviews,
+specialist reviews, and troubleshooter recovery belong under the relevant
+artifact/milestone; independent milestones remain roots. Planning provenance
+is retained separately in `planningDecisionId` and `planningRound`, and
+historical terminal Tasks are immutable.
+
+Incorrect: make every generated Task a child of the current `plan-N`, or use
+`parentTaskId` as a substitute for a dependency. Correct: attach a re-review
+to the original milestone, set its dependency to the revision Task, and leave
+the original milestone's terminal record unchanged.
+
 Projects may use the shared `review-chair` agent as a normal Task or Agent
 Graph node. The chair discovers specialist agent roles from the resolved
 visible-agent catalog, records selection reasons, and creates sibling durable