Fix: agent workflow hardening (#70)

* fix(gateway): push the branch before QA handoff so reviewers see the latest commits

The commit content tool commits locally without pushing; only open_pr pushed
the branch. On the first submission that was fine, but a fix committed while
addressing needs_revision never reached origin (open_pr is skipped once the PR
exists), so QA — which reviews the remote PR branch — re-reviewed the stale
remote and re-failed the task on every cycle, a loop that never converged.

i_am_done now pushes the task branch (idempotent; a no-op when nothing is
unpushed) as part of the shared submit gate, covering both the normal and
resume-from-verifying paths. A push failure blocks the handoff with a clear
remediation rather than parking the task in awaiting_qa with commits that exist
only in the developer's local workspace.

* fix(orchestrator): don't reap a stale claim while the agent's container is alive

The stale-claim reaper released any claimed/in_progress task whose
last_heartbeat_at exceeded the TTL. The heartbeat only updates on certain
gateway calls, so a developer deep in a long edit/test cycle outran the TTL and
had its claim reaped mid-work — churning the task and risking a double spawn
against the still-running container.

The reaper now skips a task whose assignee still holds a live (ACTIVE) agent
instance, trusting container liveness — the ground truth — over the heartbeat
proxy. The check is defensive on missing fields so a heartbeat-only caller (and
the reaper's existing unit tests) behave exactly as before.

* fix(gateway): refuse to unblock a task while a dependency is unfinished

A PM unblock on a dependency-gated task moved it straight to in_progress,
overriding the dependency — letting a dependent proceed without its upstream's
work (e.g. a frontend task built before its UX design lands). A dependency
block is meant to clear on its own via _unblock_dependents the moment the
upstream reaches a terminal state.

unblock now refuses while any dependency is still non-terminal, returning a
clear remediation that the block resolves automatically. Manual unblock remains
available for genuine, non-dependency blockers.

* fix(gateway): release a dependency-blocked claim to pending instead of looping

A task that reached claimed/in_progress with an unfinished dependency was left
in that state when the claim guard rejected, so the orchestrator's respawn loop
kept reviving its assignee — which could make no progress — burning work for
nothing.

The claim guard now releases such a task back to pending. claimed -> blocked is
not a legal transition, so pending — held by the dispatch dependency filter — is
the lifecycle-correct resting state: the respawn loop ignores pending tasks, and
_unblock_dependents re-dispatches it once the upstream reaches a terminal state.
release_dependency_blocked_claim shares a _force_unclaim_to_pending core with
unclaim_for_reaper so both record a truthful work-session abandon reason.

* feat(security): warn at startup in header-trust mode + document the auth posture

When ROBOCO_AGENT_AUTH_REQUIRED is not enabled the API accepts the X-Agent-Id /
X-Agent-Role headers without a signed token, so any client that can reach it may
act as any role (including 'ceo'). The API now logs a clear warning at startup
in this mode, and the README gains a Security section documenting the auth
posture and how to harden it. Acceptable only on a trusted private network — do
not expose the API to untrusted networks.

* fix(workspace): scope the refresh fetch to current + default branch

ensure_workspace's healthy short-circuit ran an all-refs 'git fetch origin' to
keep every origin/<branch> ref current. On a monorepo with many accumulated
feature/* branches that exceeds the refresh timeout, the fetch silently fails,
and the workspace keeps a stale base — so an agent builds on an out-of-date
branch.

The refresh now fetches only the workspace's current branch and the repo's
default branch (resolved via origin/HEAD), with --no-tags --prune: it transfers
near-nothing and can't time out. Readers need their own branch and the default;
the integration branch is refreshed at branch-creation time.

* fix(git): refresh a dependency-blocked task's branch off the current integration tip

A cross-cell dependent (e.g. a frontend task waiting on the UX design) was
branched off a base captured before its upstream merged into the integration
branch, and the branch was never re-synced — so the agent built on a stale
snapshot with none of the upstream's work.

Two changes close the gap:
- release_dependency_blocked_claim now clears branch_name, so the re-claim
  (after the dependency clears) re-runs branch creation.
- create_branch, when the branch is already on disk with no commits of its own,
  resets it onto the freshly-pulled base — the dependent now builds on the
  current integration tip. A branch carrying real commits is left untouched, so
  no work is discarded; the cell->leaf cascade carries the upstream down to the
  dev branch automatically.

* refactor(gateway): drop the sibling-sequence claim guard

Sibling sequence no longer gates a claim. Cross-cell ordering is
enforced by task dependencies — a cell task that depends on another is
held until its upstream reaches a terminal state, a stronger,
status-aware gate than the sequence-number check. That check was
dormant in practice anyway: every fan-out child carries sequence 0, on
which the guard short-circuited. `sequence` stays a sibling-ordering /
dispatch-priority field (list_pending ordering and the panel).

Removes sibling_sequence_guard and its _earlier_blocking_sibling
helper, the now-unused skip_sequence parameter threaded through the
claim verbs, and the sibling fetch that fed it.

* feat(gateway): sort a cross-cell dependent after its upstream

When the frontend cell task is wired to depend on its UX/UI sibling, set
its sequence to the upstream's sequence + 1 so it sorts after the design
it waits on — list_pending ordering and the panel now show UX ahead of
the implementation it gates, in either delegation order.

Adds TaskService.set_sequence (the sibling-ordering field is a service
write; it carries no claim-gating semantics — dependencies gate claims).

* feat(gateway): make the backend cell depend on UX too

UX/UI design defines the screens and API contracts both implementation
cells build against, so the backend cell — not just the frontend — waits
on the UX/UI cell task in a product fan-out and sorts after it. Wires in
either delegation order: a backend task delegated after UX gets the
dependency directly; a UX task delegated after a still-pending backend
sibling retro-wires it.

Mirrors the existing frontend wiring (_depend_backend_on_ux and
_depend_pending_backends_on_ux). Backend is held by the same dependency
gate, so it costs no extra dispatch churn.

* fix(websocket): forward notification acks instead of logging them incomplete

The bridge handler serves both notification.sent and notification.acked,
but acked events carry `agent_id` (the acking agent) rather than
`recipient_id`, so every acknowledgement tripped the missing-field guard
and logged "Incomplete notification event" instead of reaching the panel.
Accept either field as the recipient.

* feat(api): hint the full UUID when a truncated task id fails validation

Agents copy the 8-character task prefix the system shows them (the commit
prefix, task summaries) and send it as task_id, which fails UUID
validation with an opaque "invalid length" 422 and wastes a call. The
request-validation handler now detects a task_id UUID error and attaches
a `remediate` hint telling the agent to retry with the full 36-character
UUID from its task envelope.

* fix(audit): record the blocked transition when a task is escalated

Escalation sets a task to blocked by writing task.status directly, which
bypassed the validated transition helper and so never emitted a
task.blocked audit row — the lifecycle moved but the Auditor saw nothing.
Extract the audit emit from the central transition helper into
_emit_status_transition_audit and call it from the escalate path,
capturing the prior status and outgoing owner before reassignment so the
row is attributed correctly.

* fix(docs): stop doubling the docs path so design specs index into RAG

The documenter sometimes hands a doc path already rooted at docs/, and
joining it onto DOCS_BASE_PATH (/app/docs) produced /app/docs/docs/...,
so the file was never found and the spec never indexed — the frontend
cell could not retrieve the UX design over RAG. Normalize the path
before joining: trust an absolute path, otherwise strip a single
redundant leading docs/ segment.

* feat(security): let the control panel authenticate in secure mode

With ROBOCO_AGENT_AUTH_REQUIRED=true every request must carry a valid
HMAC token, which locked the human control panel out — it sends role
headers but no token. nginx, the only trusted hop between the browser
and the API, now injects the CEO token on /api and /ws, so the browser
never holds the signing secret. The injected value is just the existing
per-agent token issued for the CEO identity (issue_panel_token), so the
token-verification path is unchanged. An empty value (dev/header-trust
mode) renders to no header.

`make panel-token` prints the value; set it as ROBOCO_PANEL_AGENT_TOKEN
in .env before enabling secure mode. .env.example and the README
Security section document the flow.

* chore(compose): consolidate the two compose files into one

docker-compose.yml and docker-compose.yaml had diverged: .yml — the file
Docker actually uses — carried ROBOCO_PUBLIC_BASE_URL but was missing the
/app/manifests bind-mount, while .yaml had the manifests mount but not
the base URL. Merge the union into docker-compose.yml and delete the
duplicate so there is one source of truth and no "multiple config files"
warning.

This activates the manifests mount in the deployed file: without it the
orchestrator writes per-agent tool manifests to its ephemeral container
fs, they never reach the host for the daemon to bind-mount, and agents
fall back to all-verbs registration. Drop the stale .yaml reference from
the config.py docstring, the labeler, and the CI path filters.

---------

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

tests/unit/services/test_git.py

@@ -22,6 +22,7 @@ if TYPE_CHECKING:
     from contextlib import AbstractContextManager
 
 _EXPECTED_PR_NUMBER = 7
+_PUSHED_COMMIT_COUNT = 2
 
 
 def _make_session(execute_returns: object | None = None) -> MagicMock:
@@ -126,6 +127,46 @@ async def test_project_for_task_uses_project_id_when_present() -> None:
     assert out is fake_project
 
 
+# ---------------------------------------------------------------------------
+# push_task_branch: idempotent push at the QA-submission boundary
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_push_task_branch_resolves_workspace_and_pushes() -> None:
+    """Resolves the task's project + workspace, then pushes; returns the count."""
+    task = MagicMock(branch_name="feature/backend/abc")
+    project = MagicMock(slug="roboco")
+    svc = _service()
+    _bind(svc, "_assert_task_owned_with_branch", AsyncMock(return_value=task))
+    _bind(svc, "_project_for_task", AsyncMock(return_value=project))
+    _bind(svc, "get_workspace", AsyncMock(return_value=Path("/tmp/ws")))
+    _bind(svc, "_assert_on_task_branch", AsyncMock())
+    push_mock = AsyncMock(return_value=("feature/backend/abc", _PUSHED_COMMIT_COUNT))
+    _bind(svc, "push", push_mock)
+
+    pushed = await svc.push_task_branch(uuid4(), uuid4())
+
+    assert pushed == _PUSHED_COMMIT_COUNT
+    push_mock.assert_awaited_once_with(Path("/tmp/ws"))
+
+
+@pytest.mark.asyncio
+async def test_push_task_branch_noop_for_project_less_task() -> None:
+    """A git-exempt task (no resolvable project) is a no-op, not an error."""
+    task = MagicMock(branch_name="feature/main_pm/abc")
+    svc = _service()
+    _bind(svc, "_assert_task_owned_with_branch", AsyncMock(return_value=task))
+    _bind(svc, "_project_for_task", AsyncMock(return_value=None))
+    push_mock = AsyncMock()
+    _bind(svc, "push", push_mock)
+
+    pushed = await svc.push_task_branch(uuid4(), uuid4())
+
+    assert pushed == 0
+    push_mock.assert_not_awaited()
+
+
 # ---------------------------------------------------------------------------
 # diff: derives parent + invokes git diff
 # ---------------------------------------------------------------------------
@@ -404,3 +445,80 @@ async def test_create_branch_idempotent_when_branch_already_exists() -> None:
 
     assert ["checkout", "-b", branch] in calls, "checkout -b attempted"
     assert ["checkout", branch] in calls, "fell back to existing branch on 128"
+
+
+def _create_branch_stubs(svc: GitService) -> None:
+    object.__setattr__(svc, "_resolve_base_branch", AsyncMock(return_value="master"))
+    object.__setattr__(svc, "_project_default_branch", AsyncMock(return_value="master"))
+    object.__setattr__(svc, "_token_for_project", AsyncMock(return_value=None))
+    object.__setattr__(
+        svc, "_checkout_base_with_fallback", AsyncMock(return_value="master")
+    )
+
+
+async def _run_create_branch_with_existing_branch(
+    svc: GitService, branch: str, unique_commits: str
+) -> list[list[str]]:
+    """Drive create_branch where `checkout -b` fails (branch exists) and the
+    branch has `unique_commits` commits of its own. Returns the git argv calls.
+    """
+    calls: list[list[str]] = []
+
+    async def fake_run_git(
+        _workspace: object, args: list[str], **_kw: object
+    ) -> object:
+        calls.append(list(args))
+        if list(args[:2]) == ["checkout", "-b"]:
+            return MagicMock(stdout="", returncode=1)  # branch already exists
+        if list(args[:2]) == ["rev-list", "--count"]:
+            return MagicMock(stdout=f"{unique_commits}\n", returncode=0)
+        return MagicMock(stdout="", returncode=0)
+
+    object.__setattr__(svc, "_run_git", fake_run_git)
+    with (
+        patch("roboco.services.git.build_branch_name", AsyncMock(return_value=branch)),
+        patch(
+            "roboco.services.git.get_task_service",
+            MagicMock(return_value=MagicMock(update=AsyncMock())),
+        ),
+    ):
+        await svc.create_branch(
+            Path("/tmp/ws"),
+            "frontend",
+            GitCreateBranchRequest(
+                project_slug="roboco-panel",
+                task_id=uuid4(),
+                branch_type="feature",
+                agent_id=str(uuid4()),
+                parent_branch=None,
+            ),
+        )
+    return calls
+
+
+@pytest.mark.asyncio
+async def test_create_branch_refreshes_no_work_existing_branch_to_base() -> None:
+    """An existing branch with no commits of its own is re-pointed at the fresh
+    base — a dependency-blocked task re-claimed after its upstream merged must
+    not keep building on the stale snapshot."""
+    svc = _service()
+    _create_branch_stubs(svc)
+    calls = await _run_create_branch_with_existing_branch(
+        svc, "feature/frontend/abc12345--def67890", unique_commits="0"
+    )
+    assert ["reset", "--hard", "master"] in calls, (
+        "a no-work existing branch must be reset onto the fresh base"
+    )
+
+
+@pytest.mark.asyncio
+async def test_create_branch_keeps_existing_branch_that_has_work() -> None:
+    """An existing branch carrying its own commits is NOT reset (work preserved)."""
+    svc = _service()
+    _create_branch_stubs(svc)
+    calls = await _run_create_branch_with_existing_branch(
+        svc, "feature/frontend/abc12345--def67890", unique_commits="3"
+    )
+    assert not any(c[:2] == ["reset", "--hard"] for c in calls), (
+        "a branch with real work must never be reset"
+    )