devrites 3.2.26 → 3.2.28

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.2.28](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.27...v3.2.28) (2026-07-29)
+
+### Fixed
+
+* **agents:** bind durable V2 agent starts ([1da2cef](https://github.com/ViktorsBaikers/DevRites/commit/1da2cefd2a1e6b2ecb6a626224cc94fa0fc3662e))
+
+## [3.2.27](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.26...v3.2.27) (2026-07-29)
+
+### Fixed
+
+* **rite:** separate recovery causes from symptoms ([c01f516](https://github.com/ViktorsBaikers/DevRites/commit/c01f5164ce349e5caad6ce450cfa6d76c7ce522b))
+
 ## [3.2.26](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.25...v3.2.26) (2026-07-29)
 
 ### Fixed

package/README.md

@@ -25,7 +25,7 @@ final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.2.26`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.26): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.28`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.28): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 

package/engine/hooks_agent_dispatch.go

@@ -517,7 +517,7 @@ func durableCodexV2DispatchAttempts(
 		var childMeta codexRolloutRecord
 		if strings.TrimSpace(spawn.Result) != "" {
 			childPath, childMeta, err = findCodexV2ChildRollout(
-				sessionsDir, parentPath, projectRoot, sessionID, spawn.AgentPath,
+				sessionsDir, parentPath, projectRoot, sessionID, spawn.AgentPath, "",
 			)
 			if err != nil {
 				return nil, err
@@ -687,10 +687,14 @@ func readCodexV2ParentRollout(
 }
 
 func findCodexV2ChildRollout(
-	sessionsDir, parentPath, projectRoot, sessionID, agentPath string,
+	sessionsDir, parentPath, projectRoot, sessionID, agentPath, agentID string,
 ) (string, codexRolloutRecord, error) {
 	var childPath string
 	var childMeta codexRolloutRecord
+	selector := agentPath
+	if selector == "" {
+		selector = agentID
+	}
 	err := filepath.WalkDir(sessionsDir, func(path string, entry fs.DirEntry, walkErr error) error {
 		if walkErr != nil {
 			if os.IsNotExist(walkErr) {
@@ -707,12 +711,13 @@ func findCodexV2ChildRollout(
 		}
 		if record.Type != "session_meta" ||
 			record.Payload.ParentThreadID != sessionID ||
-			record.Payload.AgentPath != agentPath ||
+			(agentPath != "" && record.Payload.AgentPath != agentPath) ||
+			(agentID != "" && record.Payload.ID != agentID) ||
 			!sameResolvedPath(record.Payload.CWD, projectRoot) {
 			return nil
 		}
 		if childPath != "" {
-			return fmt.Errorf("multiple Codex child rollouts match %s", agentPath)
+			return fmt.Errorf("multiple Codex child rollouts match %s", selector)
 		}
 		childPath = path
 		childMeta = record
@@ -1540,6 +1545,12 @@ func bindAgentDispatchStart(root string, in agentDispatchHookInput) (string, boo
 	started := map[string]struct{}{}
 	for _, event := range events {
 		if event.Event == "started" {
+			if event.AgentID == in.AgentID {
+				if event.AgentType != in.AgentType || event.Role == "" {
+					return "", false, fmt.Errorf("subagent %s is already bound to a different dispatch", in.AgentID)
+				}
+				return event.Role, true, nil
+			}
 			started[event.ToolUseID] = struct{}{}
 		}
 	}
@@ -1558,7 +1569,7 @@ func bindAgentDispatchStart(root string, in agentDispatchHookInput) (string, boo
 		candidates = append(candidates, event)
 	}
 	if len(candidates) == 0 {
-		return "", false, nil
+		return bindDurableCodexV2Start(root, in, events)
 	}
 	if len(candidates) != 1 {
 		return "", false, fmt.Errorf("ambiguous subagent start: %d pending %s dispatches lack a parent tool-use binding", len(candidates), in.AgentType)
@@ -1578,6 +1589,84 @@ func bindAgentDispatchStart(root string, in agentDispatchHookInput) (string, boo
 	return event.Role, true, nil
 }
 
+func bindDurableCodexV2Start(
+	root string, in agentDispatchHookInput, events []agentDispatchEvent,
+) (string, bool, error) {
+	if !devritesAgentNameRe.MatchString(in.AgentType) || in.AgentType == agentDispatchSkillGuard {
+		return "", false, nil
+	}
+	parentPath, sessionsDir, err := findCodexParentRollout(in.SessionID)
+	if err != nil || parentPath == "" {
+		return "", false, err
+	}
+	projectRoot := filepath.Dir(root)
+	childPath, childMeta, err := findCodexV2ChildRollout(
+		sessionsDir, parentPath, projectRoot, in.SessionID, "", in.AgentID,
+	)
+	if err != nil || childPath == "" || childMeta.Payload.AgentRole != in.AgentType {
+		return "", false, err
+	}
+
+	turns := map[string]struct{}{}
+	for _, event := range events {
+		if event.TurnID != "" {
+			turns[event.TurnID] = struct{}{}
+		}
+	}
+	type binding struct {
+		turnID, windowID string
+	}
+	var matches []binding
+	for turnID := range turns {
+		armed, _ := dispatchTurnState(events, turnID)
+		_, required := armed[in.AgentType]
+		_, guarded := armed[agentDispatchSkillGuard]
+		if !required && !guarded {
+			continue
+		}
+		spawns, _, err := readCodexV2ParentRollout(
+			parentPath, projectRoot, in.SessionID, turnID, armed,
+		)
+		if err != nil {
+			return "", false, err
+		}
+		spawn := spawns[childMeta.Payload.AgentPath]
+		if spawn == nil || spawn.Role != in.AgentType {
+			continue
+		}
+		windowID := ""
+		if in.AgentType == "devrites-slice-wright" {
+			windowID = currentReconcileWindowID()
+			if windowID == "" || !reconcileWindowPredates(spawn.SpawnedAt) {
+				continue
+			}
+		}
+		matches = append(matches, binding{turnID: turnID, windowID: windowID})
+	}
+	if len(matches) == 0 {
+		return "", false, nil
+	}
+	if len(matches) != 1 {
+		return "", false, fmt.Errorf(
+			"ambiguous durable subagent start: %d parent spawns match %s",
+			len(matches), in.AgentID,
+		)
+	}
+	match := matches[0]
+	if err := appendAgentDispatchEvent(root, in.SessionID, agentDispatchEvent{
+		Event:     "started",
+		TurnID:    match.turnID,
+		ToolUseID: "codex-v2:" + in.AgentID,
+		AgentID:   in.AgentID,
+		AgentType: in.AgentType,
+		Role:      in.AgentType,
+		WindowID:  match.windowID,
+	}); err != nil {
+		return "", false, err
+	}
+	return in.AgentType, true, nil
+}
+
 type boundAgentDispatchAttempt struct {
 	TurnID    string
 	AgentType string

package/engine/tests/hook_test.go

@@ -2082,6 +2082,52 @@ func TestCodexAgentDispatchConfirmsDurableV2NamedRole(t *testing.T) {
 	}
 }
 
+func TestCodexAgentDispatchBindsDurableV2NamedStartWithoutPreToolReceipt(t *testing.T) {
+	root := newWorkspace(t)
+	codeHome := t.TempDir()
+	sessionID, turnID := "session-v2-start", "turn-v2-start"
+	role := "devrites-plan-reviewer"
+	taskName := "devrites_plan_reviewer_named"
+	writeCodexAgentContract(t, root, role)
+	writeCodexSkillContract(t, root, "rite-vet", role)
+
+	runDevritesIO(t, root, hookPayload(t, map[string]any{
+		"hook_event_name": "UserPromptSubmit",
+		"session_id":      sessionID,
+		"turn_id":         turnID,
+		"prompt":          "$rite-vet",
+	}), nil, "hook", "agent-dispatch", "--harness=codex")
+	writeCodexV2Rollouts(
+		t, codeHome, filepath.Dir(root), sessionID, turnID, role,
+		taskName, false, false, false,
+	)
+
+	mismatched, _, _ := runDevritesIO(t, root, hookPayload(t, map[string]any{
+		"hook_event_name": "SubagentStart",
+		"session_id":      sessionID,
+		"turn_id":         "child-turn",
+		"agent_id":        "child-" + taskName,
+		"agent_type":      "devrites-plan-drafter",
+	}), []string{"CODEX_HOME=" + codeHome}, "hook", "subagent-orient", "--harness=codex")
+	if !strings.Contains(mismatched, "Unbound named start") {
+		t.Fatalf("mismatched named role was bound: %s", mismatched)
+	}
+
+	out, stderr, code := runDevritesIO(t, root, hookPayload(t, map[string]any{
+		"hook_event_name": "SubagentStart",
+		"session_id":      sessionID,
+		"turn_id":         "child-turn",
+		"agent_id":        "child-" + taskName,
+		"agent_type":      role,
+	}), []string{"CODEX_HOME=" + codeHome}, "hook", "subagent-orient", "--harness=codex")
+	if code != 0 {
+		t.Fatalf("start exit=%d stderr=%s", code, stderr)
+	}
+	if !strings.Contains(out, "Confirmed role") || strings.Contains(out, "Unbound named start") {
+		t.Fatalf("durable named start was not bound: %s", out)
+	}
+}
+
 func TestCodexAgentDispatchConfirmsDurableV2ChildRoleWhenParentOmitsAgentType(t *testing.T) {
 	root := newWorkspace(t)
 	codeHome := t.TempDir()

package/pack/.claude/skills/devrites-debug-recovery/reference/cleanup-and-classify.md

@@ -2,8 +2,10 @@
 
 ## Classify one causal fingerprint
 
-Use one class per normalized root cause. A class changes only when new evidence changes
-the diagnosis:
+Fingerprint the causal diagnosis, never the failing test or symptom. Reuse it while
+plausible. If a discriminating fix proves the cause absent but the symptom remains,
+preserve that diagnosis as a dead end and classify a new fingerprint. Failure alone
+never resets a budget.
 
 - `intent_gap`: desired behavior, scope, policy, or risk choice is unsettled.
 - `spec_gap`: an acceptance outcome or product decision is missing.
@@ -20,11 +22,9 @@ Ask the engine for the canonical owner and action:
 devrites-engine recovery route <class>
 ```
 
-Follow the `recovery-route/v1` result. `humanPause: true` routes an unresolved intent or
-spec choice through Clarify. Technical routes stay agent-owned: repair the implementation
-or proof tool, normalize the environment, or repair the plan without asking permission to
-retry. A credential, external quota, irreversible action, or user-owned process that only
-the human can handle gets an exact human-intervention gate; it is not retry authorization.
+Follow `recovery-route/v1`. `humanPause: true` routes unresolved intent/spec through
+Clarify. Technical routes stay agent-owned. Gate only an exact human credential, quota,
+irreversible action, or user-owned process—never retry authorization.
 
 Record the class with every new failed attempt and green clear:
 

package/pack/.claude/skills/rite-plan/reference/replan-and-repair.md

@@ -33,9 +33,9 @@ errors: `devrites-api-interface`), then split into a backend slice (can land wit
 stub consumer) and a frontend slice (can land against a mock/real contract).
 
 ## unblock
-A `/rite-prove` failure can't be fixed inside the current slice. Capture the blocker in
-`state.md`, decide: route around it (reorder), shrink the slice (reslice), or escalate
-to the user (if it changes scope). Don't loop on the same failing approach.
+An exhausted fingerprint blocks diagnosis, not symptom. Route around/reslice; escalate
+only for scope change. If proof removed that cause but symptom remains, keep the dead
+end and plan a new diagnosis/proof fingerprint. Never clear/reuse old one.
 
 ## Always
 Update `state.md` (phase, next step) and append a dated line to `decisions.md`

package/pack/generated/claude/skills/devrites-debug-recovery/reference/cleanup-and-classify.md

@@ -2,8 +2,10 @@
 
 ## Classify one causal fingerprint
 
-Use one class per normalized root cause. A class changes only when new evidence changes
-the diagnosis:
+Fingerprint the causal diagnosis, never the failing test or symptom. Reuse it while
+plausible. If a discriminating fix proves the cause absent but the symptom remains,
+preserve that diagnosis as a dead end and classify a new fingerprint. Failure alone
+never resets a budget.
 
 - `intent_gap`: desired behavior, scope, policy, or risk choice is unsettled.
 - `spec_gap`: an acceptance outcome or product decision is missing.
@@ -20,11 +22,9 @@ Ask the engine for the canonical owner and action:
 devrites-engine recovery route <class>
 ```
 
-Follow the `recovery-route/v1` result. `humanPause: true` routes an unresolved intent or
-spec choice through Clarify. Technical routes stay agent-owned: repair the implementation
-or proof tool, normalize the environment, or repair the plan without asking permission to
-retry. A credential, external quota, irreversible action, or user-owned process that only
-the human can handle gets an exact human-intervention gate; it is not retry authorization.
+Follow `recovery-route/v1`. `humanPause: true` routes unresolved intent/spec through
+Clarify. Technical routes stay agent-owned. Gate only an exact human credential, quota,
+irreversible action, or user-owned process—never retry authorization.
 
 Record the class with every new failed attempt and green clear:
 

package/pack/generated/claude/skills/rite-plan/reference/replan-and-repair.md

@@ -33,9 +33,9 @@ errors: `devrites-api-interface`), then split into a backend slice (can land wit
 stub consumer) and a frontend slice (can land against a mock/real contract).
 
 ## unblock
-A `/rite-prove` failure can't be fixed inside the current slice. Capture the blocker in
-`state.md`, decide: route around it (reorder), shrink the slice (reslice), or escalate
-to the user (if it changes scope). Don't loop on the same failing approach.
+An exhausted fingerprint blocks diagnosis, not symptom. Route around/reslice; escalate
+only for scope change. If proof removed that cause but symptom remains, keep the dead
+end and plan a new diagnosis/proof fingerprint. Never clear/reuse old one.
 
 ## Always
 Update `state.md` (phase, next step) and append a dated line to `decisions.md`

package/pack/generated/codex/skills/devrites-debug-recovery/reference/cleanup-and-classify.md

@@ -2,8 +2,10 @@
 
 ## Classify one causal fingerprint
 
-Use one class per normalized root cause. A class changes only when new evidence changes
-the diagnosis:
+Fingerprint the causal diagnosis, never the failing test or symptom. Reuse it while
+plausible. If a discriminating fix proves the cause absent but the symptom remains,
+preserve that diagnosis as a dead end and classify a new fingerprint. Failure alone
+never resets a budget.
 
 - `intent_gap`: desired behavior, scope, policy, or risk choice is unsettled.
 - `spec_gap`: an acceptance outcome or product decision is missing.
@@ -20,11 +22,9 @@ Ask the engine for the canonical owner and action:
 devrites-engine recovery route <class>
 ```
 
-Follow the `recovery-route/v1` result. `humanPause: true` routes an unresolved intent or
-spec choice through Clarify. Technical routes stay agent-owned: repair the implementation
-or proof tool, normalize the environment, or repair the plan without asking permission to
-retry. A credential, external quota, irreversible action, or user-owned process that only
-the human can handle gets an exact human-intervention gate; it is not retry authorization.
+Follow `recovery-route/v1`. `humanPause: true` routes unresolved intent/spec through
+Clarify. Technical routes stay agent-owned. Gate only an exact human credential, quota,
+irreversible action, or user-owned process—never retry authorization.
 
 Record the class with every new failed attempt and green clear:
 

package/pack/generated/codex/skills/rite-plan/reference/replan-and-repair.md

@@ -33,9 +33,9 @@ errors: `devrites-api-interface`), then split into a backend slice (can land wit
 stub consumer) and a frontend slice (can land against a mock/real contract).
 
 ## unblock
-A `$rite-prove` failure can't be fixed inside the current slice. Capture the blocker in
-`state.md`, decide: route around it (reorder), shrink the slice (reslice), or escalate
-to the user (if it changes scope). Don't loop on the same failing approach.
+An exhausted fingerprint blocks diagnosis, not symptom. Route around/reslice; escalate
+only for scope change. If proof removed that cause but symptom remains, keep the dead
+end and plan a new diagnosis/proof fingerprint. Never clear/reuse old one.
 
 ## Always
 Update `state.md` (phase, next step) and append a dated line to `decisions.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.2.26",
+  "version": "3.2.28",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",