fix(run-hardening): break PM decision-gate, stale-agent, and empty-diff loops (#255)

Forensic triage of a 24h run reconstructed the dominant gateway.rejected
loops from the audit_log. After earlier deploys fixed the i_will_plan crash
and the open_pr push-gap, three real, recurring-capable burn loops remained.
This fixes them at the architecture level, not by prompt-nagging.

journal:decision write-then-gate (the dominant completion-path blocker):
PM decision-point verbs required a separate note(scope='decision') call
before the verb, which loaded/weak models forget to chain — so complete and
unblock hit a tracing_gap (journal:decision missing) and respawn-looped,
stranding finished tasks forever. Each verb now auto-records its OWN
rationale as the journal:decision before the gate runs (the proven
i_am_blocked -> write_struggle pattern), so the gate passes off real,
persisted reasoning. unblock gains a required `reason` (threaded MCP tool ->
request schema -> routes -> choreographer); delegate derives the decision
from its title + description; complete/submit_up/submit_root/escalate_up/
escalate_to_ceo reuse their existing notes/reason. The gate still runs as
defense-in-depth; the auto-record is idempotent within the decision window
and best-effort. Adds JournalService.write_decision and
Choreographer._ensure_pm_decision.

open_pr empty-diff 422: an overlapping-decomposition leaf with zero commits
vs its base makes GitHub 422 "No commits between ...". The generic
invalid_state "retry" looped the dev 15x on one task. open_pr now steers to a
terminal i_am_blocked hand-off so the PM completes or cancels the redundant
leaf.

owns_task stale-agent loop (41x): a superseded agent (task reassigned away)
calling i_am_done/open_pr got a PRECONDITION_OWNERSHIP tracing_gap it read as
a fixable precondition and retried forever. Both verbs now short-circuit with
the clear not_authorized "no longer yours -> give_me_work" steer that
resume/unclaim already use.

RAG docs updated for the new unblock(reason) signature; CHANGELOG entries
added under 0.11.0 (unreleased). open_pr refactored into
_open_pr_preflight_rejection + _open_pr_failure_env to stay within the
return-count and complexity budgets.

Co-authored-by: Renn F <rennf93@users.noreply.github.com>

tests/integration/test_lifecycle_real_db.py

@@ -915,7 +915,9 @@ async def test_block_then_unblock_restore(
     assert blocked.assigned_to == cell_pm_agent.id
     assert blocked.blocker_raised_by == dev_agent.id
 
-    env = await c.unblock(cell_pm_agent.id, task.id, restore=True)
+    env = await c.unblock(
+        cell_pm_agent.id, task.id, "block resolved upstream; restoring", restore=True
+    )
     assert env.error is None, f"unblock failed: {env.message}"
     assert env.status == Status.IN_PROGRESS.value
 

tests/unit/api/routes/v1/test_flow_cell_pm.py

@@ -97,7 +97,7 @@ async def test_unblock_dispatches_task_id_with_restore_true() -> None:
 
     resp = client.post(
         "/api/v1/flow/cell_pm/unblock",
-        json={"task_id": _TASK_ID},
+        json={"task_id": _TASK_ID, "reason": "block resolved upstream; restoring"},
         headers=_HEADERS,
     )
 
@@ -107,6 +107,7 @@ async def test_unblock_dispatches_task_id_with_restore_true() -> None:
     mock_chore.unblock.assert_awaited_once()
     call_kwargs = mock_chore.unblock.call_args.kwargs
     assert call_kwargs["restore"] is True
+    assert mock_chore.unblock.call_args.args[2] == "block resolved upstream; restoring"
 
 
 @pytest.mark.asyncio
@@ -120,7 +121,11 @@ async def test_unblock_with_restore_false() -> None:
 
     resp = client.post(
         "/api/v1/flow/cell_pm/unblock",
-        json={"task_id": _TASK_ID, "restore": False},
+        json={
+            "task_id": _TASK_ID,
+            "reason": "block resolved upstream; restoring",
+            "restore": False,
+        },
         headers=_HEADERS,
     )
 

tests/unit/api/routes/v1/test_flow_main_pm.py

@@ -119,7 +119,7 @@ async def test_unblock_dispatches_task_id_with_restore_true() -> None:
 
     resp = client.post(
         "/api/v1/flow/main_pm/unblock",
-        json={"task_id": _TASK_ID},
+        json={"task_id": _TASK_ID, "reason": "block resolved upstream; restoring"},
         headers=_HEADERS,
     )
 
@@ -127,6 +127,7 @@ async def test_unblock_dispatches_task_id_with_restore_true() -> None:
     mock_chore.unblock.assert_awaited_once()
     call_kwargs = mock_chore.unblock.call_args.kwargs
     assert call_kwargs["restore"] is True
+    assert mock_chore.unblock.call_args.args[2] == "block resolved upstream; restoring"
 
 
 @pytest.mark.asyncio

tests/unit/gateway/test_choreographer_dev.py

@@ -559,12 +559,15 @@ async def test_i_am_done_blocks_when_journal_reflect_missing() -> None:
 
 
 @pytest.mark.asyncio
-async def test_i_am_done_not_assigned_returns_tracing_gap() -> None:
-    """Spec's PRECONDITION_OWNERSHIP rejects with tracing_gap (owns_task).
+async def test_i_am_done_reassigned_steers_to_give_me_work() -> None:
+    """A stale agent (task reassigned away) gets a clear not_authorized that
+    steers to give_me_work — NOT the owns_task tracing_gap it would retry.
 
-    Pre-spec migration the verb returned not_authorized via an inline
-    ownership check; that's now driven by the spec's extra precondition
-    so the rejection_kind is tracing_gap.
+    A reassignment short-circuit runs before the spec gate (matching
+    resume/unclaim), so a superseded agent is told plainly that the task is
+    no longer its own and to fetch new work, instead of reading the
+    PRECONDITION_OWNERSHIP tracing_gap as a fixable precondition and looping
+    i_am_done forever (the observed owns_task burn-loop).
     """
     agent_id = uuid4()
     other_agent = uuid4()
@@ -587,8 +590,9 @@ async def test_i_am_done_not_assigned_returns_tracing_gap() -> None:
 
     env = await c.i_am_done(agent_id, task_id, "completed the work")
     body = env.as_dict()
-    assert body["error"] == "tracing_gap"
-    assert "owns_task" in body["missing"]
+    assert body["error"] == "not_authorized"
+    assert "no longer assigned" in (body.get("message") or "").lower()
+    assert "give_me_work" in (body.get("remediate") or "")
 
 
 @pytest.mark.asyncio

tests/unit/gateway/test_choreographer_impl_branches.py

@@ -857,7 +857,7 @@ async def test_unblock_task_not_found() -> None:
     task_svc.get.return_value = None
     deps = _make_deps(task=task_svc)
     c = Choreographer(deps)
-    env = await c.unblock(pm_id, task_id)
+    env = await c.unblock(pm_id, task_id, "block resolved upstream; restoring")
     body = env.as_dict()
     assert body["error"] == "not_found"
 

tests/unit/gateway/test_choreographer_pm.py

@@ -154,7 +154,9 @@ async def test_unblock_restores_pre_block_state() -> None:
     deps = _make_deps(task=task_svc, journal=journal_svc)
     c = Choreographer(deps)
 
-    env = await c.unblock(pm_id, task_id, restore=True)
+    env = await c.unblock(
+        pm_id, task_id, "block resolved upstream; restoring", restore=True
+    )
     assert env.error is None
     assert env.status == "awaiting_documentation"
     task_svc.unblock_with_restore.assert_awaited_once_with(pm_id, task_id, restore=True)
@@ -182,7 +184,7 @@ async def test_unblock_default_restores() -> None:
     c = Choreographer(deps)
 
     # restore omitted -> defaults to True
-    env = await c.unblock(pm_id, task_id)
+    env = await c.unblock(pm_id, task_id, "block resolved upstream; restoring")
     assert env.status == "awaiting_qa"
 
 
@@ -199,7 +201,7 @@ async def test_unblock_blocks_without_journal_decision() -> None:
     deps = _make_deps(task=task_svc, journal=journal_svc)
     c = Choreographer(deps)
 
-    env = await c.unblock(pm_id, task_id)
+    env = await c.unblock(pm_id, task_id, "block resolved upstream; restoring")
     body = env.as_dict()
     assert body["error"] == "tracing_gap"
     assert "journal:decision" in body["missing"]
@@ -215,7 +217,7 @@ async def test_unblock_wrong_state_returns_invalid_state() -> None:
     deps = _make_deps(task=task_svc)
     c = Choreographer(deps)
 
-    env = await c.unblock(pm_id, task_id)
+    env = await c.unblock(pm_id, task_id, "block resolved upstream; restoring")
     body = env.as_dict()
     assert body["error"] == "invalid_state"
 
@@ -241,7 +243,9 @@ async def test_unblock_restore_false_returns_legacy_message() -> None:
     deps = _make_deps(task=task_svc, journal=journal_svc)
     c = Choreographer(deps)
 
-    env = await c.unblock(pm_id, task_id, restore=False)
+    env = await c.unblock(
+        pm_id, task_id, "block resolved upstream; restoring", restore=False
+    )
     body = env.as_dict()
     assert body["status"] == "in_progress"
     assert "re-engage" in body["next"].lower()
@@ -267,7 +271,7 @@ async def test_unblock_refused_while_a_dependency_is_unfinished() -> None:
     deps = _make_deps(task=task_svc, journal=journal_svc)
     c = Choreographer(deps)
 
-    env = await c.unblock(pm_id, task_id)
+    env = await c.unblock(pm_id, task_id, "block resolved upstream; restoring")
     body = env.as_dict()
 
     assert body["error"] == "invalid_state"

tests/unit/gateway/test_choreographer_submit_qa_gates.py

@@ -359,13 +359,13 @@ async def test_i_am_done_proceeds_when_all_gates_pass() -> None:
 
 @pytest.mark.asyncio
 async def test_i_am_done_blocks_unauthorized() -> None:
-    """Spec's PRECONDITION_OWNERSHIP rejects with tracing_gap when the
-    caller does not own the task.
+    """A caller that does not own the task gets a clear not_authorized that
+    steers to give_me_work — not the owns_task tracing_gap it would retry.
 
-    Pre-spec migration the verb returned a separate not_authorized
-    envelope from an inline ownership check; the spec now drives this
-    decision via PRECONDITION_OWNERSHIP, which surfaces as tracing_gap
-    with the `owns_task` missing token.
+    A reassignment short-circuit runs before the spec gate, so a stale /
+    superseded agent is told plainly the task is no longer its own (instead
+    of reading PRECONDITION_OWNERSHIP's tracing_gap as a fixable precondition
+    and looping i_am_done — the observed owns_task burn-loop).
     """
     agent_id = uuid4()
     other_id = uuid4()
@@ -381,5 +381,6 @@ async def test_i_am_done_blocks_unauthorized() -> None:
 
     env = await c.i_am_done(agent_id, task_id, "done")
     body = env.as_dict()
-    assert body["error"] == "tracing_gap"
-    assert "owns_task" in body["missing"]
+    assert body["error"] == "not_authorized"
+    assert "no longer assigned" in (body.get("message") or "").lower()
+    assert "give_me_work" in (body.get("remediate") or "")

tests/unit/gateway/test_open_pr.py

@@ -117,7 +117,14 @@ async def test_open_pr_pushes_and_opens_pr() -> None:
 
 
 @pytest.mark.asyncio
-async def test_open_pr_rejects_when_not_assigned() -> None:
+async def test_open_pr_reassigned_steers_to_give_me_work() -> None:
+    """A stale agent (task reassigned away) gets a clear not_authorized that
+    steers to give_me_work — NOT the owns_task tracing_gap it would retry.
+
+    The reassignment short-circuit runs before the spec gate, so the agent
+    never sees the misleading 'fixable precondition' framing that drove the
+    observed open_pr owns_task retry-loops.
+    """
     aid = uuid4()
     other = uuid4()
     tid = uuid4()
@@ -141,10 +148,48 @@ async def test_open_pr_rejects_when_not_assigned() -> None:
 
     git_svc.push_branch.assert_not_awaited()
     git_svc.create_pr.assert_not_awaited()
-    # Spec's PRECONDITION_OWNERSHIP surfaces as tracing_gap (owns_task missing)
-    # rather than the previous bespoke not_authorized message.
-    assert env.error == "tracing_gap"
-    assert env.missing == ["owns_task"]
+    assert env.error == "not_authorized"
+    assert "no longer assigned" in (env.message or "").lower()
+    assert "give_me_work" in (env.remediate or "")
+
+
+@pytest.mark.asyncio
+async def test_open_pr_empty_diff_steers_to_blocked_not_retry() -> None:
+    """An empty-diff subtask (branch has no commits vs base → GitHub 422
+    'No commits between') gets a terminal i_am_blocked steer, not a generic
+    'retry' invalid_state that loops the dev forever."""
+    aid = uuid4()
+    tid = uuid4()
+    t = MagicMock(
+        id=tid,
+        status="in_progress",
+        assigned_to=aid,
+        plan="x",
+        commits=[{"sha": "abc"}],
+        pr_number=None,
+        parent_task_id=None,
+        branch_name="feature/backend/abc12345",
+    )
+    task_svc = AsyncMock()
+    task_svc.get.side_effect = [t, t]
+    task_svc.agent_for.return_value = MagicMock(role="developer", team="backend")
+    _wire_savepoint(task_svc)
+    git_svc = AsyncMock()
+    git_svc.push_branch.return_value = ("feature/backend/abc12345", 1)
+    git_svc.create_pr.side_effect = Exception(
+        'GitHub API refused PR creation (422): {"message":"Validation Failed",'
+        '"errors":[{"message":"No commits between feature/backend/abc12345 and '
+        'feature/backend/abc12345--child"}]}'
+    )
+    deps = _make_deps(task=task_svc, git=git_svc)
+    c = Choreographer(deps)
+
+    env = await c.open_pr(aid, tid)
+
+    assert env.error == "invalid_state"
+    assert "no commits" in (env.message or "").lower()
+    assert "i_am_blocked" in (env.remediate or "")
+    assert "do not retry" in (env.remediate or "").lower()
 
 
 @pytest.mark.asyncio

tests/unit/gateway/test_pm_decision_autorecord.py

@@ -0,0 +1,112 @@
+"""Tests for ``_ensure_pm_decision`` — the write-then-gate auto-record.
+
+A PM verb that carries a substantive rationale (complete/submit_up/
+submit_root ``notes``, escalate ``reason``, or a synthesized unblock line)
+records it as the journal:decision the tracing gate requires *before* the
+gate runs. This removes the dominant stall where a loaded/weak-model PM
+forgot the separate note(scope='decision') call and looped on a
+tracing_gap → respawn. The gate itself is unchanged (see
+test_pm_decision_window.py) — this only ensures a fresh decision exists.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+from roboco.config import settings as _roboco_settings
+from roboco.services.gateway.choreographer import (
+    Choreographer,
+    ChoreographerDeps,
+)
+
+
+def _make_deps(**overrides: Any) -> ChoreographerDeps:
+    """Async-mock every service the Choreographer depends on."""
+    base = {
+        "task": AsyncMock(),
+        "work_session": AsyncMock(),
+        "git": AsyncMock(),
+        "a2a": AsyncMock(),
+        "journal": AsyncMock(),
+        "audit": AsyncMock(),
+        "evidence_repo": AsyncMock(),
+    }
+    base.update(overrides)
+    task = base["task"]
+    task.session = MagicMock()
+    task.session.begin_nested = MagicMock(
+        return_value=MagicMock(
+            __aenter__=AsyncMock(return_value=None),
+            __aexit__=AsyncMock(return_value=False),
+        )
+    )
+    return ChoreographerDeps(**base)
+
+
+@pytest.mark.asyncio
+async def test_writes_decision_when_none_exists() -> None:
+    agent_id, task_id = uuid4(), uuid4()
+    journal = AsyncMock()
+    journal.latest_decision_at.return_value = None
+    c = Choreographer(_make_deps(journal=journal))
+
+    await c._ensure_pm_decision(agent_id, task_id, "Merging PR #120; all ACs verified")
+
+    journal.write_decision.assert_awaited_once()
+    _args, kwargs = journal.write_decision.call_args
+    assert kwargs["agent_id"] == agent_id
+    assert kwargs["task_id"] == task_id
+    assert "Merging PR #120" in kwargs["content"]
+
+
+@pytest.mark.asyncio
+async def test_skips_when_fresh_decision_already_exists() -> None:
+    journal = AsyncMock()
+    journal.latest_decision_at.return_value = datetime.now(UTC) - timedelta(seconds=60)
+    c = Choreographer(_make_deps(journal=journal))
+
+    await c._ensure_pm_decision(uuid4(), uuid4(), "rationale text here")
+
+    journal.write_decision.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_writes_when_existing_decision_is_stale() -> None:
+    journal = AsyncMock()
+    journal.latest_decision_at.return_value = datetime.now(UTC) - timedelta(
+        seconds=_roboco_settings.pm_decision_window_seconds + 1
+    )
+    c = Choreographer(_make_deps(journal=journal))
+
+    await c._ensure_pm_decision(uuid4(), uuid4(), "fresh rationale around this point")
+
+    journal.write_decision.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_noop_on_empty_rationale() -> None:
+    journal = AsyncMock()
+    c = Choreographer(_make_deps(journal=journal))
+
+    await c._ensure_pm_decision(uuid4(), uuid4(), "   ")
+    await c._ensure_pm_decision(uuid4(), uuid4(), None)
+
+    journal.latest_decision_at.assert_not_awaited()
+    journal.write_decision.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_swallows_write_failure_best_effort() -> None:
+    """A journal write failure must not crash the verb — the gate then
+    rejects normally (the pre-fix behaviour), never a 500."""
+    journal = AsyncMock()
+    journal.latest_decision_at.return_value = None
+    journal.write_decision.side_effect = RuntimeError("db down")
+    c = Choreographer(_make_deps(journal=journal))
+
+    # Must not raise.
+    await c._ensure_pm_decision(uuid4(), uuid4(), "rationale that triggers a write")

tests/unit/mcp_servers/test_flow_server.py

@@ -368,12 +368,16 @@ def test_unblock_with_restore_true(monkeypatch: pytest.MonkeyPatch) -> None:
     fake_client = _make_fake_client({"status": "in_progress"})
 
     with patch("httpx.Client", return_value=fake_client):
-        result = srv.unblock("task-uuid")
+        result = srv.unblock("task-uuid", "block resolved upstream; restoring")
 
     assert result["status"] == "in_progress"
     args, kwargs = fake_client.post.call_args
     assert "/api/v1/flow/cell_pm/unblock" in args[0]
-    assert kwargs["json"] == {"task_id": "task-uuid", "restore": True}
+    assert kwargs["json"] == {
+        "task_id": "task-uuid",
+        "reason": "block resolved upstream; restoring",
+        "restore": True,
+    }
 
 
 def test_unblock_with_restore_false(monkeypatch: pytest.MonkeyPatch) -> None:
@@ -384,11 +388,17 @@ def test_unblock_with_restore_false(monkeypatch: pytest.MonkeyPatch) -> None:
     fake_client = _make_fake_client({"status": "in_progress"})
 
     with patch("httpx.Client", return_value=fake_client):
-        result = srv.unblock("task-uuid", restore=False)
+        result = srv.unblock(
+            "task-uuid", "block resolved upstream; restoring", restore=False
+        )
 
     assert result["status"] == "in_progress"
     _args, kwargs = fake_client.post.call_args
-    assert kwargs["json"] == {"task_id": "task-uuid", "restore": False}
+    assert kwargs["json"] == {
+        "task_id": "task-uuid",
+        "reason": "block resolved upstream; restoring",
+        "restore": False,
+    }
 
 
 def test_complete_passes_notes(monkeypatch: pytest.MonkeyPatch) -> None:

tests/unit/services/test_journal.py

@@ -115,6 +115,44 @@ async def test_write_struggle_handles_empty_content_gracefully() -> None:
     assert params.title == "Struggle"
 
 
+@pytest.mark.asyncio
+async def test_write_decision_calls_add_decision_log_with_task_id() -> None:
+    """write_decision delegates to add_decision_log with a DECISION_LOG entry.
+
+    Title comes from the first content line (truncated to 100 chars); the
+    full content is carried in the rationale field so the auto-recorded
+    decision reads coherently in journal lists and RAG retrieval.
+    """
+    svc = JournalService(MagicMock(flush=AsyncMock()))
+    add_decision_mock = AsyncMock(
+        return_value=MagicMock(type=JournalEntryType.DECISION_LOG)
+    )
+    _bind(svc, "add_decision_log", add_decision_mock)
+    agent_id = uuid4()
+    task_id = uuid4()
+    content = "Completing PR #120: all 3 acceptance criteria verified\nmore detail"
+    out = await svc.write_decision(agent_id=agent_id, task_id=task_id, content=content)
+    assert out is not None
+    add_decision_mock.assert_awaited_once()
+    args, _kwargs = add_decision_mock.call_args
+    assert args[0] == agent_id
+    params = args[1]
+    assert params.task_id == task_id
+    assert params.title == "Completing PR #120: all 3 acceptance criteria verified"
+    assert content in params.rationale
+
+
+@pytest.mark.asyncio
+async def test_write_decision_handles_empty_content_gracefully() -> None:
+    svc = JournalService(MagicMock(flush=AsyncMock()))
+    add_decision_mock = AsyncMock(return_value=MagicMock())
+    _bind(svc, "add_decision_log", add_decision_mock)
+    await svc.write_decision(agent_id=uuid4(), task_id=uuid4(), content="")
+    args, _kwargs = add_decision_mock.call_args
+    params = args[1]
+    assert params.title == "Decision"
+
+
 # ---------------------------------------------------------------------------
 # latest_decision_at — windowed-satisfaction support for the PM-decision gate
 # (C8). Returns the `created_at` of the newest DECISION_LOG entry for an