fix(gateway): unblock task claim; full Phase 0/1/2 remediation

Resolves the 100% claim-failure rate introduced by the gateway rewrite
  (commit 62bda0c plus 78 follow-ups). Live smoke runs hit
  `404 /api/v2/flow/developer/...` on every dev verb plus a manifest
  fallback that silently exposed off-role verbs to PMs — confirmed
  firing simultaneously in NAS agent logs (be-dev-1, be-pm, main-pm).

  Audit reports under docs/internal/audit_2026_05_04/ catalogue 49
  defects across gateway, services, prompts, MCP transport, substrate,
  and tests (8 detail reports + master synthesis). Six smoking guns;
  three proven in production logs.

  Phase 0 — unblock claim:
  - URL prefix /api/v2/flow/dev → /developer; slug-map board roles
    (product_owner, head_marketing) → /board (D-01)
  - _i_will_work_on AttributeError on None across pending /
    needs_revision / claimed re-entry branches (D-02)
  - Seed last_heartbeat_at in _qa_or_doc_claim (D-03)
  - Drop misleading i_have_committed verb; dev flow uses commit() (D-04)
  - Manifest mount via compose; flow_server + do_server fail loud
    instead of exposing all-verbs fallback (D-12)
  - MCP _post() surfaces envelope body on 4xx so agents see remediate
    hints (D-13)
    on git failure so retries aren't blocked by half-state (S-01)

  Phase 1 — lifecycle stability:
  - _resolve_skill falls back to AgentTable.capabilities (D-06)
  - main_pm_complete uses kwargs for escalate_to_ceo (D-07)
  - i_am_done auto-runs submit_verification when in_progress (D-08)
  - active_claimant_id wired in claim/unclaim paths — single-claimant
    invariant now functional (D-05)
  - qa_pass/qa_fail assert claimed_by parity with qa_agent_id (D-18)
  - Prompt-drift sweep: fail() shape, i_am_done(task_id, notes),
    subtask cap (12 hard / 8 soft), error-code symbology rewritten in
    base.md + per-role anti-patterns (D-10/11/29/30/31, D-37)

  Phase 2 — invariants + architecture:
  - Real-DB integration test exercising claim → in_progress → commit
    → submit_for_qa → i_am_done → awaiting_qa (P2-1)
  - choreographer.py → package; 3 of 6 role mixins extracted
    (board, doc, qa). _impl.py 2,526 → 2,080 lines (-18%). Continuation
    plan in docs/internal/audit_2026_05_04/p2_2_decompose_plan.md (P2-2)
  - Closure guards consolidated via _subtasks_not_terminal_envelope (P2-3)
  - TaskService.unclaim_for_reaper routed through canonical
    _validate_and_set_status; in_progress → pending added to
    VALID_TRANSITIONS (P2-4)
  - Dead code removed: i_am_done_with_catchup verb, _run_catch_up helper
    (P2-5)
  - 6 state-machine invariants asserted via property test (P2-6)
  - attempt_id (uuid4) stamped on every gateway.rejected audit row (P2-7)
  - _reconcile_orphan_claims_on_startup rolls back tasks left CLAIMED
    with branch_name=NULL from prior crashes (P2-8)
  - scripts/regenerate_verb_tables.py introspects Pydantic schemas +
    role_config; compose_prompt injects per-role tables as a layer.
    Eliminates the prompt-drift class structurally (P2-9)

  Other:
  - D-48: orchestrator mounts host's ~/.claude.json when present so
    agents don't boot from backup recovery on every spawn
  - D-49: dev dispatcher rejects role-mismatched spawns (e.g. doc task
    assigned to dev agent)

  Tests: 553 pass · ruff + mypy clean. Live NAS smoke verification
  pending — needs the stack brought back up.

roboco/mcp/do_server.py

@@ -51,16 +51,34 @@ def _build_headers() -> dict[str, str]:
 
 
 def _post(path: str, body: dict[str, Any]) -> dict[str, Any]:
-    """POST a request to the orchestrator and return the JSON envelope."""
+    """POST a request to the orchestrator and return the JSON envelope.
+
+    Mirrors flow_server._post: surfaces the orchestrator's envelope on
+    both 2xx and 4xx so the agent always sees ``remediate``. Only
+    fabricates a transport_error envelope when the body is unparseable.
+    """
     with httpx.Client(timeout=_TIMEOUT) as client:
         response = client.post(
             f"{ORCHESTRATOR_URL}{path}",
             headers=_build_headers(),
             json=body,
         )
-        response.raise_for_status()
-        result: dict[str, Any] = response.json()
-        return result
+        try:
+            payload: dict[str, Any] = response.json()
+        except (ValueError, json.JSONDecodeError):
+            return {
+                "error": "transport_error",
+                "message": (
+                    f"orchestrator returned HTTP {response.status_code}"
+                    f" with no JSON body for {path}"
+                ),
+                "remediate": (
+                    "check that the orchestrator is up and the route exists;"
+                    " contact the human operator if this persists"
+                ),
+                "missing": [],
+            }
+        return payload
 
 
 def commit(message: str, files: list[str] | None = None) -> dict[str, Any]:
@@ -168,26 +186,35 @@ def _load_manifest_do_tools() -> list[str] | None:
 
 
 def _register_tools() -> list[str]:
-    """Register MCP tools according to the manifest, or all tools as a failsafe.
+    """Register MCP tools according to the manifest. Fails loud if absent.
+
+    Mirrors flow_server's behaviour: refuse to start if the manifest is
+    missing rather than silently exposing the full do-tool set (which
+    includes ``commit`` — the role-gate would reject it server-side, but
+    the agent shouldn't see it on its tool palette in the first place).
 
     Returns the list of tool names actually registered.
     """
     allowed = _load_manifest_do_tools()
     if allowed is None:
-        log.warning(
-            "do_server: manifest unavailable; registering all do tools",
-            role=AGENT_ROLE,
+        manifest_path = os.environ.get(
+            "ROBOCO_TOOL_MANIFEST_PATH", "/app/tool-manifest.json"
         )
-        names = list(_TOOLS)
-    else:
-        unknown = [verb for verb in allowed if verb not in _TOOLS]
-        if unknown:
-            log.warning(
-                "do_server: manifest references unknown do tools",
-                role=AGENT_ROLE,
-                missing=sorted(unknown),
-            )
-        names = [verb for verb in allowed if verb in _TOOLS]
+        msg = (
+            f"do_server: manifest unavailable at {manifest_path};"
+            f" refusing to register all-tools fallback for role"
+            f" {AGENT_ROLE!r}. Check the orchestrator manifest mount."
+        )
+        log.error("do_server: manifest missing", role=AGENT_ROLE, path=manifest_path)
+        raise RuntimeError(msg)
+    unknown = [verb for verb in allowed if verb not in _TOOLS]
+    if unknown:
+        log.warning(
+            "do_server: manifest references unknown do tools",
+            role=AGENT_ROLE,
+            missing=sorted(unknown),
+        )
+    names = [verb for verb in allowed if verb in _TOOLS]
 
     for verb in names:
         mcp.tool(name=verb)(_TOOLS[verb])