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/gateway/test_choreographer_claim_guards.py

@@ -1,15 +1,13 @@
 """Gate Set A: claim-time guards restored from pre-gateway _helpers.py:124-204.
 
 Predicates ported into Choreographer claim verbs:
-- SEQUENCE_ORDER_VIOLATION   (earlier sibling must be terminal)
 - ALREADY_ACTIVE              (no claim while in_progress task is open)
 - PAUSED_TASKS_EXIST          (no claim while paused tasks exist)
 - PM_CANNOT_EXECUTE_CODE      (cell_pm/main_pm cannot claim task_type=code)
 - ROLE_TYPED_CLAIM            (developer/qa/documenter cannot cross-claim)
 
 These mirror pre-gateway gates at commit 0c3d15a, file
-roboco/mcp/tasks/handlers/_helpers.py lines 124-204 plus
-roboco/mcp/tasks/handlers/claim.py:121-180 for the sibling sequence check.
+roboco/mcp/tasks/handlers/_helpers.py lines 124-204.
 """
 
 from __future__ import annotations
@@ -33,21 +31,6 @@ _STEPS = [
         ),
     }
 ]
-# Full parity: a fresh dev claim authors the same rich plan a PM does.
-# These satisfy _dev_plan_gate (plan/approach >= 150 chars,
-# technical_considerations, risks).
-_GOOD_PLAN = (
-    "Append the timestamp HTML comment to the very bottom of README.md without "
-    "touching any other line, then commit it on the task branch and open a PR. "
-    "Verify the diff is a single-line addition before submitting for QA."
-)
-_GOOD_TC = ["Use a trailing newline so the comment sits on its own line."]
-_GOOD_RISKS = [
-    {
-        "risk": "An accidental reformat of README.md balloons the diff.",
-        "mitigation": "Append only; assert the diff touches one line pre-commit.",
-    }
-]
 
 
 def _make_deps(**overrides: Any) -> ChoreographerDeps:
@@ -122,138 +105,6 @@ def _task_svc_with(
     return task_svc
 
 
-# ---------------------------------------------------------------------------
-# A.1 SEQUENCE_ORDER_VIOLATION
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_i_will_work_on_blocks_when_earlier_sibling_open() -> None:
-    """Sequence=2 cannot be claimed while sequence=1 sibling is still open."""
-    agent_id = uuid4()
-    parent_id = uuid4()
-    target_id = uuid4()
-    earlier_id = uuid4()
-    target = MagicMock(
-        id=target_id,
-        status="pending",
-        plan=None,
-        assigned_to=None,
-        parent_task_id=parent_id,
-        sequence=2,
-        task_type="code",
-        team="backend",
-    )
-    earlier = MagicMock(
-        id=earlier_id,
-        status="in_progress",
-        sequence=1,
-        title="Earlier sibling",
-    )
-    later = MagicMock(
-        id=target_id,
-        status="pending",
-        sequence=2,
-    )
-    task_svc = _task_svc_with(target, lookups={"siblings": [earlier, later]})
-    deps = _make_deps(task=task_svc)
-    c = Choreographer(deps)
-
-    env = await c.i_will_work_on(agent_id, target_id, plan="x", steps=_STEPS)
-    body = env.as_dict()
-    assert body["error"] == "invalid_state"
-    assert "sequence" in body["message"].lower()
-    assert str(earlier_id) in body["remediate"]
-    task_svc.claim.assert_not_awaited()
-
-
-@pytest.mark.asyncio
-async def test_i_will_work_on_allows_when_earlier_sibling_terminal() -> None:
-    """Earlier siblings completed/cancelled do not block."""
-    agent_id = uuid4()
-    parent_id = uuid4()
-    target_id = uuid4()
-    target = MagicMock(
-        id=target_id,
-        status="pending",
-        plan={"x": 1},
-        assigned_to=None,
-        parent_task_id=parent_id,
-        sequence=2,
-        task_type="code",
-        team="backend",
-    )
-    earlier_done = MagicMock(id=uuid4(), status="completed", sequence=1)
-    earlier_cancelled = MagicMock(id=uuid4(), status="cancelled", sequence=0)
-    self_row = MagicMock(id=target_id, status="pending", sequence=2)
-    task_svc = _task_svc_with(
-        target,
-        agent_id=agent_id,
-        lookups={"siblings": [earlier_done, earlier_cancelled, self_row]},
-    )
-    task_svc.claim.return_value = MagicMock(
-        id=target_id,
-        status="claimed",
-        plan={"x": 1},
-        assigned_to=agent_id,
-        task_type="code",
-    )
-    task_svc.start.return_value = MagicMock(
-        id=target_id, status="in_progress", plan={"x": 1}, assigned_to=agent_id
-    )
-    deps = _make_deps(task=task_svc)
-    c = Choreographer(deps)
-
-    env = await c.i_will_work_on(
-        agent_id,
-        target_id,
-        plan=_GOOD_PLAN,
-        steps=_STEPS,
-        technical_considerations=_GOOD_TC,
-        risks=_GOOD_RISKS,
-    )
-    assert env.error is None
-    task_svc.claim.assert_awaited_once_with(target_id, agent_id)
-
-
-@pytest.mark.asyncio
-async def test_root_task_no_sequence_check() -> None:
-    """Root tasks (no parent) skip the sequence check entirely."""
-    agent_id = uuid4()
-    target_id = uuid4()
-    target = MagicMock(
-        id=target_id,
-        status="pending",
-        plan={"x": 1},
-        assigned_to=None,
-        parent_task_id=None,
-        sequence=5,
-        task_type="code",
-        team="backend",
-    )
-    task_svc = _task_svc_with(target, agent_id=agent_id)
-    task_svc.claim.return_value = MagicMock(
-        id=target_id, status="claimed", plan={"x": 1}, assigned_to=agent_id
-    )
-    task_svc.start.return_value = MagicMock(
-        id=target_id, status="in_progress", plan={"x": 1}, assigned_to=agent_id
-    )
-    deps = _make_deps(task=task_svc)
-    c = Choreographer(deps)
-
-    env = await c.i_will_work_on(
-        agent_id,
-        target_id,
-        plan=_GOOD_PLAN,
-        steps=_STEPS,
-        technical_considerations=_GOOD_TC,
-        risks=_GOOD_RISKS,
-    )
-    assert env.error is None
-    # Sequence check should not have queried siblings on a root task
-    task_svc.get_subtasks.assert_not_awaited()
-
-
 # ---------------------------------------------------------------------------
 # A.2 ALREADY_ACTIVE
 # ---------------------------------------------------------------------------